Skip to content

fontlab.flGuideLine

flGuideLine

What is a guideline?

Guidelines are the non-printing reference lines you draw across your canvas to help align things. They are the blue (or custom-colored) lines that mark cap height, x-height, descender, optical margins, stem axes, and any other alignment target you care about.

FontLab has two scopes of guidelines:

  • Font-level guidelines live in flPackage.guidelines. They appear in every glyph you open — they are global to the whole font. These are perfect for metrics references like ascender, cap height, x-height, descender, and baseline, because those values are relevant to every glyph.

  • Glyph-level guidelines live in flLayer.guidelines. They only appear when that specific glyph (and layer) is open in the editor. Use these for glyph-specific construction lines, like the exact center of a capital O, or the shoulder angle on a lowercase n.

Beyond simple horizontal and vertical lines, guidelines can be:

  • Angled — any angle in degrees. Useful for italic slant guides or diagonal construction lines.
  • Expression-based — a guideline whose position is tied to a font metric by a formula, like "=xHeight". If you change xHeight, the guideline moves with it automatically.
  • Power guides — guidelines that FontLab auto-generates from the extremes of your outlines. They snap to the tops, bottoms, and sides of your contours, making it easy to align multiple glyphs to common optical heights.

What is flSnapLine?

flSnapLine is the technical base class that handles all the snap and measurement geometry — the center node, the vector node, the snap flags, and the distance/offset math. You rarely need to interact with flSnapLine directly; flGuideLine inherits everything from it and adds the extra features (color, tags, style, expressions) that you'll actually use. Think of flSnapLine as the engine and flGuideLine as the car.

Tutorial

from PythonQt.QtCore import QPointF
from PythonQt.QtGui import QColor
import fontlab as fl
from fontlab import flGuideLine

font  = fl.CurrentFont()
glyph = font['H']
layer = glyph.layers[0]

# ============================================================
# 1. Font-level (global) guidelines
# ============================================================
# Font-level guidelines appear in every glyph. They're ideal for
# shared metrics references like cap height, ascender, x-height,
# and descender. Add them once and they show up everywhere.

# Create a horizontal guideline at y = 700 (cap height reference).
# angle=0 means horizontal; the QPointF gives the position.
h_guide = flGuideLine(0.0, QPointF(0, 700))
font.addGuideline(h_guide)
print("Font-level guidelines:", len(font.guidelines))

# Create a vertical guideline at x = 300 (a stem axis reference).
# angle=90 means vertical.
v_guide = flGuideLine(90.0, QPointF(300, 0))
font.addGuideline(v_guide)

# ============================================================
# 2. Glyph-level guidelines
# ============================================================
# Glyph-level guidelines only appear in the one glyph where you
# add them. Great for construction lines specific to that letter —
# like the shoulder angle on a lowercase 'n', or the center of a
# round letter's bowl.

# A 45° diagonal guideline through the point (100, 100):
a_guide = flGuideLine(45.0, QPointF(100, 100))
layer.appendGuidelines([a_guide])
print("Glyph-level guidelines in this layer:", len(layer.guidelines))

# ============================================================
# 3. Inspecting guidelines
# ============================================================
# Loop through all font-level guides and print their properties.

for gl in font.guidelines:
    print(f"  angle={gl.angle:.1f}°  "
          f"pos={gl.centerPoint}  "
          f"vertical={gl.isVertical()}  "
          f"horizontal={gl.isHorizontal()}")

# ============================================================
# 4. Moving a guideline with a transform
# ============================================================
# The guideline doesn't have a simple ".y = 720" setter, so you
# move it with applyTransform(). QTransform().translate(dx, dy)
# shifts it by (dx, dy) in font units.

gl = font.guidelines[0]
print("Before move:", gl.centerPoint)

from PythonQt.QtGui import QTransform
gl.applyTransform(QTransform().translate(0, 20))   # move up 20 units
print("After move:", gl.centerPoint)

# ============================================================
# 5. Coloring guidelines
# ============================================================
# You can assign any color to a guideline to help distinguish it.
# Red for construction guides, blue for metrics, green for
# opticals — whatever helps your visual system.

gl.color = QColor(220, 60, 60)   # a warm red
print("Has custom color:", gl.hasColor)   # True

# ============================================================
# 6. Expression-based guidelines
# ============================================================
# An expression ties the guideline's position to a font metric.
# When you update the metric (e.g. change xHeight in Font Info),
# the guideline follows automatically. The expression string starts
# with "=" followed by a metric name or arithmetic formula.

gl.expression = "=xHeight"
print("Expression:", gl.expression)
print("Position controlled by expression:", gl.hasExpression)

# You can also use arithmetic:
h_guide.expression = "=capHeight * 0.5"   # midpoint of cap height

# ============================================================
# 7. Tagging guidelines for filtering
# ============================================================
# Tags let you group guides by purpose so your scripts can
# work on just a subset without touching everything.

h_guide.tags = {"metrics", "horizontal"}
v_guide.tags = {"construction"}

# Find all guides tagged "metrics":
metric_guides = [g for g in font.guidelines if "metrics" in g.tags]
print("Metric guides:", len(metric_guides))

# ============================================================
# 8. Snap geometry (distanceTo, offsetTo)
# ============================================================
# You can query how far a point is from a guideline, or get the
# snap vector that would move a point onto the guide.
# This is useful if you want to measure how far a node is
# from an alignment target.

pt = QPointF(100, 680)
dist   = gl.distanceTo(pt, 0)    # perpendicular distance, signed
offset = gl.offsetTo(pt, 0)      # vector to snap onto the guide
print(f"Distance from point to guide: {dist:.1f} units")
print(f"Snap offset: ({offset.x():.1f}, {offset.y():.1f})")

# ============================================================
# 9. Markers on a guideline
# ============================================================
# Some guidelines carry measurement markers — tick marks that
# label distances or stem widths. If you're scripting metrics
# or stem analysis, you can read them here.

for m in gl.markers:
    print(f"  Marker at position={m.position}")

# ============================================================
# 10. Power guides (auto-generated from outlines)
# ============================================================
# Power guides are automatically created from the extreme points
# of your contours. They snap to the optical tops, bottoms, and
# sides of your shapes — useful for aligning multiple glyphs
# to a shared optical height.
#
# flGuideLine.createPowerGuides(font, layer,
#     horizontal=True,   ← capture top/bottom extremes
#     vertical=True,     ← capture left/right extremes
#     diagonal=False)    ← skip diagonal tangent points

ok = flGuideLine.createPowerGuides(font, layer,
    True, True, False,
    use_glyph_guides=True,
    use_font_guides=True)
print("Power guides created:", ok)
print("Layer guides after power-guide generation:", len(layer.guidelines))

# ============================================================
# 11. Sorting guidelines
# ============================================================
# Sort font guidelines from bottom to top (ascending y position):
sorted_guides = flGuideLine.sortGuideLines(list(font.guidelines), True)
for g in sorted_guides:
    print(f"  y={g.centerPoint.y():.0f}  angle={g.angle:.0f}°")

# ============================================================
# 12. Removing a guideline
# ============================================================

font.removeGuideline(v_guide)
print("Font guidelines remaining:", len(font.guidelines))

fl.Update()

Common Scripting Patterns

Set font metrics as expression guidelines

from PythonQt.QtCore import QPointF
# Create guides for the four main font metrics, tied to expressions
# so they stay correct even if you later change the values.
import fontlab as fl
from fontlab import flGuideLine

font = fl.CurrentFont()

metrics = [
    ("=ascender",   "metrics"),
    ("=capHeight",  "metrics"),
    ("=xHeight",    "metrics"),
    ("=descender",  "metrics"),
]

for expr, tag in metrics:
    g = flGuideLine(0.0, QPointF(0, 0))   # position is set by expression
    g.expression = expr
    g.tags = {tag}
    font.addGuideline(g)

fl.Update()

Remove all guidelines from a layer

# Clear every glyph-level guide from a specific layer.
# Font-level guides are untouched.
layer = fl.CurrentFont()['n'].layers[0]
layer.removeGuides(True, True)   # True, True = remove all guidelines (both orientations)
fl.Update()

Color-code guidelines by type

from PythonQt.QtGui import QColor
# Walk through all font guidelines and assign colors
# based on whether they're horizontal, vertical, or diagonal.
font = fl.CurrentFont()
for g in font.guidelines:
    if g.isHorizontal():
        g.color = QColor(50, 100, 200)    # blue for horizontal
    elif g.isVertical():
        g.color = QColor(200, 100, 50)    # orange for vertical
    else:
        g.color = QColor(100, 180, 100)   # green for diagonal
fl.Update()

Measure how far nodes are from a guide

from PythonQt.QtCore import QPointF
# Find all nodes that are within 5 units of the cap-height guide.
font = fl.CurrentFont()
cap_guide = next(
    (g for g in font.guidelines if g.expression == "=capHeight"), None
)
if cap_guide:
    glyph = font['H']
    layer = glyph.layers[0]
    for contour in layer.getContours():
        for node in contour.nodes():
            pt = QPointF(node.x, node.y)
            if abs(cap_guide.distanceTo(pt, 0)) < 5:
                print(f"Node at ({node.x}, {node.y}) is near cap height")

Generate power guides for every glyph in the font

# Build power guides for every glyph's first layer.
# Useful for identifying optical height variation across glyphs.
font = fl.CurrentFont()
for glyph in font.glyphs:
    layer = glyph.layers[0]
    flGuideLine.createPowerGuides(font, layer, True, True, False)
fl.Update()

Constructors: flGuideLine() flGuideLine(flObject) flGuideLine(flGuideLine) flGuideLine(double angle, QPointF canvas_point, uint=flSnaps::Vector, SnapObjectsStyle=gsPageGuideline) flGuideLine(QLineF line, uint=flSnaps::Vector, SnapObjectsStyle=gsPageGuideline) flGuideLine(QPointF center, QPointF vector_point, uint =flSnaps::Vector, SnapObjectsStyle=gsPageGuideline)

Native bases: object

Captured native MRO: flGuideLine, 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: An editing guideline with angle, centerPoint and vectorPoint attributes. The captured declaration identifies centerPoint and vectorPoint as QPointF values, and linef as a QLineF. name identifies the object; color is a QColor value. Consult the retained constructors for supported line and point forms.

Source: FontLab Proteus API documentation

Source: generated/fontlab.py: flGuideLine 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)
angle attribute Any The angle of the guideline in degrees.
angleMode attribute Any Controls how the angle snaps or is constrained during interactive editing
applyTransform function (self, arg0: QTransform) -> None Move, rotate, or scale the guideline using a transform matrix.
center attribute Any The node that defines the guideline's origin/center point.
centerPoint attribute Any The center position as a plain QPointF.
changed function (self) -> Any (shared captured text)
checkInitHistoryState function (self, history_ix: int) -> Any (shared captured text)
clearAboveHistory function (self, history_ix: int) -> Any (shared captured text)
clearFlag function (self, f: int) -> Any (shared captured text)
clearFlags function (self) -> Any (shared captured text)
clone function (self, *args: Any, **kwargs: Any) -> Any Clone the object (shared captured text)
cloneObject function (*args: Any, **kwargs: Any) -> Any (shared captured text)
color attribute Any A custom color for this guideline.
constraints attribute Any A rectangle that limits how far the guideline can be moved interactively.
counterPaper function () -> int Return the number of paper (font-level) guidelines currently in the font
createInstance function () -> flGuideLine Allocate a new guideline instance
createObject function (*args: Any, **kwargs: Any) -> Any FlObject/Nothing createObject(int); (shared captured text)
createPowerGuides function (arg0: fgFont, arg1: flLayer, horizontal: bool, vertical: bool, use_glyph_guides: Any=...) -> bool Auto-generate power guides from the extreme points of existing contours in this layer.
currentHistoryState function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
disconnectFromContour function (self) -> Any If this guideline was "locked" to a specific node on a contour, this breaks that connection, making the guideline free-floating again
distanceTo function (self, arg0: QPointF, mode: int) -> float
expression attribute Any An arithmetic expression that determines this guideline's position.
extLinef attribute Any The extended line segment, if present
extPosition attribute Any An extended position value.
extension attribute Any FlNode: existing extension node, or None if absent (read-only)
flObjectFlags attribute dict (shared captured text)
flag function (self, f: int) -> Any (shared captured text)
getHashCode function (arg0: QPointF, angle: float) -> int Compute a unique hash for a given position + angle combination.
getProperties function (self, *args: Any, **kwargs: Any) -> Any Get object's properties list (shared captured text)
getProperty function (self, *args: Any, **kwargs: Any) -> Any Get object property by 'key' or number (shared captured text)
getPropertyFloat function (self, *args: Any, **kwargs: Any) -> Any Get float object property by 'key' (shared captured text)
getPropertyInt function (self, *args: Any, **kwargs: Any) -> Any Get int object property by 'key' (shared captured text)
hasChanges attribute Any (shared captured text)
hasColor attribute Any True if a custom color has been set.
hasExpression attribute Any True if this guideline's position is controlled by an expression string
hasExtLine attribute Any True if there is an extended line segment attached (a secondary segment that extends past the main guide)
hasHistoryState function (self, history_ix: int) -> Any (shared captured text)
hasHistoryStates attribute Any (shared captured text)
hasTags attribute Any True if at least one tag has been assigned to this guideline
haveObject function (*args: Any, **kwargs: Any) -> Any (shared captured text)
historyStates function (self, accepted_state: bool) -> Any (shared captured text)
id attribute Any Object id (shared captured text)
independedAll function (self) -> Any (shared captured text)
initialHistoryState function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
instanceType function (*args: Any, **kwargs: Any) -> Any (shared captured text)
isAbsoluteMarkerPos attribute Any When True, any measurement markers on this guideline are positioned using absolute coordinates.
isChanged attribute Any (shared captured text)
isEqual function (self, arg0: flObject) -> Any (shared captured text)
isExluded attribute Any
isGhost attribute Any Bool: actual ghost-hint flag (read-only)
isGuideLine function (arg0: flObject) -> bool Check whether a generic object is actually a guideline
isHint attribute Any
isHorizontal function (self, a: Any=...) -> bool Returns True if the guideline's angle is within a degrees of horizontal (0°).
isInUse attribute Any
isMeasurementLine attribute Any
isNull attribute Any (shared captured text)
isPassive attribute Any
isPresent attribute Any (shared captured text)
isReleased attribute Any (shared captured text)
isShortGuideline attribute Any True if this is a bounded (short, finite-length) guideline rather than an infinite one
isSnapLine function (arg0: flObject) -> bool
isValid attribute Any (shared captured text)
isVertical function (self, a: Any=...) -> bool Returns True if the guideline's angle is within a degrees of vertical (90°).
isVerticalQuarter attribute Any True if the angle is exactly 90° or 270° — a perfectly vertical guideline.
isZone attribute Any
length attribute Any The visible length of the guideline segment in font units.
linef attribute Any The guideline as a Qt QLineF segment.
markers attribute Any A list of measurement markers attached to this guideline.
markersStructVersion attribute Any An integer that increments every time the markers list changes.
name attribute Any Object name (shared captured text)
offsetTo function (self, arg0: QPointF, mode: int) -> QPointF
propertyNames function (self, *args: Any, **kwargs: Any) -> Any PropertyNames(): sorted snapshot of dynamic property keys (shared captured text)
refCnt attribute Any Object references count (shared captured text)
release function (self) -> Any (shared captured text)
remove function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
removeChild function (self, arg0: flObject) -> Any (shared captured text)
reset function (self) -> Any
restoreHistoryState function (self, history_ix: int) -> Any (shared captured text)
setFlag function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
setProperty function (self, *args: Any, **kwargs: Any) -> Any Set object property by 'key' or number (shared captured text)
setPropertyFloat function (self, *args: Any, **kwargs: Any) -> Any Set float object property by 'key' (shared captured text)
setPropertyInt function (self, *args: Any, **kwargs: Any) -> Any Set int object property by 'key' (shared captured text)
setSnapFlag function (self, role: int, snapFlags: int) -> Any
setSnapFlagValue function (self, role: int, bool: Any) -> Any
snapFlag function (self, role: int) -> int
snapFlags attribute Any
sortGuideLines function (ascending: Any=...) -> Any Sort a list of guidelines by their position value (lowest to highest by default)
style attribute Any The visual style of this guideline — controls whether it draws as a standard guide, a zone boundary, a page edge, etc.
tag function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
tags attribute Any A set of string tags you can attach to this guideline for filtering.
type attribute Any Object type (shared captured text)
update function (self) -> Any (shared captured text)
vector attribute Any The node that defines the direction the guideline points.
vectorPoint attribute Any The vector endpoint as a plain QPointF