varLib: Support for OpenType Variations

• builder
  • buildVarRegionAxis()
  • buildSparseVarRegionAxis()
  • buildVarRegion()
  • buildSparseVarRegion()
  • buildVarRegionList()
  • buildSparseVarRegionList()
  • VarData_calculateNumShorts()
  • VarData_CalculateNumShorts()
  • VarData_optimize()
  • buildVarData()
  • buildVarStore()
  • buildMultiVarData()
  • buildMultiVarStore()
  • buildVarIdxMap()
  • buildDeltaSetIndexMap()
  • buildVarDevTable()
• cff
  • addCFFVarStore()
  • convertCFFtoCFF2()
  • conv_to_int()
  • get_private()
  • merge_PrivateDicts()
  • getfd_map()
  • CVarData
  • merge_region_fonts()
  • merge_charstrings()
  • CFFToCFF2OutlineExtractor
  • MergeOutlineExtractor
  • CFF2CharStringMergePen
• errors
  • VarLibError
  • VarLibValidationError
  • VarLibMergeError
  • ShouldBeConstant
  • FoundANone
  • NotANone
  • MismatchedTypes
  • LengthsDiffer
  • KeysDiffer
  • InconsistentGlyphOrder
  • InconsistentExtensions
  • UnsupportedFormat
  • InconsistentFormats
  • VarLibCFFMergeError
  • VarLibCFFDictMergeError
  • VarLibCFFPointTypeMergeError
  • VarLibCFFHintTypeMergeError
  • VariationModelError
• featureVars
  • bit_count()
  • addFeatureVariations()
  • overlayFeatureVariations()
  • overlayBox()
  • cleanupBox()
  • addFeatureVariationsRaw()
  • buildGSUB()
  • makeSubstitutionsHashable()
  • ShifterVisitor
  • buildSubstitutionLookups()
  • buildFeatureVariations()
  • buildFeatureRecord()
  • buildFeatureVariationRecord()
  • buildFeatureTableSubstitutionRecord()
  • buildConditionTable()
  • findFeatureVariationRecord()
  • sortFeatureList()
  • remapFeatures()
• instancer
  • AxisRange()
  • NormalizedAxisRange()
  • AxisTriple
  • NormalizedAxisTriple
  • NormalizedAxisTripleAndDistances
  • AxisLimits
  • NormalizedAxisLimits
  • OverlapMode
  • instantiateVARC()
  • instantiateTupleVariationStore()
  • changeTupleVariationsAxisLimits()
  • changeTupleVariationAxisLimit()
  • instantiateCFF2()
  • instantiateGvarGlyph()
  • instantiateGvar()
  • setCvarDeltas()
  • instantiateCvar()
  • setMvarDeltas()
  • verticalMetricsKeptInSync()
  • instantiateMVAR()
  • instantiateHVAR()
  • instantiateVVAR()
  • instantiateItemVariationStore()
  • instantiateOTL()
  • instantiateAvar()
  • isInstanceWithinAxisRanges()
  • instantiateFvar()
  • instantiateSTAT()
  • axisValuesFromAxisLimits()
  • setMacOverlapFlags()
  • normalize()
  • sanityCheckVariableTables()
  • instantiateVariableFont()
  • setRibbiBits()
  • parseLimits()
  • parseArgs()
  • main()
• interpolatable
  • Glyph
  • test_gen()
  • test()
  • recursivelyAddGlyph()
  • ensure_parent_dir()
  • main()
• interpolate_layout
  • interpolate_layout()
  • main()
• iup
  • iup_segment()
  • iup_contour()
  • iup_delta()
  • can_iup_in_between()
  • iup_contour_optimize()
  • iup_delta_optimize()
• merger
  • Merger
  • AligningMerger
  • InstancerMerger
  • MutatorMerger
  • VariationMerger
  • buildVarDevTable()
  • COLRVariationMerger
• models
  • normalizeValue()
  • normalizeLocation()
  • supportScalar()
  • piecewiseLinearMap()
  • VariationModel
• mutator
  • interpolate_cff2_PrivateDict()
  • interpolate_cff2_charstrings()
  • interpolate_cff2_metrics()
  • instantiateVariableFont()
  • main()
• mvar
  • fontTools.varLib.mvar.MVAR_ENTRIES
• plot
  • stops()
  • plotLocations()
  • plotDocument()
  • plotModelFromMasters()
  • main()
• varStore
  • bit_count()
  • OnlineVarStoreBuilder
  • VarData_addItem()
  • VarRegion_get_support()
  • VarStore___bool__()
  • VarStoreInstancer
  • VarStore_subset_varidxes()
  • VarStore_prune_regions()
  • Object_collect_device_varidxes()
  • Object_remap_device_varidxes()
  • VarStore_optimize()
  • main()

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.

Module for dealing with ‘gvar’-style font variations, also known as run-time interpolation.

The ideas here are very similar to MutatorMath. There is even code to read MutatorMath .designspace files in the varLib.designspace module.

For now, if you run this file on a designspace file, it tries to find ttf-interpolatable files for the masters and build a variable-font from them. Such ttf-interpolatable and designspace files can be generated from a Glyphs source, eg., using noto-source as an example:

$ fontmake -o ttf-interpolatable -g NotoSansArabic-MM.glyphs

Then you can make a variable-font this way:

$ fonttools varLib master_ufo/NotoSansArabic.designspace

API will change in near future.

fontTools.varLib.load_designspace(designspace, log_enabled=True, *, require_sources=True)

fontTools.varLib.set_default_weight_width_slant(font, location)

fontTools.varLib.drop_implied_oncurve_points(*masters: TTFont) → int

Drop impliable on-curve points from all the simple glyphs in masters.

In TrueType glyf outlines, on-curve points can be implied when they are located exactly at the midpoint of the line connecting two consecutive off-curve points.

The input masters’ glyf tables are assumed to contain same-named glyphs that are interpolatable. Oncurve points are only dropped if they can be implied for all the masters. The fonts are modified in-place.

Parameters:

masters – The TTFont(s) to modify

Returns:

The total number of points that were dropped if any.

Reference: https://developer.apple.com/fonts/TrueType-Reference-Manual/RM01/Chap1.html

fontTools.varLib.build_many(designspace: ~fontTools.designspaceLib.DesignSpaceDocument, master_finder=<function <lambda>>, exclude=[], optimize=True, skip_vf=<function <lambda>>, colr_layer_reuse=True, drop_implied_oncurves=False)

Build variable fonts from a designspace file, version 5 which can define several VFs, or version 4 which has implicitly one VF covering the whole doc.

If master_finder is set, it should be a callable that takes master filename as found in designspace file and map it to master font binary as to be opened (eg. .ttf or .otf).

skip_vf can be used to skip building some of the variable fonts defined in the input designspace. It’s a predicate that takes as argument the name of the variable font and returns bool.

Always returns a Dict[str, TTFont] keyed by VariableFontDescriptor.name

fontTools.varLib.build(designspace, master_finder=<function <lambda>>, exclude=[], optimize=True, colr_layer_reuse=True, drop_implied_oncurves=False)

Build variation font from a designspace file.

If master_finder is set, it should be a callable that takes master filename as found in designspace file and map it to master font binary as to be opened (eg. .ttf or .otf).

fontTools.varLib.load_masters(designspace, master_finder=<function <lambda>>)

Ensure that all SourceDescriptor.font attributes have an appropriate TTFont object loaded, or else open TTFont objects from the SourceDescriptor.path attributes.

The paths can point to either an OpenType font, a TTX file, or a UFO. In the latter case, use the provided master_finder callable to map from UFO paths to the respective master font binaries (e.g. .ttf, .otf or .ttx).

Return list of master TTFont objects in the same order they are listed in the DesignSpaceDocument.

class fontTools.varLib.MasterFinder(template)

Bases: object

fontTools.varLib.addGSUBFeatureVariations(vf, designspace, featureTags=(), *, log_enabled=False)

Add GSUB FeatureVariations table to variable font, based on DesignSpace rules.

Parameters:

• vf – A TTFont object representing the variable font.

• designspace – A DesignSpaceDocument object.

• featureTags – Optional feature tag(s) to use for the FeatureVariations records. If unset, the key ‘com.github.fonttools.varLib.featureVarsFeatureTag’ is looked up in the DS <lib> and used; otherwise the default is ‘rclt’ if the <rules processing=”last”> attribute is set, else ‘rvrn’. See <https://fonttools.readthedocs.io/en/latest/designspaceLib/xml.html#rules-element>

• log_enabled – If True, log info about DS axes and sources. Default is False, as the same info may have already been logged as part of varLib.build.

fontTools.varLib.main(args=None)

Build variable fonts from a designspace file and masters