1""" 2The `OpenType specification <https://docs.microsoft.com/en-us/typography/opentype/spec/otff#data-types>`_ 3defines two fixed-point data types: 4 5``Fixed`` 6 A 32-bit signed fixed-point number with a 16 bit twos-complement 7 magnitude component and 16 fractional bits. 8``F2DOT14`` 9 A 16-bit signed fixed-point number with a 2 bit twos-complement 10 magnitude component and 14 fractional bits. 11 12To support reading and writing data with these data types, this module provides 13functions for converting between fixed-point, float and string representations. 14 15.. data:: MAX_F2DOT14 16 17 The maximum value that can still fit in an F2Dot14. (1.99993896484375) 18""" 19 20from .roundTools import otRound 21import logging 22 23log = logging.getLogger(__name__) 24 25__all__ = [ 26 "MAX_F2DOT14", 27 "fixedToFloat", 28 "floatToFixed", 29 "floatToFixedToFloat", 30 "floatToFixedToStr", 31 "fixedToStr", 32 "strToFixed", 33 "strToFixedToFloat", 34 "ensureVersionIsLong", 35 "versionToFixed", 36] 37 38 39MAX_F2DOT14 = 0x7FFF / (1 << 14) 40 41 42def fixedToFloat(value, precisionBits): 43 """Converts a fixed-point number to a float given the number of 44 precision bits. 45 46 Args: 47 value (int): Number in fixed-point format. 48 precisionBits (int): Number of precision bits. 49 50 Returns: 51 Floating point value. 52 53 Examples:: 54 55 >>> import math 56 >>> f = fixedToFloat(-10139, precisionBits=14) 57 >>> math.isclose(f, -0.61883544921875) 58 True 59 """ 60 return value / (1 << precisionBits) 61 62 63def floatToFixed(value, precisionBits): 64 """Converts a float to a fixed-point number given the number of 65 precision bits. 66 67 Args: 68 value (float): Floating point value. 69 precisionBits (int): Number of precision bits. 70 71 Returns: 72 int: Fixed-point representation. 73 74 Examples:: 75 76 >>> floatToFixed(-0.61883544921875, precisionBits=14) 77 -10139 78 >>> floatToFixed(-0.61884, precisionBits=14) 79 -10139 80 """ 81 return otRound(value * (1 << precisionBits)) 82 83 84def floatToFixedToFloat(value, precisionBits): 85 """Converts a float to a fixed-point number and back again. 86 87 By converting the float to fixed, rounding it, and converting it back 88 to float again, this returns a floating point values which is exactly 89 representable in fixed-point format. 90 91 Note: this **is** equivalent to ``fixedToFloat(floatToFixed(value))``. 92 93 Args: 94 value (float): The input floating point value. 95 precisionBits (int): Number of precision bits. 96 97 Returns: 98 float: The transformed and rounded value. 99 100 Examples:: 101 >>> import math 102 >>> f1 = -0.61884 103 >>> f2 = floatToFixedToFloat(-0.61884, precisionBits=14) 104 >>> f1 != f2 105 True 106 >>> math.isclose(f2, -0.61883544921875) 107 True 108 """ 109 scale = 1 << precisionBits 110 return otRound(value * scale) / scale 111 112 113def fixedToStr(value, precisionBits): 114 """Converts a fixed-point number to a string representing a decimal float. 115 116 This chooses the float that has the shortest decimal representation (the least 117 number of fractional decimal digits). 118 119 For example, to convert a fixed-point number in a 2.14 format, use 120 ``precisionBits=14``:: 121 122 >>> fixedToStr(-10139, precisionBits=14) 123 '-0.61884' 124 125 This is pretty slow compared to the simple division used in ``fixedToFloat``. 126 Use sporadically when you need to serialize or print the fixed-point number in 127 a human-readable form. 128 129 Args: 130 value (int): The fixed-point value to convert. 131 precisionBits (int): Number of precision bits, *up to a maximum of 16*. 132 133 Returns: 134 str: A string representation of the value. 135 """ 136 if not value: return "0.0" 137 138 scale = 1 << precisionBits 139 value /= scale 140 eps = .5 / scale 141 lo = value - eps 142 hi = value + eps 143 # If the range of valid choices spans an integer, return the integer. 144 if int(lo) != int(hi): 145 return str(float(round(value))) 146 fmt = "%.8f" 147 lo = fmt % lo 148 hi = fmt % hi 149 assert len(lo) == len(hi) and lo != hi 150 for i in range(len(lo)): 151 if lo[i] != hi[i]: 152 break 153 period = lo.find('.') 154 assert period < i 155 fmt = "%%.%df" % (i - period) 156 return fmt % value 157 158 159def strToFixed(string, precisionBits): 160 """Converts a string representing a decimal float to a fixed-point number. 161 162 Args: 163 string (str): A string representing a decimal float. 164 precisionBits (int): Number of precision bits, *up to a maximum of 16*. 165 166 Returns: 167 int: Fixed-point representation. 168 169 Examples:: 170 171 >>> ## to convert a float string to a 2.14 fixed-point number: 172 >>> strToFixed('-0.61884', precisionBits=14) 173 -10139 174 """ 175 value = float(string) 176 return otRound(value * (1 << precisionBits)) 177 178 179def strToFixedToFloat(string, precisionBits): 180 """Convert a string to a decimal float with fixed-point rounding. 181 182 This first converts string to a float, then turns it into a fixed-point 183 number with ``precisionBits`` fractional binary digits, then back to a 184 float again. 185 186 This is simply a shorthand for fixedToFloat(floatToFixed(float(s))). 187 188 Args: 189 string (str): A string representing a decimal float. 190 precisionBits (int): Number of precision bits. 191 192 Returns: 193 float: The transformed and rounded value. 194 195 Examples:: 196 197 >>> import math 198 >>> s = '-0.61884' 199 >>> bits = 14 200 >>> f = strToFixedToFloat(s, precisionBits=bits) 201 >>> math.isclose(f, -0.61883544921875) 202 True 203 >>> f == fixedToFloat(floatToFixed(float(s), precisionBits=bits), precisionBits=bits) 204 True 205 """ 206 value = float(string) 207 scale = 1 << precisionBits 208 return otRound(value * scale) / scale 209 210 211def floatToFixedToStr(value, precisionBits): 212 """Convert float to string with fixed-point rounding. 213 214 This uses the shortest decimal representation (ie. the least 215 number of fractional decimal digits) to represent the equivalent 216 fixed-point number with ``precisionBits`` fractional binary digits. 217 It uses fixedToStr under the hood. 218 219 >>> floatToFixedToStr(-0.61883544921875, precisionBits=14) 220 '-0.61884' 221 222 Args: 223 value (float): The float value to convert. 224 precisionBits (int): Number of precision bits, *up to a maximum of 16*. 225 226 Returns: 227 str: A string representation of the value. 228 229 """ 230 fixed = otRound(value * (1 << precisionBits)) 231 return fixedToStr(fixed, precisionBits) 232 233 234def ensureVersionIsLong(value): 235 """Ensure a table version is an unsigned long. 236 237 OpenType table version numbers are expressed as a single unsigned long 238 comprising of an unsigned short major version and unsigned short minor 239 version. This function detects if the value to be used as a version number 240 looks too small (i.e. is less than ``0x10000``), and converts it to 241 fixed-point using :func:`floatToFixed` if so. 242 243 Args: 244 value (Number): a candidate table version number. 245 246 Returns: 247 int: A table version number, possibly corrected to fixed-point. 248 """ 249 if value < 0x10000: 250 newValue = floatToFixed(value, 16) 251 log.warning( 252 "Table version value is a float: %.4f; " 253 "fix to use hex instead: 0x%08x", value, newValue) 254 value = newValue 255 return value 256 257 258def versionToFixed(value): 259 """Ensure a table version number is fixed-point. 260 261 Args: 262 value (str): a candidate table version number. 263 264 Returns: 265 int: A table version number, possibly corrected to fixed-point. 266 """ 267 value = int(value, 0) if value.startswith("0") else float(value) 268 value = ensureVersionIsLong(value) 269 return value 270