Calculate Engraving Defaults

Calculate engraving defaults from glyph contours.

This script calculates and sets attribute values for the EngravingDefaults class based on glyph dimensions, registration, metrics, and point placement.

It offers options to override automatic contour measurements and reassign attributes to different ruler functions or glyphs. Refer to ENGRAVING_DEFAULTS_MAPPING for a comprehensive list of attributes and their default corresponding glyphs and assigned ruler functions.

Note

The setting for textFontFamily must be set manually within the override parameter.

The script requires SMufoLib to be installed in its execution environment. It can be used from the command line or as a Python module. See the Command Line Interface and Python API sections below for usage details.

Changed in version 0.5.0: The referenceIndex parameter has been removed from all ruler functions and is no longer needed when providing remappings.

The ruler functions have been removed from this script and are now available in the rulers module.

Command Line Interface

$ calculate-engraving-defaults <font> [-o <override>] [-r <remap>] [-e <attributes> ...] [-s] [-v]

Positional Arguments

<font>

Path to font file or font object.

Options

-o <override>, --override <override>

JSON string of attributes and values to manually override, in the format:

'{"<attributeName>": <value>, ...}'
-r <remap>, --remap <remap>

JSON string of ruler and glyph remappings, in the format:

'{"<attribute name>": {"ruler": "<functionName>", "glyph": "<glyphName>"}, ...}'
-e <attributes>..., --exclude <attributes>...

List of attributes to exclude from calculation.

-s, --spaces

Whether values for overrides are given in staff spaces instead of font units.

-v, --verbose

Make output verbose.

Python API

>>> from bin.calculateEngravingDefaults import calculateEngravingDefaults
>>> calculateEngravingDefaults("path/to/MyFont.ufo", override={"staffSpace": 0.25})
calculateEngravingDefaults(font: Font | Path | str, exclude: tuple[str] | list[str] | None = None, override: dict[str, int | float | tuple[str, ...] | None] | None = None, remap: dict[str, dict[str, str]] | None = None, spaces: bool = False, verbose: bool = False) → None[source]

Calculate engraving defaults from glyph contours (Python API).

Parameters:

  • font – Target Font object or path to font file.

  • exclude – EngravingDefaults attributes to exclude. Defaults to None.

  • override – EngravingDefaults attributes to manually override mapped to their values. Defaults to None.

  • remap –

    EngravingDefaults attributes mapped to remappings dict, e.g.:

    r = {
    "arrowShaftThickness": {
        "ruler": "glyphBoundsXMinAbs",
        "glyph": "uniEB60"
    }
}

    Defaults to None.

  • spaces – Whether values for overrides are given in staff spaces instead of font units. Defaults to False.

  • verbose – Make output verbose. Defaults to False.

Raises:

  • TypeError – If any parameter value is not the expected type.

  • ValueError – If any parameter value item is not the expected type or value.

Check Anchors

Check SMuFL glyph anchors against reference font metadata.

This script checks font anchors against reference font metadata, identifying missing or superfluous glyph anchors according to the SMuFL standard.

Discrepancies are printed to console, and glyphs may be marked with a specified color value. Glyphs without annotated smufl names or glyph names will be skipped.

The script requires SMufoLib to be installed in its execution environment. It can be used from the command line or as a Python module. See the Command Line Interface and Python API sections below for usage details.

Command Line Interface

$ check-anchors <font> [<fontData>] [-m] [-c <color>] [-v]

Positional Arguments

<font>

Path to the font file to check.

Options

-F <font-data>, --font-data <font-data>

Path to the reference font data file. Defaults to metadata.paths.font, falling back to metadata.fallbacks.font if the former is unavailable.

-m, --mark

Mark discrepant glyphs in the font with the color specified by --color.

-c <r> <g> <b> <a>, --color <r> <g> <b> <a>

RGBA color to use for marking glyphs. Only used when --mark is set. Defaults to color.marks.mark1.

-v, --verbose

Make output verbose.

Python API

>>> from bin.checkAnchors import checkAnchors
>>> checkAnchors("path/to/MyFont.ufo", mark=True)
checkAnchors(font, fontData=Request(CONFIG['metadata.paths']['font'], CONFIG['metadata.fallbacks']['font']), mark=False, color=None, verbose=False)[source]

Check font anchors against SMuFL reference data (Python API).

Parameters:
Raises:

TypeError – If any parameter value is not the expected type or if mark is True while color is None.

Clean Font

Remove SMuFL font data.

Warning

This script will permanently delete data. Always back up your font file before use.

This script deletes SMuFL-specific metadata and glyph anchors from a UFO font file.

The following attribute and anchor names may be specified for inclusion or exclusion:

Attributes

  • designSize

  • sizeRange

  • engravingDefaults

  • name

  • classes

  • description

  • spaces

Anchors

  • splitStemUpSE

  • splitStemUpSW

  • splitStemDownNE

  • splitStemDownNW

  • stemUpSE

  • stemDownNW

  • stemUpNW

  • stemDownSW

  • nominalWidth

  • numeralTop

  • numeralBottom

  • cutOutNE

  • cutOutSE

  • cutOutSW

  • cutOutNW

  • graceNoteSlashSW

  • graceNoteSlashNE

  • graceNoteSlashNW

  • graceNoteSlashSE

  • repeatOffset

  • noteheadOrigin

  • opticalCenter

The script requires SMufoLib to be installed in its execution environment. It can be used from the command line or as a Python module. See the Command Line Interface and Python API sections below for usage details.

Command Line Interface

$ clean-font <font> [-v]

Positional Arguments

<font>

Path to the font file to clean.

Options

-i, --include <items>...

Specify items to delete. May be * (all), or one or more specified attribute or anchor names (required).

-e, --exclude <items>...

Specify items to preserve if --include is * (all). If omitted, all matching items will be deleted.

-v, --verbose

Make output verbose.

Use --include and/or --exclude to specify which items to delete or preserve.

To prevent accidental data loss, you must explicitly define what to remove. A wildcard (--include *) will remove all known SMuFL-related data from the font, unless exclusions are specified.

See the list of valid attribute and anchor names in the introduction above.

Python API

>>> from bin.cleanFont import cleanFont
>>> cleanFont("path/to/MyFont.ufo", include=["anchors", "guidelines"])
cleanFont(font: Font | Path | str, include: Iterable, exclude: Iterable | None = None, verbose: bool = False)[source]

Delete Smufl-specific attribute values (Python API).

Use the include and exclude keyword arguments to control which attributes and anchors are removed.

To avoid unintentional data loss, include must be specified. Setting include="*" will delete all SMuFL metadata and anchors.

Refer to the list of valid keys in the main docstring.

Parameters:

  • font – Target Font object or path to font file.

  • include – Items to be deleted. May be "*" (all), an individual attribute or anchor name as a str or tuple of several.

  • exclude – Items to be preserved if ìnclude="*". Defaults to None.

  • verbose – Make output verbose. Defaults to False.

Raises:

  • TypeError – If any parameter value is not the expected type.

  • ValueError – If any item in include or exclude is invalid.

Generate metadata

Generate font metadata JSON file.

This script generates a full featured metadata JSON file for SMuFL fonts from metadata sources and user specifications, including the following metadata sections:

Sections are automatically added depending on the font’s scope and assigned attribute values.

Tip

As a starting point, identification and engraving defaults attributes may be set automatically with the importID and calculateEngravingDefaults scripts respectively.

Glyphs outside the SMuFL range as well as unencoded or unnamed glyphs, are automatically skipped.

The script requires SMufoLib to be installed in its execution environment. It can be used from the command line or as a Python module. See the Command Line Interface and Python API sections below for usage details.

Command Line Interface

$ generate-metadata <font> [<targetPath>] [-f <fontData>] [-v]

Positional Arguments

<font>

Path to the font file to generate metadata for.

Options

<target-path>

Path to the target file to write the metadata to. Defaults to the font file’s path with a .json extension.

-f <font-data>, --font-data <font-data>

Path to the reference font data file. Defaults to metadata.paths.font, falling back to metadata.fallbacks.font if the former is unavailable.

-v, --verbose

Make output verbose.

Python API

>>> from bin.generateMetadata import generateMetadata
>>> generateMetadata("path/to/MyFont.ufo", targetPath="path/to/metadata.json")
generateMetadata(font, targetPath, fontData=Request(CONFIG['metadata.paths']['font'], CONFIG['metadata.fallbacks']['font']), verbose=False)[source]

Generate font metadata JSON file (Python API).

Parameters:

  • font – Source Font object or path to font file.

  • targetPath – Target directory for Metadata JSON file.

  • fontData – Request for or path to reference font metadata file. Defaults to Request passing metadata.paths.font and metadata.fallbacks.font.

  • verbose – Make output verbose. Defaults to False.

Raises:

Import Anchors

Import anchors from font metadata.

This script sets glyph anchors based on data from a SMuFL font metadata JSON file (SMuFL’s reference font, Bravura, by default).

The script requires SMufoLib to be installed in its execution environment. It can be used from the command line or as a Python module. See the Command Line Interface and Python API sections below for usage details.

Command Line Interface

$ import-anchors <font> [<fontData>] [-m] [-c <color>] [-C] [-v]

Positional Arguments

<font>

Path to the font file to import anchors into.

Options

-F <font-data>, --font-data <font-data>

Path to the reference font data file. Defaults to metadata.paths.font, falling back to metadata.fallbacks.font if the former is unavailable.

-m, --mark

Mark imported anchors in the font with the color specified by --color.

-c <r> <g> <b> <a>, --color <r> <g> <b> <a>

RGBA color to use for marking anchors. Only used when --mark is set. Defaults to color.anchors.

-x, --clear

Clear existing anchors before importing new ones.

-v, --verbose

Make output verbose.

Python API

>>> from bin.importAnchors import importAnchors
>>> importAnchors("path/to/MyFont.ufo")
importAnchors(font, fontData=Request(CONFIG['metadata.paths']['font'], CONFIG['metadata.fallbacks']['font']), mark=True, colors=CONFIG['color.anchors'], clear=False, verbose=False)[source]

Import anchors from font metadata (Python API).

Parameters:

  • font – Target Font object or path to font file.

  • fontData – Request for or path to reference font metadata file. Defaults to Request passing metadata.paths.font and metadata.fallbacks.font.

  • mark – Apply defined anchor colors. Defaults to True.

  • colors – dict of anchorNames mapped to UFO color values to apply when mark is True. Defaults to color.anchors.

  • clear – Erase preexisting anchors on append. Defaults to False.

  • verbose – Make output verbose. Defaults to False.

Raises:

Import ID

Import SMuFL identification attributes.

This script imports Smufl identification attribute values for all glyphs in a SMufoLib Font from metadata files. More specifically, it automatically sets the values for Smufl.name, Smufl.description and/or Smufl.classes, based on the official metadata files of SMuFL and Bravura, or any other compatible sources.

The script supports importing optional glyphs and controlling whether existing data is overwritten. Glyphs are skipped if they are not valid SMuFL members or if their metadata cannot be found.

The script requires SMufoLib to be installed in its execution environment. It can be used from the command line or as a Python module. See the Command Line Interface and Python API sections below for usage details.

Command Line Interface

$ import-id <font> [<attributes>] [<classesData>] [<glyphnamesData>] [<fontData>] [-o] [-v]

Positional Arguments

<font>

Path to the font file to import ID data into.

Options

-a <attributes>..., --attributes <attributes>...
ID attributes to be set. Value can be either * (all),

name, classes, description or tuple of several. Defaults to *.

-C <classes-data>, --classes-data <classes-data>

Path to the classes data file. Defaults to metadata.paths.classes, falling back to metadata.fallbacks.classes if the former is unavailable.

-G <glyphnames-data>, --glyphnames-data <glyphnames-data>

Path to the glyph names data file. Defaults to metadata.paths.glyphnames, falling back to metadata.fallbacks.glyphnames if the former is unavailable.

-F <font-data>, --font-data <font-data>

Path to the font data file. Defaults to metadata.paths.font, falling back to metadata.fallbacks.font if the former is unavailable.

-i, --include-optionals

Include optional glyphs in the import.

-o, --overwrite

Overwrite existing attributes with the same name. If not set, existing attributes will not be modified.

-v, --verbose

Make output verbose.

Optional glyphs can be included with the --include-optionals flag. When this option is used, stylistic alternates and ligatures must be named relative to their base glyph (see this note for more details).

By default, existing attribute values are preserved. To overwrite them, pass the --overwrite flag. Glyphs are also skipped if they are not part of the SMuFL range or if lookup fails (e.g., due to missing codepoints or unencoded glyphs in the metadata).

Python API

>>> from bin.importID import importID
>>> importID("path/to/MyFont.ufo", attributes=("classes", "description"))
importID(font, attributes, classesData=Request(CONFIG['metadata.paths']['classes'], CONFIG['metadata.fallbacks']['classes']), glyphnamesData=Request(CONFIG['metadata.paths']['glyphnames'], CONFIG['metadata.fallbacks']['glyphnames']), fontData=Request(CONFIG['metadata.paths']['font'], CONFIG['metadata.fallbacks']['font']), includeOptionals=False, overwrite=False, verbose=False)[source]

Import SMuFL identification attributes (Python API).

Optional glyphs can be included by setting includeOptionals to True. When enabled, stylistic alternates and ligatures must be named with reference to their base glyph (see this note for more details).

If overwrite is False, glyphs with existing attribute values are skipped. Glyphs are also skipped if they are not SMuFL members or if lookup fails (e.g., due to missing codepoints or unencoded glyphs in the metadata).

Parameters:
Raises:

  • TypeError – If any parameter value is not the expected type.

  • ValueError – If attributes value is not a valid ID attribute.