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. |