# featureVars

Module to build FeatureVariation tables: https://docs.microsoft.com/en-us/typography/opentype/spec/chapter2#featurevariations-table

NOTE: The API is experimental and subject to change.

fontTools.varLib.featureVars.addFeatureVariations(font, conditionalSubstitutions, featureTag='rvrn')

  Add conditional substitutions to a Variable Font.

  The conditionalSubstitutions argument is a list of (Region, Substitutions) tuples.

  A Region is a list of Boxes. A Box is a dict mapping axisTags to (minValue, maxValue) tuples. Irrelevant axes may be omitted and they are interpretted as extending to end of axis in each direction. A Box represents an orthogonal ‘rectangular’ subset of an N-dimensional design space. A Region represents a more complex subset of an N-dimensional design space, ie. the union of all the Boxes in the Region. For efficiency, Boxes within a Region should ideally not overlap, but functionality is not compromised if they do.

  The minimum and maximum values are expressed in normalized coordinates.

  A Substitution is a dict mapping source glyph names to substitute glyph names.

  Example:

  # >>> f = TTFont(srcPath) # >>> condSubst = [ # … # A list of (Region, Substitution) tuples. # … ([{“wdth”: (0.5, 1.0)}], {“cent”: “cent.rvrn”}), # … ([{“wght”: (0.5, 1.0)}], {“dollar”: “dollar.rvrn”}), # … ] # >>> addFeatureVariations(f, condSubst) # >>> f.save(dstPath)

fontTools.varLib.featureVars.addFeatureVariationsRaw(font, table, conditionalSubstitutions, featureTag='rvrn')

  Low level implementation of addFeatureVariations that directly models the possibilities of the FeatureVariations table.

fontTools.varLib.featureVars.buildConditionTable(axisIndex, filterRangeMinValue, filterRangeMaxValue)

  Build a ConditionTable.

fontTools.varLib.featureVars.buildFeatureRecord(featureTag, lookupListIndices)

  Build a FeatureRecord.

fontTools.varLib.featureVars.buildFeatureTableSubstitutionRecord(featureIndex, lookupListIndices)

  Build a FeatureTableSubstitutionRecord.

fontTools.varLib.featureVars.buildFeatureVariationRecord(conditionTable, substitutionRecords)

  Build a FeatureVariationRecord.

fontTools.varLib.featureVars.buildFeatureVariations(featureVariationRecords)

  Build the FeatureVariations subtable.

fontTools.varLib.featureVars.buildGSUB()

  Build a GSUB table from scratch.

fontTools.varLib.featureVars.buildSubstitutionLookups(gsub, allSubstitutions)

  Build the lookups for the glyph substitutions, return a dict mapping the substitution to lookup indices.

fontTools.varLib.featureVars.cleanupBox(box)

  Return a sparse copy of box, without redundant (default) values.

      >>> cleanupBox({})
      {}
      >>> cleanupBox({'wdth': (0.0, 1.0)})
      {'wdth': (0.0, 1.0)}
      >>> cleanupBox({'wdth': (-1.0, 1.0)})
      {}

fontTools.varLib.featureVars.makeSubstitutionsHashable(conditionalSubstitutions)

  Turn all the substitution dictionaries in sorted tuples of tuples so they are hashable, to detect duplicates so we don’t write out redundant data.

fontTools.varLib.featureVars.overlayBox(top, bot)

  Overlays `top` box on top of `bot` box.

  Returns two items:

  - Box for intersection of `top` and `bot`, or None if they don’t intersect.

  - Box for remainder of `bot`. Remainder box might not be exact (since the remainder might not be a simple box), but is inclusive of the exact remainder.

fontTools.varLib.featureVars.overlayFeatureVariations(conditionalSubstitutions)

  Compute overlaps between all conditional substitutions.

  The conditionalSubstitutions argument is a list of (Region, Substitutions) tuples.

  A Region is a list of Boxes. A Box is a dict mapping axisTags to (minValue, maxValue) tuples. Irrelevant axes may be omitted and they are interpretted as extending to end of axis in each direction. A Box represents an orthogonal ‘rectangular’ subset of an N-dimensional design space. A Region represents a more complex subset of an N-dimensional design space, ie. the union of all the Boxes in the Region. For efficiency, Boxes within a Region should ideally not overlap, but functionality is not compromised if they do.

  The minimum and maximum values are expressed in normalized coordinates.

  A Substitution is a dict mapping source glyph names to substitute glyph names.

  Returns data is in similar but different format. Overlaps of distinct substitution Boxes (not Regions) are explicitly listed as distinct rules, and rules with the same Box merged. The more specific rules appear earlier in the resulting list. Moreover, instead of just a dictionary of substitutions, a list of dictionaries is returned for substitutions corresponding to each unique space, with each dictionary being identical to one of the input substitution dictionaries. These dictionaries are not merged to allow data sharing when they are converted into font tables.

  Example:

      >>> condSubst = [
      ...     # A list of (Region, Substitution) tuples.
      ...     ([{"wght": (0.5, 1.0)}], {"dollar": "dollar.rvrn"}),
      ...     ([{"wght": (0.5, 1.0)}], {"dollar": "dollar.rvrn"}),
      ...     ([{"wdth": (0.5, 1.0)}], {"cent": "cent.rvrn"}),
      ...     ([{"wght": (0.5, 1.0), "wdth": (-1, 1.0)}], {"dollar": "dollar.rvrn"}),
      ... ]
      >>> from pprint import pprint
      >>> pprint(overlayFeatureVariations(condSubst))
      [({'wdth': (0.5, 1.0), 'wght': (0.5, 1.0)},
        [{'dollar': 'dollar.rvrn'}, {'cent': 'cent.rvrn'}]),
       ({'wdth': (0.5, 1.0)}, [{'cent': 'cent.rvrn'}]),
       ({'wght': (0.5, 1.0)}, [{'dollar': 'dollar.rvrn'}])]

fontTools.varLib.featureVars.popCount(self, /)

  Number of ones in the binary representation of the absolute value of self.

  Also known as the population count.

      >>> bin(13)
      '0b1101'
      >>> (13).bit_count()
      3

fontTools.varLib.featureVars.remapFeatures(table, featureRemap)

  Go through the scripts list, and remap feature indices.

fontTools.varLib.featureVars.sortFeatureList(table)

  Sort the feature list by feature tag, and remap the feature indices elsewhere. This is needed after the feature list has been modified.