roundTools: Tools for rounding floats

Various round-to-integer helpers.

fontTools.misc.roundTools.noRound(value: float) → float

Return float value unmodified; do not round.

Parameters:

value (float) – The input floating-point value.

Returns

float: The same value.

fontTools.misc.roundTools.otRound(value: float) → int

Round float value to nearest integer towards +Infinity.

The OpenType spec (in the section on “normalization” of OpenType Font Variations) defines the required method for converting floating point values to fixed-point. In particular it specifies the following rounding strategy:

for fractional values of 0.5 and higher, take the next higher integer; for other fractional values, truncate.

This function rounds the floating-point value according to this strategy in preparation for conversion to fixed-point.

Parameters:

value (float) – The input floating-point value.

Returns

int: The rounded value.

fontTools.misc.roundTools.maybeRound(v: float, tolerance: float, round: ~collections.abc.Callable[[float], float] = <function otRound>) → float

Round only if rounding changes the value by no more than a given amount.

Parameters:

• value (float) – The input floating-point value.

• tolerance (float) – The maximum absolute difference permitted.

• round (function) – The rounding strategy, taking and giving a float.

Returns

float: A rounded value if within tolerance, otherwise the original.

fontTools.misc.roundTools.roundFunc(tolerance: float, round: ~collections.abc.Callable[[float], float] = <function otRound>) → Callable[[float], float]

Make a conditional rounding strategy from a base strategy and tolerance.

This preconfigures maybeRound() with fixed arguments, allowing it to be used anywhere a simple rounding function is accepted.

The tolerance is validated to ensure it is absolute, and the cases where rounding would never or always occur are optimized. Rounding must never change a value by more than 0.5 for this to be sound (e.g. ceil() could change by too much).

Parameters:

• tolerance (float) – The maximum absolute difference permitted.

• round (function) – The rounding strategy, taking and giving a float.

Returns

function: A strategy that conditionally rounds based on tolerance.

fontTools.misc.roundTools.nearestMultipleShortestRepr(value: float, factor: float) → str

Round to nearest multiple of factor and return shortest decimal representation.

This chooses the float that is closer to a multiple of the given factor while having the shortest decimal representation (the least number of fractional decimal digits).

For example, given the following:

>>> nearestMultipleShortestRepr(-0.61883544921875, 1.0/(1<<14))
'-0.61884'

Useful when you need to serialize or print a fixed-point number (or multiples thereof, such as F2Dot14 fractions of 180 degrees in COLRv1 PaintRotate) in a human-readable form.

Parameters:

• value (value) – The value to be rounded and serialized.

• factor (float) – The value which the result is a close multiple of.

Returns:

A compact string representation of the value.

Return type:

str