1##################################
2varLib: OpenType Variation Support
3##################################
4
5The ``fontTools.varLib`` package contains a number of classes and routines
6for handling, building and interpolating variable font data. These routines
7rely on a common set of concepts, many of which are equivalent to concepts
8in the OpenType Specification, but some of which are unique to ``varLib``.
9
10Terminology
11-----------
12
13axis
14   "A designer-determined variable in a font face design that can be used to
15   derive multiple, variant designs within a family." (OpenType Specification)
16   An axis has a minimum value, a maximum value and a default value.
17
18designspace
19   The n-dimensional space formed by the font's axes. (OpenType Specification
20   calls this the "design-variation space")
21
22scalar
23   A value which is able to be varied at different points in the designspace:
24   for example, the horizontal advance width of the glyph "a" is a scalar.
25   However, see also *support scalar* below.
26
27default location
28   A point in the designspace whose coordinates are the default value of
29   all axes.
30
31location
32   A point in the designspace, specified as a set of coordinates on one or
33   more axes. In the context of ``varLib``, a location is a dictionary with
34   the keys being the axis tags and the values being the coordinates on the
35   respective axis. A ``varLib`` location dictionary may be "sparse", in the
36   sense that axes defined in the font may be omitted from the location's
37   coordinates, in which case the default value of the axis is assumed.
38   For example, given a font having a ``wght`` axis ranging from 200-1000
39   with default 400, and a ``wdth`` axis ranging 100-300 with default 150,
40   the location ``{"wdth": 200}`` represents the point ``wght=400,wdth=200``.
41
42master
43   The value of a scalar at a given location. **Note that this is a
44   considerably more general concept than the usual type design sense of
45   the term "master".**
46
47normalized location
48   While the range of an axis is determined by its minimum and maximum values
49   as set by the designer, locations are specified internally to the font binary
50   in the range -1 to 1, with 0 being the default, -1 being the minimum and
51   1 being the maximum. A normalized location is one which is scaled to the
52   range (-1,1) on all of its axes. Note that as the range from minimum to
53   default and from default to maximum on a given axis may differ (for
54   example, given ``wght min=200 default=500 max=1000``, the difference
55   between a normalized location -1 of a normalized location of 0 represents a
56   difference of 300 units while the difference between a normalized location
57   of 0 and a normalized location of 1 represents a difference of 700 units),
58   a location is scaled by a different factor depending on whether it is above
59   or below the axis' default value.
60
61support
62   While designers tend to think in terms of masters - that is, a precise
63   location having a particular value - OpenType Variations specifies the
64   variation of scalars in terms of deltas which are themselves composed of
65   the combined contributions of a set of triangular regions, each having
66   a contribution value of 0 at its minimum value, rising linearly to its
67   full contribution at the *peak* and falling linearly to zero from the
68   peak to the maximum value. The OpenType Specification calls these "regions",
69   while ``varLib`` calls them "supports" (a mathematical term used in real
70   analysis) and expresses them as a dictionary mapping each axis tag to a
71   tuple ``(min, peak, max)``.
72
73box
74   ``varLib`` uses the term "box" to denote the minimum and maximum "corners" of
75   a support, ignoring its peak value.
76
77delta
78   The term "delta" is used in OpenType Variations in two senses. In the
79   more general sense, a delta is the difference between a scalar at a
80   given location and its value at the default location. Additionally, inside
81   the font, variation data is stored as a mapping between supports and deltas.
82   The delta (in the first sense) is computed by summing the product of the
83   delta of each support by a factor representing the support's contribution
84   at this location (see "support scalar" below).
85
86support scalar
87   When interpolating a set of variation data, the support scalar represents
88   the scalar multiplier of the support's contribution at this location. For
89   example, the support scalar will be 1 at the support's peak location, and
90   0 below its minimum or above its maximum.
91
92
93.. toctree::
94   :maxdepth: 2
95
96   builder
97   cff
98   errors
99   featureVars
100   instancer
101   interpolatable
102   interpolate_layout
103   iup
104   merger
105   models
106   mutator
107   mvar
108   plot
109   varStore
110
111.. automodule:: fontTools.varLib
112   :inherited-members:
113   :members:
114   :undoc-members:
115