| ################################## |
| varLib: OpenType Variation Support |
| ################################## |
| |
| The ``fontTools.varLib`` package contains a number of classes and routines |
| for handling, building and interpolating variable font data. These routines |
| rely on a common set of concepts, many of which are equivalent to concepts |
| in the OpenType Specification, but some of which are unique to ``varLib``. |
| |
| Terminology |
| ----------- |
| |
| axis |
| "A designer-determined variable in a font face design that can be used to |
| derive multiple, variant designs within a family." (OpenType Specification) |
| An axis has a minimum value, a maximum value and a default value. |
| |
| designspace |
| The n-dimensional space formed by the font's axes. (OpenType Specification |
| calls this the "design-variation space") |
| |
| scalar |
| A value which is able to be varied at different points in the designspace: |
| for example, the horizontal advance width of the glyph "a" is a scalar. |
| However, see also *support scalar* below. |
| |
| default location |
| A point in the designspace whose coordinates are the default value of |
| all axes. |
| |
| location |
| A point in the designspace, specified as a set of coordinates on one or |
| more axes. In the context of ``varLib``, a location is a dictionary with |
| the keys being the axis tags and the values being the coordinates on the |
| respective axis. A ``varLib`` location dictionary may be "sparse", in the |
| sense that axes defined in the font may be omitted from the location's |
| coordinates, in which case the default value of the axis is assumed. |
| For example, given a font having a ``wght`` axis ranging from 200-1000 |
| with default 400, and a ``wdth`` axis ranging 100-300 with default 150, |
| the location ``{"wdth": 200}`` represents the point ``wght=400,wdth=200``. |
| |
| master |
| The value of a scalar at a given location. **Note that this is a |
| considerably more general concept than the usual type design sense of |
| the term "master".** |
| |
| normalized location |
| While the range of an axis is determined by its minimum and maximum values |
| as set by the designer, locations are specified internally to the font binary |
| in the range -1 to 1, with 0 being the default, -1 being the minimum and |
| 1 being the maximum. A normalized location is one which is scaled to the |
| range (-1,1) on all of its axes. Note that as the range from minimum to |
| default and from default to maximum on a given axis may differ (for |
| example, given ``wght min=200 default=500 max=1000``, the difference |
| between a normalized location -1 of a normalized location of 0 represents a |
| difference of 300 units while the difference between a normalized location |
| of 0 and a normalized location of 1 represents a difference of 700 units), |
| a location is scaled by a different factor depending on whether it is above |
| or below the axis' default value. |
| |
| support |
| While designers tend to think in terms of masters - that is, a precise |
| location having a particular value - OpenType Variations specifies the |
| variation of scalars in terms of deltas which are themselves composed of |
| the combined contributions of a set of triangular regions, each having |
| a contribution value of 0 at its minimum value, rising linearly to its |
| full contribution at the *peak* and falling linearly to zero from the |
| peak to the maximum value. The OpenType Specification calls these "regions", |
| while ``varLib`` calls them "supports" (a mathematical term used in real |
| analysis) and expresses them as a dictionary mapping each axis tag to a |
| tuple ``(min, peak, max)``. |
| |
| box |
| ``varLib`` uses the term "box" to denote the minimum and maximum "corners" of |
| a support, ignoring its peak value. |
| |
| delta |
| The term "delta" is used in OpenType Variations in two senses. In the |
| more general sense, a delta is the difference between a scalar at a |
| given location and its value at the default location. Additionally, inside |
| the font, variation data is stored as a mapping between supports and deltas. |
| The delta (in the first sense) is computed by summing the product of the |
| delta of each support by a factor representing the support's contribution |
| at this location (see "support scalar" below). |
| |
| support scalar |
| When interpolating a set of variation data, the support scalar represents |
| the scalar multiplier of the support's contribution at this location. For |
| example, the support scalar will be 1 at the support's peak location, and |
| 0 below its minimum or above its maximum. |
| |
| |
| .. toctree:: |
| :maxdepth: 2 |
| |
| builder |
| cff |
| errors |
| featureVars |
| instancer |
| interpolatable |
| interpolate_layout |
| iup |
| merger |
| models |
| mutator |
| mvar |
| plot |
| varStore |
| |
| .. automodule:: fontTools.varLib |
| :inherited-members: |
| :members: |
| :undoc-members: |