@canvas-commons/2d 0.2.0

package/src/lib/curves/Polynomial.ts

@@ -0,0 +1,355 @@
+import {clamp} from '@canvas-commons/core';
+
+/**
+ * A polynomial in the form ax^3 + bx^2 + cx + d up to a cubic polynomial.
+ *
+ * Source code liberally taken from:
+ * https://github.com/FreyaHolmer/Mathfs/blob/master/Runtime/Curves/Polynomial.cs
+ */
+export class Polynomial {
+  public readonly c1: number;
+  public readonly c2: number;
+  public readonly c3: number;
+
+  /**
+   * Constructs a constant polynomial
+   *
+   * @param c0 - The constant coefficient
+   */
+  public static constant(c0: number): Polynomial {
+    return new Polynomial(c0);
+  }
+
+  /**
+   * Constructs a linear polynomial
+   *
+   * @param c0 - The constant coefficient
+   * @param c1 - The linear coefficient
+   */
+  public static linear(c0: number, c1: number): Polynomial {
+    return new Polynomial(c0, c1);
+  }
+
+  /**
+   * Constructs a quadratic polynomial
+   *
+   * @param c0 - The constant coefficient
+   * @param c1 - The linear coefficient
+   * @param c2 - The quadratic coefficient
+   */
+  public static quadratic(c0: number, c1: number, c2: number): Polynomial {
+    return new Polynomial(c0, c1, c2);
+  }
+
+  /**
+   * Constructs a cubic polynomial
+   *
+   * @param c0 - The constant coefficient
+   * @param c1 - The linear coefficient
+   * @param c2 - The quadratic coefficient
+   * @param c3 - The cubic coefficient
+   */
+  public static cubic(
+    c0: number,
+    c1: number,
+    c2: number,
+    c3: number,
+  ): Polynomial {
+    return new Polynomial(c0, c1, c2, c3);
+  }
+
+  /**
+   * The degree of the polynomial
+   */
+  public get degree(): number {
+    if (this.c3 !== 0) {
+      return 3;
+    } else if (this.c2 !== 0) {
+      return 2;
+    } else if (this.c1 !== 0) {
+      return 1;
+    }
+    return 0;
+  }
+
+  /**
+   * @param c0 - The constant coefficient
+   */
+  public constructor(c0: number);
+  /**
+   * @param c0 - The constant coefficient
+   * @param c1 - The linear coefficient
+   */
+  public constructor(c0: number, c1: number);
+  /**
+   * @param c0 - The constant coefficient
+   * @param c1 - The linear coefficient
+   * @param c2 - The quadratic coefficient
+   */
+  public constructor(c0: number, c1: number, c2: number);
+  /**
+   * @param c0 - The constant coefficient
+   * @param c1 - The linear coefficient
+   * @param c2 - The quadratic coefficient
+   * @param c3 - The cubic coefficient
+   */
+  public constructor(c0: number, c1: number, c2: number, c3: number);
+  public constructor(
+    public readonly c0: number,
+    c1?: number,
+    c2?: number,
+    c3?: number,
+  ) {
+    this.c1 = c1 ?? 0;
+    this.c2 = c2 ?? 0;
+    this.c3 = c3 ?? 0;
+  }
+
+  /**
+   * Return the nth derivative of the polynomial.
+   *
+   * @param n - The number of times to differentiate the polynomial.
+   */
+  public differentiate(n = 1): Polynomial {
+    switch (n) {
+      case 0:
+        return this;
+      case 1:
+        return new Polynomial(this.c1, 2 * this.c2, 3 * this.c3, 0);
+      case 2:
+        return new Polynomial(2 * this.c2, 6 * this.c3, 0, 0);
+      case 3:
+        return new Polynomial(6 * this.c3, 0, 0, 0);
+      default:
+        throw new Error('Unsupported derivative');
+    }
+  }
+
+  /**
+   * Evaluate the polynomial at the given value t.
+   *
+   * @param t - The value to sample at
+   */
+  public eval(t: number): number;
+  /**
+   * Evaluate the nth derivative of the polynomial at the given value t.
+   *
+   * @param t - The value to sample at
+   * @param derivative - The derivative of the polynomial to sample from
+   */
+  public eval(t: number, derivative: number): number;
+  public eval(t: number, derivative = 0): number {
+    if (derivative !== 0) {
+      return this.differentiate(derivative).eval(t);
+    }
+    return this.c3 * (t * t * t) + this.c2 * (t * t) + this.c1 * t + this.c0;
+  }
+
+  /**
+   * Split the polynomial into two polynomials of the same overall shape.
+   *
+   * @param u - The point at which to split the polynomial.
+   */
+  public split(u: number): [Polynomial, Polynomial] {
+    const d = 1 - u;
+
+    const pre = new Polynomial(
+      this.c0,
+      this.c1 * u,
+      this.c2 * u * u,
+      this.c3 * u * u * u,
+    );
+    const post = new Polynomial(
+      this.eval(0),
+      d * this.differentiate(1).eval(u),
+      ((d * d) / 2) * this.differentiate(2).eval(u),
+      ((d * d * d) / 6) * this.differentiate(3).eval(u),
+    );
+
+    return [pre, post];
+  }
+
+  /**
+   * Calculate the roots (values where this polynomial = 0).
+   *
+   * @remarks
+   * Depending on the degree of the polynomial, returns between 0 and 3 results.
+   */
+  public roots(): number[] {
+    switch (this.degree) {
+      case 3:
+        return this.solveCubicRoots();
+      case 2:
+        return this.solveQuadraticRoots();
+      case 1:
+        return this.solveLinearRoot();
+      case 0:
+        return [];
+      default:
+        throw new Error(`Unsupported polynomial degree: ${this.degree}`);
+    }
+  }
+
+  /**
+   * Calculate the local extrema of the polynomial.
+   */
+  public localExtrema(): number[] {
+    return this.differentiate().roots();
+  }
+
+  /**
+   * Calculate the local extrema of the polynomial in the unit interval.
+   */
+  public localExtrema01(): number[] {
+    const all = this.localExtrema();
+    const valids = [];
+    for (let i = 0; i < all.length; i++) {
+      const t = all[i];
+      if (t >= 0 && t <= 1) {
+        valids.push(all[i]);
+      }
+    }
+    return valids;
+  }
+
+  /**
+   * Return the output value range within the unit interval.
+   */
+  public outputRange01(): number[] {
+    let range = [this.eval(0), this.eval(1)];
+
+    // Expands the minimum or maximum value of the range to contain the given
+    // value.
+    const encapsulate = (value: number) => {
+      if (range[1] > range[0]) {
+        range = [Math.min(range[0], value), Math.max(range[1], value)];
+      } else {
+        range = [Math.min(range[1], value), Math.max(range[0], value)];
+      }
+    };
+
+    this.localExtrema01().forEach(t => encapsulate(this.eval(t)));
+
+    return range;
+  }
+
+  private solveCubicRoots() {
+    const a = this.c0;
+    const b = this.c1;
+    const c = this.c2;
+    const d = this.c3;
+
+    // First, depress the cubic to make it easier to solve
+    const aa = a * a;
+    const ac = a * c;
+    const bb = b * b;
+    const p = (3 * ac - bb) / (3 * aa);
+    const q = (2 * bb * b - 9 * ac * b + 27 * aa * d) / (27 * aa * a);
+
+    const dpr = this.solveDepressedCubicRoots(p, q);
+
+    // We now have the roots of the depressed cubic, now convert back to the
+    // normal cubic
+    const undepressRoot = (r: number) => r - b / (3 * a);
+    switch (dpr.length) {
+      case 1:
+        return [undepressRoot(dpr[0])];
+      case 2:
+        return [undepressRoot(dpr[0]), undepressRoot(dpr[1])];
+      case 3:
+        return [
+          undepressRoot(dpr[0]),
+          undepressRoot(dpr[1]),
+          undepressRoot(dpr[2]),
+        ];
+      default:
+        return [];
+    }
+  }
+
+  private solveDepressedCubicRoots(p: number, q: number): number[] {
+    // t³+pt+q = 0
+
+    // Triple root - one solution. solve x³+q = 0 => x = cr(-q)
+    if (this.almostZero(p)) {
+      return [Math.cbrt(-q)];
+    }
+
+    const TAU = Math.PI * 2;
+    const discriminant = 4 * p * p * p + 27 * q * q;
+    if (discriminant < 0.00001) {
+      // Two or three roots guaranteed, use trig solution
+      const pre = 2 * Math.sqrt(-p / 3);
+      const acosInner = ((3 * q) / (2 * p)) * Math.sqrt(-3 / p);
+
+      const getRoot = (k: number) =>
+        pre *
+        Math.cos((1 / 3) * Math.acos(clamp(-1, 1, acosInner)) - (TAU / 3) * k);
+
+      // If acos hits 0 or TAU/2, the offsets will have the same value,
+      // which means we have a double root plus one regular root on our hands
+      if (acosInner >= 0.9999) {
+        // two roots - one single and one double root
+        return [getRoot(0), getRoot(2)];
+      }
+
+      if (acosInner <= -0.9999) {
+        // two roots - one single and one double root
+        return [getRoot(1), getRoot(2)];
+      }
+
+      return [getRoot(0), getRoot(1), getRoot(2)];
+    }
+
+    if (discriminant > 0 && p < 0) {
+      // one root
+      const coshInner =
+        (1 / 3) *
+        Math.acosh(((-3 * Math.abs(q)) / (2 * p)) * Math.sqrt(-3 / p));
+      const r = -2 * Math.sign(q) * Math.sqrt(-p / 3) * Math.cosh(coshInner);
+      return [r];
+    }
+
+    if (p > 0) {
+      // one root
+      const sinhInner =
+        (1 / 3) * Math.asinh(((3 * q) / (2 * p)) * Math.sqrt(3 / p));
+      const r = -2 * Math.sqrt(p / 3) * Math.sinh(sinhInner);
+      return [r];
+    }
+
+    // no roots
+    return [];
+  }
+
+  private solveQuadraticRoots() {
+    const a = this.c2;
+    const b = this.c1;
+    const c = this.c0;
+    const rootContent = b * b - 4 * a * c;
+
+    if (this.almostZero(rootContent)) {
+      // two equivalent solutions at one point
+      return [-b / (2 * a)];
+    }
+
+    if (rootContent >= 0) {
+      const root = Math.sqrt(rootContent);
+      // crosses at two points
+      const r0 = (-b - root) / (2 * a);
+      const r1 = (-b + root) / (2 * a);
+
+      return [Math.min(r0, r1), Math.max(r0, r1)];
+    }
+
+    return [];
+  }
+
+  private solveLinearRoot() {
+    return [-this.c0 / this.c1];
+  }
+
+  private almostZero(value: number) {
+    return Math.abs(0 - value) <= Number.EPSILON;
+  }
+}

package/src/lib/curves/Polynomial2D.ts

@@ -0,0 +1,62 @@
+import {BBox, Vector2} from '@canvas-commons/core';
+
+import {Polynomial} from './Polynomial';
+
+export class Polynomial2D {
+  public readonly x: Polynomial;
+  public readonly y: Polynomial;
+
+  public constructor(c0: Vector2, c1: Vector2, c2: Vector2, c3: Vector2);
+  public constructor(c0: Vector2, c1: Vector2, c2: Vector2);
+  public constructor(x: Polynomial, y: Polynomial);
+  public constructor(
+    public readonly c0: Vector2 | Polynomial,
+    public readonly c1: Vector2 | Polynomial,
+    public readonly c2?: Vector2,
+    public readonly c3?: Vector2,
+  ) {
+    if (c0 instanceof Polynomial) {
+      this.x = c0;
+      this.y = c1 as Polynomial;
+    } else if (c3 !== undefined) {
+      this.x = new Polynomial(c0.x, (c1 as Vector2).x, c2!.x, c3.x);
+      this.y = new Polynomial(c0.y, (c1 as Vector2).y, c2!.y, c3.y);
+    } else {
+      this.x = new Polynomial(c0.x, (c1 as Vector2).x, c2!.x);
+      this.y = new Polynomial(c0.y, (c1 as Vector2).y, c2!.y);
+    }
+  }
+
+  public eval(t: number, derivative = 0): Vector2 {
+    return new Vector2(
+      this.x.differentiate(derivative).eval(t),
+      this.y.differentiate(derivative).eval(t),
+    );
+  }
+
+  public split(u: number): [Polynomial2D, Polynomial2D] {
+    const [xPre, xPost] = this.x.split(u);
+    const [yPre, yPost] = this.y.split(u);
+    return [new Polynomial2D(xPre, yPre), new Polynomial2D(xPost, yPost)];
+  }
+
+  public differentiate(n = 1): Polynomial2D {
+    return new Polynomial2D(this.x.differentiate(n), this.y.differentiate(n));
+  }
+
+  public evalDerivative(t: number): Vector2 {
+    return this.differentiate().eval(t);
+  }
+
+  /**
+   * Calculate the tight axis-aligned bounds of the curve in the unit interval.
+   */
+  public getBounds(): BBox {
+    const rangeX = this.x.outputRange01();
+    const rangeY = this.y.outputRange01();
+    return BBox.fromPoints(
+      new Vector2(Math.min(...rangeX), Math.max(...rangeY)),
+      new Vector2(Math.max(...rangeX), Math.min(...rangeY)),
+    );
+  }
+}

package/src/lib/curves/PolynomialSegment.ts

@@ -0,0 +1,151 @@
+import {BBox, Vector2} from '@canvas-commons/core';
+import {moveTo} from '../utils';
+import {CurvePoint} from './CurvePoint';
+import {Polynomial2D} from './Polynomial2D';
+import {Segment} from './Segment';
+import {UniformPolynomialCurveSampler} from './UniformPolynomialCurveSampler';
+
+export abstract class PolynomialSegment extends Segment {
+  protected readonly pointSampler: UniformPolynomialCurveSampler;
+
+  public get arcLength(): number {
+    return this.length;
+  }
+
+  public abstract override get points(): Vector2[];
+
+  protected constructor(
+    protected readonly curve: Polynomial2D,
+    protected readonly length: number,
+  ) {
+    super();
+    this.pointSampler = new UniformPolynomialCurveSampler(this);
+  }
+
+  public getBBox(): BBox {
+    return this.curve.getBounds();
+  }
+
+  /**
+   * Evaluate the polynomial at the given t value.
+   *
+   * @param t - The t value at which to evaluate the curve.
+   */
+  public eval(t: number): CurvePoint {
+    const tangent = this.tangent(t);
+
+    return {
+      position: this.curve.eval(t),
+      tangent,
+      normal: tangent.perpendicular,
+    };
+  }
+
+  /**
+   * Split the curve into two separate polynomials at the given t value. The two
+   * resulting curves form the same overall shape as the original curve.
+   *
+   * @param t - The t value at which to split the curve.
+   */
+  public abstract split(t: number): [PolynomialSegment, PolynomialSegment];
+
+  public getPoint(distance: number): CurvePoint {
+    const closestPoint = this.pointSampler.pointAtDistance(
+      this.arcLength * distance,
+    );
+    return {
+      position: closestPoint.position,
+      tangent: closestPoint.tangent,
+      normal: closestPoint.tangent.perpendicular,
+    };
+  }
+
+  public transformPoints(matrix: DOMMatrix): Vector2[] {
+    return this.points.map(point => point.transformAsPoint(matrix));
+  }
+
+  /**
+   * Return the tangent of the point that sits at the provided t value on the
+   * curve.
+   *
+   * @param t - The t value at which to evaluate the curve.
+   */
+  public tangent(t: number): Vector2 {
+    return this.curve.evalDerivative(t).normalized;
+  }
+
+  public draw(
+    context: CanvasRenderingContext2D | Path2D,
+    start = 0,
+    end = 1,
+    move = true,
+  ): [CurvePoint, CurvePoint] {
+    let curve: PolynomialSegment | null = null;
+    let startT = start;
+    let endT = end;
+    let points = this.points;
+
+    if (start !== 0 || end !== 1) {
+      const startDistance = this.length * start;
+      const endDistance = this.length * end;
+
+      startT = this.pointSampler.distanceToT(startDistance);
+      endT = this.pointSampler.distanceToT(endDistance);
+      const relativeEndT = (endT - startT) / (1 - startT);
+
+      const [, startSegment] = this.split(startT);
+      [curve] = startSegment.split(relativeEndT);
+      points = curve.points;
+    }
+
+    if (move) {
+      moveTo(context, points[0]);
+    }
+    (curve ?? this).doDraw(context);
+
+    const startTangent = this.tangent(startT);
+    const endTangent = this.tangent(endT);
+
+    return [
+      {
+        position: points[0],
+        tangent: startTangent,
+        normal: startTangent.perpendicular,
+      },
+      {
+        position: points.at(-1)!,
+        tangent: endTangent,
+        normal: endTangent.perpendicular,
+      },
+    ];
+  }
+
+  public toSVGCommands(start = 0, end = 1, move = true): string {
+    let curve: PolynomialSegment | null = null;
+    let points = this.points;
+
+    if (start !== 0 || end !== 1) {
+      const startDistance = this.length * start;
+      const endDistance = this.length * end;
+
+      const startT = this.pointSampler.distanceToT(startDistance);
+      const endT = this.pointSampler.distanceToT(endDistance);
+      const relativeEndT = (endT - startT) / (1 - startT);
+
+      const [, startSegment] = this.split(startT);
+      [curve] = startSegment.split(relativeEndT);
+      points = curve.points;
+    }
+
+    const commands: string[] = [];
+    if (move) {
+      commands.push(`M ${points[0].x} ${points[0].y}`);
+    }
+    commands.push((curve ?? this).doSVGCommands());
+
+    return commands.join(' ');
+  }
+
+  protected abstract doDraw(context: CanvasRenderingContext2D | Path2D): void;
+  protected abstract doSVGCommands(): string;
+}

package/src/lib/curves/QuadBezierSegment.ts

@@ -0,0 +1,66 @@
+import {Vector2, lazy} from '@canvas-commons/core';
+import {quadraticCurveTo} from '../utils';
+import {Polynomial2D} from './Polynomial2D';
+import {PolynomialSegment} from './PolynomialSegment';
+
+/**
+ * A spline segment representing a quadratic Bézier curve.
+ */
+export class QuadBezierSegment extends PolynomialSegment {
+  @lazy(() => document.createElementNS('http://www.w3.org/2000/svg', 'path'))
+  private static el: SVGPathElement;
+
+  public get points(): Vector2[] {
+    return [this.p0, this.p1, this.p2];
+  }
+
+  public constructor(
+    public readonly p0: Vector2,
+    public readonly p1: Vector2,
+    public readonly p2: Vector2,
+  ) {
+    super(
+      new Polynomial2D(
+        p0,
+        // 2*(-p0+p1)
+        p0.flipped.add(p1).scale(2),
+        // p0-2*p1+p2
+        p0.sub(p1.scale(2)).add(p2),
+      ),
+      QuadBezierSegment.getLength(p0, p1, p2),
+    );
+  }
+
+  public split(t: number): [PolynomialSegment, PolynomialSegment] {
+    const a = new Vector2(
+      this.p0.x + (this.p1.x - this.p0.x) * t,
+      this.p0.y + (this.p1.y - this.p0.y) * t,
+    );
+    const b = new Vector2(
+      this.p1.x + (this.p2.x - this.p1.x) * t,
+      this.p1.y + (this.p2.y - this.p1.y) * t,
+    );
+    const p = new Vector2(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t);
+
+    const left = new QuadBezierSegment(this.p0, a, p);
+    const right = new QuadBezierSegment(p, b, this.p2);
+
+    return [left, right];
+  }
+
+  protected static getLength(p0: Vector2, p1: Vector2, p2: Vector2): number {
+    QuadBezierSegment.el.setAttribute(
+      'd',
+      `M ${p0.x} ${p0.y} Q ${p1.x} ${p1.y} ${p2.x} ${p2.y}`,
+    );
+    return QuadBezierSegment.el.getTotalLength();
+  }
+
+  protected override doDraw(context: CanvasRenderingContext2D | Path2D) {
+    quadraticCurveTo(context, this.p1, this.p2);
+  }
+
+  protected override doSVGCommands(): string {
+    return `Q ${this.p1.x} ${this.p1.y} ${this.p2.x} ${this.p2.y}`;
+  }
+}

package/src/lib/curves/Segment.ts

@@ -0,0 +1,31 @@
+import {Vector2} from '@canvas-commons/core';
+import {CurvePoint} from './CurvePoint';
+
+export abstract class Segment {
+  public abstract readonly points: Vector2[];
+
+  public abstract draw(
+    context: CanvasRenderingContext2D | Path2D,
+    start: number,
+    end: number,
+    move: boolean,
+  ): [CurvePoint, CurvePoint];
+
+  public abstract getPoint(distance: number): CurvePoint;
+
+  public abstract get arcLength(): number;
+
+  /**
+   * Convert this segment to SVG path commands.
+   *
+   * @param start - Start distance along the segment (0 to arcLength)
+   * @param end - End distance along the segment (0 to arcLength)
+   * @param move - Whether to include a moveTo command at the start
+   * @returns SVG path data string for this segment
+   */
+  public abstract toSVGCommands(
+    start: number,
+    end: number,
+    move: boolean,
+  ): string;
+}