# PathGeometry

`PathGeometry` is mutable, inspectable geometry backed by private typed arrays.
It supports the Canvas path-building vocabulary, segment editing, 2D affine
transforms, and independent native/SVG conversion.

## Operations at a glance

This is the operation map for editable `PathGeometry`. All functions below are
public exports of `@pibbl/core`; methods belong to a geometry instance.

### Build and edit

| Goal                                | API                                                                  | Result                                                |
| ----------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- |
| Draw contours                       | `moveTo`, `lineTo`, `quadraticCurveTo`, `bezierCurveTo`, `closePath` | Mutates this geometry; returns void                   |
| Add curved and rectangular shapes   | `arc`, `arcTo`, `ellipse`, `geometry.rect()`, `roundRect`            | Mutates this geometry; returns void                   |
| Copy without sharing edits          | `new PathGeometry(source)`, `clone()`                                | Independent `PathGeometry`                            |
| Append another path                 | `addPath(other, matrix?)`                                            | Mutates this geometry; optionally transforms the copy |
| Inspect segments                    | `segmentCount`, `getSegment(index)`, iteration                       | Count or independent segment values                   |
| Replace, insert, or remove segments | `setSegment`, `spliceSegments`                                       | Mutates this geometry                                 |
| Empty and reuse storage             | `clear()`                                                            | Mutates this geometry                                 |
| Detect edits                        | `revision`                                                           | Mutation counter, not a reactive signal               |

See [construction and editing](#construction-and-editing) and the
[editable geometry example](/playground/#/examples/drawing/path-geometry).

### Move, bend, and warp

Mapping constructors return a reusable `PathTransform`, not geometry.
`transformPath(geometry, mapping, { tolerance })` applies one and returns an
independent `PathGeometry`. `composeTransforms(...)` combines mappings left to
right before that final approximation. A mapping's `mapPoint(...)` also maps
individual points, useful for handles and annotations.

| Goal                                                         | API                                    | Working example                                          |
| ------------------------------------------------------------ | -------------------------------------- | -------------------------------------------------------- |
| Translate, rotate, scale, skew, or reflect in place          | `geometry.transform(matrix)`           | [Editable geometry](/playground/#/examples/drawing/path-geometry)    |
| Apply an affine mapping without changing the original        | `affineTransform` with `transformPath` | [Transform examples](/reference/functions/path-transforms/)                 |
| Fit into four corners, using bilinear or perspective mapping | `quadTransform`                        | [Interactive quad warp](/playground/#/examples/drawing/path-warp)    |
| Stretch between two or more guide paths                      | `envelopeTransform`                    | [Multi-guide envelope](/playground/#/examples/drawing/text-envelope) |
| Warp through a grid of curved boundaries                     | `meshTransform`                        | [Mesh reference](/reference/functions/path-transforms/#meshes)              |
| Bend around a circular arc                                   | `arcBendTransform`                     | [Arc and path bending](/playground/#/examples/drawing/path-bending)  |
| Bend along a smooth guide path                               | `pathBendTransform`                    | [Arc and path bending](/playground/#/examples/drawing/path-bending)  |
| Combine mappings and apply them once                         | `composeTransforms`, `transformPath`   | [Transform examples](/reference/functions/path-transforms/)                 |

See [composable path transforms](/reference/functions/path-transforms/) for source rectangles,
guide correspondence, mesh boundaries, tolerance, and domain limits. See
[path bending](/reference/functions/path-bending/) for baseline, alignment, fitting, and overflow.
Affine mappings preserve curves; nonlinear mappings produce line segments.

### Change detail and export

| Goal                                                    | API                  | Result                                                                     |
| ------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------- |
| Adaptively approximate curves with lines                | `flattenPath`        | Independent line-only geometry                                             |
| Flatten with uniform parameter steps using Wang's bound | `flattenPathWang`    | Independent line-only geometry; predictable segment allocation             |
| Reduce polyline vertices                                | `simplifyPath`       | Independent simplified geometry; curves must be flattened first            |
| Simplify with a radial-distance prepass                 | `simplifyPathRadial` | Independent simplified geometry; the two stages share the tolerance budget |
| Split segments into more editable pieces                | `subdividePath`      | Independent geometry; preserves curves, not equal physical spacing         |
| Draw with native Canvas APIs                            | `toPath2D`           | Fresh native `Path2D` snapshot                                             |
| Export SVG path data                                    | `toSvgPathData`      | SVG path-data string                                                       |

See [geometry utilities](#geometry-utilities) and the
[utility comparison example](/playground/#/examples/drawing/path-geometry).

### Boundaries and larger examples

Geometry edits do not schedule rendering: notify a consumed signal after editing.
Changing `Path` or `Group` presentation transforms does not rewrite the source
geometry. Pixel filters likewise do not edit its segments.

Native `Path2D` is opaque: Pibbl cannot turn it back into editable geometry. The
`create*Path` factories return native paths, not `PathGeometry`. Start with the
builder when later editing or warping is needed. Text outlines from `@pibbl/text`
can also provide editable geometry; see [text geometry](/reference/functions/text-geometry/).
Boolean union/intersection/subtraction, equal-distance resampling, and curve
fitting are not provided by this surface.

Explore the [multi-guide text envelope example](/playground/#/examples/drawing/text-envelope)
for a larger composition using the same mapping APIs.

## Smallest construction example

```ts
import { PathGeometry, toPath2D, toSvgPathData } from "@pibbl/core";

const geometry = new PathGeometry();
geometry.moveTo(10, 10);
geometry.bezierCurveTo(10, 40, 40, 40, 40, 10);
geometry.closePath();
const native = toPath2D(geometry);
const svgData = toSvgPathData(geometry);
```

## Construction and editing

The mutable builder methods are `moveTo`, `lineTo`, `quadraticCurveTo`,
`bezierCurveTo`, `closePath`, `arc`, `arcTo`, `ellipse`, `geometry.rect()`, and `roundRect`.
They use the corresponding Canvas argument order and return void. Nonfinite
builder inputs are ignored; invalid radii follow Canvas exception categories.

`new PathGeometry(source?)` and `clone()` copy independently. `addPath(other,
matrix?)` copies another geometry, optionally transformed, including self-addition.
Native Path2D and SVG-string import are not supported because native paths do
not expose their segments for reading.

`revision` advances on mutation. Save it separately when checking whether an
instance changed: reading two references to the same object cannot recover a
previous revision. Mutation does not schedule a frame or invalidate a retained
Layer; update a separate signal consumed by your component after editing.

`segmentCount` counts canonical segments. `getSegment(index)` returns an
independent `PathSegment`. `setSegment(index, segment)` replaces a segment;
`spliceSegments(start, deleteCount, segments?)` inserts/removes/replaces segments.
Indices are zero-based, and splice requires an in-range nonnegative deletion
count. A nonempty path must start with Move. Failed edits leave it unchanged.

Segment types use these fields:

| Type           | Fields                                                    |
| -------------- | --------------------------------------------------------- |
| `move`, `line` | `x`, `y`                                                  |
| `quadratic`    | `cpx`, `cpy`, `x`, `y`                                    |
| `cubic`        | `cp1x`, `cp1y`, `cp2x`, `cp2y`, `x`, `y`                  |
| `arc`          | `cx`, `cy`, `ux`, `uy`, `vx`, `vy`, `startAngle`, `sweep` |
| `close`        | none                                                      |

An arc is `center + u*cos(t) + v*sin(t)`; its start and signed sweep are in
radians within one revolution. This preserves ellipses through skew and
reflection. Rectangle/rounded-rectangle and arcTo calls resolve to canonical
segments, not a retained history of builder calls. Editing their points does
not rerun those original calls. Iteration yields independent segment values;
mutation during iteration throws. `clear()` removes geometry but retains buffer
capacity for reuse. Segment lookup scans the packed buffer; sequential iteration
is linear overall.

## Transforms and conversion

`transform(matrix)` mutates coordinates using a finite 2D DOMMatrix-compatible
matrix. Matrix dictionaries accept platform aliases/defaults. 3D/perspective
matrices and overflowing coordinates are rejected before modifying geometry.

`toPath2D(geometry)` always returns a fresh caller-owned snapshot.
`toSvgPathData(geometry)` returns absolute SVG data without decimal rounding.
Neither function caches publicly. Ellipses remain analytic; singular transforms
export traversal-preserving lines. Turning-point stroke joins can differ from a
browser's degenerate native ellipse representation.

Path, Clip, explicit event-target and cursor/event-hook inputs accept geometry
alongside native Path2D. Pibbl privately caches by identity and saved revision;
paint, clipping and interaction use the same native snapshot. Already-rendered
hit regions stay unchanged until their consumer renders again. Browser canvas
methods still require `toPath2D` output. Particle path assets snapshot geometry
when defining an effect, consistent with immutable effect ownership.

## Geometry utilities

```ts
import { flattenPath, simplifyPath, subdividePath } from "@pibbl/core";

const lines = flattenPath(geometry, { tolerance: 0.25 });
const reduced = simplifyPath(lines, { tolerance: 0.5 });
const moreHandles = subdividePath(geometry, { divisions: 3 });
```

All three return independent geometry and preserve separate contours/closure.
Their option types are `FlattenPathOptions`, `SimplifyPathOptions`, and
`SubdividePathOptions`. Each accepts optional `maxSegments` (default 1,000,000,
including Move/Close). Exceeding it throws without changing the input.

- Flatten adaptively replaces curves with lines. Required positive `tolerance`
  measures geometric error in input coordinate units. Transform a clone first
  if you need output/tolerance in screen coordinates. Unachievable numerical
  precision or output limits cause an explicit error, not a partial result.
- Simplify removes polyline vertices using required positive `tolerance`. Curved
  inputs require explicit flattening. Open endpoints and closure are preserved;
  nondegenerate closed rings retain at least three distinct vertices. Topology,
  hole preservation, and freedom from new intersections are not promised.
  Its error is relative to the polyline input, so earlier flattening error adds.
- Subdivide splits each segment into a positive integer `divisions`, preserving
  curves up to floating-point precision. Equal parameter intervals do not mean
  equal physical lengths. Closing edges are subdivided and remain closed.

Equal-distance resampling and curve fitting are separate future operations.
Try the [editable path example](/playground/#/examples/drawing/path-geometry).

## Spatial transformations

Use [composable path transforms](/reference/functions/path-transforms/) to apply affine, quad,
envelope, mesh, and bend mappings through `transformPath`. `PathGeometry.transform`
remains the low-level in-place affine operation.

## API details from source

<span id="api-flattenPathWang"></span>

### flattenPathWang

Flattens curves with Wang's uniform-parameter bound.

This trades adaptive placement for a known output count and independent point
evaluation. It is most useful when predictable allocation or parallel output
generation matters more than minimizing the number of line segments.

```ts
flattenPathWang: (path: PathGeometry, options: Readonly<FlattenPathOptions>) => PathGeometry
```

Related API: [flattenPathWang](/reference/functions/path-geometry/), [PathGeometry](/reference/functions/path-geometry/), [FlattenPathOptions](/reference/functions/path-geometry/).

#### Parameters

- **`path`** — Source geometry; it is not modified. See [PathGeometry](/reference/functions/path-geometry/).

- **`options`** — Maximum approximation error and flattening work limits. See
[FlattenPathOptions](/reference/functions/path-geometry/) .

#### Returns

Independent geometry with curves replaced by line segments. See [PathGeometry](/reference/functions/path-geometry/).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[FlattenPathOptions](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-wang.ts:24](/source/packages/core/src/lib/geometry/path-wang-ts/#L24)

<span id="api-simplifyPathRadial"></span>

### simplifyPathRadial

Simplifies line-only paths with a radial-distance prepass followed by the
default Douglas--Peucker implementation. Each stage receives half of the
requested error budget, so their errors compose within `tolerance`.

```ts
simplifyPathRadial: (path: PathGeometry, options: Readonly<SimplifyPathOptions>) => PathGeometry
```

Related API: [simplifyPathRadial](/reference/functions/path-geometry/), [PathGeometry](/reference/functions/path-geometry/), [SimplifyPathOptions](/reference/functions/path-geometry/).

#### Parameters

- **`path`** — Source geometry; it is not modified. See [PathGeometry](/reference/functions/path-geometry/).

- **`options`** — Simplification tolerance and work limits. See [SimplifyPathOptions](/reference/functions/path-geometry/).

#### Returns

Independent geometry with redundant line vertices removed. See [PathGeometry](/reference/functions/path-geometry/).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[SimplifyPathOptions](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-radial.ts:18](/source/packages/core/src/lib/geometry/path-radial-ts/#L18)

<span id="api-PathGeometry"></span>

### PathGeometry

Mutable packed geometry. Mutations do not schedule Pibbl rendering.

```ts
class PathGeometry implements Iterable<PathSegment>
```

Related API: [PathGeometry](/reference/functions/path-geometry/), [PathSegment](/reference/functions/path-geometry/).

#### See also

[PathSegment](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-geometry.ts:143](/source/packages/core/src/lib/geometry/path-geometry-ts/#L143)

#### Properties and methods

<span id="api-PathGeometry-revision"></span>
<details>
<summary>revision</summary>


```ts
readonly revision: number
```

Monotonic mutation revision; changing geometry does not itself request a Pibbl frame. See
PathGeometry.

##### Returns

The mutation revision used to invalidate cached representations.

[View source — packages/core/src/lib/geometry/path-geometry.ts:167](/source/packages/core/src/lib/geometry/path-geometry-ts/#L167)

</details>

<span id="api-PathGeometry-segmentCount"></span>
<details>
<summary>segmentCount</summary>


```ts
readonly segmentCount: number
```

Number of stored path segments, including move and close commands. See PathGeometry.

##### Returns

The number of stored path segments.

[View source — packages/core/src/lib/geometry/path-geometry.ts:172](/source/packages/core/src/lib/geometry/path-geometry-ts/#L172)

</details>

<span id="api-PathGeometry-clone"></span>
<details>
<summary>clone</summary>


```ts
clone: () => PathGeometry
```

Related API: [PathGeometry](/reference/functions/path-geometry/).

Returns an independent copy with its own mutation revision. See PathGeometry.

##### Returns

An independent copy of this path's segments. See [PathGeometry](/reference/functions/path-geometry/).

[View source — packages/core/src/lib/geometry/path-geometry.ts:178](/source/packages/core/src/lib/geometry/path-geometry-ts/#L178)

</details>

<span id="api-PathGeometry-clear"></span>
<details>
<summary>clear</summary>


```ts
clear: () => void
```

Removes all segments and resets the current point. See PathGeometry.

[View source — packages/core/src/lib/geometry/path-geometry.ts:181](/source/packages/core/src/lib/geometry/path-geometry-ts/#L181)

</details>

<span id="api-PathGeometry-moveTo"></span>
<details>
<summary>moveTo</summary>


```ts
moveTo: (x: number, y: number) => void
```

Begins a subpath at the supplied coordinates. See PathGeometry.

##### Parameters

- **`x`** — Horizontal coordinate of the new subpath's starting point.

- **`y`** — Vertical coordinate of the new subpath's starting point.

[View source — packages/core/src/lib/geometry/path-geometry.ts:195](/source/packages/core/src/lib/geometry/path-geometry-ts/#L195)

</details>

<span id="api-PathGeometry-lineTo"></span>
<details>
<summary>lineTo</summary>


```ts
lineTo: (x: number, y: number) => void
```

Appends a straight segment to the supplied coordinates. See PathGeometry.

##### Parameters

- **`x`** — Horizontal coordinate of the line endpoint.

- **`y`** — Vertical coordinate of the line endpoint.

[View source — packages/core/src/lib/geometry/path-geometry.ts:201](/source/packages/core/src/lib/geometry/path-geometry-ts/#L201)

</details>

<span id="api-PathGeometry-quadraticCurveTo"></span>
<details>
<summary>quadraticCurveTo</summary>


```ts
quadraticCurveTo: (cpx: number, cpy: number, x: number, y: number) => void
```

Appends a quadratic curve using one control point and an endpoint. See PathGeometry.

##### Parameters

- **`cpx`** — Horizontal coordinate of the quadratic control point.

- **`cpy`** — Vertical coordinate of the quadratic control point.

- **`x`** — Horizontal coordinate of the curve endpoint.

- **`y`** — Vertical coordinate of the curve endpoint.

[View source — packages/core/src/lib/geometry/path-geometry.ts:209](/source/packages/core/src/lib/geometry/path-geometry-ts/#L209)

</details>

<span id="api-PathGeometry-bezierCurveTo"></span>
<details>
<summary>bezierCurveTo</summary>


```ts
bezierCurveTo: (cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number) => void
```

Appends a cubic curve using two control points and an endpoint. See PathGeometry.

##### Parameters

- **`cp1x`** — Horizontal coordinate of the first control point.

- **`cp1y`** — Vertical coordinate of the first control point.

- **`cp2x`** — Horizontal coordinate of the second control point.

- **`cp2y`** — Vertical coordinate of the second control point.

- **`x`** — Horizontal coordinate of the curve endpoint.

- **`y`** — Vertical coordinate of the curve endpoint.

[View source — packages/core/src/lib/geometry/path-geometry.ts:221](/source/packages/core/src/lib/geometry/path-geometry-ts/#L221)

</details>

<span id="api-PathGeometry-closePath"></span>
<details>
<summary>closePath</summary>


```ts
closePath: () => void
```

Closes the current subpath; an already closed or empty path is unchanged. See
PathGeometry.

[View source — packages/core/src/lib/geometry/path-geometry.ts:228](/source/packages/core/src/lib/geometry/path-geometry-ts/#L228)

</details>

<span id="api-PathGeometry-arc"></span>
<details>
<summary>arc</summary>


```ts
arc: (x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean) => void
```

Appends a circular arc using Canvas-compatible angles in radians. See PathGeometry.

##### Parameters

- **`x`** — Horizontal coordinate of the circle center.

- **`y`** — Vertical coordinate of the circle center.

- **`radius`** — Circle radius in path units.

- **`startAngle`** — Starting angle in radians.

- **`endAngle`** — Ending angle in radians.

- **`counterclockwise`** — Whether the arc runs counterclockwise; defaults to false.

[View source — packages/core/src/lib/geometry/path-geometry.ts:243](/source/packages/core/src/lib/geometry/path-geometry-ts/#L243)

</details>

<span id="api-PathGeometry-ellipse"></span>
<details>
<summary>ellipse</summary>


```ts
ellipse: (x: number, y: number, radiusX: number, radiusY: number, rotation: number, startAngle: number, endAngle: number, counterclockwise?: boolean) => void
```

Appends an elliptical arc; rotation and arc angles are in radians. See PathGeometry.

##### Parameters

- **`x`** — Horizontal coordinate of the ellipse center.

- **`y`** — Vertical coordinate of the ellipse center.

- **`radiusX`** — Horizontal radius in path units.

- **`radiusY`** — Vertical radius in path units.

- **`rotation`** — Ellipse rotation in radians.

- **`startAngle`** — Starting angle in radians.

- **`endAngle`** — Ending angle in radians.

- **`counterclockwise`** — Whether the arc runs counterclockwise; defaults to false.

[View source — packages/core/src/lib/geometry/path-geometry.ts:258](/source/packages/core/src/lib/geometry/path-geometry-ts/#L258)

</details>

<span id="api-PathGeometry-arcTo"></span>
<details>
<summary>arcTo</summary>


```ts
arcTo: (x1: number, y1: number, x2: number, y2: number, radius: number) => void
```

Appends a circular arc tangent to two lines using Canvas-compatible geometry. See
PathGeometry.

##### Parameters

- **`x1`** — Horizontal coordinate of the first tangent intersection.

- **`y1`** — Vertical coordinate of the first tangent intersection.

- **`x2`** — Horizontal coordinate of the second tangent endpoint.

- **`y2`** — Vertical coordinate of the second tangent endpoint.

- **`radius`** — Arc radius in path units.

[View source — packages/core/src/lib/geometry/path-geometry.ts:291](/source/packages/core/src/lib/geometry/path-geometry-ts/#L291)

</details>

<span id="api-PathGeometry-rect"></span>
<details>
<summary>rect</summary>


```ts
rect: (x: number, y: number, width: number, height: number) => void
```

Appends a closed rectangle subpath. See PathGeometry.

##### Parameters

- **`x`** — Horizontal coordinate of the rectangle origin.

- **`y`** — Vertical coordinate of the rectangle origin.

- **`width`** — Signed horizontal extent in path units.

- **`height`** — Signed vertical extent in path units.

[View source — packages/core/src/lib/geometry/path-geometry.ts:322](/source/packages/core/src/lib/geometry/path-geometry-ts/#L322)

</details>

<span id="api-PathGeometry-roundRect"></span>
<details>
<summary>roundRect</summary>


```ts
roundRect: (x: number, y: number, width: number, height: number, radii?: number | DOMPointInit | (number | DOMPointInit)[]) => void
```

Appends a closed rectangle with Canvas-compatible corner radii. See PathGeometry.

##### Parameters

- **`x`** — Horizontal coordinate of the rectangle origin.

- **`y`** — Vertical coordinate of the rectangle origin.

- **`width`** — Signed horizontal extent in path units.

- **`height`** — Signed vertical extent in path units.

- **`radii`** — Circular or elliptical corner radii, using Canvas roundRect ordering; defaults
to zero.

[View source — packages/core/src/lib/geometry/path-geometry.ts:345](/source/packages/core/src/lib/geometry/path-geometry-ts/#L345)

</details>

<span id="api-PathGeometry-addPath"></span>
<details>
<summary>addPath</summary>


```ts
addPath: (other: PathGeometry, matrix?: DOMMatrix2DInit) => void
```

Related API: [PathGeometry](/reference/functions/path-geometry/).

Appends a copy of another path, optionally transformed by a 2D matrix. See
PathGeometry.

##### Parameters

- **`other`** — Geometry whose segments are appended. See [PathGeometry](/reference/functions/path-geometry/).

- **`matrix`** — Optional affine transform applied to the appended segments; defaults to
identity.

[View source — packages/core/src/lib/geometry/path-geometry.ts:388](/source/packages/core/src/lib/geometry/path-geometry-ts/#L388)

</details>

<span id="api-PathGeometry-spliceSegments"></span>
<details>
<summary>spliceSegments</summary>


```ts
spliceSegments: (start: number, deleteCount: number, segments?: readonly PathSegment[]) => void
```

Related API: [PathSegment](/reference/functions/path-geometry/).

Replaces a segment range with validated independent segment values. See PathGeometry.

##### Parameters

- **`start`** — Index at which to begin replacing segments.

- **`deleteCount`** — Number of segments to remove.

- **`segments`** — Replacement segments; defaults to no inserted segments. See
[PathSegment](/reference/functions/path-geometry/) .

[View source — packages/core/src/lib/geometry/path-geometry.ts:419](/source/packages/core/src/lib/geometry/path-geometry-ts/#L419)

</details>

<span id="api-PathGeometry-getSegment"></span>
<details>
<summary>getSegment</summary>


```ts
getSegment: (index: number) => PathSegment
```

Related API: [PathSegment](/reference/functions/path-geometry/).

Returns an independent segment value at the specified index. See PathSegment.

##### Parameters

- **`index`** — Zero-based segment index.

##### Returns

The segment at the requested index. See [PathSegment](/reference/functions/path-geometry/).

[View source — packages/core/src/lib/geometry/path-geometry.ts:480](/source/packages/core/src/lib/geometry/path-geometry-ts/#L480)

</details>

<span id="api-PathGeometry-setSegment"></span>
<details>
<summary>setSegment</summary>


```ts
setSegment: (index: number, segment: PathSegment) => void
```

Related API: [PathSegment](/reference/functions/path-geometry/).

Replaces one stored segment with a validated independent value. See PathGeometry.

##### Parameters

- **`index`** — Zero-based index of the segment to replace.

- **`segment`** — Replacement segment data. See [PathSegment](/reference/functions/path-geometry/).

[View source — packages/core/src/lib/geometry/path-geometry.ts:489](/source/packages/core/src/lib/geometry/path-geometry-ts/#L489)

</details>

<span id="api-PathGeometry-transform"></span>
<details>
<summary>transform</summary>


```ts
transform: (matrix: DOMMatrix2DInit) => void
```

Applies a finite 2D affine matrix. Old native conversions remain unchanged.

##### Parameters

- **`matrix`** — Affine matrix applied to all segments in this path.

[View source — packages/core/src/lib/geometry/path-geometry.ts:512](/source/packages/core/src/lib/geometry/path-geometry-ts/#L512)

</details>

<span id="api-PathSegment"></span>

### PathSegment

A canonical, independently editable path segment.

<details>
<summary>Full type declaration</summary>

```ts
type PathSegment = | {
      /** Selects `"move"`, `"line"` for type. See {@link PathSegment}. */
      type: 'move' | 'line';
      /**
       * Horizontal coordinate or displacement in the containing coordinate system. See
       * {@link PathSegment}.
       */
      x: number;
      /**
       * Vertical coordinate or displacement in the containing coordinate system. See
       * {@link PathSegment}.
       */
      y: number;
    }
  | {
      /** The literal "quadratic" identifying this variant. See {@link PathSegment}. */
      type: 'quadratic';
      /** Horizontal coordinate of the quadratic control point. See {@link PathSegment}. */
      cpx: number;
      /** Vertical coordinate of the quadratic control point. See {@link PathSegment}. */
      cpy: number;
      /**
       * Horizontal coordinate or displacement in the containing coordinate system. See
       * {@link PathSegment}.
       */
      x: number;
      /**
       * Vertical coordinate or displacement in the containing coordinate system. See
       * {@link PathSegment}.
       */
      y: number;
    }
  | {
      /** The literal "cubic" identifying this variant. See {@link PathSegment}. */
      type: 'cubic';
      /** Horizontal coordinate of the first cubic control point. See {@link PathSegment}. */
      cp1x: number;
      /** Vertical coordinate of the first cubic control point. See {@link PathSegment}. */
      cp1y: number;
      /** Horizontal coordinate of the second cubic control point. See {@link PathSegment}. */
      cp2x: number;
      /** Vertical coordinate of the second cubic control point. See {@link PathSegment}. */
      cp2y: number;
      /**
       * Horizontal coordinate or displacement in the containing coordinate system. See
       * {@link PathSegment}.
       */
      x: number;
      /**
       * Vertical coordinate or displacement in the containing coordinate system. See
       * {@link PathSegment}.
       */
      y: number;
    }
  | ArcSegment
  | {
      /** The literal "close" identifying this variant. See {@link PathSegment}. */
      type: 'close';
    }
```

</details>

Related API: [PathSegment](/reference/functions/path-geometry/), [displacement](/reference/types/filters/#displacement).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-geometry.ts:7](/source/packages/core/src/lib/geometry/path-geometry-ts/#L7)

#### Properties and methods

<span id="api-PathSegment-type"></span>
<details>
<summary>type</summary>


```ts
type: "arc" | "close" | "cubic" | "line" | "move" | "quadratic"
```

Selects `"move"`, `"line"` for type. See PathSegment.
The literal "quadratic" identifying this variant. See PathSegment.
The literal "cubic" identifying this variant. See PathSegment.
The literal "close" identifying this variant. See PathSegment.

[View source — packages/core/src/lib/geometry/path-arc.ts:3](/source/packages/core/src/lib/geometry/path-arc-ts/#L3)

</details>

<span id="api-toPath2D"></span>

### toPath2D

Creates a fresh caller-owned native snapshot; never returns a shared cache.

```ts
toPath2D: (geometry: PathGeometry) => Path2D
```

Related API: [toPath2D](/reference/functions/path-geometry/), [PathGeometry](/reference/functions/path-geometry/).

#### Parameters

- **`geometry`** — Pibbl geometry to convert. See [PathGeometry](/reference/functions/path-geometry/).

#### Returns

A native Canvas path representing the geometry.

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-conversion.ts:12](/source/packages/core/src/lib/geometry/path-conversion-ts/#L12)

<span id="api-toSvgPathData"></span>

### toSvgPathData

Serializes independent absolute SVG path data without implicit rounding.

```ts
toSvgPathData: (geometry: PathGeometry) => string
```

Related API: [toSvgPathData](/reference/functions/path-geometry/), [PathGeometry](/reference/functions/path-geometry/).

#### Parameters

- **`geometry`** — Pibbl geometry to serialize. See [PathGeometry](/reference/functions/path-geometry/).

#### Returns

SVG path data representing the geometry.

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-conversion.ts:47](/source/packages/core/src/lib/geometry/path-conversion-ts/#L47)

<span id="api-flattenPath"></span>

### flattenPath

Returns independent geometry with curves approximated by line segments within the requested
tolerance.

```ts
flattenPath: (path: PathGeometry, options: Readonly<FlattenPathOptions>) => PathGeometry
```

Related API: [flattenPath](/reference/functions/path-geometry/), [PathGeometry](/reference/functions/path-geometry/), [FlattenPathOptions](/reference/functions/path-geometry/).

#### Parameters

- **`path`** — Source geometry; it is not modified. See [PathGeometry](/reference/functions/path-geometry/).

- **`options`** — Maximum approximation error and flattening work limits. See
[FlattenPathOptions](/reference/functions/path-geometry/) .

#### Returns

Independent geometry with curves replaced by line segments. See [PathGeometry](/reference/functions/path-geometry/).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[FlattenPathOptions](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-utilities.ts:62](/source/packages/core/src/lib/geometry/path-utilities-ts/#L62)

<span id="api-simplifyPath"></span>

### simplifyPath

Returns independent polyline geometry with redundant points removed within the requested
tolerance.

```ts
simplifyPath: (path: PathGeometry, options: Readonly<SimplifyPathOptions>) => PathGeometry
```

Related API: [simplifyPath](/reference/functions/path-geometry/), [PathGeometry](/reference/functions/path-geometry/), [SimplifyPathOptions](/reference/functions/path-geometry/).

#### Parameters

- **`path`** — Source geometry; it is not modified. See [PathGeometry](/reference/functions/path-geometry/).

- **`options`** — Simplification tolerance and work limits. See [SimplifyPathOptions](/reference/functions/path-geometry/).

#### Returns

Independent geometry with redundant line vertices removed. See [PathGeometry](/reference/functions/path-geometry/).

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[SimplifyPathOptions](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-utilities.ts:164](/source/packages/core/src/lib/geometry/path-utilities-ts/#L164)

<span id="api-subdividePath"></span>

### subdividePath

Returns independent geometry with each drawable segment split into the requested number of
pieces.

```ts
subdividePath: (path: PathGeometry, options: Readonly<SubdividePathOptions>) => PathGeometry
```

Related API: [subdividePath](/reference/functions/path-geometry/), [PathGeometry](/reference/functions/path-geometry/), [SubdividePathOptions](/reference/functions/path-geometry/).

#### Parameters

- **`path`** — Source geometry; it is not modified. See [PathGeometry](/reference/functions/path-geometry/).

- **`options`** — Subdivision length and work limits. See [SubdividePathOptions](/reference/functions/path-geometry/).

#### Returns

Independent geometry with segments split according to the requested limits. See
[PathGeometry](/reference/functions/path-geometry/) .

#### See also

[PathGeometry](/reference/functions/path-geometry/)

[SubdividePathOptions](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-utilities.ts:108](/source/packages/core/src/lib/geometry/path-utilities-ts/#L108)

<span id="api-FlattenPathOptions"></span>

### FlattenPathOptions

Positive approximation tolerance and output-segment budget for curve flattening.

```ts
interface FlattenPathOptions
```

Related API: [FlattenPathOptions](/reference/functions/path-geometry/).

#### See also

[flattenPath](/reference/functions/path-geometry/)

[flattenPathWang](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-utilities.ts:14](/source/packages/core/src/lib/geometry/path-utilities-ts/#L14)

#### Properties and methods

<span id="api-FlattenPathOptions-tolerance"></span>
<details>
<summary>tolerance</summary>


```ts
readonly tolerance: number
```

Positive maximum geometric approximation error. See FlattenPathOptions.

[View source — packages/core/src/lib/geometry/path-utilities.ts:16](/source/packages/core/src/lib/geometry/path-utilities-ts/#L16)

</details>

<span id="api-FlattenPathOptions-maxSegments"></span>
<details>
<summary>maxSegments (optional)</summary>


```ts
readonly maxSegments?: number | undefined
```

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

[View source — packages/core/src/lib/geometry/path-utilities.ts:18](/source/packages/core/src/lib/geometry/path-utilities-ts/#L18)

</details>

<span id="api-SimplifyPathOptions"></span>

### SimplifyPathOptions

Positive tolerance and output-segment budget for polyline simplification.

```ts
interface SimplifyPathOptions
```

Related API: [SimplifyPathOptions](/reference/functions/path-geometry/).

#### See also

[simplifyPath](/reference/functions/path-geometry/)

[simplifyPathRadial](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-utilities.ts:27](/source/packages/core/src/lib/geometry/path-utilities-ts/#L27)

#### Properties and methods

<span id="api-SimplifyPathOptions-tolerance"></span>
<details>
<summary>tolerance</summary>


```ts
readonly tolerance: number
```

Positive maximum geometric approximation error. See SimplifyPathOptions.

[View source — packages/core/src/lib/geometry/path-utilities.ts:29](/source/packages/core/src/lib/geometry/path-utilities-ts/#L29)

</details>

<span id="api-SimplifyPathOptions-maxSegments"></span>
<details>
<summary>maxSegments (optional)</summary>


```ts
readonly maxSegments?: number | undefined
```

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

[View source — packages/core/src/lib/geometry/path-utilities.ts:31](/source/packages/core/src/lib/geometry/path-utilities-ts/#L31)

</details>

<span id="api-SubdividePathOptions"></span>

### SubdividePathOptions

Subdivision count and output-segment budget for splitting path segments.

```ts
interface SubdividePathOptions
```

Related API: [SubdividePathOptions](/reference/functions/path-geometry/).

#### See also

[subdividePath](/reference/functions/path-geometry/)

[View source — packages/core/src/lib/geometry/path-utilities.ts:39](/source/packages/core/src/lib/geometry/path-utilities-ts/#L39)

#### Properties and methods

<span id="api-SubdividePathOptions-divisions"></span>
<details>
<summary>divisions</summary>


```ts
readonly divisions: number
```

Number of pieces produced from each drawable path segment. See SubdividePathOptions.

[View source — packages/core/src/lib/geometry/path-utilities.ts:43](/source/packages/core/src/lib/geometry/path-utilities-ts/#L43)

</details>

<span id="api-SubdividePathOptions-maxSegments"></span>
<details>
<summary>maxSegments (optional)</summary>


```ts
readonly maxSegments?: number | undefined
```

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

[View source — packages/core/src/lib/geometry/path-utilities.ts:45](/source/packages/core/src/lib/geometry/path-utilities-ts/#L45)

</details>

## Implementation guidance for agents

Read the [Drawing, layout, and effects companion](/agents/topics/layout/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Editable path geometry](/minimal-examples/paths/geometry/): Build a cubic path, convert it, and compare flattening and simplification utilities. [Plain source](/minimal/paths/geometry.ts)
## Interactive examples

- [Path playground](/examples/path-geometry/) · [Full page](/experience/path-geometry/)
- [Editable text outlines](/examples/text-geometry/) · [Full page](/experience/text-geometry/)
- [Four-corner path warp](/examples/path-warp/) · [Full page](/experience/path-warp/)
- [Along Arc](/examples/path-bending/) · [Full page](/experience/path-bending/)
- [Along Path](/examples/along-path/) · [Full page](/experience/along-path/)
- [Text envelope playground](/examples/text-envelope/) · [Full page](/experience/text-envelope/)
## Documentation version

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