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.

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 fixedToStr 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.otRound(value)[source]

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

float: The rounded value.

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