From 516d0f7dfe111ebd74671ccd1cbc21c9e8d5909f Mon Sep 17 00:00:00 2001 From: Simon Cozens Date: Wed, 3 Mar 2021 12:57:52 +0000 Subject: [PATCH 1/2] Add definitions for varLib-specific terms --- Doc/source/varLib/index.rst | 93 +++++++++++++++++++++++++++++++++++-- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/Doc/source/varLib/index.rst b/Doc/source/varLib/index.rst index 5394d6287..f22967f4d 100644 --- a/Doc/source/varLib/index.rst +++ b/Doc/source/varLib/index.rst @@ -1,6 +1,93 @@ -###### -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 From a0d6ca3b7630d8c8005be91fb41ff9b38b6de406 Mon Sep 17 00:00:00 2001 From: Simon Cozens Date: Wed, 3 Mar 2021 13:33:58 +0000 Subject: [PATCH 2/2] ReStructuredText nits --- Doc/source/varLib/index.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Doc/source/varLib/index.rst b/Doc/source/varLib/index.rst index f22967f4d..7b2249674 100644 --- a/Doc/source/varLib/index.rst +++ b/Doc/source/varLib/index.rst @@ -1,17 +1,18 @@ -########################## -OpenType Variation Support -########################## +################################## +varLib: OpenType Variation Support +################################## -The `fontTools.varLib` package contains a number of classes and routines +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`. +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) + "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 @@ -70,7 +71,7 @@ support tuple ``(min, peak, max)``. box - `varLib` uses the term "box" to denote the minimum and maximum "corners" of + ``varLib`` uses the term "box" to denote the minimum and maximum "corners" of a support, ignoring its peak value. delta