@weasel-js/geom 1.10.1 → 1.11.1

package/dist/warp/index.d.ts

@@ -0,0 +1,254 @@
+import { b as Point, P as PolygonPath } from '../path-BW8d_2RY.js';
+
+/**
+ * Maps from the unit square onto a quadrilateral: what a box becomes when its
+ * four corners are dragged apart independently.
+ */
+
+/** Four corners, in the order the unit square's land on them: (0,0), (1,0),
+ *  (1,1), (0,1) — a box's top-left, top-right, bottom-right, bottom-left. */
+type Quad = readonly [Point, Point, Point, Point];
+/** A map from unit-square coordinates to the plane. */
+type UvMap = (u: number, v: number) => Point;
+/**
+ * The bilinear map onto `q`: each corner weighted by its share of the square.
+ * Lines of constant `u` or `v` stay straight; any other line bends.
+ */
+declare function bilinearQuad(q: Quad): UvMap;
+/**
+ * The projective map taking the unit square onto `q`, as `[a, b, c, d, e, f,
+ * g, h]`: `x = (a·u + b·v + c) / w` and `y = (d·u + e·v + f) / w`, where
+ * `w = g·u + h·v + 1`. Null when `q` is not strictly convex, since no
+ * projective map then sends the square's inside onto the quad's.
+ */
+declare function squareToQuadHomography(q: Quad): readonly number[] | null;
+/**
+ * The projective map onto `q`: straight lines stay straight, and the box's far
+ * side foreshortens the way a plane seen at an angle does. Null where
+ * {@link squareToQuadHomography} is.
+ */
+declare function projectiveQuad(q: Quad): UvMap | null;
+
+/**
+ * Maps from the unit square through a grid of control points: an envelope
+ * mesh. The grid's points are interpolated, so a grid laid evenly over a box
+ * maps the box onto itself.
+ */
+
+/** A grid of `rows` × `cols` patches: `(rows + 1) × (cols + 1)` points, row by
+ *  row from the top. */
+interface MeshGrid {
+    rows: number;
+    cols: number;
+    points: readonly Point[];
+}
+/** An even grid of `rows` × `cols` patches over the box. */
+declare function meshGridOver(box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, rows: number, cols: number): MeshGrid;
+/** A grid of `rows` × `cols` patches whose points are where `map` sends an
+ *  even grid over the unit square — a mesh resampled at a new resolution. */
+declare function meshGridFrom(map: UvMap, rows: number, cols: number): MeshGrid;
+/**
+ * The smooth surface through every grid point: a Catmull-Rom spline along each
+ * row, and another down the columns through those. Bending one point bends its
+ * neighborhood smoothly, across patch edges included.
+ */
+declare function bicubicMesh(grid: MeshGrid): UvMap;
+/**
+ * One Coons patch per grid cell: the cell's four edges are the splines through
+ * the grid lines, and its inside is blended from those edges alone. Edges
+ * match the bicubic surface; the inside follows them more literally, without
+ * the bicubic surface's pull from points beyond the cell.
+ */
+declare function coonsMesh(grid: MeshGrid): UvMap;
+
+/** A triangle mesh at rest: interleaved `x, y` vertices and vertex-index triples. */
+interface ArapMesh {
+    vertices: Float64Array;
+    triangles: Uint32Array;
+}
+/**
+ * A stage of a solve: `similarity` is the first linear step, `rigid` the
+ * second, `local-global` each round after them, and `injective` each round
+ * of the pass that runs when those leave a triangle turned over. That pass's
+ * last step is the result: its pins set exactly, or the local/global result
+ * again when the pins cannot be set without a fold.
+ */
+type ArapStage = 'similarity' | 'rigid' | 'local-global' | 'injective';
+/** A solve's state after one stage: every vertex's position, interleaved `x, y`. */
+interface ArapStep {
+    stage: ArapStage;
+    /** Which round of its stage, from 1. */
+    round: number;
+    vertices: Float64Array;
+}
+/** Options for {@link ArapSolver.solve}. */
+interface ArapSolveOptions {
+    /** The most local/global rounds to run after the two linear steps; 0
+     *  returns their result alone. Rounds stop early once the mesh settles.
+     *  Default {@link ARAP_ROUNDS}. */
+    iterations?: number;
+    /** The most rounds of the injective pass; 0 skips it. Default
+     *  {@link ARAP_INJECTIVE_ROUNDS}. */
+    injectiveIterations?: number;
+    /** Called with the state after each stage, in order; the last call carries
+     *  the result. A step's `vertices` is the caller's to keep. */
+    trace?: (step: ArapStep) => void;
+}
+/** A factored deformation; `solve` takes each pinned vertex's target, as
+ *  interleaved `x, y` in pin order, and returns every vertex's position. */
+interface ArapSolver {
+    solve(targets: ArrayLike<number>, opts?: ArapSolveOptions): Float64Array;
+}
+/** The default most local/global rounds per solve. */
+declare const ARAP_ROUNDS = 5;
+/** The default most injective rounds per solve. */
+declare const ARAP_INJECTIVE_ROUNDS = 100;
+/**
+ * Factor the deformation of `mesh` with vertices `pinned` held. A piece of
+ * the mesh holding two pins or more deforms as rigidly as they allow; one
+ * holding a single pin moves with it; one holding none moves rigidly with the
+ * pins as a whole.
+ */
+declare function createArapSolver(mesh: ArapMesh, pinned: readonly number[]): ArapSolver;
+
+/** A puppet's mesh, and the vertex standing for each pin. */
+interface PuppetMesh extends ArapMesh {
+    pinVertex: Int32Array;
+}
+/** Options for {@link puppetMesh}. */
+interface PuppetMeshOptions {
+    /** Roughly how many vertices to spread over the region. Default 400. */
+    vertices?: number;
+}
+/**
+ * The mesh a puppet with pins at `pins` deforms over `path`'s fill. A pin
+ * inside the fill gets a vertex where it is; one on the outline, or off the
+ * shape, gets the nearest point of the outline. Pins on one spot share a vertex.
+ */
+declare function puppetMesh(path: PolygonPath, pins: readonly Point[], opts?: PuppetMeshOptions): PuppetMesh;
+
+/**
+ * Puppet deformation: pins placed on a shape and dragged, with everything
+ * between them moved as rigidly as the pins allow. The shape's fill is
+ * triangulated (`puppetMesh`) and deformed as-rigid-as-possible (`arap`), so
+ * the pull of a pin travels through the shape: two limbs that nearly touch
+ * share no triangle and move apart. A point is carried by a smooth
+ * (Clough–Tocher) interpolation of the deformed mesh, so a bend has no kink
+ * where two triangles meet.
+ */
+
+/** A pin: where it was placed on the unwarped shape, and where it is now. */
+interface PuppetPin {
+    from: Point;
+    to: Point;
+}
+/**
+ * The map `pins` make of `source`'s fill: smooth across the deformed mesh,
+ * through every pin, and carried on past the outline for a point off the
+ * shape. The mesh and its solve are set up once per source and pin set, so
+ * moving pins only re-solves. No pins, or none moved, is the identity, and
+ * one pin moves the whole shape with it.
+ */
+declare function puppetMap(source: PolygonPath, pins: readonly PuppetPin[]): (p: Point) => Point;
+/**
+ * The mesh `puppetMap` deforms for `pins` and where its vertices land, solved
+ * with `opts` — its `trace` reports every stage of the solve, and its round
+ * caps bound it. With the default options the vertices are the ones
+ * `puppetMap` places points by. Null with no pins, or when none landed on the
+ * mesh (then `puppetMap` moves the shape with the first pin).
+ */
+declare function puppetSolve(source: PolygonPath, pins: readonly PuppetPin[], opts?: ArapSolveOptions): {
+    mesh: PuppetMesh;
+    vertices: Float64Array;
+} | null;
+/**
+ * The point `map` sends to `target`, found by stepping from `guess` by the
+ * miss until it is within `tolerance` — for a map that stays close to rigid,
+ * as a puppet's does, a few steps suffice. Returns the best point found.
+ */
+declare function unwarpPoint(map: (p: Point) => Point, target: Point, guess?: Point, tolerance?: number): Point;
+
+/** Options for {@link warpPath}. */
+interface WarpPathOptions {
+    /** How far, in output units, the refitted curves may stray from the warped
+     *  original. Default 0.5. */
+    tolerance?: number;
+}
+/**
+ * `path` carried through `map`, point by point, and refitted as cubics within
+ * `tolerance` of the warped curve. Every anchor stays an anchor, at the point
+ * it maps to, so the result edits like the original; a segment the map keeps
+ * straight stays a straight segment, and one it bends gains anchors only where
+ * one cubic cannot follow it. Fill rules carry over.
+ */
+declare function warpPath(path: PolygonPath, map: (p: Point) => Point, opts?: WarpPathOptions): PolygonPath;
+
+/**
+ * A warp as data: what a shape was warped by, held beside the shape so the
+ * warp can be edited again later. Each kind names its controls in the same
+ * space as the path it warps.
+ */
+
+/** An axis-aligned box: the area a distort or an envelope was laid over. */
+interface WarpBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** How a distort maps its box onto its corners. `free` is bilinear, and bends
+ *  straight lines; `perspective` is projective, and keeps them straight. */
+type DistortMode = 'free' | 'perspective';
+/** How an envelope interpolates its mesh. See `bicubicMesh` and `coonsMesh`. */
+type EnvelopeMapping = 'bicubic' | 'coons';
+/** The box's four corners, each dragged on its own. */
+interface DistortWarp {
+    kind: 'distort';
+    mode: DistortMode;
+    box: WarpBox;
+    /** Where the box's top-left, top-right, bottom-right and bottom-left went. */
+    corners: Quad;
+}
+/** A grid of control points laid over the box. */
+interface EnvelopeWarp {
+    kind: 'envelope';
+    mapping: EnvelopeMapping;
+    box: WarpBox;
+    mesh: MeshGrid;
+}
+/** Pins on the shape, each dragged on its own. */
+interface PuppetWarp {
+    kind: 'puppet';
+    pins: readonly PuppetPin[];
+}
+/** Any of the warps a path can hold. */
+type PathWarp = DistortWarp | EnvelopeWarp | PuppetWarp;
+/** A distort over `box` that leaves it where it is. */
+declare function distortOver(box: WarpBox, mode?: DistortMode): DistortWarp;
+/** An envelope of `rows` × `cols` patches over `box` that leaves it where it is. */
+declare function envelopeOver(box: WarpBox, rows: number, cols: number, mapping?: EnvelopeMapping): EnvelopeWarp;
+/** `warp` with a mesh of `rows` × `cols` patches, placed where the current
+ *  mesh carries an even grid, so the shape changes as little as a coarser or
+ *  finer grid allows. */
+declare function resizeEnvelope(warp: EnvelopeWarp, rows: number, cols: number): EnvelopeWarp;
+/**
+ * Where `warp`, laid over `source`, sends each point of the plane. A
+ * perspective distort whose corners no longer make a convex quad has no
+ * projective map, and falls back to the bilinear one until they do. Only a
+ * puppet reads `source`: its pins pull through the shape's fill.
+ */
+declare function pathWarpMap(warp: PathWarp, source: PolygonPath): (p: Point) => Point;
+/** `source` warped by `warp`, refitted within `tolerance` (`warpPath`). */
+declare function applyPathWarp(source: PolygonPath, warp: PathWarp, tolerance?: number): PolygonPath;
+/** The points a user drags to change `warp`: a distort's corners, an
+ *  envelope's mesh points, a puppet's pins where they are now. */
+declare function warpControls(warp: PathWarp): readonly Point[];
+/** `warp` with control `index` (as {@link warpControls} counts them) at `to`. */
+declare function moveWarpControl(warp: PathWarp, index: number, to: Point): PathWarp;
+
+export { ARAP_INJECTIVE_ROUNDS, ARAP_ROUNDS, type ArapMesh, type ArapSolveOptions, type ArapSolver, type ArapStage, type ArapStep, type DistortMode, type DistortWarp, type EnvelopeMapping, type EnvelopeWarp, type MeshGrid, type PathWarp, type PuppetMesh, type PuppetMeshOptions, type PuppetPin, type PuppetWarp, type Quad, type UvMap, type WarpBox, type WarpPathOptions, applyPathWarp, bicubicMesh, bilinearQuad, coonsMesh, createArapSolver, distortOver, envelopeOver, meshGridFrom, meshGridOver, moveWarpControl, pathWarpMap, projectiveQuad, puppetMap, puppetMesh, puppetSolve, resizeEnvelope, squareToQuadHomography, unwarpPoint, warpControls, warpPath };