fixedTools: Tools for working with fixed-point numbers

The OpenType specification defines two fixed-point data types:

Fixed: A 32-bit signed fixed-point number with a 16 bit twos-complement magnitude component and 16 fractional bits.
F2DOT14: A 16-bit signed fixed-point number with a 2 bit twos-complement magnitude component and 14 fractional bits.

To support reading and writing data with these data types, this module provides functions for converting between fixed-point, float and string representations.

fontTools.misc.fixedTools.MAX_F2DOT14: The maximum value that can still fit in an F2Dot14. (1.99993896484375)

fontTools.misc.fixedTools.ensureVersionIsLong(value)[source]

Ensure a table version is an unsigned long.

OpenType table version numbers are expressed as a single unsigned long comprising of an unsigned short major version and unsigned short minor version. This function detects if the value to be used as a version number looks too small (i.e. is less than 0x10000), and converts it to fixed-point using floatToFixed() if so.

Parameters:: value (Number) – a candidate table version number.
Returns:: A table version number, possibly corrected to fixed-point.
Return type:: int

fontTools.misc.fixedTools.fixedToFloat(value, precisionBits)[source]

Converts a fixed-point number to a float given the number of precision bits.

Parameters:

value (int) – Number in fixed-point format.
precisionBits (int) – Number of precision bits.

Returns:

Floating point value.

Examples:

>>> import math
>>> f = fixedToFloat(-10139, precisionBits=14)
>>> math.isclose(f, -0.61883544921875)
True

fontTools.misc.fixedTools.fixedToStr(value, precisionBits)[source]

Converts a fixed-point number to a string representing a decimal float.

This chooses the float that has the shortest decimal representation (the least number of fractional decimal digits).

For example, to convert a fixed-point number in a 2.14 format, use precisionBits=14:

>>> fixedToStr(-10139, precisionBits=14)
'-0.61884'

This is pretty slow compared to the simple division used in fixedToFloat. Use sporadically when you need to serialize or print the fixed-point number in a human-readable form. It uses nearestMultipleShortestRepr under the hood.

Parameters:

value (int) – The fixed-point value to convert.
precisionBits (int) – Number of precision bits, up to a maximum of 16.

Returns:

A string representation of the value.

Return type:

str

fontTools.misc.fixedTools.floatToFixed(value, precisionBits)[source]

Converts a float to a fixed-point number given the number of precision bits.

Parameters:

value (float) – Floating point value.
precisionBits (int) – Number of precision bits.

Returns:

Fixed-point representation.

Return type:

int

Examples:

>>> floatToFixed(-0.61883544921875, precisionBits=14)
-10139
>>> floatToFixed(-0.61884, precisionBits=14)
-10139

fontTools.misc.fixedTools.floatToFixedToFloat(value, precisionBits)[source]

Converts a float to a fixed-point number and back again.

By converting the float to fixed, rounding it, and converting it back to float again, this returns a floating point values which is exactly representable in fixed-point format.

Note: this is equivalent to fixedToFloat(floatToFixed(value)).

Parameters:

value (float) – The input floating point value.
precisionBits (int) – Number of precision bits.

Returns:

The transformed and rounded value.

Return type:

float

Examples::

>>> import math
>>> f1 = -0.61884
>>> f2 = floatToFixedToFloat(-0.61884, precisionBits=14)
>>> f1 != f2
True
>>> math.isclose(f2, -0.61883544921875)
True

fontTools.misc.fixedTools.floatToFixedToStr(value, precisionBits)[source]

Convert float to string with fixed-point rounding.

This uses the shortest decimal representation (ie. the least number of fractional decimal digits) to represent the equivalent fixed-point number with precisionBits fractional binary digits. It uses nearestMultipleShortestRepr under the hood.

>>> floatToFixedToStr(-0.61883544921875, precisionBits=14)
'-0.61884'

Parameters:

value (float) – The float value to convert.
precisionBits (int) – Number of precision bits, up to a maximum of 16.

Returns:

A string representation of the value.

Return type:

str

fontTools.misc.fixedTools.strToFixed(string, precisionBits)[source]

Converts a string representing a decimal float to a fixed-point number.

Parameters:

string (str) – A string representing a decimal float.
precisionBits (int) – Number of precision bits, up to a maximum of 16.

Returns:

Fixed-point representation.

Return type:

int

Examples:

>>> ## to convert a float string to a 2.14 fixed-point number:
>>> strToFixed('-0.61884', precisionBits=14)
-10139

fontTools.misc.fixedTools.strToFixedToFloat(string, precisionBits)[source]

Convert a string to a decimal float with fixed-point rounding.

This first converts string to a float, then turns it into a fixed-point number with precisionBits fractional binary digits, then back to a float again.

This is simply a shorthand for fixedToFloat(floatToFixed(float(s))).

Parameters:

string (str) – A string representing a decimal float.
precisionBits (int) – Number of precision bits.

Returns:

The transformed and rounded value.

Return type:

float

Examples:

>>> import math
>>> s = '-0.61884'
>>> bits = 14
>>> f = strToFixedToFloat(s, precisionBits=bits)
>>> math.isclose(f, -0.61883544921875)
True
>>> f == fixedToFloat(floatToFixed(float(s), precisionBits=bits), precisionBits=bits)
True

fontTools.misc.fixedTools.versionToFixed(value)[source]

Ensure a table version number is fixed-point.

Parameters:: value (str) – a candidate table version number.
Returns:: A table version number, possibly corrected to fixed-point.
Return type:: int