Skip to content

fontlab.flAxis

flAxis

What is a design axis?

A design axis is one dimension of variation in a variable font. Think of it as a slider. At one end of the slider lives one extreme of your design; at the other end lives the opposite extreme. As you drag the slider, the letterforms interpolate smoothly between those two extremes.

Some common axes and what they control:

Axis Tag Typical range What it does
Weight wght 100–900 Light ↔ Bold
Width wdth 50–200 Condensed ↔ Extended
Italic ital 0–1 Upright ↔ Italic
Slant slnt −90–0 Oblique angle
Optical Size opsz 6–144 Caption ↔ Display
Custom any any Whatever you design

Every axis has:

  • A 4-character tag (like wght or wdth) that the OpenType spec defines for registered axes, or a custom uppercase tag (like XOPQ) for private axes.
  • A name — the human-readable label shown in font editors and CSS ("Weight", "Width", etc.).
  • A numeric range: minimum, default, and maximum values.
  • An optional design-space vs user-space mapping for non-linear interpolation.

User space vs design space

Sometimes the numbers designers think in (user space) don't map linearly to the underlying interpolation math (design space). For example, a Weight axis might run from 100–900 in user space (CSS weight values), but internally the interpolation happens between masters at design-space values of 0–1000. The map property stores this piecewise-linear translation. If your axis is simple and linear, user space and design space are the same, and you don't need the map.

Tutorial

Axes are what turn a static font into a variable font. Here is how to read and manipulate axis definitions.

import fontlab as fl

# ============================================================
# Read all axes defined in the current font.
# ============================================================

font = fl.CurrentFont()
if not font.axes:
    print("This font has no axes — it is not a variable font.")
    raise SystemExit

print(f"Axes in '{font.fontName}':")
for axis in font.axes:
    print(f"  tag='{axis.tag}'  name='{axis.name}'")
    print(f"    min={axis.minimal}  default={axis.default}  max={axis.maximum}")
    print(f"    hidden={axis.hidden}  registered={axis.tag in ('wght','wdth','ital','slnt','opsz')}")

# ============================================================
# Create a new custom axis.
# ============================================================

from fontlab import flAxis
new_axis = flAxis()
new_axis.tag          = "XHGT"    # four uppercase letters = private axis
new_axis.name         = "X-Height"
new_axis.minimal  = 0
new_axis.default  = 100
new_axis.maximum  = 200
# font.axes.append(new_axis)   # uncomment to actually add it
print(f"\nNew axis prepared: {new_axis.tag} '{new_axis.name}' "
      f"[{new_axis.minimal}, {new_axis.default}, {new_axis.maximum}]")

# ============================================================
# Move to a specific location along an axis.
# ============================================================

loc = font.currentLocation()
print("\nCurrent location:")
for tag in loc:
    print(f"  {tag}: {loc[tag]}")

Common Scripting Patterns

Find an axis by tag

import fontlab as fl

font = fl.CurrentFont()
wght = next((a for a in font.axes if a.tag == "wght"), None)
if wght:
    print(f"Weight axis: {wght.minimal}–{wght.maximum}  default={wght.default}")

Check whether the font is a variable font

import fontlab as fl

font = fl.CurrentFont()
if font.axes:
    print(f"Variable font with {len(font.axes)} axis/axes: "
          + ", ".join(a.tag for a in font.axes))
else:
    print("Static font (no axes).")

Constructors: flAxis() - default flAxis(string name) flAxis(string name, string tag, string short_name)

Native bases: object

Captured native MRO: flAxis, 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 variation axis. The captured declaration exposes the attributes name, tag, shortName, minimal, default, maximum, designMin, designDef, designMax, hidden, map and playRange, and methods including checkValue, getRange, mappedValue, normalize, styleName, styleValue, valueWeight and valueWidth. It is created as flAxis(), flAxis(string name) or flAxis(string name, string tag, string short_name).

Source: FontLab Proteus API documentation

Source: generated/fontlab.py: flAxis 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)
_has_axis_name function (*args: Any, **kwargs: Any) -> Any Checks axis name uniqueness.
checkValue function (self, v: float) -> float Clamps v to the valid range [minimal, maximum].
default attribute Any The default user-space value.
designDef attribute Any The default value in internal design space
designMax attribute Any The maximum value in internal design space
designMin attribute Any The minimum value in internal design space.
extrapolate attribute Any Defaults to False.
getRange function (self) -> float Returns maximum − minimum.
hidden attribute Any When True, this axis is hidden from the user-facing axis list.
instanceIndex function (self, v: float) -> int Returns the index of the named instance nearest to the value v.
instances2map function (self) -> bool Builds the axis map by reading the current named instances.
instances2string function (self) -> Any Serializes the named-instance list to a compact string.
isWeight function (s: Any) -> bool Returns True if the string s matches the OpenType weight axis tag (wght).
isWidth function (s: Any) -> bool Returns True if s matches the OpenType width axis tag (wdth)
locationName function (axes: list[flAxis], location: flLocation) -> str Generates a human-readable name for a design-space location based on all the axis values it contains.
map attribute Any A piecewise-linear map from design-space values to user-space values.
map2instances function (self) -> bool Pushes the axis value map onto the named instances, updating each instance's stored axis value to its mapped equivalent
mappedValue function (self, v: float) -> float Applies the axis's design-to-user-space map to a raw design-space value, returning the corresponding user-space value
maximum attribute Any The maximum user-space value — the "heaviest" or "most extended" master
minimal attribute Any The minimum user-space value for this axis — the value at the "lightest" or "most condensed" master
name attribute Any The full axis name as it appears in Font Info, e.g.
normalize function (self, userValue: float) -> float Converts a user-space value to the OpenType normalized range: −1 at minimum, 0 at default, +1 at maximum.
onEdge function (self, v: float) -> bool Returns True if v equals exactly minimal or maximum — i.e., the value sits at one of the extreme ends of the axis range
playRange attribute Any (double, double)
shortName attribute Any A short display abbreviation, e.g.
string2instances function (self, s: Any) -> bool Parses instances from a compact string.
styleName function (self, v: float) -> Any Returns the name of the named instance that is closest to the value v on this axis
styleValue function (self, style_name: Any) -> float Returns the axis value associated with the named instance that has style_name as its name.
tag attribute Any The 4-character OpenType axis tag, e.g.
updateInstances function (self) -> None Refreshes the list of named instances to be consistent with the current axis range and mapping
updateShortName function (self) -> None Re-derives the short display name from the axis name.
updateTag function (self) -> None Re-derives the 4-letter OpenType tag from the axis name.
valueWeight function (location: flLocation, value: float) -> float Maps a raw weight axis value to its CSS font-weight equivalent (100–900 scale).
valueWidth function (location: flLocation, value: float) -> float Maps a raw width axis value to its CSS font-stretch percentage equivalent