pts 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pts",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A library for visualization and creative coding.",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -62,7 +62,8 @@
     "prepack": "pnpm build",
     "docs": "node scripts/build-docs-runtime.mjs && node scripts/generate-docs.mjs && node scripts/generate-guides.mjs && node scripts/generate-markdown-docs.mjs",
     "build:docs-runtime": "node scripts/build-docs-runtime.mjs",
-    "build:editor": "node scripts/build-editor.mjs"
+    "build:editor": "node scripts/build-editor.mjs",
+    "test:path:fuzz": "node scripts/fuzz-path.mjs"
   },
   "keywords": [
     "canvas",

package/src/Canvas.ts

@@ -1296,8 +1296,44 @@ export class CanvasForm<
    * @param pts a Group or an Iterable<PtLike> representing a line
    */
   line(pts: PtLikeIterable): this {
-    CanvasForm.line(this._ctx, pts);
-    this._paint();
+    const p = Util.iterToArray(pts);
+    if (Util.arrayCheck(p)) {
+      CanvasForm.line(this._ctx, p);
+      this._paint();
+    }
+    return this;
+  }
+
+  /**
+   * A static function to draw a chain of cubic Bezier curves as one native path.
+   * @param ctx canvas rendering context
+   * @param pts a Group or an Iterable<PtLike> in the layout of [`Curve.bezier`](#link): an anchor followed by 2 control points and an anchor per segment
+   */
+  static bezier(ctx: RenderingContext2D, pts: PtLikeIterable) {
+    const p = Util.iterToArray(pts);
+    if (p.length < 4) return;
+    ctx.beginPath();
+    ctx.moveTo(p[0][0], p[0][1]);
+    for (let i = 3; i < p.length; i += 3) {
+      const c1 = p[i - 2];
+      const c2 = p[i - 1];
+      ctx.bezierCurveTo(c1[0], c1[1], c2[0], c2[1], p[i][0], p[i][1]);
+    }
+  }
+
+  /**
+   * Draw a chain of cubic Bezier curves as one native path. Unlike a polyline from [`Curve.bezier`](#link),
+   * the path stays smooth at any zoom and exports as compact SVG. Use [`Curve.cardinalToBezier`](#link) or
+   * [`Curve.bsplineToBezier`](#link) to draw those curves this way.
+   * @param pts a Group or an Iterable<PtLike> in the layout of [`Curve.bezier`](#link): an anchor followed by 2 control points and an anchor per segment
+   * @example `form.bezier( Curve.cardinalToBezier( pts ) )`
+   */
+  bezier(pts: PtLikeIterable): this {
+    const p = Util.iterToArray(pts);
+    if (Util.arrayCheck(p, 4)) {
+      CanvasForm.bezier(this._ctx, p);
+      this._paint();
+    }
     return this;
   }
 
@@ -1317,8 +1353,67 @@ export class CanvasForm<
    * @param pts a Group or an Iterable<PtLike> representingg a polygon
    */
   polygon(pts: PtLikeIterable): this {
-    CanvasForm.polygon(this._ctx, pts);
-    this._paint();
+    const p = Util.iterToArray(pts);
+    if (Util.arrayCheck(p)) {
+      CanvasForm.polygon(this._ctx, p);
+      this._paint();
+    }
+    return this;
+  }
+
+  /**
+   * A static function to draw a compound polygon: several rings as one path, so that a ring inside another with the opposite orientation becomes a hole (the nonzero winding rule).
+   * @param ctx canvas rendering context
+   * @param rings an Array/Iterable of rings, each a Group or an Iterable<PtLike>; rings with fewer than 2 points are skipped
+   */
+  static compound(ctx: RenderingContext2D, rings: Iterable<PtLikeIterable>) {
+    let started = false;
+    for (const ring of rings) {
+      const p = Util.iterToArray(ring);
+      if (p.length < 2) continue;
+      if (typeof p[0][0] !== "number") {
+        // a list of polygons (such as a Path.divide result) instead of a list of rings
+        Util.warn(
+          "compound expects rings of points; draw each polygon of a divide or crop result separately",
+        );
+        return;
+      }
+      if (!started) {
+        ctx.beginPath();
+        started = true;
+      }
+      ctx.moveTo(p[0][0], p[0][1]);
+      for (let i = 1, len = p.length; i < len; i++)
+        ctx.lineTo(p[i][0], p[i][1]);
+      ctx.closePath();
+    }
+  }
+
+  /**
+   * Draw a compound polygon: several rings as one path, so that a ring inside another with the opposite orientation becomes a hole
+   * (the nonzero winding rule). This is how a [`Path`](#link) result is drawn; [`CanvasForm.polygons`](#link) would fill the holes.
+   * @param rings an Array/Iterable of rings, each a Group or an Iterable<PtLike>; rings with fewer than 2 points are skipped, and nothing is drawn if no ring remains
+   * @example `form.fillOnly("#f03").compound( Path.minusFront( [disc, hole] ) )`
+   */
+  compound(rings: Iterable<PtLikeIterable>): this {
+    const list: PtLike[][] = [];
+    let drawable = false;
+    for (const ring of rings) {
+      const p = Util.iterToArray(ring);
+      if (p.length > 0 && typeof p[0][0] !== "number") {
+        // a list of polygons (such as a Path.divide result) instead of a list of rings
+        return Util.warn(
+          "compound expects rings of points; draw each polygon of a divide or crop result separately",
+          this,
+        );
+      }
+      if (p.length >= 2) drawable = true;
+      list.push(p);
+    }
+    if (drawable) {
+      CanvasForm.compound(this._ctx, list);
+      this._paint();
+    }
     return this;
   }
 

package/src/Create.ts

@@ -1,6 +1,6 @@
 /*! Pts.js is licensed under Apache License 2.0. Copyright © 2017-current William Ngan and contributors. (https://github.com/williamngan/pts) */
 
-import { Pt, Group, type Bound } from "./Pt";
+import { Pt, Group, Bound } from "./Pt";
 import { Line, Triangle } from "./Op";
 import { Const, Util } from "./Util";
 import { Num, Geom } from "./Num";
@@ -14,6 +14,7 @@ import {
   type DelaunayShape,
   type FlockBoundary,
   type FlockOptions,
+  type PoissonDiskOptions,
 } from "./Types";
 
 /**
@@ -190,6 +191,31 @@ export class Create {
     for (const p of pts) flock.addBoid(p);
     return flock;
   }
+
+  /**
+   * Create a set of Pts that are randomly placed but never closer than `radius` to each other,
+   * using Poisson-disk sampling (also called blue noise).
+   * Compared with [`Create.distributeRandom`](#link), the points avoid clumping.
+   * Sampling uses a finite candidate budget, so gaps can remain when it finishes.
+   * The returned [`PoissonDisk`](#link) is a complete Group; to grow a set gradually instead,
+   * construct a `PoissonDisk` and call its [`PoissonDisk.step`](#link) or [`PoissonDisk.sample`](#link).
+   * See a [demo here](https://ptsjs.org/demo/?name=create.sampling).
+   *
+   * Randomness comes from [`Num.random`](#link), so seeding with [`Num.seed`](#link) makes the set reproducible.
+   *
+   * @param bound the rectangular boundary
+   * @param radius minimum distance between any two points
+   * @param options optional [`PoissonDiskOptions`](#link)
+   * @returns an instance of the PoissonDisk class, which is a Group of Pts
+   * @example `Create.sampling( space.innerBound, 10 )`
+   */
+  static sampling(
+    bound: Bound,
+    radius: number,
+    options: PoissonDiskOptions = {},
+  ): PoissonDisk {
+    return new PoissonDisk().setup(bound, radius, options).sample();
+  }
 }
 
 /**
@@ -1545,3 +1571,264 @@ export class Flock extends Group {
     }
   }
 }
+
+// Cell offsets in scan order for `PoissonDisk`, nearest first
+const __near = [0, -1, 1, -2, 2];
+
+/**
+ * PoissonDisk is a Group of Pts produced by Poisson-disk sampling: every point is at least
+ * [`PoissonDisk.radius`](#link) away from every other. Create a finished set with
+ * [`Create.sampling`](#link), or construct one directly and grow it with [`PoissonDisk.step`](#link)
+ * (one point at a time) or [`PoissonDisk.sample`](#link) (a batch at a time), which is how the
+ * [demo](https://ptsjs.org/demo/?name=create.sampling) shows the packing as it forms.
+ *
+ * The sampler is Bridson's grid-accelerated algorithm with Roberts' candidate placement: each
+ * visit to an active point tries up to [`PoissonDisk.candidates`](#link) candidates on the circle
+ * just outside `radius` around it, at evenly spaced angles from a random offset, and accepts the
+ * first one with no existing point within `radius`. It runs in linear time on one small integer
+ * grid. In a bound thinner than the radius, candidates take random positions across the thin
+ * axis and alternate along the long one, since a circle of candidates would miss the strip.
+ *
+ * Three traits to know: most points sit just beyond `radius` from the point that spawned them,
+ * which packs tighter than candidates at random distances; the candidate budget is finite, so
+ * a finished set can still have gaps; and coordinates are compared as float32 (the precision of
+ * a Pt), exact at pixel scales but rejecting some candidates when coordinates exceed roughly
+ * 8000 times the radius.
+ *
+ * Treat the Group as read-only while sampling: pushing or moving its Pts by hand would
+ * desynchronize the grid that enforces the spacing. A PoissonDisk produced by `map`, `filter`
+ * or `slice` is a plain copy that reports radius 0 and `done`, and needs `setup` before sampling.
+ */
+export class PoissonDisk extends Group {
+  private _radius = 0;
+  private _candidates = 8;
+  // per-setup constants of the candidate placement, hoisted out of step()
+  private _dist = 0; // radius with an allowance for float32 rounding
+  private _cos = 1; // rotation between candidates
+  private _sin = 0;
+  private _narrowX = false; // the bound is thinner than a candidate circle across x
+  private _narrowY = false; // or across y
+  private _x0 = 0;
+  private _y0 = 0;
+  private _x1 = 0;
+  private _y1 = 0;
+  private _cell = 1;
+  private _cols = 0;
+  private _rows = 0;
+  private _grid = new Int32Array(0); // one sample index per cell, or -1
+  private _active: number[] = []; // indices of samples that may still spawn neighbors
+
+  /**
+   * Reset this sampler and place its first sample. Calling `setup` again empties the group and
+   * starts over, which is how a sketch restarts sampling after a resize.
+   * @param bound the rectangular boundary
+   * @param radius minimum distance between any two points
+   * @param options optional [`PoissonDiskOptions`](#link)
+   * @returns this
+   * @example `new PoissonDisk().setup( space.innerBound, 12 ).sample( 40 )`
+   */
+  setup(bound: Bound, radius: number, options: PoissonDiskOptions = {}): this {
+    if (!(radius > 0) || !Number.isFinite(radius)) {
+      throw new Error("PoissonDisk radius must be a positive finite number");
+    }
+    const x0 = bound.x ?? NaN;
+    const y0 = bound.y ?? NaN;
+    const width = bound.width;
+    const height = bound.height;
+    const x1 = x0 + width;
+    const y1 = y0 + height;
+    if (![x0, y0, x1, y1].every(Number.isFinite) || width < 0 || height < 0) {
+      throw new Error("PoissonDisk bound must have a finite position and size");
+    }
+    // A size can vanish when added to a far larger position (e.g. 1 at 1e20)
+    if ((width > 0 && x1 <= x0) || (height > 0 && y1 <= y0)) {
+      throw new Error(
+        "PoissonDisk bound size must be representable at its position",
+      );
+    }
+    const k = options.candidates ?? 8;
+    if (!(k >= 1) || !Number.isFinite(k)) {
+      throw new Error("PoissonDisk candidates must be a number of at least 1");
+    }
+
+    // Each grid cell is small enough to hold at most one sample
+    const cell = radius / Math.SQRT2;
+    const hasArea = width > 0 && height > 0;
+    const cols = hasArea ? Math.ceil(width / cell) : 0;
+    const rows = hasArea ? Math.ceil(height / cell) : 0;
+    if (cols * rows > 1 << 26) {
+      throw new Error(
+        "PoissonDisk radius is too small for this bound: the grid would exceed 2^26 cells",
+      );
+    }
+
+    this.length = 0;
+    this._active.length = 0;
+    this._radius = radius;
+    this._candidates = Math.floor(k);
+    this._x0 = x0;
+    this._y0 = y0;
+    this._x1 = x1;
+    this._y1 = y1;
+    this._cell = cell;
+    this._cols = cols;
+    this._rows = rows;
+    this._grid = new Int32Array(cols * rows).fill(-1);
+    this._dist = radius * 1.001; // allow for float32 rounding at ordinary canvas scales
+    this._cos = Math.cos(Const.two_pi / this._candidates);
+    this._sin = Math.sin(Const.two_pi / this._candidates);
+    // A full circle of candidates can miss a strip thinner than `dist` entirely; there,
+    // candidates take a random position across the strip and alternate along it instead.
+    this._narrowX = width < this._dist && width <= height;
+    this._narrowY = height < this._dist && !this._narrowX;
+
+    if (options.start !== undefined) {
+      const s = options.start;
+      if (!this._tryAdd(Math.fround(s[0]), Math.fround(s[1]))) {
+        throw new Error(
+          "PoissonDisk start point must lie on or after the bound's top-left edges and before its bottom-right edges",
+        );
+      }
+    } else if (cols * rows > 0) {
+      // Redraw on the rare float32 rounding that lands exactly on the far edge
+      while (
+        !this._tryAdd(
+          Math.fround(x0 + Num.random() * width),
+          Math.fround(y0 + Num.random() * height),
+        )
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Minimum distance between any two points in this set.
+   */
+  get radius(): number {
+    return this._radius;
+  }
+
+  /**
+   * Maximum candidates tried per visit to an active sample before retiring it if none succeed.
+   */
+  get candidates(): number {
+    return this._candidates;
+  }
+
+  /**
+   * The rectangular boundary that the samples fill.
+   */
+  get bound(): Bound {
+    return new Bound(new Pt(this._x0, this._y0), new Pt(this._x1, this._y1));
+  }
+
+  /**
+   * Whether no active samples remain. Gaps may still fit further points, but sampling has stopped.
+   */
+  get done(): boolean {
+    return this._active.length === 0;
+  }
+
+  /**
+   * Add the next sample and return it, or return `undefined` once no active samples remain.
+   * The new Pt is also the last element of this group.
+   * @example `let p = pd.step(); if (p) form.point( p, 2 );`
+   */
+  step(): Pt | undefined {
+    const active = this._active;
+    const k = this._candidates;
+    const dist = this._dist;
+    const cos = this._cos;
+    const sin = this._sin;
+    const width = this._x1 - this._x0;
+    const height = this._y1 - this._y0;
+    const narrowX = this._narrowX;
+    const narrowY = this._narrowY;
+
+    while (active.length > 0) {
+      const ai = Math.floor(Num.random() * active.length);
+      const p = this[active[ai]];
+      const a0 = Num.random() * Const.two_pi;
+      let dx = dist * Math.cos(a0);
+      let dy = dist * Math.sin(a0);
+      let along = a0 < Math.PI ? 1 : -1;
+      for (let j = 0; j < k; j++) {
+        if (narrowX) {
+          dx = this._x0 + Num.random() * width - p[0];
+          dy = along * Math.sqrt(Math.max(0, dist * dist - dx * dx));
+          along = -along;
+        } else if (narrowY) {
+          dy = this._y0 + Num.random() * height - p[1];
+          dx = along * Math.sqrt(Math.max(0, dist * dist - dy * dy));
+          along = -along;
+        } else if (j > 0) {
+          const x = dx * cos - dy * sin;
+          dy = dx * sin + dy * cos;
+          dx = x;
+        }
+        if (this._tryAdd(Math.fround(p[0] + dx), Math.fround(p[1] + dy))) {
+          return this[this.length - 1];
+        }
+      }
+      // This visit exhausted its candidate budget: retire the sample
+      active[ai] = active[active.length - 1];
+      active.pop();
+    }
+    return undefined;
+  }
+
+  /**
+   * Add up to `count` more samples, or every remaining sample by default.
+   * @param count maximum number of samples to add, rounded down; nonpositive values and NaN add none
+   * @example `pd.sample( 20 )` adds twenty points per frame; `pd.sample()` completes the set
+   */
+  sample(count: number = Infinity): this {
+    const limit = Math.floor(count);
+    for (let i = 0; i < limit; i++) {
+      if (this.step() === undefined) break;
+    }
+    return this;
+  }
+
+  /**
+   * Store the point at (x, y) if it lies inside the bound and no sample is within `radius` of it.
+   * Coordinates must already be float32 values, so what is tested is exactly what is stored.
+   */
+  private _tryAdd(x: number, y: number): boolean {
+    if (!(x >= this._x0 && x < this._x1 && y >= this._y0 && y < this._y1)) {
+      return false;
+    }
+    const cols = this._cols;
+    const rows = this._rows;
+    const cx = Math.min(cols - 1, Math.floor((x - this._x0) / this._cell));
+    const cy = Math.min(rows - 1, Math.floor((y - this._y0) / this._cell));
+    const grid = this._grid;
+
+    // A conflicting sample lies within two cells in each direction, but never in the four
+    // corners of that window. Scan from the center outward: a rejected candidate usually
+    // conflicts with a sample close to it, so the scan ends after a few cells.
+    const r2 = this._radius * this._radius;
+    for (const dj of __near) {
+      const j = cy + dj;
+      if (j < 0 || j >= rows) continue;
+      const row = j * cols;
+      const reach = dj === -2 || dj === 2 ? 1 : 2;
+      for (const di of __near) {
+        const i = cx + di;
+        if (di > reach || di < -reach || i < 0 || i >= cols) continue;
+        const s = grid[row + i];
+        if (s >= 0) {
+          const q = this[s];
+          const dx = q[0] - x;
+          const dy = q[1] - y;
+          if (dx * dx + dy * dy < r2) return false;
+        }
+      }
+    }
+
+    grid[cy * cols + cx] = this.length;
+    this._active.push(this.length);
+    this.push(new Pt(x, y));
+    return true;
+  }
+}

package/src/Dom.ts

@@ -347,7 +347,7 @@ export class DOMSpace extends MultiTouchSpace {
 
 /**
  * @deprecated HTML rendering is deprecated and will be removed in a future major version. Use [`SVGSpace`](#link) for DOM-based output instead — it shares the supported subset of the [`CanvasForm`](#link) drawing API.
- * **[Experimental]** HTMLSpace is a subclass of DOMSpace that works with HTML elements. See [a demo here](https://ptsjs.org/demo/?name=htmlform.scope).
+ * **[Experimental]** HTMLSpace is a subclass of DOMSpace that works with HTML elements.
  */
 export class HTMLSpace extends DOMSpace {
   /**

package/src/Num.ts

@@ -26,7 +26,9 @@ export class Num {
    * @param threshold threshold value that specifies the minimum difference within which the two numbers are considered equal
    */
   static equals(a: number, b: number, threshold = 0.00001): boolean {
-    return Math.abs(a - b) < threshold;
+    // A value equals itself (infinities included, whose difference is NaN),
+    // and a difference equal to the threshold is included, as in Pt.equals.
+    return a === b || Math.abs(a - b) <= threshold;
   }
 
   /**