pts 0.12.9 → 1.0.1

package/src/Op.ts

@@ -0,0 +1,2442 @@
+/*! Pts.js is licensed under Apache License 2.0. Copyright © 2017-current William Ngan and contributors. (https://github.com/williamngan/pts) */
+
+import { Util } from "./Util";
+import { Geom, Num } from "./Num";
+import { Pt, Group } from "./Pt";
+import { Mat } from "./LinearAlgebra";
+import { overlay } from "./_path";
+import {
+  type PtLike,
+  type GroupLike,
+  type PtLikeIterable,
+  type IntersectContext,
+  type PtIterable,
+  type PolygonLike,
+} from "./Types";
+
+let _errorLength = (obj: any, param: number | string = "expected") =>
+  Util.warn("Group's length is less than " + param, obj);
+let _errorOutofBound = (obj: any, param: number | string = "") =>
+  Util.warn(`Index ${param} is out of bound in Group`, obj);
+
+/**
+ * Line class provides static functions to create and operate on lines. A line is usually represented as a Group of 2 Pts.
+ * You can use the static functions as-is, or apply the [`Group.op`](#link) or [`Pt.op`](#link) to enable functional programming.
+ * See [Op guide](../guide/Op-0400.html) for details.
+ */
+export class Line {
+  /**
+   * Create a line that originates from an anchor point, given an angle and a magnitude.
+   * @param anchor an anchor Pt
+   * @param angle an angle in radian
+   * @param magnitude magnitude of the line
+   * @return a Group of 2 Pts representing a line segement
+   */
+  static fromAngle(anchor: PtLike, angle: number, magnitude: number): Group {
+    let g = new Group(new Pt(anchor), new Pt(anchor));
+    g[1].toAngle(angle, magnitude, true);
+    return g;
+  }
+
+  /**
+   * Calculate the slope of a line.
+   * @param p1 line's first end point
+   * @param p2 line's second end point
+   */
+  static slope(p1: PtLike, p2: PtLike): number | undefined {
+    return p2[0] - p1[0] === 0 ? undefined : (p2[1] - p1[1]) / (p2[0] - p1[0]);
+  }
+
+  /**
+   * Calculate the slope and xy intercepts of a line.
+   * @param p1 line's first end point
+   * @param p2 line's second end point
+   * @returns an object with `slope`, `xi`, `yi` properties
+   */
+  static intercept(
+    p1: PtLike,
+    p2: PtLike,
+  ): { slope: number; xi: number | undefined; yi: number } | undefined {
+    if (p2[0] - p1[0] === 0) {
+      return undefined;
+    } else {
+      let m = (p2[1] - p1[1]) / (p2[0] - p1[0]);
+      let c = p1[1] - m * p1[0];
+      return { slope: m, yi: c, xi: m === 0 ? undefined : -c / m };
+    }
+  }
+
+  /**
+   * Given a 2D path and a point, find whether the point is on left or right side of the line.
+   * @param line  a Group or an Iterable<PtLike> representing a line
+   * @param pt a Pt or numeric array
+   * @returns a negative value if on left and a positive value if on right. If collinear, then the return value is 0.
+   */
+  static sideOfPt2D(line: PtLikeIterable, pt: PtLike): number {
+    let _line = Util.iterToArray(line);
+    return (
+      (_line[1][0] - _line[0][0]) * (pt[1] - _line[0][1]) -
+      (pt[0] - _line[0][0]) * (_line[1][1] - _line[0][1])
+    );
+  }
+
+  /**
+   * Check if three Pts are collinear, ie, on the same straight path.
+   * @param p1 first Pt
+   * @param p2 second Pt
+   * @param p3 third Pt
+   * @param threshold a threshold where a smaller value means higher precision threshold for the straight line. Default is 0.01.
+   */
+  static collinear(
+    p1: PtLike,
+    p2: PtLike,
+    p3: PtLike,
+    threshold: number = 0.01,
+  ): boolean {
+    // Compare the cross product normalized by the segment magnitudes (the
+    // sine of the angle between them), so the threshold is scale-free.
+    const a = new Pt(0, 0, 0).to(p1).$subtract(p2);
+    const b = new Pt(0, 0, 0).to(p1).$subtract(p3);
+    const magSq = a.magnitudeSq() * b.magnitudeSq();
+    if (magSq === 0) return true; // coincident points are collinear
+    return a.$cross(b).magnitudeSq() / magSq <= threshold * threshold;
+  }
+
+  /**
+   * Get magnitude of a line segment.
+   * @param line a Group or an Iterable<Pt> with at least 2 Pt
+   */
+  static magnitude(line: PtIterable): number {
+    let _line = Util.iterToArray(line);
+    return _line.length >= 2 ? _line[1].$subtract(_line[0]).magnitude() : 0;
+  }
+
+  /**
+   * Get squared magnitude of a line segment.
+   * @param line a Group or an Iterable<Pt> with at least 2 Pt
+   */
+  static magnitudeSq(line: PtIterable): number {
+    let _line = Util.iterToArray(line);
+    return _line.length >= 2 ? _line[1].$subtract(_line[0]).magnitudeSq() : 0;
+  }
+
+  /**
+   * Find a point on a line that is perpendicular (shortest distance) to a target point.
+   * @param line a Group or an Iterable<Pt> that defines a line
+   * @param pt a target Pt
+   * @param asProjection if true, this returns the projection vector instead. Default is false.
+   * @returns a Pt on the line that is perpendicular to the target Pt, or a projection vector if `asProjection` is true.
+   */
+  static perpendicularFromPt(
+    line: PtIterable,
+    pt: PtLike,
+    asProjection: boolean = false,
+  ): Pt | undefined {
+    let _line = Util.iterToArray(line);
+    if (_line[0].equals(_line[1])) return undefined;
+    let a = _line[0].$subtract(_line[1]);
+    let b = _line[1].$subtract(pt);
+    let proj = b.$subtract(a.$project(b));
+
+    return asProjection ? proj : proj.$add(pt);
+  }
+
+  /**
+   * Given a line and a point, find the shortest distance from the point to the line.
+   * @param line a Group of 2 Pts
+   * @param pt a Pt
+   * @see `Line.perpendicularFromPt`
+   */
+  static distanceFromPt(line: GroupLike, pt: PtLike | number[]): number {
+    let _line = Util.iterToArray(line);
+    let projectionVector = Line.perpendicularFromPt(_line, pt, true);
+    if (projectionVector) {
+      return projectionVector.magnitude();
+    } else {
+      // line is made of 2 identical points, return distance between this point and pt
+      return _line[0].$subtract(pt).magnitude();
+    }
+  }
+
+  /**
+   * Given two lines as rays (infinite lines), find their intersection point if any.
+   * @param la a Group or an Iterable<Pt> with 2 Pt representing a ray
+   * @param lb a Group or an Iterable<Pt> with 2 Pts representing another ray
+   * @returns an intersection Pt or undefined if no intersection
+   */
+  static intersectRay2D(la: PtIterable, lb: PtIterable): Pt | undefined {
+    const _la = Util.iterToArray(la);
+    const _lb = Util.iterToArray(lb);
+
+    const pa = _la[0];
+    const pb = _lb[0];
+
+    // parametric form: no slope blow-up near vertical lines and uniform
+    // handling of vertical/horizontal cases
+    const rx = _la[1][0] - pa[0];
+    const ry = _la[1][1] - pa[1];
+    const sx = _lb[1][0] - pb[0];
+    const sy = _lb[1][1] - pb[1];
+
+    // a zero-length input does not define a ray
+    if ((rx === 0 && ry === 0) || (sx === 0 && sy === 0)) return undefined;
+
+    const det = rx * sy - ry * sx;
+    if (det === 0) {
+      // parallel; if collinear, keep legacy behavior of returning la's start
+      const qpx = pb[0] - pa[0];
+      const qpy = pb[1] - pa[1];
+      return qpx * ry - qpy * rx === 0 ? new Pt(pa[0], pa[1]) : undefined;
+    }
+
+    const t = ((pb[0] - pa[0]) * sy - (pb[1] - pa[1]) * sx) / det;
+    return new Pt(pa[0] + t * rx, pa[1] + t * ry);
+  }
+
+  /**
+   * Given two line segemnts, find their intersection point if any.
+   * @param la a Group or an Iterable<Pt> with 2 Pt representing a line segment
+   * @param lb a Group or an Iterable<Pt> with 2 Pt representing a line segment
+   * @returns an intersection Pt or undefined if no intersection
+   */
+  static intersectLine2D(la: PtIterable, lb: PtIterable): Pt | undefined {
+    let _la = Util.iterToArray(la);
+    let _lb = Util.iterToArray(lb);
+
+    let pt = Line.intersectRay2D(_la, _lb);
+    return pt &&
+      Geom.withinBound(pt, _la[0], _la[1]) &&
+      Geom.withinBound(pt, _lb[0], _lb[1])
+      ? pt
+      : undefined;
+  }
+
+  /**
+   * Given a line segemnt and a ray (infinite line), find their intersection point if any.
+   * @param line a Group of 2 Pts representing a line segment
+   * @param ray a Group of 2 Pts representing a ray
+   * @returns an intersection Pt or undefined if no intersection
+   */
+  static intersectLineWithRay2D(
+    line: PtIterable,
+    ray: PtIterable,
+  ): Pt | undefined {
+    let _line = Util.iterToArray(line);
+    let _ray = Util.iterToArray(ray);
+    let pt = Line.intersectRay2D(_line, _ray);
+    return pt && Geom.withinBound(pt, _line[0], _line[1]) ? pt : undefined;
+  }
+
+  /**
+   * Given a line segemnt or a ray (infinite line), find its intersection point(s) with a polygon.
+   * @param lineOrRay a Group or an Iterable<Pt> with 2 Pt representing a line or ray
+   * @param poly a Group or an Iterable<Pt> representing a polygon
+   * @param sourceIsRay a boolean value to treat the line as a ray (infinite line). Default is `false`.
+   */
+  static intersectPolygon2D(
+    lineOrRay: PtIterable,
+    poly: PtIterable,
+    sourceIsRay: boolean = false,
+  ): Group | undefined {
+    let _lineOrRay = Util.iterToArray(lineOrRay);
+    let _poly = Util.iterToArray(poly);
+
+    let fn = sourceIsRay ? Line.intersectLineWithRay2D : Line.intersectLine2D;
+    let pts = new Group();
+    for (let i = 0, len = _poly.length; i < len; i++) {
+      let next = i === len - 1 ? 0 : i + 1;
+      let d = fn([_poly[i], _poly[next]], _lineOrRay);
+      if (d) pts.push(d);
+    }
+    return pts.length > 0 ? pts : undefined;
+  }
+
+  /**
+   * Find intersection points of 2 sets of lines. This checks all line segments in the two lists. Consider using a bounding-box check before calling this. If you are checking convex polygon intersections, using [`Polygon.intersectPolygon2D`](#link) will be more efficient.
+   * @param lines1 an Array/Iterable of (Groups or Iterables<Pt>)
+   * @param lines2 an Array/Iterable of (Groups or Iterables<Pt>)
+   * @param isRay a boolean value to treat the line as a ray (infinite line). Default is `false`.
+   */
+  static intersectLines2D(
+    lines1: Iterable<PtIterable>,
+    lines2: Iterable<PtIterable>,
+    isRay: boolean = false,
+  ): Group {
+    let group = new Group();
+    let fn = isRay ? Line.intersectLineWithRay2D : Line.intersectLine2D;
+    for (let l1 of lines1) {
+      for (let l2 of lines2) {
+        let _ip = fn(l1, l2);
+        if (_ip) group.push(_ip);
+      }
+    }
+    return group;
+  }
+
+  /**
+   * Get two points of a ray that intersects with a point on a 2D grid.
+   * @param ray a Group or an Iterable<Pt> representing a ray
+   * @param gridPt a Pt on the grid
+   * @returns a group of two intersecting Pts. The first one is horizontal intersection and the second one is vertical intersection.
+   */
+  static intersectGridWithRay2D(ray: PtIterable, gridPt: PtLike): Group {
+    let _ray = Util.iterToArray(ray);
+    let t = Line.intercept(
+      new Pt(_ray[0]).subtract(gridPt),
+      new Pt(_ray[1]).subtract(gridPt),
+    );
+    let g = new Group();
+    if (t && t.xi !== undefined) g.push(new Pt(gridPt[0] + t.xi, gridPt[1]));
+    if (t && t.yi !== undefined) g.push(new Pt(gridPt[0], gridPt[1] + t.yi));
+    return g;
+  }
+
+  /**
+   * Get two intersection Pts of a line segment with a 2D grid point.
+   * @param line a ray specified by 2 Pts
+   * @param gridPt a Pt on the grid
+   * @returns a group of two intersecting Pts. The first one is horizontal intersection and the second one is vertical intersection.
+   */
+  static intersectGridWithLine2D(
+    line: GroupLike,
+    gridPt: PtLike | number[],
+  ): Group {
+    let _line = Util.iterToArray(line);
+    let g = Line.intersectGridWithRay2D(_line, gridPt);
+    let gg = new Group();
+    for (let i = 0, len = g.length; i < len; i++) {
+      if (Geom.withinBound(g[i], _line[0], _line[1])) gg.push(g[i]);
+    }
+    return gg;
+  }
+
+  /**
+   * An easy way to get rectangle-line intersection points. For more optimized implementation, store the rectangle's sides separately (eg, `Rectangle.sides()`) and use `Polygon.intersectPolygon2D()`.
+   * @param line a Group representing a line
+   * @param rect a Group representing a rectangle
+   * @returns a Group of intersecting Pts
+   */
+  static intersectRect2D(line: GroupLike, rect: GroupLike): Group {
+    let _line = Util.iterToArray(line);
+    let _rect = Util.iterToArray(rect);
+    let box = Geom.boundingBox(Group.fromPtArray(_line));
+    if (!Rectangle.hasIntersectRect2D(box, _rect)) return new Group();
+    return Line.intersectLines2D([_line], Rectangle.sides(_rect));
+  }
+
+  /**
+   * Get evenly distributed points on a line. Similar to [`Create.distributeLinear`](#link) but excluding end points.
+   * @param line a Group or an Iterable<PtLike> representing a line
+   * @param num number of points to get
+   */
+  static subpoints(line: PtLikeIterable, num: number) {
+    let _line = Util.iterToArray(line);
+    let pts = new Group();
+    for (let i = 1; i <= num; i++) {
+      pts.push(Geom.interpolate(_line[0], _line[1], i / (num + 1)));
+    }
+    return pts;
+  }
+
+  /**
+   * Crop this line by a circle or rectangle at end points. This can be useful for creating arrows that connect to an object's edge.
+   * @param line a Group or an Iterable<Pt> representing a line to crop
+   * @param size size of circle or rectangle as Pt
+   * @param index line's end point index, ie, 0 = start and 1 = end.
+   * @param cropAsCircle a boolean to specify whether the `size` parameter should be treated as circle. Default is `true`.
+   * @return an intersecting point on the line that can be used for cropping.
+   */
+  static crop(
+    line: PtIterable,
+    size: PtLike,
+    index: number = 0,
+    cropAsCircle: boolean = true,
+  ): Pt | undefined {
+    let _line = Util.iterToArray(line);
+    let tdx = index === 0 ? 1 : 0;
+    let ls = _line[tdx].$subtract(_line[index]);
+
+    if (ls.magnitudeSq() === 0) return _line[index]; // zero-length line
+
+    if (cropAsCircle) {
+      let d = ls.unit().multiply(size[1]);
+      return _line[index].$add(d);
+    } else {
+      if (size[0] === 0) return _line[index]; // degenerate rectangle
+      let rect = Rectangle.fromCenter(_line[index], size);
+      let sides = Rectangle.sides(rect);
+      let sideIdx = 0;
+
+      if (Math.abs(ls[1] / ls[0]) > Math.abs(size[1] / size[0])) {
+        sideIdx = ls[1] < 0 ? 0 : 2;
+      } else {
+        sideIdx = ls[0] < 0 ? 3 : 1;
+      }
+      return Line.intersectRay2D(sides[sideIdx], _line);
+    }
+  }
+
+  /**
+   * Create an marker arrow or line, placed at an end point of this line.
+   * @param line a Group or an Iterable<Pt> representing a line to place marker
+   * @param size size of the marker as Pt
+   * @param graphic either "arrow" or "line"
+   * @param atTail a boolean, if `true`, the marker will be positioned at tail of the line (ie, index = 1). Default is `true`.
+   * @returns a Group that defines the marker's shape
+   */
+  static marker(
+    line: PtIterable,
+    size: PtLike,
+    graphic: string = "arrow",
+    atTail: boolean = true,
+  ): Group {
+    let _line = Util.iterToArray(line);
+    let h = atTail ? 0 : 1;
+    let t = atTail ? 1 : 0;
+    let unit = _line[h].$subtract(_line[t]);
+
+    if (unit.magnitudeSq() === 0) return new Group();
+    unit.unit();
+
+    let ps = Geom.perpendicular(unit).multiply(size[0]).add(_line[t]);
+    if (graphic == "arrow") {
+      ps.add(unit.$multiply(size[1]));
+      return new Group(_line[t], ps[0], ps[1]);
+    } else {
+      return new Group(ps[0], ps[1]);
+    }
+  }
+
+  /**
+   * Convert this line to a new rectangle representation.
+   * @param line a Group representing a line
+   */
+  static toRect(line: GroupLike) {
+    let _line = Util.iterToArray(line);
+    return new Group(_line[0].$min(_line[1]), _line[0].$max(_line[1]));
+  }
+}
+
+/**
+ * Rectangle class provides static functions to create and operate on rectangles. A rectangle is usually represented as a Group of 2 Pts, marking the top-left and bottom-right corners of the rectangle.
+ * You can use the static functions as-is, or apply the [`Group.op`](#link) or [`Pt.op`](#link) to enable functional programming.
+ * See [Op guide](../guide/Op-0400.html) for details.
+ */
+export class Rectangle {
+  /**
+   * Create a rectangle from top-left anchor point. Same as [`Rectangle.fromTopLeft`](#link).
+   * @param topLeft top-left point
+   * @param widthOrSize width as a number, or a Pt that defines its size
+   * @param height optional height as a number
+   * @returns a Group of 2 Pts representing a rectangle
+   */
+  static from(
+    topLeft: PtLike,
+    widthOrSize: number | PtLike,
+    height?: number,
+  ): Group {
+    return Rectangle.fromTopLeft(topLeft, widthOrSize, height);
+  }
+
+  /**
+   * Create a rectangle given a top-left position and a size.
+   * @param topLeft top-left point
+   * @param widthOrSize width as a number, or a Pt that defines its size
+   * @param height optional height as a number
+   * @returns a Group of 2 Pts representing a rectangle
+   */
+  static fromTopLeft(
+    topLeft: PtLike,
+    widthOrSize: number | PtLike,
+    height?: number,
+  ): Group {
+    let size =
+      typeof widthOrSize == "number"
+        ? [widthOrSize, height ?? widthOrSize]
+        : widthOrSize;
+    return new Group(new Pt(topLeft), new Pt(topLeft).add(size));
+  }
+
+  /**
+   * Create a rectangle given a center position and a size.
+   * @param center center point
+   * @param widthOrSize width as a number, or a Pt that defines its size
+   * @param height optional height as a number
+   * @returns a Group of 2 Pts representing a rectangle
+   */
+  static fromCenter(
+    center: PtLike,
+    widthOrSize: number | PtLike,
+    height?: number,
+  ): Group {
+    let half =
+      typeof widthOrSize == "number"
+        ? [widthOrSize / 2, (height ?? widthOrSize) / 2]
+        : new Pt(widthOrSize).divide(2);
+    return new Group(new Pt(center).subtract(half), new Pt(center).add(half));
+  }
+
+  /**
+   * Create a new circle that either fits within or encloses the rectangle. Same as [`Circle.fromRect`](#link).
+   * @param pts a Group or an Iterable<Pt> with 2 Pt representing a rectangle
+   * @param enclose if `true`, the circle will enclose the rectangle. If `false`, the circle will fit inside the rectangle.
+   * @returns a Group that represents a circle
+   */
+  static toCircle(pts: PtIterable, enclose: boolean = true): Group {
+    return Circle.fromRect(pts, enclose);
+  }
+
+  /**
+   * Create a square that either fits within or encloses a rectangle.
+   * @param pts a Group or an Iterable<Pt> with 2 Pt representing a rectangle
+   * @param enclose if `true`, the square will enclose the rectangle. Default is `false`, which will fit the square inside the rectangle.
+   * @returns a Group of 2 Pts representing a rectangle
+   */
+  static toSquare(pts: PtIterable, enclose = false): Group {
+    let _pts = Util.iterToArray(pts);
+    let s = Rectangle.size(_pts);
+    let m = enclose ? s.maxValue().value : s.minValue().value;
+    return Rectangle.fromCenter(Rectangle.center(_pts), m, m);
+  }
+
+  /**
+   * Get the size of this rectangle as a Pt.
+   * @param pts a Group or an Iterable<Pt> with 2 Pt representing a Rectangle
+   */
+  static size(pts: PtIterable): Pt {
+    let p = Util.iterToArray(pts);
+    return p[0].$max(p[1]).subtract(p[0].$min(p[1]));
+  }
+
+  /**
+   * Get the center of this rectangle.
+   * @param pts a Group or an Iterable<Pt> with 2 Pt representing a Rectangle
+   */
+  static center(pts: PtIterable): Pt {
+    let p = Util.iterToArray(pts);
+    let min = p[0].$min(p[1]);
+    let max = p[0].$max(p[1]);
+    return min.add(max.$subtract(min).divide(2));
+  }
+
+  /**
+   * Get the 4 corners of this rectangle as a Group.
+   * @param rect a Group or an Iterable<Pt> with 2 Pt representing a Rectangle
+   */
+  static corners(rect: PtIterable): Group {
+    let _rect = Util.iterToArray(rect);
+    let p0 = _rect[0].$min(_rect[1]);
+    let p2 = _rect[0].$max(_rect[1]);
+    return new Group(p0, new Pt(p2.x, p0.y), p2, new Pt(p0.x, p2.y));
+  }
+
+  /**
+   * Get the 4 sides of this rectangle as an array of 4 Groups.
+   * @param rect a Group or an Iterable<Pt> with 2 Pt representing a Rectangle
+   * @returns an array of 4 Groups, each of which represents a line segment
+   */
+  static sides(rect: PtIterable): Group[] {
+    let [p0, p1, p2, p3] = Rectangle.corners(rect);
+    return [
+      new Group(p0, p1),
+      new Group(p1, p2),
+      new Group(p2, p3),
+      new Group(p3, p0),
+    ];
+  }
+
+  /**
+   * Given an array of rectangles, get a rectangle that bounds all of them.
+   * @param rects an array of (Groups or Iterables<PtLike>) that represents a set of rectangles
+   * @returns the bounding rectangle as a Group
+   */
+  static boundingBox(rects: Iterable<PtLikeIterable>): Group {
+    let _rects = Util.iterToArray(rects);
+    let merged = Util.flatten(_rects, false);
+    if (merged.length === 0) return new Group();
+
+    // Infinity, not Number.MAX_VALUE/MIN_VALUE. Pt is a Float32Array, in which
+    // MAX_VALUE overflows to Infinity and MIN_VALUE flushes to 0, which would
+    // leave the running maximum starting above every negative coordinate.
+    let min = Pt.make(2, Infinity);
+    let max = Pt.make(2, -Infinity);
+
+    // calculate min max in a single pass
+    for (let i = 0, len = merged.length; i < len; i++) {
+      let p = merged[i];
+      let dim = Math.min(2, p.length);
+      for (let k = 0; k < dim; k++) {
+        min[k] = Math.min(min[k], p[k]);
+        max[k] = Math.max(max[k], p[k]);
+      }
+    }
+    return new Group(min, max);
+  }
+
+  /**
+   * Convert this rectangle into a Group representing a polygon. An alias for [`Rectangle.corners`](#link)
+   * @param rect a Group or an Iterable<Pt> with 2 Pt representing a Rectangle
+   */
+  static polygon(rect: PtIterable): Group {
+    return Rectangle.corners(rect);
+  }
+
+  /**
+   * Subdivide a rectangle into 4 rectangles, one for each quadrant.
+   * @param rect a Group or an Iterable<Pt> with 2 Pt representing a Rectangle
+   * @returns an array of 4 Groups of rectangles
+   */
+  static quadrants(rect: PtIterable, center?: PtLike): Group[] {
+    let _rect = Util.iterToArray(rect);
+    let corners = Rectangle.corners(_rect);
+    let _center =
+      center != undefined ? new Pt(center) : Rectangle.center(_rect);
+    return corners.map((c) => new Group(c, _center).boundingBox());
+  }
+
+  /**
+   * Subdivde a rectangle into 2 rectangles, by row or by column.
+   * @param rect a Group or an Iterable<Pt> with 2 Pt representing a Rectangle
+   * @param ratio a value between 0 to 1 to indicate the split ratio
+   * @param asRows if `true`, split into 2 rows. Default is `false` which splits into 2 columns.
+   * @returns an array of 2 Groups of rectangles
+   */
+  static halves(
+    rect: PtIterable,
+    ratio: number = 0.5,
+    asRows: boolean = false,
+  ): Group[] {
+    let _rect = Util.iterToArray(rect);
+    let min = _rect[0].$min(_rect[1]);
+    let max = _rect[0].$max(_rect[1]);
+    let mid = asRows
+      ? Num.lerp(min[1], max[1], ratio)
+      : Num.lerp(min[0], max[0], ratio);
+    return asRows
+      ? [
+          new Group(min, new Pt(max[0], mid)),
+          new Group(new Pt(min[0], mid), max),
+        ]
+      : [
+          new Group(min, new Pt(mid, max[1])),
+          new Group(new Pt(mid, min[1]), max),
+        ];
+  }
+
+  /**
+   * Check if a point is within a rectangle.
+   * @param rect a Group of 2 Pts representing a Rectangle
+   * @param pt the point to check
+   */
+  static withinBound(rect: GroupLike, pt: PtLike): boolean {
+    let _rect = Util.iterToArray(rect);
+    return Geom.withinBound(pt, _rect[0], _rect[1]);
+  }
+
+  /**
+   * Check if a rectangle is within the bounds of another rectangle.
+   * @param rect1 a Group of 2 Pts representing a rectangle
+   * @param rect2 a Group of 2 Pts representing a rectangle
+   * @param resetBoundingBox if `true`, reset the bounding box. Default is `false` which assumes the rect's first Pt at is its top-left corner.
+   */
+  static hasIntersectRect2D(
+    rect1: GroupLike,
+    rect2: GroupLike,
+    resetBoundingBox: boolean = false,
+  ): boolean {
+    let _rect1 = Util.iterToArray(rect1);
+    let _rect2 = Util.iterToArray(rect2);
+
+    if (resetBoundingBox) {
+      _rect1 = Geom.boundingBox(_rect1);
+      _rect2 = Geom.boundingBox(_rect2);
+    }
+
+    if (_rect1[0][0] > _rect2[1][0] || _rect2[0][0] > _rect1[1][0])
+      return false;
+    if (_rect1[0][1] > _rect2[1][1] || _rect2[0][1] > _rect1[1][1])
+      return false;
+    return true;
+  }
+
+  /**
+   * An easy way to get rectangle-rectangle intersection points. For more optimized implementation, store the rectangle's sides separately (eg, `Rectangle.sides()`) and use `Polygon.intersectPolygon2D()`.
+   * @param rect1 a Group of 2 Pts representing a rectangle
+   * @param rect2 a Group of 2 Pts representing a rectangle
+   */
+  static intersectRect2D(rect1: GroupLike, rect2: GroupLike): Group {
+    let _rect1 = Util.iterToArray(rect1);
+    let _rect2 = Util.iterToArray(rect2);
+    if (!Rectangle.hasIntersectRect2D(_rect1, _rect2)) return new Group();
+    return Line.intersectLines2D(
+      Rectangle.sides(_rect1),
+      Rectangle.sides(_rect2),
+    );
+  }
+}
+
+/**
+ * Circle class provides static functions to create and operate on circles. A circle is usually represented as a Group of 2 Pts, where the first Pt specifies the center, and the second Pt specifies the radius.
+ * To move a circle without changing its radius, move only its center, eg `circle[0].to(20, 20)`. Group transforms such as `circle.moveTo(20, 20)` affect both Pts, including the radius.
+ * You can use the static functions as-is, or apply the [`Group.op`](#link) or [`Pt.op`](#link) to enable functional programming.
+ * See [Op guide](../guide/Op-0400.html) for details.
+ */
+export class Circle {
+  /**
+   * Create a circle that either fits within, or encloses, a rectangle.
+   * @param pts a Group or an Iterable<PtLike> with 2 Pt representing a rectangle
+   * @param enclose if `true`, the circle will enclose the rectangle. Default is `false`, which will fit the circle inside the rectangle.
+   * @returns a Group that represents a circle
+   */
+  static fromRect(pts: PtLikeIterable, enclose = false): Group {
+    let _pts = Util.iterToArray(pts);
+    let r = 0;
+    let min = (r = Rectangle.size(_pts).minValue().value / 2);
+    if (enclose) {
+      let max = Rectangle.size(_pts).maxValue().value / 2;
+      r = Math.sqrt(min * min + max * max);
+    } else {
+      r = min;
+    }
+    return new Group(Rectangle.center(_pts), new Pt(r, r));
+  }
+
+  /**
+   * Create a circle that either fits within, or encloses, a triangle. Same as [`Triangle.circumcircle`](#link) or [`Triangle.incircle`](#link).
+   * @param pts a Group or an Iterable<Pt> with 3 Pt representing a rectangle
+   * @param enclose if `true`, the circle will enclose the triangle. Default is `false`, which will fit the circle inside the triangle.
+   * @returns a Group that represents a circle
+   */
+  static fromTriangle(
+    pts: PtIterable,
+    enclose: boolean = false,
+  ): Group | undefined {
+    if (enclose) {
+      return Triangle.circumcircle(pts);
+    } else {
+      return Triangle.incircle(pts);
+    }
+  }
+
+  /**
+   * Create a circle based on a center point and a radius.
+   * @param pt center point of circle
+   * @param radius radius of circle
+   * @returns a Group that represents a circle
+   */
+  static fromCenter(pt: PtLike, radius: number): Group {
+    return new Group(new Pt(pt), new Pt(radius, radius));
+  }
+
+  /**
+   * Check if a point is within a circle.
+   * @param pts a Group or an Iterable<Pt> with 2 Pt representing a circle
+   * @param pt the point to checks
+   * @param threshold an optional small number to set threshold. Default is 0.
+   */
+  static withinBound(
+    pts: PtIterable,
+    pt: PtLike,
+    threshold: number = 0,
+  ): boolean {
+    let _pts = Util.iterToArray(pts);
+    let d = _pts[0].$subtract(pt);
+    return d.dot(d) + threshold < _pts[1].x * _pts[1].x;
+  }
+
+  /**
+   * Get the intersection points between a circle and a ray (infinite line).
+   * @param circle a Group or an Iterable<Pt> with 2 Pt representing a circle
+   * @param ray a Group or an Iterable<Pt> with 2 Pt representing a ray
+   * @returns a Group of intersection points, or an empty Group if no intersection is found
+   */
+  static intersectRay2D(circle: PtIterable, ray: PtIterable): Group {
+    let _pts = Util.iterToArray(circle);
+    let _ray = Util.iterToArray(ray);
+
+    let d = _ray[0].$subtract(_ray[1]);
+    let f = _pts[0].$subtract(_ray[0]);
+
+    let a = d.dot(d);
+    if (a === 0) return new Group(); // degenerate ray (two identical points)
+    let b = f.dot(d);
+    let c = f.dot(f) - _pts[1].x * _pts[1].x;
+    let p = b / a;
+    let q = c / a;
+    let disc = p * p - q; // discriminant
+
+    if (disc < 0) {
+      return new Group();
+    } else {
+      let discSqrt = Math.sqrt(disc);
+
+      let t1 = -p + discSqrt;
+      let p1 = _ray[0].$subtract(d.$multiply(t1));
+      if (disc === 0) return new Group(p1);
+
+      let t2 = -p - discSqrt;
+      let p2 = _ray[0].$subtract(d.$multiply(t2));
+      return new Group(p1, p2);
+    }
+  }
+
+  /**
+   * Get the intersection points between a circle and a line segment.
+   * @param circle a Group or an Iterable<Pt> with Pt representing a circle
+   * @param line a Group or an Iterable<Pt> with 2 Pt representing a line
+   * @returns a Group of intersection points, or an empty Group if no intersection is found
+   */
+  static intersectLine2D(circle: PtIterable, line: PtIterable): Group {
+    let _pts = Util.iterToArray(circle);
+    let _line = Util.iterToArray(line);
+
+    let ps = Circle.intersectRay2D(_pts, _line);
+    let g = new Group();
+    if (ps.length > 0) {
+      for (let i = 0, len = ps.length; i < len; i++) {
+        if (Rectangle.withinBound(_line, ps[i])) g.push(ps[i]);
+      }
+    }
+    return g;
+  }
+
+  /**
+   * Get the intersection points between two circles.
+   * @param circle1 a Group or an Iterable<Pt> with 2 Pt representing a circle
+   * @param circle2 a Group or an Iterable<Pt> with 2 Pt representing a circle
+   * @returns a Group of intersection points, or an empty Group if no intersection is found
+   */
+  static intersectCircle2D(circle1: PtIterable, circle2: PtIterable): Group {
+    let _pts = Util.iterToArray(circle1);
+    let _circle = Util.iterToArray(circle2);
+
+    let dv = _circle[0].$subtract(_pts[0]);
+    let dr2 = dv.magnitudeSq();
+    let dr = Math.sqrt(dr2);
+
+    let ar = _pts[1].x;
+    let br = _circle[1].x;
+    let ar2 = ar * ar;
+    let br2 = br * br;
+
+    if (dr > ar + br) {
+      // not intersected
+      return new Group();
+    } else if (dr < Math.abs(ar - br)) {
+      // completely enclosed
+      return new Group(_pts[0].clone());
+    } else if (dr === 0) {
+      // coincident circles: no discrete intersection points
+      return new Group();
+    } else {
+      let a = (ar2 - br2 + dr2) / (2 * dr);
+      let h = Math.sqrt(ar2 - a * a);
+      let p = dv.$multiply(a / dr).add(_pts[0]);
+      return new Group(
+        new Pt(p.x + (h * dv.y) / dr, p.y - (h * dv.x) / dr),
+        new Pt(p.x - (h * dv.y) / dr, p.y + (h * dv.x) / dr),
+      );
+    }
+  }
+
+  /**
+   * Quick way to check rectangle intersection with a circle.
+   * For more optimized implementation, store the rectangle's sides separately (eg, [`Rectangle.sides`](#link)) and use [`Polygon.intersectPolygon2D()`](#link).
+   * @param circle a Group or an Iterable<Pt> with 2 Pt representing a circle
+   * @param rect a Group or an Iterable<Pt> with 2 Pt representing a rectangle
+   * @returns a Group of intersection points, or an empty Group if no intersection is found
+   */
+  static intersectRect2D(circle: PtIterable, rect: PtIterable): Group {
+    let _pts = Util.iterToArray(circle);
+    let _rect = Util.iterToArray(rect);
+
+    let sides = Rectangle.sides(_rect);
+    let g = [];
+    for (let i = 0, len = sides.length; i < len; i++) {
+      let ps = Circle.intersectLine2D(_pts, sides[i]);
+      if (ps.length > 0) g.push(ps);
+    }
+    return Util.flatten(g);
+  }
+
+  /**
+   * Get a rectangle that either fits within or encloses this circle. See also [`Rectangle.toCircle`](#link)
+   * @param circle a Group or an Iterable<Pt> with 2 Pt representing a circle
+   * @param within if `true`, the rectangle will be within the circle. If `false`, the rectangle will enclose the circle.
+   * @returns a Group representing a rectangle
+   */
+  static toRect(circle: PtIterable, within: boolean = false): Group {
+    let _pts = Util.iterToArray(circle);
+    let r = _pts[1][0];
+    if (within) {
+      // half-side of the maximal inscribed square (its corners on the circle)
+      let half = r / Math.SQRT2;
+      return new Group(_pts[0].$subtract(half), _pts[0].$add(half));
+    } else {
+      return new Group(_pts[0].$subtract(r), _pts[0].$add(r));
+    }
+  }
+
+  /**
+   * Get a triangle that fits within this circle.
+   * @param circle a Group or an Iterable<Pt> with 2 Pt representing a circle
+   * @param within if `true`, the triangle will be within the circle. If `false`, the triangle will enclose the circle.
+   */
+  static toTriangle(circle: PtIterable, within: boolean = true): Group {
+    let _pts = Util.iterToArray(circle);
+    if (within) {
+      let ang = -Math.PI / 2;
+      let inc = (Math.PI * 2) / 3;
+      let g = new Group();
+      for (let i = 0; i < 3; i++) {
+        g.push(_pts[0].clone().toAngle(ang, _pts[1][0], true));
+        ang += inc;
+      }
+      return g;
+    } else {
+      return Triangle.fromCenter(_pts[0], _pts[1][0]);
+    }
+  }
+}
+
+/**
+ * Triangle class provides static functions to create and operate on trianges. A triange is a polygon represented as a Group of 3 Pts.
+ * You can use the static functions as-is, or apply the [`Group.op`](#link) or [`Pt.op`](#link) to enable functional programming.
+ * See [Op guide](../guide/Op-0400.html) for details.
+ */
+export class Triangle {
+  /**
+   * Create a triangle from a rectangle. The triangle will be isosceles, with the bottom of the rectangle as its base.
+   * @param rect a Group or an Iterable<Pt> with 2 Pt representing a rectangle
+   */
+  static fromRect(rect: PtIterable): Group {
+    let _rect = Util.iterToArray(rect);
+    let top = _rect[0].$add(_rect[1]).divide(2);
+    top.y = _rect[0][1];
+    let left = _rect[1].clone();
+    left.x = _rect[0][0];
+    return new Group(top, _rect[1].clone(), left);
+  }
+
+  /**
+   * Create a triangle that fits within a circle.
+   * @param circle a Group or an Iterable<Pt> with 2 Pt representing a circle
+   */
+  static fromCircle(circle: PtIterable): Group {
+    return Circle.toTriangle(circle, true);
+  }
+
+  /**
+   * Create an equilateral triangle based on a center point and a size.
+   * @param pt the center point
+   * @param size size is the magnitude of lines from center to the triangle's vertices, like a "radius".
+   */
+  static fromCenter(pt: PtLike, size: number): Group {
+    return Triangle.fromCircle(Circle.fromCenter(pt, size));
+  }
+
+  /**
+   * Get the medial, which is an inner triangle formed by connecting the midpoints of this triangle's sides.
+   * @param tri a Group or an Iterable<Pt> representing a triangle
+   * @returns a Group representing a medial triangle
+   */
+  static medial(tri: PtIterable): Group {
+    let _pts = Util.iterToArray(tri);
+    if (_pts.length < 3) return _errorLength(new Group(), 3);
+    return Polygon.midpoints(_pts, true);
+  }
+
+  /**
+   * Given a point of the triangle, the opposite side is the side which the point doesn't touch.
+   * @param tri a Group or an Iterable<Pt> representing a triangle
+   * @param index a Pt on the triangle group
+   * @returns a Group that represents a line of the opposite side
+   */
+  static oppositeSide(tri: PtIterable, index: number): Group {
+    let _pts = Util.iterToArray(tri);
+    if (_pts.length < 3) return _errorLength(new Group(), 3);
+    if (index === 0) {
+      return Group.fromPtArray([_pts[1], _pts[2]]);
+    } else if (index === 1) {
+      return Group.fromPtArray([_pts[0], _pts[2]]);
+    } else {
+      return Group.fromPtArray([_pts[0], _pts[1]]);
+    }
+  }
+
+  /**
+   * Get a triangle's altitude, which is a line from a triangle's point to its opposite side, and perpendicular to its opposite side.
+   * @param tri a Group or an Iterable<Pt> representing a triangle
+   * @param index a Pt on the triangle group
+   * @returns a Group that represents the altitude line
+   */
+  static altitude(tri: PtIterable, index: number): Group {
+    let _pts = Util.iterToArray(tri);
+    let opp = Triangle.oppositeSide(_pts, index);
+    if (opp.length > 1) {
+      return new Group(
+        _pts[index],
+        Line.perpendicularFromPt(opp, _pts[index])!,
+      );
+    } else {
+      return new Group();
+    }
+  }
+
+  /**
+   * Get orthocenter, which is the intersection point of a triangle's 3 altitudes (the 3 lines that are perpendicular to its 3 opposite sides).
+   * @param tri a Group or an Iterable<Pt> representing a triangle
+   * @returns the orthocenter as a Pt
+   */
+  static orthocenter(tri: PtIterable): Pt | undefined {
+    let _pts = Util.iterToArray(tri);
+    if (_pts.length < 3) return _errorLength(undefined, 3);
+    let a = Triangle.altitude(_pts, 0);
+    let b = Triangle.altitude(_pts, 1);
+    return Line.intersectRay2D(a, b);
+  }
+
+  /**
+   * Get incenter, which is the center point of its inner circle, and also the intersection point of its 3 angle bisector lines (each of which cuts one of the 3 angles in half).
+   * @param tri a Group or an Iterable<Pt> representing a triangle
+   * @returns the incenter as a Pt
+   */
+  static incenter(tri: PtIterable): Pt | undefined {
+    let _pts = Util.iterToArray(tri);
+    if (_pts.length < 3) return _errorLength(undefined, 3);
+    let a = Polygon.bisector(_pts, 0)!.add(_pts[0]);
+    let b = Polygon.bisector(_pts, 1)!.add(_pts[1]);
+    return Line.intersectRay2D(new Group(_pts[0], a), new Group(_pts[1], b));
+  }
+
+  /**
+   * Get an interior circle, which is the largest circle completed enclosed by this triangle.
+   * @param tri a Group or an Iterable<Pt> representing a triangle
+   * @param center Optional parameter if the incenter is already known. Otherwise, leave it empty and the incenter will be calculated
+   */
+  static incircle(tri: PtIterable, center?: Pt): Group | undefined {
+    let _pts = Util.iterToArray(tri);
+    let c = center ? center : Triangle.incenter(_pts);
+    if (!c) return undefined; // degenerate (collinear) triangle
+    let area = Polygon.area(_pts);
+    let perim = Polygon.perimeter(_pts, true);
+    let r = (2 * area) / perim.total;
+    // incenter can still resolve for some collinear orderings; a zero-area
+    // triangle has no incircle regardless of point order
+    if (!(r > 0)) return undefined;
+    return Circle.fromCenter(c, r);
+  }
+
+  /**
+   * Get circumcenter, which is the intersection point of its 3 perpendicular bisectors lines ( each of which divides a side in half and is perpendicular to the side).
+   * @param tri a Group or an Iterable<Pt> representing a triangle
+   * @returns the circumcenter as a Pt
+   */
+  static circumcenter(tri: PtIterable): Pt | undefined {
+    let _pts = Util.iterToArray(tri);
+    let md = Triangle.medial(_pts);
+    let a = [
+      md[0],
+      Geom.perpendicular(_pts[0].$subtract(md[0])).p1.$add(md[0]),
+    ];
+    let b = [
+      md[1],
+      Geom.perpendicular(_pts[1].$subtract(md[1])).p1.$add(md[1]),
+    ];
+    return Line.intersectRay2D(a, b);
+  }
+
+  /**
+   * Get circumcenter, which is the intersection point of its 3 perpendicular bisectors lines ( each of which divides a side in half and is perpendicular to the side).
+   * @param tri a Group or an Iterable<Pt> representing a triangle
+   * @param center Optional parameter if the circumcenter is already known. Otherwise, leave it empty and the circumcenter will be calculated
+   */
+  static circumcircle(tri: PtIterable, center?: Pt): Group | undefined {
+    let _pts = Util.iterToArray(tri);
+    let c = center ? center : Triangle.circumcenter(_pts);
+    if (!c) return undefined; // degenerate (collinear) triangle
+    let r = _pts[0].$subtract(c).magnitude();
+    return Circle.fromCenter(c, r);
+  }
+}
+
+/**
+ * Polygon class provides static functions to create and operate on polygons. A polygon is usually represented as a Group of 3 or more Pts.
+ * You can use the static functions as-is, or apply the [`Group.op`](#link) or [`Pt.op`](#link) to enable functional programming.
+ * See [Op guide](../guide/Op-0400.html) for details.
+ */
+export class Polygon {
+  /**
+   * Get the centroid of a polygon, which is the average of all its points.
+   * @param pts a Group or an Iterable<PtLike> representing a polygon
+   */
+  static centroid(pts: PtLikeIterable): Pt {
+    return Geom.centroid(pts);
+  }
+
+  /**
+   * Create a rectangular polygon. Same as creating a Rectangle and then getting its corners via [`Rectangle.corners`](#link).
+   * @param center center point of the rectangle
+   * @param widthOrSize width as number, or a Pt representing the size of the rectangle
+   * @param height optional height
+   */
+  static rectangle(
+    center: PtLike,
+    widthOrSize: number | PtLike,
+    height?: number,
+  ): Group {
+    return Rectangle.corners(Rectangle.fromCenter(center, widthOrSize, height));
+  }
+
+  /**
+   * Create a regular polygon.
+   * @param center The center position of the polygon
+   * @param radius The radius, ie, a length from the center position to one of the polygon's corners.
+   * @param sides Number of sides
+   */
+  static fromCenter(center: PtLike, radius: number, sides: number) {
+    let g = new Group();
+    for (let i = 0; i < sides; i++) {
+      let ang = (Math.PI * 2 * i) / sides;
+      g.push(
+        new Pt(Math.cos(ang) * radius, Math.sin(ang) * radius).add(center),
+      );
+    }
+    return g;
+  }
+
+  /**
+   * Given a polygon, get one edge using an index.
+   * @param pts a Group or an Iterable<PtLike> representing a polygon
+   * @param index index of a Pt in the Group
+   */
+  static lineAt(pts: PtLikeIterable, index: number) {
+    let _pts = Util.iterToArray(pts);
+    if (index < 0 || index >= _pts.length)
+      throw new Error("index out of the Polygon's range");
+    return new Group(
+      _pts[index],
+      index === _pts.length - 1 ? _pts[0] : _pts[index + 1],
+    );
+  }
+
+  /**
+   * Get the line segments in this polygon.
+   * @param poly a Group or an Iterable<Pt>
+   * @param closePath a boolean to specify whether the polygon should be closed (ie, whether the final segment should be counted).
+   * @returns an array of Groups which has 2 Pts in each group
+   */
+  static lines(poly: PtIterable, closePath: boolean = true): Group[] {
+    let _pts = Util.iterToArray(poly);
+    if (_pts.length < 2) return _errorLength(new Group(), 2);
+    // build real Groups; indexed assignment avoids the slow spread through
+    // the Array subclass constructor
+    const count = closePath ? _pts.length : _pts.length - 1;
+    const sp: Group[] = new Array(count);
+    for (let i = 0; i < count; i++) {
+      const seg = new Group();
+      seg[0] = _pts[i];
+      seg[1] = _pts[i === _pts.length - 1 ? 0 : i + 1];
+      sp[i] = seg;
+    }
+    return sp;
+  }
+
+  /**
+   * Get a new polygon group that is derived from midpoints in this polygon.
+   * @param poly a Group or an Iterable<Pt>
+   * @param closePath a boolean to specify whether the polygon should be closed (ie, whether the final segment should be counted).
+   * @param t a value between 0 to 1 for interpolation. Default to 0.5 which will get the middle point.
+   */
+  static midpoints(
+    poly: PtIterable,
+    closePath: boolean = false,
+    t: number = 0.5,
+  ): Group {
+    const sides = Polygon.lines(poly, closePath);
+    const mids = new Group();
+    for (let i = 0, len = sides.length; i < len; i++) {
+      mids[i] = Geom.interpolate(sides[i][0], sides[i][1], t);
+    }
+    return mids;
+  }
+
+  /**
+   * Given a Pt in the polygon group, the adjacent sides are the two sides which the Pt touches.
+   * @param poly a Group or an Iterable<Pt>
+   * @param index the target Pt
+   * @param closePath a boolean to specify whether the polygon should be closed (ie, whether the final segment should be counted).
+   */
+  static adjacentSides(
+    poly: PtIterable,
+    index: number,
+    closePath: boolean = false,
+  ): Group[] {
+    let _pts = Util.iterToArray(poly);
+    if (_pts.length < 2) return _errorLength(new Group(), 2);
+    if (index < 0 || index >= _pts.length)
+      return _errorOutofBound(new Group(), index);
+
+    let gs = [];
+    let left = index - 1;
+    if (closePath && left < 0) left = _pts.length - 1;
+    if (left >= 0) gs.push(new Group(_pts[index], _pts[left]));
+
+    let right = index + 1;
+    if (closePath && right > _pts.length - 1) right = 0;
+    if (right <= _pts.length - 1) gs.push(new Group(_pts[index], _pts[right]));
+
+    return gs;
+  }
+
+  /**
+   * Get a bisector which is a line that split between two sides of a polygon equally.
+   * @param poly a Group or an Iterable<Pt>
+   * @param index the Pt in the polygon to bisect from
+   * @returns a bisector direction Pt, the average of the two adjacent sides' unit vectors (not itself normalized)
+   */
+  static bisector(poly: PtIterable, index: number): Pt | undefined {
+    let sides = Polygon.adjacentSides(poly, index, true);
+    if (sides.length >= 2) {
+      let a = sides[0][1].$subtract(sides[0][0]).unit();
+      let b = sides[1][1].$subtract(sides[1][0]).unit();
+      return a.add(b).divide(2);
+    } else {
+      return undefined;
+    }
+  }
+
+  /**
+   * Find the perimeter of this polygon, ie, the lengths of its sides.
+   * @param poly a Group or an Iterable<Pt>
+   * @param closePath a boolean to specify whether the polygon should be closed (ie, whether the final segment should be counted).
+   * @returns an object with `total` length, and `segments` which is a Pt that stores each segment's length
+   */
+  static perimeter(
+    poly: PtIterable,
+    closePath: boolean = false,
+  ): { total: number; segments: Pt } {
+    const _pts = Util.iterToArray(poly);
+    if (_pts.length < 2) {
+      _errorLength(new Group(), 2);
+      return { total: 0, segments: Pt.make(0, 0) };
+    }
+
+    const count = closePath ? _pts.length : _pts.length - 1;
+    const p = Pt.make(count, 0);
+    let mag = 0;
+
+    for (let i = 0; i < count; i++) {
+      const a = _pts[i];
+      const b = _pts[i === _pts.length - 1 ? 0 : i + 1];
+      const dx = b[0] - a[0];
+      const dy = b[1] - a[1];
+      const m = Math.sqrt(dx * dx + dy * dy);
+      mag += m;
+      p[i] = m;
+    }
+
+    return {
+      total: mag,
+      segments: p,
+    };
+  }
+
+  /**
+   * Find the area of a simple (non-self-intersecting) polygon using the shoelace formula.
+   * @param pts a Group or an Iterable<PtLike> representing a polygon
+   */
+  static area(pts: PtLikeIterable): number {
+    let _pts = Util.iterToArray(pts);
+    if (_pts.length < 3) return _errorLength(0, 3);
+    // determinant
+    let det = (a: PtLike, b: PtLike) => a[0] * b[1] - a[1] * b[0];
+
+    let area = 0;
+    for (let i = 0, len = _pts.length; i < len; i++) {
+      if (i < _pts.length - 1) {
+        area += det(_pts[i], _pts[i + 1]);
+      } else {
+        area += det(_pts[i], _pts[0]);
+      }
+    }
+    return Math.abs(area / 2);
+  }
+
+  /**
+   * Get a convex hull of a set of points, using Melkman's algorithm. ([Reference](http://geomalgorithms.com/a12-_hull-3.html)).
+   * @param pts a Group or an Iterable<PtLike>
+   * @param sorted a boolean value to indicate if the group is pre-sorted by x position. Default is false.
+   * @returns a group of Pt that defines the convex hull polygon
+   */
+  static convexHull(pts: PtLikeIterable, sorted: boolean = false): Group {
+    let _pts = Util.iterToArray(pts);
+    if (_pts.length < 3) return _errorLength(new Group(), 3);
+
+    if (!sorted) {
+      _pts = _pts.slice();
+      _pts.sort((a, b) => a[0] - b[0]);
+    }
+
+    // check if is on left of ray a-b
+    let left = (a: PtLike, b: PtLike, c: PtLike) => {
+      return (b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1]) > 0;
+    };
+
+    // double end queue
+    let dq = [];
+    let bot = _pts.length - 2;
+    let top = bot + 3;
+    dq[bot] = _pts[2];
+    dq[top] = _pts[2];
+
+    // first 3 pt as counter-clockwise triangle
+    if (left(_pts[0], _pts[1], _pts[2])) {
+      dq[bot + 1] = _pts[0];
+      dq[bot + 2] = _pts[1];
+    } else {
+      dq[bot + 1] = _pts[1];
+      dq[bot + 2] = _pts[0];
+    }
+
+    // remaining pts
+    for (let i = 3, len = _pts.length; i < len; i++) {
+      let pt = _pts[i];
+
+      // if inside the hull
+      if (left(dq[bot], dq[bot + 1], pt) && left(dq[top - 1], dq[top], pt)) {
+        continue;
+      }
+
+      // rightmost tangent
+      while (!left(dq[bot], dq[bot + 1], pt)) {
+        bot += 1;
+      }
+      bot -= 1;
+      dq[bot] = pt;
+
+      // leftmost tangent
+      while (!left(dq[top - 1], dq[top], pt)) {
+        top -= 1;
+      }
+      top += 1;
+      dq[top] = pt;
+    }
+
+    let hull = new Group();
+    for (let h = 0; h < top - bot; h++) {
+      hull.push(dq[bot + h]);
+    }
+
+    return hull;
+  }
+
+  /**
+   * Given a point in the polygon as an origin, get an array of lines that connect all the remaining points to the origin point.
+   * @param poly a Group or an Iterable<Pt> representing a polygon
+   * @param originIndex the origin point's index in the polygon
+   * @returns an array of Groups of line segments
+   */
+  static network(poly: PtIterable, originIndex: number = 0): Group[] {
+    let _pts = Util.iterToArray(poly);
+    let g = [];
+    for (let i = 0, len = _pts.length; i < len; i++) {
+      if (i != originIndex) g.push(new Group(_pts[originIndex], _pts[i]));
+    }
+    return g;
+  }
+
+  /**
+   * Given a target Pt, find a Pt in the polygon's corners that's nearest to it.
+   * @param poly a Group or an Iterable<Pt>
+   * @param pt Pt to check
+   * @returns an index in the pts indicating the nearest Pt, or -1 if none found
+   */
+  static nearestPt(poly: PtIterable, pt: PtLike): number {
+    const _poly = Util.iterToArray(poly);
+    const px = pt[0];
+    const py = pt[1];
+    let _near = Number.MAX_VALUE;
+    let _item = -1;
+    for (let i = 0, len = _poly.length; i < len; i++) {
+      const dx = _poly[i][0] - px;
+      const dy = _poly[i][1] - py;
+      const d = dx * dx + dy * dy;
+      if (d < _near) {
+        _near = d;
+        _item = i;
+      }
+    }
+    return _item;
+  }
+
+  /**
+   * Project axis (eg, for use in Separation Axis Theorem).
+   * @param poly a Group or an Iterable<Pt>
+   * @param unitAxis unit axis for calculating dot product
+   */
+  static projectAxis(poly: PtIterable, unitAxis: Pt): Pt {
+    let _poly = Util.iterToArray(poly);
+    let min = unitAxis.dot(_poly[0]);
+    let max = min;
+    for (let n = 1, len = _poly.length; n < len; n++) {
+      const dot = unitAxis.dot(_poly[n]);
+      if (dot < min) min = dot;
+      else if (dot > max) max = dot;
+    }
+    return new Pt(min, max);
+  }
+
+  /**
+   * Scalar core of the axis-overlap test used by the SAT functions: project both polygons on
+   * the unit axis (ax, ay) and return the gap between the intervals (negative means overlap).
+   */
+  private static _axisOverlap2D(
+    poly1: Pt[],
+    poly2: Pt[],
+    ax: number,
+    ay: number,
+  ): number {
+    let min1 = ax * poly1[0][0] + ay * poly1[0][1];
+    let max1 = min1;
+    for (let n = 1, len = poly1.length; n < len; n++) {
+      const d = ax * poly1[n][0] + ay * poly1[n][1];
+      if (d < min1) min1 = d;
+      else if (d > max1) max1 = d;
+    }
+    let min2 = ax * poly2[0][0] + ay * poly2[0][1];
+    let max2 = min2;
+    for (let n = 1, len = poly2.length; n < len; n++) {
+      const d = ax * poly2[n][0] + ay * poly2[n][1];
+      if (d < min2) min2 = d;
+      else if (d > max2) max2 = d;
+    }
+    return min1 < min2 ? min2 - max1 : min1 - max2;
+  }
+
+  /**
+   * Check overlap distance from projected axis.
+   * @param poly1 a Group or an Iterable<Pt> representing the first polygon
+   * @param poly2 a Group or an Iterable<Pt> representing the second polygon
+   * @param unitAxis unit axis
+   */
+  protected static _axisOverlap(
+    poly1: PtIterable,
+    poly2: PtIterable,
+    unitAxis: Pt,
+  ) {
+    let pa = Polygon.projectAxis(poly1, unitAxis);
+    let pb = Polygon.projectAxis(poly2, unitAxis);
+    return pa[0] < pb[0] ? pb[0] - pa[1] : pa[0] - pb[1];
+  }
+
+  /**
+   * Check if a Pt is inside a convex polygon.
+   * @param poly a Group or an Iterable<PtLike> representing a convex polygon
+   * @param pt the Pt to check
+   */
+  static hasIntersectPoint(poly: PtLikeIterable, pt: PtLike): boolean {
+    const _poly = Util.iterToArray(poly);
+    const px = pt[0];
+    const py = pt[1];
+    let c = false;
+    // same ray-cast as before, without a Group allocation per edge
+    for (let i = 0, len = _poly.length; i < len; i++) {
+      const a = _poly[i];
+      const b = _poly[i === len - 1 ? 0 : i + 1];
+      if (
+        a[1] > py != b[1] > py &&
+        px < ((b[0] - a[0]) * (py - a[1])) / (b[1] - a[1]) + a[0]
+      ) {
+        c = !c;
+      }
+    }
+    return c;
+  }
+
+  /**
+   * Check if a convex polygon and a circle has intersections using Separating Axis Theorem.
+   * @param poly a Group or an Iterable<Pt> representing a convex polygon
+   * @param circle a Group or an Iterable<Pt> representing a circle
+   * @returns an `IntersectContext` object that stores the intersection info, or undefined if there's no intersection
+   */
+  static hasIntersectCircle(
+    poly: PtIterable,
+    circle: PtIterable,
+  ): IntersectContext | null {
+    let _poly = Util.iterToArray(poly);
+    let _circle = Util.iterToArray(circle);
+
+    const c = _circle[0];
+    const r = _circle[1][0];
+
+    // AABB pre-reject against the circle's bounding box. The corner cases this
+    // skips are exactly those the perpendicular-foot check below would reject.
+    let bx0 = Infinity;
+    let by0 = Infinity;
+    let bx1 = -Infinity;
+    let by1 = -Infinity;
+    for (let i = 0, len = _poly.length; i < len; i++) {
+      const p = _poly[i];
+      if (p[0] < bx0) bx0 = p[0];
+      if (p[0] > bx1) bx1 = p[0];
+      if (p[1] < by0) by0 = p[1];
+      if (p[1] > by1) by1 = p[1];
+    }
+    if (c[0] + r < bx0 || c[0] - r > bx1 || c[1] + r < by0 || c[1] - r > by1) {
+      return null;
+    }
+
+    let minDist = Number.MAX_SAFE_INTEGER;
+    let minEdge: Group | null = null;
+    let minAx = 0;
+    let minAy = 0;
+    let which = -1;
+
+    for (let i = 0, len = _poly.length; i < len; i++) {
+      const ea = _poly[i];
+      const eb = _poly[i === len - 1 ? 0 : i + 1];
+      let ax = ea[1] - eb[1]; // unit perpendicular of the edge
+      let ay = eb[0] - ea[0];
+      const alen = Math.sqrt(ax * ax + ay * ay);
+      if (alen === 0) continue; // degenerate edge (duplicate points)
+      ax /= alen;
+      ay /= alen;
+
+      // the circle projects onto the axis as [center·axis − r, center·axis + r]
+      let minP = ax * _poly[0][0] + ay * _poly[0][1];
+      let maxP = minP;
+      for (let n = 1; n < len; n++) {
+        const d = ax * _poly[n][0] + ay * _poly[n][1];
+        if (d < minP) minP = d;
+        else if (d > maxP) maxP = d;
+      }
+      const dotC = ax * c[0] + ay * c[1];
+      const dist = minP < dotC - r ? dotC - r - maxP : minP - (dotC + r);
+
+      if (dist > 0) {
+        return null;
+      } else if (Math.abs(dist) < minDist) {
+        // Fix edge case and make sure the circle is intersecting. To be improved.
+        const edge = Polygon.lineAt(_poly, i);
+        const check =
+          Rectangle.withinBound(edge, Line.perpendicularFromPt(edge, c)!) ||
+          Circle.intersectLine2D(_circle, edge).length > 0;
+
+        if (check) {
+          minEdge = edge;
+          minAx = ax;
+          minAy = ay;
+          minDist = Math.abs(dist);
+          which = i;
+        }
+      }
+    }
+
+    if (!minEdge) return null;
+
+    // Edge normals alone miss the case where the circle sits past a vertex:
+    // the separating axis there runs from the nearest vertex to the center.
+    let vx = 0;
+    let vy = 0;
+    let vd = Infinity;
+    for (let i = 0, len = _poly.length; i < len; i++) {
+      const dx = c[0] - _poly[i][0];
+      const dy = c[1] - _poly[i][1];
+      const d = dx * dx + dy * dy;
+      if (d < vd) {
+        vd = d;
+        vx = dx;
+        vy = dy;
+      }
+    }
+    if (vd > 0) {
+      const vlen = Math.sqrt(vd);
+      vx /= vlen;
+      vy /= vlen;
+      let minP = Infinity;
+      let maxP = -Infinity;
+      for (let i = 0, len = _poly.length; i < len; i++) {
+        const d = vx * _poly[i][0] + vy * _poly[i][1];
+        if (d < minP) minP = d;
+        if (d > maxP) maxP = d;
+      }
+      const dotC = vx * c[0] + vy * c[1];
+      if (dotC - r > maxP || dotC + r < minP) return null;
+    }
+
+    // direction
+    const centroid = Polygon.centroid(_poly);
+    if (minAx * (c[0] - centroid[0]) + minAy * (c[1] - centroid[1]) < 0) {
+      minAx = -minAx;
+      minAy = -minAy;
+    }
+
+    return {
+      which,
+      dist: minDist,
+      normal: new Pt(minAx, minAy),
+      edge: minEdge,
+      vertex: c,
+    };
+  }
+
+  /**
+   * Check if two convex polygons have intersections using Separating Axis Theorem.
+   * @param poly1 a Group or an Iterable<Pt> representing a convex polygon
+   * @param poly2 a Group or an Iterable<Pt> representing another convex polygon
+   * @return an `IntersectContext` object that stores the intersection info, or undefined if there's no intersection
+   */
+  static hasIntersectPolygon(
+    poly1: PtIterable,
+    poly2: PtIterable,
+  ): IntersectContext | null {
+    // Reference: https://www.gamedev.net/articles/programming/math-and-physics/a-verlet-based-approach-for-2d-game-physics-r2714/
+    let _poly1 = Util.iterToArray(poly1);
+    let _poly2 = Util.iterToArray(poly2);
+    const len1 = _poly1.length;
+    const len2 = _poly2.length;
+
+    // AABB pre-reject: for convex polygons, disjoint bounding boxes guarantee
+    // that a separating edge normal exists, so the axis scan can be skipped
+    let ax0 = Infinity;
+    let ay0 = Infinity;
+    let ax1 = -Infinity;
+    let ay1 = -Infinity;
+    for (let i = 0; i < len1; i++) {
+      const p = _poly1[i];
+      if (p[0] < ax0) ax0 = p[0];
+      if (p[0] > ax1) ax1 = p[0];
+      if (p[1] < ay0) ay0 = p[1];
+      if (p[1] > ay1) ay1 = p[1];
+    }
+    let bx0 = Infinity;
+    let by0 = Infinity;
+    let bx1 = -Infinity;
+    let by1 = -Infinity;
+    for (let i = 0; i < len2; i++) {
+      const p = _poly2[i];
+      if (p[0] < bx0) bx0 = p[0];
+      if (p[0] > bx1) bx1 = p[0];
+      if (p[1] < by0) by0 = p[1];
+      if (p[1] > by1) by1 = p[1];
+    }
+    if (ax0 > bx1 || bx0 > ax1 || ay0 > by1 || by0 > ay1) return null;
+
+    // scan all edge normals as separating axes, tracking the smallest overlap
+    let minDist = Number.MAX_SAFE_INTEGER;
+    let minIndex = -1;
+    let minAx = 0;
+    let minAy = 0;
+
+    for (let i = 0, plen = len1 + len2; i < plen; i++) {
+      const src = i < len1 ? _poly1 : _poly2;
+      const ei = i < len1 ? i : i - len1;
+      const ea = src[ei];
+      const eb = src[ei === src.length - 1 ? 0 : ei + 1];
+      let ax = ea[1] - eb[1]; // unit perpendicular of the edge
+      let ay = eb[0] - ea[0];
+      const alen = Math.sqrt(ax * ax + ay * ay);
+      if (alen === 0) continue; // degenerate edge (duplicate points)
+      ax /= alen;
+      ay /= alen;
+
+      const dist = Polygon._axisOverlap2D(_poly1, _poly2, ax, ay);
+      if (dist > 0) {
+        return null;
+      } else if (Math.abs(dist) < minDist) {
+        minDist = Math.abs(dist);
+        minIndex = i;
+        minAx = ax;
+        minAy = ay;
+      }
+    }
+
+    if (minIndex < 0) return null;
+
+    const which = minIndex < len1 ? 0 : 1;
+    const edge =
+      which === 0
+        ? Polygon.lineAt(_poly1, minIndex)
+        : Polygon.lineAt(_poly2, minIndex - len1);
+
+    // flip if needed to make sure vertex and edge are in corresponding polygons
+    const b1 = which === 0 ? _poly2 : _poly1;
+    const b2 = which === 0 ? _poly1 : _poly2;
+
+    const c1 = Polygon.centroid(b1);
+    const c2 = Polygon.centroid(b2);
+
+    // direction
+    if (minAx * (c1[0] - c2[0]) + minAy * (c1[1] - c2[1]) < 0) {
+      minAx = -minAx;
+      minAy = -minAy;
+    }
+
+    // find vertex at smallest distance
+    let smallest = Number.MAX_SAFE_INTEGER;
+    let vertex: Pt = null!;
+    for (let i = 0, len = b1.length; i < len; i++) {
+      const d = minAx * (b1[i][0] - c2[0]) + minAy * (b1[i][1] - c2[1]);
+      if (d < smallest) {
+        smallest = d;
+        vertex = b1[i];
+      }
+    }
+
+    return {
+      which,
+      dist: minDist,
+      normal: new Pt(minAx, minAy),
+      edge,
+      vertex,
+    };
+  }
+
+  /**
+   * Find intersection points of 2 polygons by checking every side of both polygons. Performance may be slow for complex polygons.
+   * @param poly1 a Group or an Iterable<Pt> representing a polygon
+   * @param poly2 a Group or an Iterable<Pt> representing another polygon
+   */
+  static intersectPolygon2D(poly1: PtIterable, poly2: PtIterable): Group {
+    let _poly1 = Util.iterToArray(poly1);
+    let _poly2 = Util.iterToArray(poly2);
+
+    let lp = Polygon.lines(_poly1);
+    let g = [];
+    for (let i = 0, len = lp.length; i < len; i++) {
+      let ins = Line.intersectPolygon2D(lp[i], _poly2, false);
+      if (ins) g.push(ins);
+    }
+    return Util.flatten(g, true) as Group;
+  }
+
+  /**
+   * Get a bounding box for each polygon group, as well as a union bounding-box for all groups.
+   * @param polys an Array/Iterable of (Groups or Iterables<Pt>)
+   */
+  static toRects(polys: Iterable<PtIterable>): Group[] {
+    let boxes = [];
+    for (let g of polys) {
+      boxes.push(Geom.boundingBox(g));
+    }
+
+    let merged = Util.flatten(boxes, false);
+    boxes.unshift(Geom.boundingBox(merged));
+    return boxes;
+  }
+}
+
+/**
+ * Path class provides static functions to combine polygons with boolean operations:
+ * unite, intersect, exclude, subtract the shapes in front or behind, divide into faces, or crop by the top shape.
+ * Shapes are listed in stacking order, the first at the back and the last in front, like the order you would draw them in.
+ * A shape is a polygon (a Group, or any iterable of points), or a list of rings that together form a polygon with holes,
+ * such as the result of another Path function. Every result is such a list of rings: an outer ring followed by its
+ * holes, in opposite orientations, which [`CanvasForm.compound`](#link) draws as one path. Rings are open (the first point
+ * is not repeated), 2D, and never share Pts with the input. Clockwise and counterclockwise rings are the same shape, and
+ * a self-intersecting ring covers what `form.polygon` would fill (the nonzero rule). Input vertices closer together than a
+ * millionth of the largest absolute coordinate are merged before finding intersections. For small shapes at large offsets,
+ * work in local coordinates to avoid losing detail to this tolerance or the Float32 output.
+ * See [Op guide](../guide/Op-0400.html) for details.
+ */
+export class Path {
+  /**
+   * Unite: merge all shapes into one polygon (the area inside any shape).
+   * @param shapes an Array/Iterable of polygons in stacking order, back to front. Each is a Group or an Iterable<PtLike>, or a list of rings for a polygon with holes. A single ring is taken as one shape.
+   * @returns the rings of the merged polygon: each outer ring followed by its holes; empty if the shapes have no area
+   * @example `form.fillOnly("#f03").compound( Path.unite( [star, disc] ) )`
+   */
+  static unite(shapes: Iterable<PolygonLike> | PtLikeIterable): Group[] {
+    return overlay(shapes, "unite");
+  }
+
+  /**
+   * Intersect: keep only the area inside every shape.
+   * @param shapes an Array/Iterable of polygons in stacking order, back to front. Each is a Group or an Iterable<PtLike>, or a list of rings for a polygon with holes. A single ring is taken as one shape.
+   * @returns the rings of the common polygon: each outer ring followed by its holes; empty if the shapes do not all overlap
+   * @example `Path.intersect( [a, b, c] )`
+   */
+  static intersect(shapes: Iterable<PolygonLike> | PtLikeIterable): Group[] {
+    return overlay(shapes, "intersect");
+  }
+
+  /**
+   * Exclude: keep the area inside an odd number of shapes, so where two shapes overlap becomes a hole.
+   * @param shapes an Array/Iterable of polygons in stacking order, back to front. Each is a Group or an Iterable<PtLike>, or a list of rings for a polygon with holes. A single ring is taken as one shape.
+   * @returns the rings of the result: each outer ring followed by its holes; empty if the shapes cancel out
+   * @example `Path.exclude( [a, b] )`
+   */
+  static exclude(shapes: Iterable<PolygonLike> | PtLikeIterable): Group[] {
+    return overlay(shapes, "exclude");
+  }
+
+  /**
+   * Minus Front: subtract every shape in front from the backmost (first) shape.
+   * @param shapes an Array/Iterable of polygons in stacking order, back to front. Each is a Group or an Iterable<PtLike>, or a list of rings for a polygon with holes. A single ring is taken as one shape.
+   * @returns the rings of what remains of the first shape: each outer ring followed by its holes; empty if nothing remains
+   * @example `Path.minusFront( [disc, hole] )` cuts `hole` out of `disc`
+   */
+  static minusFront(shapes: Iterable<PolygonLike> | PtLikeIterable): Group[] {
+    return overlay(shapes, "minusFront");
+  }
+
+  /**
+   * Minus Back: subtract every shape behind from the frontmost (last) shape.
+   * @param shapes an Array/Iterable of polygons in stacking order, back to front. Each is a Group or an Iterable<PtLike>, or a list of rings for a polygon with holes. A single ring is taken as one shape.
+   * @returns the rings of what remains of the last shape: each outer ring followed by its holes; empty if nothing remains
+   * @example `Path.minusBack( [wall, window] )` keeps the part of `window` not covered by `wall`
+   */
+  static minusBack(shapes: Iterable<PolygonLike> | PtLikeIterable): Group[] {
+    return overlay(shapes, "minusBack");
+  }
+
+  /**
+   * Divide: split the shapes at every crossing into separate faces. Each face is the largest area not cut by any edge, so
+   * a region inside two shapes is its own face, and a self-overlapping region of one shape is too.
+   * @param shapes an Array/Iterable of polygons in stacking order, back to front. Each is a Group or an Iterable<PtLike>, or a list of rings for a polygon with holes. A single ring is taken as one shape.
+   * @returns an array of polygons, one per face, each an outer ring followed by its holes
+   * @example `Path.divide( [a, b] ).forEach( (face, i) => form.fillOnly( colors[i] ).compound( face ) )`
+   */
+  static divide(shapes: Iterable<PolygonLike> | PtLikeIterable): Group[][] {
+    return overlay(shapes, "divide");
+  }
+
+  /**
+   * Crop: use the frontmost (last) shape as a mask, keeping the faces of the other shapes inside it and deleting the mask itself.
+   * Like [`Path.divide`](#link), the shapes under the mask stay divided where they overlap.
+   * See a [demo here](https://ptsjs.org/demo/?name=path.crop).
+   * @param shapes an Array/Iterable of polygons in stacking order, back to front. Each is a Group or an Iterable<PtLike>, or a list of rings for a polygon with holes. A single ring is taken as one shape.
+   * @returns an array of polygons, one per face inside the mask, each an outer ring followed by its holes
+   * @example `Path.crop( [photo, frame] )`
+   */
+  static crop(shapes: Iterable<PolygonLike> | PtLikeIterable): Group[][] {
+    return overlay(shapes, "crop");
+  }
+}
+
+/**
+ * Curve class provides static functions to interpolate curves. A curve is usually represented as a Group of 3 or more control points.
+ * You can use the static functions as-is, or apply the [`Group.op`](#link) or [`Pt.op`](#link) to enable functional programming.
+ * See [Op guide](../guide/Op-0400.html) for details.
+ */
+export class Curve {
+  /**
+   * Get a precalculated coefficients per step.
+   * @param steps number of steps
+   */
+  static getSteps(steps: number): Group {
+    let ts = new Group();
+    for (let i = 0; i <= steps; i++) {
+      let t = i / steps;
+      ts.push(new Pt(t * t * t, t * t, t, 1));
+    }
+    return ts;
+  }
+
+  /**
+   * Given an index for the starting position in a Pt group, get the control and/or end points of a curve segment.
+   * @param pts a Group or an Iterable<PtLike>
+   * @param index start index in `pts` array. Default is 0.
+   * @param copyStart an optional boolean value to indicate if the start index should be used twice. Default is false.
+   * @returns a group of 4 Pts
+   */
+  static controlPoints(
+    pts: PtLikeIterable,
+    index: number = 0,
+    copyStart: boolean = false,
+  ): Group {
+    let _pts = Util.iterToArray(pts);
+
+    if (index > _pts.length - 1) return new Group();
+    let _index = (i: number) => (i < _pts.length - 1 ? i : _pts.length - 1);
+
+    let p0 = _pts[index];
+    index = copyStart ? index : index + 1;
+
+    // get points based on index
+    return new Group(
+      p0,
+      _pts[_index(index++)],
+      _pts[_index(index++)],
+      _pts[_index(index++)],
+    );
+  }
+
+  /**
+   * Build a per-step table of the 4 control-point weights for a curve family.
+   * Computing these once per call (instead of a matrix product per output
+   * point) is what makes the curve functions fast.
+   */
+  private static _weights(
+    steps: number,
+    fill: (t: number, out: Float64Array, o: number) => void,
+  ): Float64Array {
+    const w = new Float64Array((steps + 1) * 4);
+    for (let i = 0; i <= steps; i++) {
+      fill(i / steps, w, i * 4);
+    }
+    return w;
+  }
+
+  /**
+   * Evaluate one curve segment with a precomputed weight table, pushing one
+   * interpolated Pt per step into `out`. Control values are read by index so
+   * both Pts and plain arrays work.
+   */
+  private static _evalSegment(
+    out: Group,
+    c: GroupLike,
+    w: Float64Array,
+    steps: number,
+  ): void {
+    const c0 = c[0];
+    const c1 = c[1];
+    const c2 = c[2];
+    const c3 = c[3];
+    const dim3 = c0.length > 2;
+    for (let i = 0; i <= steps; i++) {
+      const o = i * 4;
+      const w0 = w[o];
+      const w1 = w[o + 1];
+      const w2 = w[o + 2];
+      const w3 = w[o + 3];
+      const x = w0 * c0[0] + w1 * c1[0] + w2 * c2[0] + w3 * c3[0];
+      const y = w0 * c0[1] + w1 * c1[1] + w2 * c2[1] + w3 * c3[1];
+      out.push(
+        dim3
+          ? new Pt(x, y, w0 * c0[2] + w1 * c1[2] + w2 * c2[2] + w3 * c3[2])
+          : new Pt(x, y),
+      );
+    }
+  }
+
+  /**
+   * Calulcate weighted sum to get the interpolated points.
+   * @param ctrls anchors
+   * @param params parameters
+   */
+  static _calcPt(ctrls: GroupLike, params: PtLike): Pt {
+    let x = ctrls.reduce((a, c, i) => a + c.x * params[i], 0);
+    let y = ctrls.reduce((a, c, i) => a + c.y * params[i], 0);
+    if (ctrls[0].length > 2) {
+      let z = ctrls.reduce((a, c, i) => a + c.z * params[i], 0);
+      return new Pt(x, y, z);
+    }
+    return new Pt(x, y);
+  }
+
+  /**
+   * Weighted sum of 4 control points with scalar weights — the shared core
+   * of the single-point step functions, kept consistent with the batch
+   * `_weights` tables by construction.
+   */
+  private static _stepPt(
+    ctrls: GroupLike,
+    w0: number,
+    w1: number,
+    w2: number,
+    w3: number,
+  ): Pt {
+    const c0 = ctrls[0];
+    const c1 = ctrls[1];
+    const c2 = ctrls[2];
+    const c3 = ctrls[3];
+    const x = w0 * c0[0] + w1 * c1[0] + w2 * c2[0] + w3 * c3[0];
+    const y = w0 * c0[1] + w1 * c1[1] + w2 * c2[1] + w3 * c3[1];
+    return c0.length > 2
+      ? new Pt(x, y, w0 * c0[2] + w1 * c1[2] + w2 * c2[2] + w3 * c3[2])
+      : new Pt(x, y);
+  }
+
+  /**
+   * Create a Catmull-Rom curve. Catmull-Rom is a kind of smooth-looking Cardinal curve.
+   * @param pts a Group or an Iterable<PtLike>
+   * @param steps the number of line segments per curve. Defaults to 10 steps
+   * @returns a curve as a group of interpolated Pt
+   */
+  static catmullRom(pts: PtLikeIterable, steps: number = 10): Group {
+    let _pts = Util.iterToArray(pts);
+    if (_pts.length < 2) return new Group();
+
+    let ps = new Group();
+    const w = Curve._weights(steps, (t, out, o) => {
+      const t2 = t * t;
+      const t3 = t2 * t;
+      out[o] = -0.5 * t3 + t2 - 0.5 * t;
+      out[o + 1] = 1.5 * t3 - 2.5 * t2 + 1;
+      out[o + 2] = -1.5 * t3 + 2 * t2 + 0.5 * t;
+      out[o + 3] = 0.5 * t3 - 0.5 * t2;
+    });
+
+    // use first point twice
+    Curve._evalSegment(ps, Curve.controlPoints(_pts, 0, true), w, steps);
+
+    let k = 0;
+    while (k < _pts.length - 2) {
+      let cp = Curve.controlPoints(_pts, k);
+      if (cp.length > 0) {
+        Curve._evalSegment(ps, cp, w, steps);
+        k++;
+      }
+    }
+
+    return ps;
+  }
+
+  /**
+   * Interpolate to get a point on Catmull-Rom curve.
+   * @param step the coefficients [t*t*t, t*t, t, 1]
+   * @param ctrls a group of anchor Pts
+   * @return an interpolated Pt on the curve
+   */
+  static catmullRomStep(step: Pt, ctrls: GroupLike): Pt {
+    // same coefficients as the batch `catmullRom` weight table
+    const t3 = step[0];
+    const t2 = step[1];
+    const t = step[2];
+    return Curve._stepPt(
+      ctrls,
+      -0.5 * t3 + t2 - 0.5 * t,
+      1.5 * t3 - 2.5 * t2 + 1,
+      -1.5 * t3 + 2 * t2 + 0.5 * t,
+      0.5 * t3 - 0.5 * t2,
+    );
+  }
+
+  /**
+   * Create a Cardinal curve.
+   * @param pts a Group or an Iterable<PtLike>
+   * @param steps the number of line segments per curve. Defaults to 10 steps.
+   * @param tension optional value between 0 to 1 to specify a "tension". Default to 0.5 which is the tension for Catmull-Rom curve.
+   * @returns a curve as a group of interpolated Pt
+   */
+  static cardinal(
+    pts: PtLikeIterable,
+    steps: number = 10,
+    tension = 0.5,
+  ): Group {
+    let _pts = Util.iterToArray(pts);
+    if (_pts.length < 2) return new Group();
+
+    let ps = new Group();
+    const w = Curve._weights(steps, (t, out, o) => {
+      const t2 = t * t;
+      const t3 = t2 * t;
+      out[o] = tension * (-t3 + 2 * t2 - t);
+      out[o + 1] = tension * (-t3 + t2) + (2 * t3 - 3 * t2 + 1);
+      out[o + 2] = tension * (t3 - 2 * t2 + t) + (-2 * t3 + 3 * t2);
+      out[o + 3] = tension * (t3 - t2);
+    });
+
+    // use first point twice
+    Curve._evalSegment(ps, Curve.controlPoints(_pts, 0, true), w, steps);
+
+    let k = 0;
+    while (k < _pts.length - 2) {
+      let cp = Curve.controlPoints(_pts, k);
+      if (cp.length > 0) {
+        Curve._evalSegment(ps, cp, w, steps);
+        k++;
+      }
+    }
+
+    return ps;
+  }
+
+  /**
+   * Interpolate to get a point on Cardinal curve.
+   * @param step the coefficients [t*t*t, t*t, t, 1]
+   * @param ctrls a group of anchor Pts
+   * @param tension optional value between 0 to 1 to specify a "tension". Default to 0.5 which is the tension for Catmull-Rom curve
+   * @return an interpolated Pt on the curve
+   */
+  static cardinalStep(step: Pt, ctrls: GroupLike, tension: number = 0.5): Pt {
+    // same coefficients as the batch `cardinal` weight table
+    const t3 = step[0];
+    const t2 = step[1];
+    const t = step[2];
+    return Curve._stepPt(
+      ctrls,
+      tension * (-t3 + 2 * t2 - t),
+      tension * (-t3 + t2) + (2 * t3 - 3 * t2 + 1),
+      tension * (t3 - 2 * t2 + t) + (-2 * t3 + 3 * t2),
+      tension * (t3 - t2),
+    );
+  }
+
+  /**
+   * Convert the anchors of a Cardinal curve into cubic Bezier control points, so the same curve can be drawn as a native path
+   * with [`CanvasForm.bezier`](#link) or sampled with [`Curve.bezier`](#link).
+   * With the default `alpha`, the Bezier traces the curve that [`Curve.cardinal`](#link) approximates with line segments,
+   * subject to the float32 rounding of a Pt.
+   * See a [demo here](https://ptsjs.org/demo/?name=curve.cardinal).
+   *
+   * Set `alpha` to 0.5 for centripetal or to 1 for chordal parameterization. At the default tension of 0.5,
+   * centripetal Catmull-Rom segments with distinct adjacent anchors have no internal loops or cusps
+   * (Yuksel, Schaefer and Keyser, 2011); changing tension can introduce them.
+   * For non-uniform curves, coincident consecutive anchors give a constant segment and zero tangents at its ends.
+   * @param pts a Group or an Iterable<PtLike> of anchor points
+   * @param tension optional value between 0 to 1 to specify a "tension". Default to 0.5 which is the tension for Catmull-Rom curve.
+   * @param alpha optional knot parameterization: 0 (default) is uniform, 0.5 is centripetal, 1 is chordal
+   * @returns a Group of `3(n-1)+1` Pts in the layout that [`Curve.bezier`](#link) takes: each anchor is followed by the 2 control points of the segment that starts there
+   * @example `form.bezier( Curve.cardinalToBezier( pts ) )`
+   */
+  static cardinalToBezier(
+    pts: PtLikeIterable,
+    tension: number = 0.5,
+    alpha: number = 0,
+  ): Group {
+    const out = new Group();
+    if (!(alpha >= 0) || alpha === Infinity) {
+      return Util.warn(
+        "cardinalToBezier needs a finite alpha of 0 or more",
+        out,
+      );
+    }
+    const p = Util.iterToArray(pts);
+    const n = p.length;
+    if (n < 2) return out;
+    const dim3 = p[0].length > 2;
+
+    // Uniform curves need no knot array. Keep small nonzero distances: replacing them
+    // with an absolute epsilon changes the curve when coordinates are scaled.
+    const dt = alpha === 0 ? undefined : new Float64Array(n - 1);
+    if (dt) {
+      for (let i = 0; i < n - 1; i++) {
+        const dx = p[i + 1][0] - p[i][0];
+        const dy = p[i + 1][1] - p[i][1];
+        const dz = dim3 ? p[i + 1][2] - p[i][2] : 0;
+        const d = Math.pow(Math.hypot(dx, dy, dz), alpha);
+        dt[i] = d < Infinity ? d : 0; // an overflowing interval acts like a repeated anchor
+      }
+    }
+
+    // Each segment is a cubic Hermite between two anchors, and a Hermite converts to a Bezier by
+    // placing the control points a third of the way along the end tangents. The tangent at an
+    // anchor comes from its two neighbors in the non-uniform Catmull-Rom form; an end anchor stands
+    // in for its missing neighbor, which is the duplicated-endpoint convention of `Curve.cardinal`.
+    const control = (
+      o: PtLike,
+      k: number,
+      mx: number,
+      my: number,
+      mz: number,
+    ) => {
+      const pt = new Pt(dim3 ? 3 : 2);
+      pt[0] = o[0] + k * mx;
+      pt[1] = o[1] + k * my;
+      if (dim3) pt[2] = o[2] + k * mz;
+      return pt;
+    };
+
+    for (let i = 0; i < n; i++) {
+      const p0 = p[Math.max(i - 1, 0)];
+      const p1 = p[i];
+      const p2 = p[Math.min(i + 1, n - 1)];
+      const a = dt ? dt[Math.max(i - 1, 0)] : 1;
+      const b = dt ? dt[Math.min(i, n - 2)] : 1;
+      // Weighted adjacent differences, with weights shared across coordinates.
+      // A repeated anchor has zero tangent on both sides: constant segments stay
+      // constant, and reversing the anchors applies the same degeneracy policy.
+      let wa = 0;
+      let wb = 0;
+      if (dt && a > 0 && b > 0) {
+        const s = (2 * tension) / (a + b);
+        wa = s * (b / a);
+        wb = s * (a / b);
+      }
+      const mx = dt
+        ? wa * (p1[0] - p0[0]) + wb * (p2[0] - p1[0])
+        : tension * (p2[0] - p0[0]);
+      const my = dt
+        ? wa * (p1[1] - p0[1]) + wb * (p2[1] - p1[1])
+        : tension * (p2[1] - p0[1]);
+      const mz = dim3
+        ? dt
+          ? wa * (p1[2] - p0[2]) + wb * (p2[2] - p1[2])
+          : tension * (p2[2] - p0[2])
+        : 0;
+
+      if (i > 0) out.push(control(p1, -a / 3, mx, my, mz));
+      out.push(new Pt(p1));
+      if (i < n - 1) out.push(control(p1, b / 3, mx, my, mz));
+    }
+    return out;
+  }
+
+  /**
+   * Convert a chain of cubic Bezier curves into the anchors of a Cardinal curve: the inverse of [`Curve.cardinalToBezier`](#link).
+   * A Cardinal curve's tangents come from its neighboring anchors, so this keeps every Bezier anchor and drops the Bezier handles.
+   * The Cardinal curve still passes through the same anchors; between them it follows the handles only when they were
+   * in Cardinal form to begin with and the original tension and alpha are reused. Coordinates are rounded to float32.
+   * @param pts a Group or an Iterable<PtLike> in the layout of [`Curve.bezier`](#link); an incomplete trailing segment is ignored
+   * @returns a Group of anchors for [`Curve.cardinal`](#link) or [`Curve.cardinalToBezier`](#link), with the tension and alpha of your choice
+   * @example `Curve.cardinal( Curve.bezierToCardinal( chain ), 10, 0.5 )`
+   */
+  static bezierToCardinal(pts: PtLikeIterable): Group {
+    const p = Util.iterToArray(pts);
+    const m = Math.floor((p.length - 1) / 3); // complete segments
+    const out = new Group();
+    if (m < 1) return out;
+    for (let k = 0; k <= m; k++) out.push(new Pt(p[3 * k]));
+    return out;
+  }
+
+  /**
+   * Create a Bezier curve. In a cubic bezier curve, the first and 4th anchors are end-points, and 2nd and 3rd anchors are control-points.
+   * @param pts a group of anchor Pt
+   * @param steps the number of line segments per curve. Defaults to 10 steps.
+   * @returns a curve as a group of interpolated Pt
+   */
+  static bezier(pts: GroupLike, steps: number = 10) {
+    let _pts = Util.iterToArray(pts);
+    if (_pts.length < 4) return new Group();
+
+    let ps = new Group();
+    const w = Curve._weights(steps, (t, out, o) => {
+      const t2 = t * t;
+      const t3 = t2 * t;
+      out[o] = -t3 + 3 * t2 - 3 * t + 1;
+      out[o + 1] = 3 * t3 - 6 * t2 + 3 * t;
+      out[o + 2] = -3 * t3 + 3 * t2;
+      out[o + 3] = t3;
+    });
+
+    let k = 0;
+    while (k < _pts.length - 3) {
+      let c = Curve.controlPoints(_pts, k);
+      if (c.length > 0) {
+        Curve._evalSegment(ps, c, w, steps);
+
+        // go to the next set of point, but assume current end pt is next start pt
+        k += 3;
+      }
+    }
+
+    return ps;
+  }
+
+  /**
+   * Interpolate to get a point on a cubic Bezier curve.
+   * @param step the coefficients [t*t*t, t*t, t, 1]
+   * @param ctrls a group of anchor Pts
+   * @return an interpolated Pt on the curve
+   */
+  static bezierStep(step: Pt, ctrls: GroupLike) {
+    // same coefficients as the batch `bezier` weight table
+    const t3 = step[0];
+    const t2 = step[1];
+    const t = step[2];
+    return Curve._stepPt(
+      ctrls,
+      -t3 + 3 * t2 - 3 * t + 1,
+      3 * t3 - 6 * t2 + 3 * t,
+      -3 * t3 + 3 * t2,
+      t3,
+    );
+  }
+
+  /**
+   * Create a basis spline (NURBS) curve.
+   * @param pts a group of anchor Pt
+   * @param steps the number of line segments per curve. Defaults to 10 steps.
+   * @param tension optional value between 0 to n to specify a "tension". Default is 1 which is the usual tension.
+   * @returns a curve as a group of interpolated Pt
+   */
+  static bspline(
+    pts: GroupLike,
+    steps: number = 10,
+    tension: number = 1,
+  ): Group {
+    let _pts = Util.iterToArray(pts);
+    if (_pts.length < 2) return new Group();
+
+    let ps = new Group();
+    const w =
+      tension !== 1
+        ? Curve._weights(steps, (t, out, o) => {
+            const t2 = t * t;
+            const t3 = t2 * t;
+            const b1 = 2 * t3 - 3 * t2 + 1;
+            const b2 = -2 * t3 + 3 * t2;
+            out[o] = tension * (-t3 / 6 + 0.5 * t2 - 0.5 * t + 1 / 6);
+            out[o + 1] = tension * (-1.5 * t3 + 2 * t2 - 1 / 3) + b1;
+            out[o + 2] = tension * (1.5 * t3 - 2.5 * t2 + 0.5 * t + 1 / 6) + b2;
+            out[o + 3] = tension * (t3 / 6);
+          })
+        : Curve._weights(steps, (t, out, o) => {
+            const t2 = t * t;
+            const t3 = t2 * t;
+            out[o] = -t3 / 6 + 0.5 * t2 - 0.5 * t + 1 / 6;
+            out[o + 1] = 0.5 * t3 - t2 + 2 / 3;
+            out[o + 2] = -0.5 * t3 + 0.5 * t2 + 0.5 * t + 1 / 6;
+            out[o + 3] = t3 / 6;
+          });
+
+    let k = 0;
+    while (k < _pts.length - 3) {
+      let c = Curve.controlPoints(_pts, k);
+      if (c.length > 0) {
+        Curve._evalSegment(ps, c, w, steps);
+        k++;
+      }
+    }
+
+    return ps;
+  }
+
+  /**
+   * Interpolate to get a point on a basis spline curve.
+   * @param step the coefficients [t*t*t, t*t, t, 1]
+   * @param ctrls a group of anchor Pts
+   * @return an interpolated Pt on the curve
+   */
+  static bsplineStep(step: Pt, ctrls: GroupLike): Pt {
+    // same coefficients as the batch `bspline` weight table
+    const t3 = step[0];
+    const t2 = step[1];
+    const t = step[2];
+    return Curve._stepPt(
+      ctrls,
+      -t3 / 6 + 0.5 * t2 - 0.5 * t + 1 / 6,
+      0.5 * t3 - t2 + 2 / 3,
+      -0.5 * t3 + 0.5 * t2 + 0.5 * t + 1 / 6,
+      t3 / 6,
+    );
+  }
+
+  /**
+   * Interpolate to get a point on a basis spline curve with tension.
+   * @param step the coefficients [t*t*t, t*t, t, 1]
+   * @param ctrls a group of anchor Pts
+   * @param tension optional value between 0 to n to specify a "tension". Default to 1 which is the usual tension.
+   * @return an interpolated Pt on the curve
+   */
+  static bsplineTensionStep(
+    step: Pt,
+    ctrls: GroupLike,
+    tension: number = 1,
+  ): Pt {
+    // same coefficients as the batch `bspline` tension weight table
+    const t3 = step[0];
+    const t2 = step[1];
+    const t = step[2];
+    const b1 = 2 * t3 - 3 * t2 + 1;
+    const b2 = -2 * t3 + 3 * t2;
+    return Curve._stepPt(
+      ctrls,
+      tension * (-t3 / 6 + 0.5 * t2 - 0.5 * t + 1 / 6),
+      tension * (-1.5 * t3 + 2 * t2 - 1 / 3) + b1,
+      tension * (1.5 * t3 - 2.5 * t2 + 0.5 * t + 1 / 6) + b2,
+      tension * (t3 / 6),
+    );
+  }
+
+  /**
+   * Convert the anchors of a B-spline curve into cubic Bezier control points, so the same curve can be drawn as a native path
+   * with [`CanvasForm.bezier`](#link) or sampled with [`Curve.bezier`](#link).
+   * The Bezier traces the curve that [`Curve.bspline`](#link) approximates with line segments,
+   * subject to the float32 rounding of a Pt. See a [demo here](https://ptsjs.org/demo/?name=curve.bspline).
+   * @param pts a Group or an Iterable<PtLike> of at least 4 anchor points
+   * @param tension optional value between 0 to n to specify a "tension". Default is 1 which is the usual tension.
+   * @returns a Group of `3(n-3)+1` Pts in the layout that [`Curve.bezier`](#link) takes
+   * @example `form.bezier( Curve.bsplineToBezier( pts ) )`
+   */
+  static bsplineToBezier(pts: PtLikeIterable, tension: number = 1): Group {
+    const p = Util.iterToArray(pts);
+    const n = p.length;
+    const out = new Group();
+    if (n < 4) return out;
+    const dim3 = p[0].length > 2;
+
+    // A segment spans anchors p1..p2 with neighbors p0 and p3. Its end points blend three
+    // anchors (a, 1-2a, a) and its control points blend p1 and p2 only; at tension 1 these
+    // are the (1, 4, 1)/6 and (2, 1)/3 weights of Böhm's knot insertion.
+    const a = tension / 6;
+    const c = 1 - 2 * a;
+    const blend = (
+      u: PtLike,
+      v: PtLike,
+      w: PtLike,
+      wu: number,
+      wv: number,
+      ww: number,
+    ) => {
+      const pt = new Pt(dim3 ? 3 : 2);
+      pt[0] = wu * u[0] + wv * v[0] + ww * w[0];
+      pt[1] = wu * u[1] + wv * v[1] + ww * w[1];
+      if (dim3) pt[2] = wu * u[2] + wv * v[2] + ww * w[2];
+      return pt;
+    };
+
+    out.push(blend(p[0], p[1], p[2], a, c, a));
+    for (let i = 1; i < n - 2; i++) {
+      const p1 = p[i];
+      const p2 = p[i + 1];
+      out.push(
+        blend(p1, p2, p2, c, 2 * a, 0),
+        blend(p1, p2, p2, 2 * a, c, 0),
+        blend(p1, p2, p[i + 2], a, c, a),
+      );
+    }
+    return out;
+  }
+
+  /**
+   * Convert a chain of cubic Bezier curves into the anchors of a B-spline curve: the inverse of [`Curve.bsplineToBezier`](#link) at its default tension.
+   * A B-spline does not pass through its anchors, so they are solved for: the result is the B-spline that passes through
+   * every Bezier anchor and starts and ends along the Bezier's end handles (a tridiagonal system, solved in linear time).
+   * For a chain that `bsplineToBezier` produced at tension 1 this recovers its anchors up to float32 rounding; for any other chain the B-spline keeps
+   * the anchors and the end tangents, and its interior, being smooth to the second derivative, can only approximate the other handles.
+   * @param pts a Group or an Iterable<PtLike> in the layout of [`Curve.bezier`](#link); an incomplete trailing segment is ignored
+   * @returns a Group of `m+3` anchors for `m` Bezier segments, for [`Curve.bspline`](#link) or [`Curve.bsplineToBezier`](#link)
+   * @example `Curve.bspline( Curve.bezierToBspline( chain ) )`
+   */
+  static bezierToBspline(pts: PtLikeIterable): Group {
+    const p = Util.iterToArray(pts);
+    const m = Math.floor((p.length - 1) / 3); // complete segments
+    const out = new Group();
+    if (m < 1) return out;
+    const dim = p[0].length > 2 ? 3 : 2;
+
+    // Unknowns are the anchors P1..P(m+1). Each Bezier anchor gives one row of (1, 4, 1)·P = 6·A,
+    // and the two end rows fold in the end tangents, which also fix P0 and P(m+2) afterwards.
+    // The right-hand sides then simplify to 3× the first handle, 6× each interior anchor, and 3× the last handle.
+    const n = m + 1;
+    const r = new Float64Array(n * dim);
+    const d = new Float64Array(n); // pivots of the tridiagonal (2, 4, ..., 4, 2) with unit off-diagonals
+    for (let k = 0; k < n; k++) {
+      const src = k === 0 ? p[1] : k === m ? p[3 * m - 1] : p[3 * k];
+      const w = k === 0 || k === m ? 3 : 6;
+      for (let j = 0; j < dim; j++) r[k * dim + j] = w * src[j];
+    }
+    d[0] = 2;
+    for (let k = 1; k < n; k++) {
+      const w = 1 / d[k - 1];
+      d[k] = (k < m ? 4 : 2) - w;
+      for (let j = 0; j < dim; j++) r[k * dim + j] -= w * r[(k - 1) * dim + j];
+    }
+    for (let j = 0; j < dim; j++) r[(n - 1) * dim + j] /= d[n - 1];
+    for (let k = n - 2; k >= 0; k--) {
+      for (let j = 0; j < dim; j++) {
+        r[k * dim + j] = (r[k * dim + j] - r[(k + 1) * dim + j]) / d[k];
+      }
+    }
+
+    const first = new Pt(dim);
+    const last = new Pt(dim);
+    for (let j = 0; j < dim; j++) {
+      first[j] = r[dim + j] - 6 * (p[1][j] - p[0][j]);
+      last[j] = r[(m - 1) * dim + j] + 6 * (p[3 * m][j] - p[3 * m - 1][j]);
+    }
+    out.push(first);
+    for (let k = 0; k < n; k++) {
+      const pt = new Pt(dim);
+      for (let j = 0; j < dim; j++) pt[j] = r[k * dim + j];
+      out.push(pt);
+    }
+    out.push(last);
+    return out;
+  }
+}