Skip to content

pixtreme.draw

draw

Shape and text drawing operations.

__all__ = ('line', 'polyline', 'rectangle', 'circle', 'ellipse', 'polygon', 'text', 'Font') module-attribute

Font dataclass

Immutable draw-text font asset built from a construction-time file snapshot.

__init__()

from_file(path, *, face_index=0) classmethod

Snapshot one font file face after validating both backends and its variation axes.

path is read completely during this call; later file changes do not affect the asset. face_index selects a face in a single-face file or collection. Equality, hashing, and private caches use content bytes plus face index, never the diagnostic path. Invalid files, face indices, or axis tables fail during construction with actionable ValueError.

__hash__()

__eq__(other)

__repr__()

circle(frame, *, center, radius, color, thickness=None, fill=False, opacity=1.0, blend='normal', aa='distance', softness=0.0)

Draw a filled disk or a centered circular outline.

The center is (x, y) in the continuous system whose pixel centers are (i + 0.5, j + 0.5). fill and thickness are mutually exclusive. Coverage and blend preserve unclamped scene values. The input is unchanged and the returned Frame always owns a new allocation.

ellipse(frame, *, center, radii, rotation=0.0, color, thickness=None, fill=False, opacity=1.0, blend='normal', aa='distance', softness=0.0)

Draw a rotated filled ellipse or an isotropic-width outline.

Coordinates are (x, y) with pixel centers at (i + 0.5, j + 0.5). Radii are (rx, ry) and positive rotation is visually counterclockwise, matching lens_blur. fill excludes thickness; outline thickness is centered. Scene values are not clamped and output owns a new allocation.

line(frame, *, start, end, color, thickness, opacity=1.0, blend='normal', aa='distance', softness=0.0)

Draw one round-cap line in continuous pixel coordinates.

Coordinates are (x, y) and pixel (i, j) is sampled at (i + 0.5, j + 0.5). Thickness spreads equally around the centerline; a zero-length line is a circle of diameter thickness. Coverage, opacity, and the selected blend are applied once without clamp, so scene values pass through. The input is unchanged and the result always owns a new allocation.

polygon(frame, *, points, color, opacity=1.0, blend='normal', aa='distance', softness=0.0)

Fill a polygon with the even-odd rule in continuous coordinates.

Points are (x, y) and pixel centers are (i + 0.5, j + 0.5). Concave and self-intersecting paths are accepted; duplicate and collinear vertices contribute only zero-area degeneracies. Polygon is fill-only; use polyline(..., closed=True) for thickness. Blend does not clamp scene values, and the result always owns a new allocation.

polyline(frame, *, points, color, thickness, closed=False, opacity=1.0, blend='normal', aa='distance', softness=0.0)

Draw a round-cap, round-join polyline as one coverage union.

Coordinates use (x, y) with pixel centers at (i + 0.5, j + 0.5). Segment capsules are united before one blend, so joins and self-crossings do not composite twice. Thickness is centered, scene values are not clamped, and the result always owns a new allocation.

rectangle(frame, *, top_left, bottom_right, color, thickness=None, fill=False, corner_radius=0.0, opacity=1.0, blend='normal', aa='distance', softness=0.0)

Draw a continuous-coordinate axis-aligned rectangle.

top_left and bottom_right are (x, y) boundaries; pixel centers are (i + 0.5, j + 0.5). Corner radius saturates at half the short side. fill=True requires no thickness, while an outline requires positive thickness centered on the boundary. Scene values are not clamped and output always uses a new allocation.

text(frame, *, text, position, size, color, weight=400.0, language='ja', anchor='baseline-left', outlines=None, opacity=1.0, blend='normal', align='left', line_spacing=1.0, tracking=0.0, kerning=True, font='sans', variations=None, width=None, supersample=False)

Draw explicitly line-broken text with a bundled token or immutable Font.

Text is split literally on \n; any \r is rejected. line_spacing multiplies the font line advance, while tracking is an em ratio added after shaping. kerning toggles only the OpenType kern feature. font selects bundled sans (weight 100.0 through 900.0), bundled mono (400.0 through 700.0), or a Font.from_file bytes snapshot. For a user Font, weight controls its measured wght axis and otherwise must remain 400.0. variations partially overrides any other measured axes; unspecified axes use their font defaults and invalid tags or ranges fail before drawing. The same resolved coordinates select HarfBuzz shaping, FreeType metrics, and glyph rasterization. Bundled mono accepts 400.0 through 700.0 without saturation. width is a pixel block width used by align; justify adds positive remaining width to shaped-glyph gaps. anchor identifies the block box at position. Shaping, glyph rasters, and block atlases use private caches keyed by content bytes, face index, and resolved axis coordinates. Missing code points use the selected face's .notdef glyph without system, bundled, user, or network fallback. supersample=False keeps the standard FreeType 8-bit coverage path. supersample=True is an opt-in internal precision path that rasterizes glyph bodies and outlines at 4x size, phase, and stroke radius, then takes an fp32 4x4 box average on the unchanged output geometry. Both modes keep separate private cache entries. Composition does not clamp scene values. The input is unchanged and the result always owns new storage.