Skip to content

fontlab.flInstance

flInstance

What is a named instance?

A named instance is a preset — a specific location in design space that you've given a name to, like "Regular", "Bold", "Light Italic", or "SemiBold Condensed". Named instances are the styles that end users see in their font menu when they install your variable font. They're also what get exported as separate font files when you generate a family of static fonts from your variable font source.

Each named instance has: - A name (the style name the user sees) - A location (where it sits on all your axes, as an flLocation dict) - Export flags (should it be included when you export?) - Style-linking values (is this the bold of another style? The italic?) - Typographic naming (how it fits into OpenType name table entries)

For example, in a Weight+Width variable font, you might have instances at: - Regular: {wght: 400, wdth: 100} - Bold: {wght: 700, wdth: 100} - Condensed: {wght: 400, wdth: 75} - Bold Condensed: {wght: 700, wdth: 75}

Tutorial

import fontlab as fl
from fontlab import flAxis, flInstance, flLocation

font = fl.CurrentFont()

# ============================================================
# 1. Inspecting existing axes
# ============================================================
# Start by seeing what axes are already defined in your font.
# Most variable fonts have at least one — probably Weight.

print("Design axes:")
for axis in font.axes:
    print(f"  '{axis.name}'  tag={axis.tag}  "
          f"min={axis.minimal}  "
          f"default={axis.default}  "
          f"max={axis.maximum}  "
          f"range={axis.getRange()}")

# ============================================================
# 2. Creating a new Weight axis
# ============================================================
# Here we build a weight axis from scratch and add it to the font.
# The tag "wght" is the registered OpenType tag for weight.

wt_axis = flAxis()
wt_axis.name    = "Weight"
wt_axis.tag     = "wght"
wt_axis.minimal  = 100      # the lightest extreme (Thin)
wt_axis.default  = 400      # Regular — the "zero" of the normalized range
wt_axis.maximum  = 900      # the heaviest extreme (Black)

# After setting the name, you can ask FontLab to re-derive the tag:
wt_axis.updateTag()

font.addAxis(wt_axis)
print(f"Added axis '{wt_axis.name}' ({wt_axis.tag})")

# ============================================================
# 3. Normalizing a value
# ============================================================
# The normalize() method converts a user-space value to the
# normalized range: -1 at min, 0 at default, +1 at max.
# This is the range that OpenType interpolation actually uses.

print(f"400 normalized: {wt_axis.normalize(400):.2f}")   # 0.0  (default)
print(f"700 normalized: {wt_axis.normalize(700):.2f}")   # ~0.6
print(f"100 normalized: {wt_axis.normalize(100):.2f}")   # -1.0 (min)
print(f"900 normalized: {wt_axis.normalize(900):.2f}")   # 1.0  (max)

# ============================================================
# 4. Checking and clamping values
# ============================================================

# Is a value at the edge of the axis range?
print("On edge (100):", wt_axis.onEdge(100))    # True
print("On edge (400):", wt_axis.onEdge(400))    # False

# Clamp an out-of-range value:
clamped = wt_axis.checkValue(1200)
print(f"Clamped 1200 → {clamped}")              # 900

# ============================================================
# 5. Inspecting existing named instances
# ============================================================
# Named instances are the "presets" visible in font menus.

print("\nNamed instances:")
for inst in font.instances:
    print(f"  '{inst.name}'  "
          f"location={dict(inst.location)}  "
          f"exportable={inst.exportable}  "
          f"bold={inst.bold}  italic={inst.italic}")

# ============================================================
# 6. Creating named instances
# ============================================================
# Add instances for Light, Regular, Semibold, and Bold.

instance_specs = [
    ("Light",    300, False, False),
    ("Regular",  400, False, False),
    ("Semibold", 600, False, False),
    ("Bold",     700, True,  False),
]

for inst_name, wght_val, is_bold, is_italic in instance_specs:
    inst = flInstance()
    inst.name     = inst_name
    inst.bold     = is_bold
    inst.italic   = is_italic
    inst.exportable = True

    # Build the location (where this instance sits in design space)
    loc = flLocation()
    loc["wght"] = wght_val
    inst.location = loc

    font.addInstance(inst)
    print(f"  Added instance '{inst.name}' at wght={wght_val}")

# ============================================================
# 7. Auto-generating style names from the OS/2 table
# ============================================================
# FontLab can auto-compute style names and linking values for you.

bold_inst = font.instances[-1]       # the Bold instance we just added
print("Auto TSN:", bold_inst.autoTSN())
print("Auto SLV:", bold_inst.autoSLV())

# ============================================================
# 8. Finding an instance by axis value
# ============================================================
# Use instanceIndex and styleName to look up instances by value.

idx  = wt_axis.instanceIndex(700)
name = wt_axis.styleName(700)
print(f"Nearest instance to wght=700: index={idx}  name='{name}'")

# And the reverse: what value does "Regular" correspond to?
val = wt_axis.styleValue("Regular")
print(f"'Regular' is at wght={val}")

# ============================================================
# 9. Generating a human-readable location name
# ============================================================

loc = flLocation()
loc["wght"] = 700
loc_name = flAxis.locationName(list(font.axes), loc)
print(f"Location name: '{loc_name}'")     # e.g. "Bold"

# ============================================================
# 10. Updating axis tags and short names
# ============================================================

wt_axis.updateTag()
wt_axis.updateShortName()
print(f"Tag: {wt_axis.tag}  ShortName: {wt_axis.shortName}")

fl.Update()

Common Scripting Patterns

Print a full instance summary

# Print every instance with its full location and naming info.
import fontlab as fl

font = fl.CurrentFont()
print(f"{'Name':<25} {'Location':<35} {'Export'}")
print("-" * 65)
for inst in font.instances:
    loc_str = ", ".join(
        f"{k}={float(v):.0f}" for k, v in inst.location.items()
    )
    print(f"{inst.name:<25} {loc_str:<35} {inst.exportable}")

Add a second axis (Width) to an existing variable font

import fontlab as fl
from fontlab import flAxis

font = fl.CurrentFont()

wd_axis = flAxis()
wd_axis.name    = "Width"
wd_axis.tag     = "wdth"
wd_axis.minimal  = 75
wd_axis.default  = 100
wd_axis.maximum  = 125
font.addAxis(wd_axis)
fl.Update()

Mark all instances as exportable

import fontlab as fl
font = fl.CurrentFont()
for inst in font.instances:
    inst.exportable = True
fl.Update()

Find which instances are on the edge of any axis

# Identify instances that sit at the min or max of at least one axis.
# These are typically the "extreme" masters or corner instances.
import fontlab as fl

font = fl.CurrentFont()
axes_by_tag = {a.tag: a for a in font.axes}

for inst in font.instances:
    for tag, val in inst.location.items():
        if tag in axes_by_tag:
            axis = axes_by_tag[tag]
            if axis.onEdge(float(val)):
                print(f"'{inst.name}' is at the edge of axis '{tag}'")
                break

Normalize all instance locations

# Print the normalized axis values for every instance.
# These are the values that OpenType actually interpolates.
import fontlab as fl

font = fl.CurrentFont()
axes_by_tag = {a.tag: a for a in font.axes}

for inst in font.instances:
    norm_vals = {}
    for tag, val in inst.location.items():
        if tag in axes_by_tag:
            norm_vals[tag] = round(axes_by_tag[tag].normalize(float(val)), 3)
    print(f"'{inst.name}': {norm_vals}")

Constructors: flInstance() flInstance(string name, string tsn, flLocation location)

Native bases: object

Captured native MRO: flInstance, object

Native new allocation evidence (not an init overload): (args, *kwargs) Create and return a new object. See help(type) for accurate signature.

Supplemental documentation: A font instance with the string attributes name, sgn, tsn, weight and width, the bool attributes bold, exportable and italic, the numeric attributes slv (int) and weightValue (double), and a location attribute. The captured declaration exposes autoSGN, autoSLV, autoTSN and setSLV. It is created as flInstance() or as flInstance(name, tsn, location).

Source: FontLab Proteus API documentation

Source: generated/fontlab.py: flInstance captured declaration

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
__init__ function (self, /, *args: Any, **kwargs: Any) -> None Initialize self. (shared captured text)
autoSGN function (self, *args: Any, **kwargs: Any) -> Any Auto-generates the Style Group Name from the typographic family name tfn.
autoSLV function (self) -> int Auto-computes the OS/2 fsSelection style-linking value (the byte that encodes bold/italic/regular).
autoTSN function (self) -> Any Auto-generates the Typographic Subfamily Name (the name table entry 2 equivalent) based on this instance's axis values and style flags
bold attribute Any True if this instance is the "bold" of a style-linking pair.
exportable attribute Any When True, this instance is included when you export font files.
italic attribute Any True if this instance is italic.
location attribute Any The full design-space location of this instance — a mapping from axis tags to values.
name attribute Any Internal instance name; use tsn for the displayed style name
setSLV function (self, bold: bool, italic: bool) -> Any Set the style-linking values directly by specifying whether this instance should be considered the bold and/or italic variant of a nearby style
sgn attribute Any Style Group Name — used for grouping instances into families in Windows font menus
slv attribute Any The OS/2 style-linking value as a raw integer.
tfn attribute Any String: family override; empty inherits the source family
tsn attribute Any Typographic Subfamily Name.
weight attribute Any A human-readable weight descriptor string, e.g.
weightValue attribute Any The numeric weight value for this instance on the weight axis (e.g.
width attribute Any A human-readable width descriptor string, e.g.