@pibbl/core 0.0.1

package/dist/lib/geometry/path-radial.js

@@ -0,0 +1,107 @@
+import { PathGeometry } from "./path-geometry.js";
+import { simplifyPath } from "./path-utilities.js";
+function simplifyPathRadial(path, options) {
+  const tolerance = requiredPositive(options.tolerance, "tolerance");
+  const stageTolerance = tolerance / 2;
+  if (stageTolerance === 0) return simplifyPath(path, options);
+  const filtered = new PathGeometry();
+  let current;
+  let start;
+  let run = [];
+  const flushOpen = () => {
+    if (!run.length) return;
+    appendOpen(filtered, radialFilterOpen(run, stageTolerance));
+    run = current ? [current] : [];
+  };
+  for (const segment of path) {
+    switch (segment.type) {
+      case "move":
+        flushOpen();
+        current = start = [segment.x, segment.y];
+        run = [current];
+        filtered.moveTo(segment.x, segment.y);
+        break;
+      case "line":
+        current = [segment.x, segment.y];
+        run.push(current);
+        break;
+      case "close": {
+        if (!current || !start) throw new TypeError("simplifyPathRadial requires a move segment before close.");
+        const raw = withoutClosingDuplicate(run);
+        const radial = radialFilterClosed(raw, stageTolerance);
+        appendOpen(filtered, radial.length >= 3 && hasThreeDistinct(radial) ? radial : raw);
+        filtered.closePath();
+        current = start;
+        run = [current];
+        break;
+      }
+      default:
+        throw new TypeError("simplifyPathRadial requires line-only geometry.");
+    }
+  }
+  flushOpen();
+  return simplifyPath(filtered, { tolerance: stageTolerance, maxSegments: options.maxSegments });
+}
+function appendOpen(path, points) {
+  for (const [x, y] of points.slice(1)) path.lineTo(x, y);
+}
+function radialFilterOpen(points, tolerance) {
+  if (points.length <= 2) return [...points];
+  const result = [points[0]];
+  let previous = points[0];
+  for (let i = 1; i < points.length - 1; i++) {
+    if (distance(points[i], previous) > tolerance) {
+      result.push(points[i]);
+      previous = points[i];
+    }
+  }
+  const last = points.at(-1);
+  if (!samePoint(previous, last)) result.push(last);
+  return result;
+}
+function radialFilterClosed(points, tolerance) {
+  if (points.length <= 3) return [...points];
+  const result = [points[0]];
+  let previous = points[0];
+  for (let i = 1; i < points.length; i++) {
+    if (distance(points[i], previous) > tolerance) {
+      result.push(points[i]);
+      previous = points[i];
+    }
+  }
+  return result;
+}
+function withoutClosingDuplicate(points) {
+  return points.length > 1 && samePoint(points[0], points.at(-1)) ? points.slice(0, -1) : [...points];
+}
+function hasThreeDistinct(points) {
+  let first;
+  let second;
+  for (const point of points) {
+    if (!first) {
+      first = point;
+      continue;
+    }
+    if (samePoint(point, first)) continue;
+    if (!second) {
+      second = point;
+      continue;
+    }
+    if (!samePoint(point, second)) return true;
+  }
+  return false;
+}
+function requiredPositive(value, name) {
+  if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a finite positive number.`);
+  return value;
+}
+function samePoint(a, b) {
+  return a[0] === b[0] && a[1] === b[1];
+}
+function distance(a, b) {
+  return Math.hypot(a[0] - b[0], a[1] - b[1]);
+}
+export {
+  simplifyPathRadial
+};
+//# sourceMappingURL=path-radial.js.map

package/dist/lib/geometry/path-radial.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/geometry/path-radial.ts"],
+  "sourcesContent": ["import { PathGeometry } from './path-geometry.js';\nimport { simplifyPath, type SimplifyPathOptions } from './path-utilities.js';\n\ntype Point = readonly [number, number];\n\n/**\n * Simplifies line-only paths with a radial-distance prepass followed by the\n * default Douglas--Peucker implementation. Each stage receives half of the\n * requested error budget, so their errors compose within `tolerance`.\n *\n * @param path - Source geometry; it is not modified. See {@link PathGeometry}.\n * @param options - Simplification tolerance and work limits. See {@link SimplifyPathOptions}.\n * @returns Independent geometry with redundant line vertices removed. See {@link PathGeometry}.\n *\n * @see {@link PathGeometry}\n * @see {@link SimplifyPathOptions}\n */\nexport function simplifyPathRadial(path: PathGeometry, options: Readonly<SimplifyPathOptions>): PathGeometry {\n  const tolerance = requiredPositive(options.tolerance, 'tolerance');\n  const stageTolerance = tolerance / 2;\n  // A two-stage split cannot represent half of the smallest subnormal number\n  // without exceeding the caller's error budget. Retain the exact default\n  // contract in that case instead of applying the radial prepass.\n  if (stageTolerance === 0) return simplifyPath(path, options);\n  const filtered = new PathGeometry();\n  let current: Point | undefined;\n  let start: Point | undefined;\n  let run: Point[] = [];\n  const flushOpen = () => {\n    if (!run.length) return;\n    appendOpen(filtered, radialFilterOpen(run, stageTolerance));\n    run = current ? [current] : [];\n  };\n  for (const segment of path) {\n    switch (segment.type) {\n      case 'move':\n        flushOpen();\n        current = start = [segment.x, segment.y];\n        run = [current];\n        filtered.moveTo(segment.x, segment.y);\n        break;\n      case 'line':\n        current = [segment.x, segment.y];\n        run.push(current);\n        break;\n      case 'close': {\n        if (!current || !start) throw new TypeError('simplifyPathRadial requires a move segment before close.');\n        const raw = withoutClosingDuplicate(run);\n        const radial = radialFilterClosed(raw, stageTolerance);\n        // Do not make a valid closed subpath degenerate. The raw path is an\n        // exact fallback, and the shared DP stage will enforce the same rule.\n        appendOpen(filtered, radial.length >= 3 && hasThreeDistinct(radial) ? radial : raw);\n        filtered.closePath();\n        current = start;\n        run = [current];\n        break;\n      }\n      default: throw new TypeError('simplifyPathRadial requires line-only geometry.');\n    }\n  }\n  flushOpen();\n  return simplifyPath(filtered, { tolerance: stageTolerance, maxSegments: options.maxSegments });\n}\n\nfunction appendOpen(path: PathGeometry, points: readonly Point[]): void {\n  for (const [x, y] of points.slice(1)) path.lineTo(x, y);\n}\n\nfunction radialFilterOpen(points: readonly Point[], tolerance: number): Point[] {\n  if (points.length <= 2) return [...points];\n  const result: Point[] = [points[0]];\n  let previous = points[0];\n  for (let i = 1; i < points.length - 1; i++) {\n    if (distance(points[i], previous) > tolerance) {\n      result.push(points[i]);\n      previous = points[i];\n    }\n  }\n  const last = points.at(-1)!;\n  if (!samePoint(previous, last)) result.push(last);\n  return result;\n}\n\nfunction radialFilterClosed(points: readonly Point[], tolerance: number): Point[] {\n  if (points.length <= 3) return [...points];\n  const result: Point[] = [points[0]];\n  let previous = points[0];\n  for (let i = 1; i < points.length; i++) {\n    if (distance(points[i], previous) > tolerance) {\n      result.push(points[i]);\n      previous = points[i];\n    }\n  }\n  return result;\n}\n\nfunction withoutClosingDuplicate(points: readonly Point[]): Point[] {\n  return points.length > 1 && samePoint(points[0], points.at(-1)!) ? points.slice(0, -1) : [...points];\n}\nfunction hasThreeDistinct(points: readonly Point[]): boolean {\n  let first: Point | undefined;\n  let second: Point | undefined;\n  for (const point of points) {\n    if (!first) { first = point; continue; }\n    if (samePoint(point, first)) continue;\n    if (!second) { second = point; continue; }\n    if (!samePoint(point, second)) return true;\n  }\n  return false;\n}\nfunction requiredPositive(value: number, name: string): number {\n  if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a finite positive number.`);\n  return value;\n}\nfunction samePoint(a: Point, b: Point): boolean { return a[0] === b[0] && a[1] === b[1]; }\nfunction distance(a: Point, b: Point): number { return Math.hypot(a[0] - b[0], a[1] - b[1]); }\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/geometry/path-transforms.d.ts

@@ -0,0 +1,233 @@
+import { PathGeometry } from './path-geometry.js';
+import { type Pair } from './transform-math.js';
+import { type PathGuide } from './transform-guide.js';
+import { type PathWarpCorners, type PathWarpMode } from './path-warp.js';
+/**
+ * A point in source or destination path coordinates.
+ *
+ * @see {@link PathTransform}
+ * @see {@link PathRect}
+ */
+export interface PathPoint {
+    /**
+     * Horizontal coordinate or displacement in the containing coordinate system. See
+     * {@link PathPoint}.
+     */
+    readonly x: number;
+    /**
+     * Vertical coordinate or displacement in the containing coordinate system. See {@link PathPoint}
+     * .
+     */
+    readonly y: number;
+}
+/**
+ * A source rectangle with an origin and finite positive dimensions.
+ *
+ * @see {@link PathPoint}
+ * @see {@link QuadTransformOptions}
+ * @see {@link EnvelopeTransformOptions}
+ */
+export interface PathRect extends PathPoint {
+    /** Horizontal extent in the units of the containing geometry or surface. See {@link PathRect}. */
+    readonly width: number;
+    /** Vertical extent in the units of the containing geometry or surface. See {@link PathRect}. */
+    readonly height: number;
+}
+declare const transformBrand: unique symbol;
+/**
+ * A constructor-created, reusable coordinate mapping for path transformation.
+ *
+ * @see {@link PathPoint}
+ * @see {@link transformPath}
+ * @see {@link composeTransforms}
+ * @see {@link affineTransform}
+ */
+export interface PathTransform {
+    readonly [transformBrand]: true;
+    /**
+     * Evaluate in ordinary source/destination coordinates. Guide approximation is bounded by
+     * tolerance.
+     * @param point - Source point in the transform's input coordinate system. See {@link PathPoint}.
+     * @param options - Optional approximation tolerance for evaluating the mapping.
+     * @returns The mapped point in the transform's output coordinate system. See {@link PathPoint}.
+     */
+    mapPoint(point: PathPoint, options?: {
+        /** Positive maximum geometric approximation error. See {@link PathTransform}. */
+        readonly tolerance?: number;
+    }): PathPoint;
+}
+/**
+ * Accuracy and output-segment limits for applying a path transform.
+ *
+ * @see {@link transformPath}
+ */
+export interface TransformPathOptions {
+    /** Positive maximum geometric approximation error. See {@link TransformPathOptions}. */
+    readonly tolerance: number;
+    /** Upper bound on the number of output path segments. See {@link TransformPathOptions}. */
+    readonly maxSegments?: number;
+}
+/**
+ * The four destination corners used by a quadrilateral path transform.
+ *
+ * @see {@link QuadTransformOptions}
+ */
+export type PathQuadCorners = PathWarpCorners;
+/**
+ * Selects bilinear or perspective interpolation for a quadrilateral transform.
+ *
+ * @see {@link QuadTransformOptions}
+ */
+export type PathQuadMode = PathWarpMode;
+/**
+ * Source rectangle, destination corners, and interpolation mode for a quadrilateral transform.
+ *
+ * @see {@link PathRect}
+ * @see {@link PathQuadCorners}
+ * @see {@link PathQuadMode}
+ * @see {@link quadTransform}
+ */
+export interface QuadTransformOptions {
+    /** Source rectangle mapped to the destination quadrilateral. See {@link PathRect}. */
+    readonly source: PathRect;
+    /** Destination corners into which the source rectangle maps. See {@link PathQuadCorners}. */
+    readonly destination: PathQuadCorners;
+    /** Selects the supported mapping, placement, or result policy. See {@link PathQuadMode}. */
+    readonly mode?: PathQuadMode;
+}
+/**
+ * A guide path positioned at a normalized station across an envelope.
+ *
+ * @see {@link PathGuide}
+ * @see {@link EnvelopeTransformOptions}
+ */
+export interface EnvelopeGuide {
+    /** Normalized station position. See {@link EnvelopeGuide}. */
+    readonly at: number;
+    /** Path geometry used by this operation. See {@link PathGuide}. */
+    readonly path: PathGuide;
+}
+/**
+ * Source rectangle and either a top/bottom pair or ordered envelope guides.
+ *
+ * @see {@link PathRect}
+ * @see {@link PathGuide}
+ * @see {@link EnvelopeGuide}
+ * @see {@link envelopeTransform}
+ */
+export 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;
+});
+export type { PathGuide, PathGuideOptions, PathGuideStation, } from './transform-guide.js';
+export interface Stage {
+    apply?(path: PathGeometry, options: TransformPathOptions): PathGeometry;
+    evaluate(input: Pair): Pair;
+    error(input: Pair): number;
+    domain?(point: Pair, margin: number): boolean;
+    affine?: Affine;
+}
+export type Factory = (accuracy: number) => Stage;
+export declare const coordinate: (value: number, label?: string) => number;
+export declare const positive: (value: number, label: string) => number;
+export declare function rectangle(input: PathRect): PathRect;
+export declare const normalize: (input: Pair, r: PathRect) => Pair;
+export declare function make(factories: readonly Factory[]): PathTransform;
+/**
+ * Apply mappings in the order written. Empty composition is identity.
+ *
+ * @param transforms - Point mappings in the order they should be applied. See
+ * {@link PathTransform} .
+ * @returns One mapping that applies each supplied transform in order. See {@link PathTransform}.
+ *
+ * @see {@link PathTransform}
+ */
+export declare function composeTransforms(...transforms: readonly PathTransform[]): PathTransform;
+/**
+ * Creates a reusable 2D affine mapping; an omitted matrix produces identity.
+ *
+ * @param matrix - Affine matrix coefficients; omitted coefficients use the identity matrix.
+ * @returns A point mapping applying the matrix. See {@link PathTransform}.
+ *
+ * @see {@link PathTransform}
+ */
+export declare function affineTransform(matrix?: DOMMatrix2DInit): PathTransform;
+/**
+ * Maps a source rectangle into four destination corners using bilinear or perspective
+ * interpolation.
+ *
+ * @param options - Source rectangle and destination corner positions. See
+ * {@link QuadTransformOptions} .
+ * @returns A point mapping from the source rectangle to the destination quadrilateral. See
+ * {@link PathTransform} .
+ *
+ * @see {@link QuadTransformOptions}
+ * @see {@link PathTransform}
+ */
+export declare function quadTransform(options: QuadTransformOptions): PathTransform;
+/**
+ * Maps a source rectangle between ordered guide paths using linear interpolation.
+ *
+ * @param options - Source bounds and envelope guides defining the deformation. See
+ * {@link EnvelopeTransformOptions} .
+ * @returns A point mapping that deforms the source into the envelope. See {@link PathTransform}.
+ *
+ * @see {@link EnvelopeTransformOptions}
+ * @see {@link PathTransform}
+ */
+export declare function envelopeTransform(options: EnvelopeTransformOptions): PathTransform;
+/**
+ * Return independent geometry. Nonlinear mappings approximate the final composed curve once.
+ *
+ * @param path - Source geometry; it is not modified. See {@link PathGeometry}.
+ * @param transform - Point mapping to apply to the source. See {@link PathTransform}.
+ * @param options - Approximation tolerance and work limits for transformed curves. See
+ * {@link TransformPathOptions} .
+ * @returns Independent geometry containing the transformed path. See {@link PathGeometry}.
+ *
+ * @see {@link PathGeometry}
+ * @see {@link PathTransform}
+ * @see {@link TransformPathOptions}
+ */
+export declare function transformPath(path: PathGeometry, transform: PathTransform, options: TransformPathOptions): PathGeometry;
+/** @internal Merge cell enclosures; derivatives may jump at the shared edge. */
+export declare function mergePairs(outputs: readonly Pair[]): Pair;
+export declare function sourceDomain(input: Pair, source: PathRect, margin: number): boolean;
+export { meshTransform, type MeshTransformOptions } from './transform-mesh.js';
+export { arcBendTransform, pathBendTransform, type ArcBendTransformOptions, type PathBendTransformOptions, type BendTransformOptions, } from './transform-bend.js';
+interface Affine {
+    readonly a: number;
+    readonly b: number;
+    readonly c: number;
+    readonly d: number;
+    readonly e: number;
+    readonly f: number;
+}