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
wghtorwdth) that the OpenType spec defines for registered axes, or a custom uppercase tag (likeXOPQ) 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 |