Composable path transforms

Create a reusable mapping, then apply it to independent geometry:

import {
  PathGeometry,
  composeTransforms,
  envelopeTransform,
  affineTransform,
  arcBendTransform,
  transformPath,
} from "@pibbl/core";

const original = new PathGeometry();
original.rect(0, 0, 200, 50);
const textBounds = { x: 0, y: 0, width: 200, height: 50 };
const top = new PathGeometry();
top.moveTo(0, 0);
top.lineTo(200, 20);
const bottom = new PathGeometry();
bottom.moveTo(0, 50);
bottom.lineTo(200, 70);
const mapping = composeTransforms(
  envelopeTransform({ source: textBounds, top, bottom }),
  affineTransform({ a: 1.2, d: 1.2, e: 100, f: 60 }),
);
const result = transformPath(original, mapping, { tolerance: 0.25 });

Composition runs left to right in ordinary coordinates. source belongs to a mapping; each later source rectangle describes the preceding mapping’s output. transformPath approximates the final composed outline, including closing edges, in destination units. It preserves source geometry and contour order. All-affine compositions preserve curve segments. Nonlinear output uses lines. tolerance is required and positive; maxSegments defaults to one million. Work, output, precision, and domain failures throw without returning partial output.

Envelope inputs can instead use guides: [{ at: 0, path: top }, { at: 0.4, path: middle }, { at: 1, path: bottom }]. Positions strictly increase from zero to one. Interpolation is linear between guides and may crease at interior guides. Guides are independent snapshots of one nonempty open contour. They match by normalized arc length. { path, reverse: true, stations: [{ at: 0, distance: 0 }, { at: 1, distance: 1 }] } supplies direction and correspondence landmarks. Stations increase strictly on both axes; distance is measured after reversal. Crossed guides and intentional folds are allowed. Envelope source bounds are required; geometry outside them is rejected rather than clamped.

quadTransform({ source, destination, mode }) accepts the existing four named corners. Mode is bilinear (default) or perspective. Perspective requires a strictly convex destination. Quad mappings allow finite extrapolation.

mapPoint({ x, y }, { tolerance: 0.0001 }) evaluates a mapping for editor guides and annotations. The tolerance option is optional and defaults to 0.0001. Values are opaque; arbitrary objects or callbacks are not PathTransforms.

Sequential transformPath calls remain supported when intermediate geometry is useful. Each call has an independent tolerance; later maps can amplify earlier approximation error. Prefer composition for a single final accuracy target.

Meshes

meshTransform({ source, columns, rows, horizontal, vertical }) creates a grid of Coons patches. Columns and rows are strictly increasing normalized coordinates from 0 to 1. Horizontal contains one row of edges per row boundary, each with columns.length - 1 left-to-right guides. Vertical contains one column of edges per column boundary, each with rows.length - 1 top-to-bottom guides.

Edges share exact endpoint coordinates. Mismatches throw; no points are moved implicitly. Shared edges are supplied once. Each cell interpolates its four boundaries. Adjacent cells meet continuously, but matching slopes are not promised. Folds are permitted. The constructor accepts at most 4,096 cells. Source geometry must remain inside the source rectangle.

Bends

Continuing with the imports and original geometry above:

const bend = arcBendTransform({
  source: { x: 0, y: 0, width: 200, height: 50 },
  arc: { cx: 300, cy: 300, radius: 180, startAngle: -Math.PI, sweep: Math.PI },
  baseline: "bottom",
  fit: "stretch",
});
const bentResult = transformPath(
  original,
  composeTransforms(bend, affineTransform({ e: 20 })),
  {
    tolerance: 0.25,
  },
);

pathBendTransform({ source, guide, ...placement }) takes an explicit PathGeometry guide. Both constructors accept BendTransformOptions; arc and path variants add arc and guide, respectively. See path bending for alignment, baseline, fitting, offsets, and overflow rules. Bends retain their existing smooth-guide requirements; envelopes and meshes also support corners.

Migration

warpPath, bendPathAlongArc, and bendPathAlongPath are replaced by transformPath(path, quadTransform(mapping), quality), transformPath(path, arcBendTransform(mapping), quality), and transformPath(path, pathBendTransform({ ...mapping, guide }), quality). There are no root compatibility exports. Separate tolerance and maxSegments from mapping options. The root exports PathPoint, PathRect, PathQuadCorners, and PathQuadMode instead of the former warp-specific point/rectangle types.

The in-place PathGeometry.transform(matrix) builder remains available. Use affineTransform with transformPath when independent results or composition are needed. Flattening, subdivision, and simplification remain separate geometry operations rather than spatial mappings.

API details from source

meshTransform

Creates a mapping through a mesh bounded by horizontal and vertical path guides.

meshTransform: (options: MeshTransformOptions) => PathTransform

Parameters

options — Source rectangle and the four boundary guides used to deform it. See MeshTransformOptions .

Returns

A point mapping suitable for transformPath. See PathTransform.

arcBendTransform

Creates a reusable mapping that bends source geometry around a circular arc.

arcBendTransform: (options: ArcBendTransformOptions) => PathTransform

Parameters

options — Source bounds and circular bend geometry. See ArcBendTransformOptions.

Returns

A point mapping that bends the source along a circular arc. See PathTransform.

pathBendTransform

Creates a reusable mapping that bends source geometry along a guide path.

pathBendTransform: (options: PathBendTransformOptions) => PathTransform

Parameters

options — Source bounds, target guide, and alignment along that guide. See PathBendTransformOptions .

Returns

A point mapping that bends the source along the target path. See PathTransform.

MeshTransformOptions

Source rectangle, normalized cell boundaries, and horizontal/vertical path guides for a mesh transform.

interface MeshTransformOptions

Related API: MeshTransformOptions.

Properties and methods

source

readonly source: PathRect

Related API: PathRect.

Source rectangle whose normalized cells are mapped through the guide mesh. See PathRect.

View source — packages/core/src/lib/geometry/transform-mesh.ts:35

columns

readonly columns: readonly number[]

Strictly increasing normalized column boundaries, beginning at 0 and ending at 1. See MeshTransformOptions.

View source — packages/core/src/lib/geometry/transform-mesh.ts:40

rows

readonly rows: readonly number[]

Strictly increasing normalized row boundaries, beginning at 0 and ending at 1. See MeshTransformOptions.

View source — packages/core/src/lib/geometry/transform-mesh.ts:45

horizontal

readonly horizontal: readonly (readonly PathGuide[])[]

Related API: PathGuide.

Boundary rows; each contains columns.length - 1 left-to-right edges.

View source — packages/core/src/lib/geometry/transform-mesh.ts:47

vertical

readonly vertical: readonly (readonly PathGuide[])[]

Related API: PathGuide.

Boundary columns; each contains rows.length - 1 top-to-bottom edges.

View source — packages/core/src/lib/geometry/transform-mesh.ts:49

ArcBendTransformOptions

Circular bending parameters for a reusable arc transform; accuracy is supplied when applying it.

type ArcBendTransformOptions = Omit<
  BendPathAlongArcOptions,
  'tolerance' | 'maxSegments'
>

Related API: ArcBendTransformOptions.

Properties and methods

source

readonly source: PathBendFrame

Source coordinate frame used to normalize the geometry before bending. See PathBendFrame.

View source — packages/core/src/lib/geometry/path-bending.ts:64

align (optional)

readonly align?: PathBendAlign | undefined

Related API: PathBendAlign.

Placement of the source length along the guide. See PathBendAlign.

View source — packages/core/src/lib/geometry/path-bending.ts:66

baseline (optional)

readonly baseline?: PathBendBaseline | undefined

Related API: PathBendBaseline.

Source baseline mapped onto the guide. See PathBendBaseline.

View source — packages/core/src/lib/geometry/path-bending.ts:68

fit (optional)

readonly fit?: PathBendFit | undefined

Related API: PathBendFit.

Policy for fitting content within its available box. See PathBendFit.

View source — packages/core/src/lib/geometry/path-bending.ts:70

offset (optional)

readonly offset?: number | undefined

Offset along the guide. See PathBendOptions.

View source — packages/core/src/lib/geometry/path-bending.ts:72

normalOffset (optional)

readonly normalOffset?: number | undefined

Offset perpendicular to the guide. See PathBendOptions.

View source — packages/core/src/lib/geometry/path-bending.ts:74

overflow (optional)

readonly overflow?: PathBendOverflow | undefined

Related API: PathBendOverflow.

Policy for geometry extending beyond the guide’s available length. See PathBendOverflow.

View source — packages/core/src/lib/geometry/path-bending.ts:79

arc

readonly arc: PathBendArc

Related API: PathBendArc.

View source — packages/core/src/lib/geometry/path-bending.ts:85

PathBendTransformOptions

Guide path and bending parameters for a reusable path transform.

type PathBendTransformOptions = Omit<
  PathBendOptions,
  'tolerance' | 'maxSegments'
> & {
  /** Path used as the bending guide. See {@link PathGeometry}. */
  readonly guide: PathGeometry;
}

Related API: PathBendTransformOptions, Path, PathGeometry.

Properties and methods

source

readonly source: PathBendFrame

Source coordinate frame used to normalize the geometry before bending. See PathBendFrame.

View source — packages/core/src/lib/geometry/path-bending.ts:64

align (optional)

readonly align?: PathBendAlign | undefined

Related API: PathBendAlign.

Placement of the source length along the guide. See PathBendAlign.

View source — packages/core/src/lib/geometry/path-bending.ts:66

baseline (optional)

readonly baseline?: PathBendBaseline | undefined

Related API: PathBendBaseline.

Source baseline mapped onto the guide. See PathBendBaseline.

View source — packages/core/src/lib/geometry/path-bending.ts:68

fit (optional)

readonly fit?: PathBendFit | undefined

Related API: PathBendFit.

Policy for fitting content within its available box. See PathBendFit.

View source — packages/core/src/lib/geometry/path-bending.ts:70

offset (optional)

readonly offset?: number | undefined

Offset along the guide. See PathBendOptions.

View source — packages/core/src/lib/geometry/path-bending.ts:72

normalOffset (optional)

readonly normalOffset?: number | undefined

Offset perpendicular to the guide. See PathBendOptions.

View source — packages/core/src/lib/geometry/path-bending.ts:74

overflow (optional)

readonly overflow?: PathBendOverflow | undefined

Related API: PathBendOverflow.

Policy for geometry extending beyond the guide’s available length. See PathBendOverflow.

View source — packages/core/src/lib/geometry/path-bending.ts:79

guide

readonly guide: PathGeometry

Related API: PathGeometry.

Path used as the bending guide. See PathGeometry.

View source — packages/core/src/lib/geometry/transform-bend.ts:58

transformPath

Return independent geometry. Nonlinear mappings approximate the final composed curve once.

transformPath: (path: PathGeometry, transform: PathTransform, options: TransformPathOptions) => PathGeometry

Parameters

path — Source geometry; it is not modified. See PathGeometry.
transform — Point mapping to apply to the source. See PathTransform.
options — Approximation tolerance and work limits for transformed curves. See TransformPathOptions .

Returns

Independent geometry containing the transformed path. See PathGeometry.

composeTransforms

Apply mappings in the order written. Empty composition is identity.

composeTransforms: (...transforms: readonly PathTransform[]) => PathTransform

Related API: composeTransforms, PathTransform.

Parameters

transforms — Point mappings in the order they should be applied. See PathTransform .

Returns

One mapping that applies each supplied transform in order. See PathTransform.

affineTransform

Creates a reusable 2D affine mapping; an omitted matrix produces identity.

affineTransform: (matrix?: DOMMatrix2DInit) => PathTransform

Related API: affineTransform, PathTransform.

Parameters

matrix — Affine matrix coefficients; omitted coefficients use the identity matrix.

Returns

A point mapping applying the matrix. See PathTransform.

quadTransform

Maps a source rectangle into four destination corners using bilinear or perspective interpolation.

quadTransform: (options: QuadTransformOptions) => PathTransform

Parameters

options — Source rectangle and destination corner positions. See QuadTransformOptions .

Returns

A point mapping from the source rectangle to the destination quadrilateral. See PathTransform .

envelopeTransform

Maps a source rectangle between ordered guide paths using linear interpolation.

envelopeTransform: (options: EnvelopeTransformOptions) => PathTransform

Parameters

options — Source bounds and envelope guides defining the deformation. See EnvelopeTransformOptions .

Returns

A point mapping that deforms the source into the envelope. See PathTransform.

PathTransform

A constructor-created, reusable coordinate mapping for path transformation.

interface PathTransform

Related API: PathTransform.

Properties and methods

mapPoint

mapPoint: (point: PathPoint, options?: { readonly tolerance?: number; }) => PathPoint

Related API: PathPoint.

Evaluate in ordinary source/destination coordinates. Guide approximation is bounded by tolerance.

Parameters

point — Source point in the transform’s input coordinate system. See PathPoint.
options — Optional approximation tolerance for evaluating the mapping.

Returns

The mapped point in the transform’s output coordinate system. See PathPoint.

View source — packages/core/src/lib/geometry/path-transforms.ts:79

PathPoint

A point in source or destination path coordinates.

interface PathPoint

Related API: PathPoint.

Properties and methods

readonly x: number

Horizontal coordinate or displacement in the containing coordinate system. See PathPoint.

View source — packages/core/src/lib/geometry/path-transforms.ts:41

readonly y: number

Vertical coordinate or displacement in the containing coordinate system. See PathPoint .

View source — packages/core/src/lib/geometry/path-transforms.ts:46

PathRect

A source rectangle with an origin and finite positive dimensions.

interface PathRect extends PathPoint

Related API: PathRect, PathPoint.

Properties and methods

width

readonly width: number

Horizontal extent in the units of the containing geometry or surface. See PathRect.

View source — packages/core/src/lib/geometry/path-transforms.ts:57

height

readonly height: number

Vertical extent in the units of the containing geometry or surface. See PathRect.

View source — packages/core/src/lib/geometry/path-transforms.ts:59

readonly x: number

Horizontal coordinate or displacement in the containing coordinate system. See PathPoint.

View source — packages/core/src/lib/geometry/path-transforms.ts:41

readonly y: number

Vertical coordinate or displacement in the containing coordinate system. See PathPoint .

View source — packages/core/src/lib/geometry/path-transforms.ts:46

TransformPathOptions

Accuracy and output-segment limits for applying a path transform.

interface TransformPathOptions

Related API: TransformPathOptions.

Properties and methods

tolerance

readonly tolerance: number

Positive maximum geometric approximation error. See TransformPathOptions.

View source — packages/core/src/lib/geometry/path-transforms.ts:94

maxSegments (optional)

readonly maxSegments?: number | undefined

Upper bound on the number of output path segments. See TransformPathOptions.

View source — packages/core/src/lib/geometry/path-transforms.ts:96

QuadTransformOptions

Source rectangle, destination corners, and interpolation mode for a quadrilateral transform.

interface QuadTransformOptions

Related API: QuadTransformOptions.

Properties and methods

source

readonly source: PathRect

Related API: PathRect.

Source rectangle mapped to the destination quadrilateral. See PathRect.

View source — packages/core/src/lib/geometry/path-transforms.ts:120

destination

readonly destination: PathWarpCorners

Destination corners into which the source rectangle maps. See PathQuadCorners.

View source — packages/core/src/lib/geometry/path-transforms.ts:122

mode (optional)

readonly mode?: PathWarpMode | undefined

Selects the supported mapping, placement, or result policy. See PathQuadMode.

View source — packages/core/src/lib/geometry/path-transforms.ts:124

PathQuadCorners

The four destination corners used by a quadrilateral path transform.

type PathQuadCorners = PathWarpCorners

Related API: PathQuadCorners.

Properties and methods

topLeft

readonly topLeft: PathWarpPoint

View source — packages/core/src/lib/geometry/path-warp.ts:8

topRight

readonly topRight: PathWarpPoint

View source — packages/core/src/lib/geometry/path-warp.ts:9

bottomLeft

readonly bottomLeft: PathWarpPoint

View source — packages/core/src/lib/geometry/path-warp.ts:10

bottomRight

readonly bottomRight: PathWarpPoint

View source — packages/core/src/lib/geometry/path-warp.ts:11

PathQuadMode

Selects bilinear or perspective interpolation for a quadrilateral transform.

type PathQuadMode = PathWarpMode

Related API: PathQuadMode.

BendTransformOptions

Alignment, fitting, baseline, and overflow controls shared by reusable bend transforms.

type BendTransformOptions = Omit<
  PathBendOptions,
  'tolerance' | 'maxSegments'
>

Related API: BendTransformOptions.

Properties and methods

source

readonly source: PathBendFrame

Source coordinate frame used to normalize the geometry before bending. See PathBendFrame.

View source — packages/core/src/lib/geometry/path-bending.ts:64

align (optional)

readonly align?: PathBendAlign | undefined

Related API: PathBendAlign.

Placement of the source length along the guide. See PathBendAlign.

View source — packages/core/src/lib/geometry/path-bending.ts:66

baseline (optional)

readonly baseline?: PathBendBaseline | undefined

Related API: PathBendBaseline.

Source baseline mapped onto the guide. See PathBendBaseline.

View source — packages/core/src/lib/geometry/path-bending.ts:68

fit (optional)

readonly fit?: PathBendFit | undefined

Related API: PathBendFit.

Policy for fitting content within its available box. See PathBendFit.

View source — packages/core/src/lib/geometry/path-bending.ts:70

offset (optional)

readonly offset?: number | undefined

Offset along the guide. See PathBendOptions.

View source — packages/core/src/lib/geometry/path-bending.ts:72

normalOffset (optional)

readonly normalOffset?: number | undefined

Offset perpendicular to the guide. See PathBendOptions.

View source — packages/core/src/lib/geometry/path-bending.ts:74

overflow (optional)

readonly overflow?: PathBendOverflow | undefined

Related API: PathBendOverflow.

Policy for geometry extending beyond the guide’s available length. See PathBendOverflow.

View source — packages/core/src/lib/geometry/path-bending.ts:79

EnvelopeTransformOptions

Source rectangle and either a top/bottom pair or ordered envelope guides.

Full type declaration

type EnvelopeTransformOptions = {
  /** Source rectangle mapped between the envelope guides. See {@link PathRect}. */
  readonly source: PathRect;
  /** Interpolation between successive guide paths; only linear interpolation is supported. See {@link EnvelopeTransformOptions}. */
  readonly interpolation?: 'linear';
} & (
  | {
      /** Top edge value or top envelope guide. See {@link PathGuide}. */
      readonly top: PathGuide;
      /** Bottom edge value or bottom envelope guide. See {@link PathGuide}. */
      readonly bottom: PathGuide;
      /**
       * Not accepted in this variant; use the alternative fields instead. See
       * {@link EnvelopeTransformOptions}.
       */
      readonly guides?: never;
    }
  | {
      /**
       * Ordered guide paths defining the envelope from its first to last station. See
       * {@link EnvelopeGuide}.
       */
      readonly guides: readonly EnvelopeGuide[];
      /**
       * Not accepted in this variant; use the alternative fields instead. See
       * {@link EnvelopeTransformOptions}.
       */
      readonly top?: never;
      /**
       * Not accepted in this variant; use the alternative fields instead. See
       * {@link EnvelopeTransformOptions}.
       */
      readonly bottom?: never;
    }
)

Properties and methods

source

readonly source: PathRect

Related API: PathRect.

Source rectangle mapped between the envelope guides. See PathRect.

View source — packages/core/src/lib/geometry/path-transforms.ts:148

interpolation (optional)

readonly interpolation?: "linear" | undefined

Interpolation between successive guide paths; only linear interpolation is supported. See EnvelopeTransformOptions.

View source — packages/core/src/lib/geometry/path-transforms.ts:150

top (optional)

readonly top?: PathGuide | undefined

Related API: PathGuide.

Top edge value or top envelope guide. See PathGuide. Not accepted in this variant; use the alternative fields instead. See EnvelopeTransformOptions.

View source — packages/core/src/lib/geometry/path-transforms.ts:154

bottom (optional)

readonly bottom?: PathGuide | undefined

Related API: PathGuide.

Bottom edge value or bottom envelope guide. See PathGuide. Not accepted in this variant; use the alternative fields instead. See EnvelopeTransformOptions.

View source — packages/core/src/lib/geometry/path-transforms.ts:156

guides (optional)

readonly guides?: readonly EnvelopeGuide[] | undefined

Related API: EnvelopeGuide.

Not accepted in this variant; use the alternative fields instead. See EnvelopeTransformOptions. Ordered guide paths defining the envelope from its first to last station. See EnvelopeGuide.

View source — packages/core/src/lib/geometry/path-transforms.ts:161

EnvelopeGuide

A guide path positioned at a normalized station across an envelope.

interface EnvelopeGuide

Related API: EnvelopeGuide.

Properties and methods

readonly at: number

Normalized station position. See EnvelopeGuide.

View source — packages/core/src/lib/geometry/path-transforms.ts:134

path

readonly path: PathGuide

Related API: PathGuide.

Path geometry used by this operation. See PathGuide.

View source — packages/core/src/lib/geometry/path-transforms.ts:136

PathGuide

A geometry path or a path with explicit guide-sampling configuration.

type PathGuide = PathGeometry | PathGuideOptions

Related API: PathGuide, PathGeometry, PathGuideOptions.

PathGuideOptions

Geometry and stations that define how a transformation samples a guide.

interface PathGuideOptions

Related API: PathGuideOptions.

Properties and methods

path

readonly path: PathGeometry

Related API: PathGeometry.

Path geometry used by this operation. See PathGeometry.

View source — packages/core/src/lib/geometry/transform-guide.ts:41

reverse (optional)

readonly reverse?: boolean | undefined

Whether to reverse the direction of the mapping or guide. See PathGuideOptions.

View source — packages/core/src/lib/geometry/transform-guide.ts:43

stations (optional)

readonly stations?: readonly PathGuideStation[] | undefined

Related API: PathGuideStation.

Explicit correspondence between normalized stations and guide distance. See PathGuideStation.

View source — packages/core/src/lib/geometry/transform-guide.ts:48

PathGuideStation

A station mapping normalized guide position to normalized arc-length distance along its path.

interface PathGuideStation

Related API: PathGuideStation.

Properties and methods

readonly at: number

Normalized station position. See PathGuideStation.

View source — packages/core/src/lib/geometry/transform-guide.ts:28

distance

readonly distance: number

Normalized arc-length distance from 0 to 1. See PathGuideStation.

View source — packages/core/src/lib/geometry/transform-guide.ts:30

Implementation guidance for agents

Read the Drawing, layout, and effects companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Quad and envelope warps: Warp a tile through a quadrilateral and between measured guide paths. Plain source
Arc and path bending: Bend geometry around an arc and along a guide with explicit placement options. Plain source
Mesh warp: Define a one-cell guide mesh and warp a circle through it. Plain source
Affine transforms: Compose translation and scaling, then transform geometry and a sample point. Plain source

Interactive examples

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 2dccb19. ALPHA — NOT FOR PRODUCTION USE.

Composable path transforms

Meshes

Bends

Migration

API details from source

meshTransform

Parameters

Returns

See also

arcBendTransform

Parameters

Returns

See also

pathBendTransform

Parameters

Returns

See also

MeshTransformOptions

See also

Properties and methods

ArcBendTransformOptions

See also

Properties and methods

PathBendTransformOptions

See also

Properties and methods

transformPath

Parameters

Returns

See also

composeTransforms

Parameters

Returns

See also

affineTransform

Parameters

Returns

See also

quadTransform

Parameters

Returns

See also

envelopeTransform

Parameters

Returns

See also

PathTransform

See also

Properties and methods

Parameters

Returns

PathPoint

See also

Properties and methods

PathRect

See also

Properties and methods

TransformPathOptions

See also

Properties and methods

QuadTransformOptions

See also

Properties and methods

PathQuadCorners

See also

Properties and methods

PathQuadMode

See also

BendTransformOptions

See also

Properties and methods

EnvelopeTransformOptions

See also

Properties and methods

EnvelopeGuide

See also

Properties and methods

PathGuide

See also

PathGuideOptions