@twick/2d 0.11.0

package/src/lib/curves/CubicBezierSegment.ts

@@ -0,0 +1,78 @@
+import {Vector2, lazy} from '@twick/core';
+import {bezierCurveTo} from '../utils';
+import {Polynomial2D} from './Polynomial2D';
+import {PolynomialSegment} from './PolynomialSegment';
+
+/**
+ * A spline segment representing a cubic Bézier curve.
+ */
+export class CubicBezierSegment 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, this.p3];
+  }
+
+  public constructor(
+    public readonly p0: Vector2,
+    public readonly p1: Vector2,
+    public readonly p2: Vector2,
+    public readonly p3: Vector2,
+  ) {
+    super(
+      new Polynomial2D(
+        p0,
+        // 3*(-p0+p1)
+        p0.flipped.add(p1).scale(3),
+        // 3*p0-6*p1+3*p2
+        p0.scale(3).sub(p1.scale(6)).add(p2.scale(3)),
+        // -p0+3*p1-3*p2+p3
+        p0.flipped.add(p1.scale(3)).sub(p2.scale(3)).add(p3),
+      ),
+      CubicBezierSegment.getLength(p0, p1, p2, p3),
+    );
+  }
+
+  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 c = new Vector2(
+      this.p2.x + (this.p3.x - this.p2.x) * t,
+      this.p2.y + (this.p3.y - this.p2.y) * t,
+    );
+    const d = new Vector2(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t);
+    const e = new Vector2(b.x + (c.x - b.x) * t, b.y + (c.y - b.y) * t);
+    const p = new Vector2(d.x + (e.x - d.x) * t, d.y + (e.y - d.y) * t);
+
+    const left = new CubicBezierSegment(this.p0, a, d, p);
+    const right = new CubicBezierSegment(p, e, c, this.p3);
+
+    return [left, right];
+  }
+
+  protected override doDraw(context: CanvasRenderingContext2D | Path2D) {
+    bezierCurveTo(context, this.p1, this.p2, this.p3);
+  }
+
+  protected static getLength(
+    p0: Vector2,
+    p1: Vector2,
+    p2: Vector2,
+    p3: Vector2,
+  ): number {
+    // Let the browser do the work for us instead of calculating the arclength
+    // manually.
+    CubicBezierSegment.el.setAttribute(
+      'd',
+      `M ${p0.x} ${p0.y} C ${p1.x} ${p1.y} ${p2.x} ${p2.y} ${p3.x} ${p3.y}`,
+    );
+    return CubicBezierSegment.el.getTotalLength();
+  }
+}

package/src/lib/curves/CurveDrawingInfo.ts

@@ -0,0 +1,11 @@
+import type {Vector2} from '@twick/core';
+
+export interface CurveDrawingInfo {
+  path: Path2D;
+  arrowSize: number;
+  endPoint: Vector2;
+  endTangent: Vector2;
+  startPoint: Vector2;
+  startTangent: Vector2;
+  startOffset: number;
+}

package/src/lib/curves/CurvePoint.ts

@@ -0,0 +1,15 @@
+import type {Vector2} from '@twick/core';
+
+export interface CurvePoint {
+  position: Vector2;
+  /**
+   * @deprecated
+   * The tangent is currently inconsistent for different types of curves and may
+   * sometimes return the normal of the point, instead. This will be fixed in
+   * the next major version but is kept as is for now for backwards
+   * compatibility reasons. To always get the real tangent of the point, you can
+   * use `normal.flipped.perpendicular`, instead.
+   */
+  tangent: Vector2;
+  normal: Vector2;
+}

package/src/lib/curves/CurveProfile.ts

@@ -0,0 +1,7 @@
+import type {Segment} from './Segment';
+
+export interface CurveProfile {
+  arcLength: number;
+  segments: Segment[];
+  minSin: number;
+}

package/src/lib/curves/KnotInfo.ts

@@ -0,0 +1,10 @@
+import type {Vector2} from '@twick/core';
+
+export type KnotAutoHandles = {start: number; end: number};
+
+export interface KnotInfo {
+  position: Vector2;
+  startHandle: Vector2;
+  endHandle: Vector2;
+  auto: KnotAutoHandles;
+}

package/src/lib/curves/LineSegment.ts

@@ -0,0 +1,62 @@
+import type {Vector2} from '@twick/core';
+import {lineTo, moveTo} from '../utils';
+import type {CurvePoint} from './CurvePoint';
+import {Segment} from './Segment';
+
+export class LineSegment extends Segment {
+  private readonly length: number;
+  private readonly vector: Vector2;
+  private readonly normal: Vector2;
+  public override readonly points: Vector2[];
+
+  public constructor(
+    public readonly from: Vector2,
+    public readonly to: Vector2,
+  ) {
+    super();
+    this.vector = to.sub(from);
+    this.length = this.vector.magnitude;
+    this.normal = this.vector.perpendicular.normalized.safe;
+    this.points = [from, to];
+  }
+
+  public get arcLength(): number {
+    return this.length;
+  }
+
+  public draw(
+    context: CanvasRenderingContext2D | Path2D,
+    start = 0,
+    end = 1,
+    move = false,
+  ): [CurvePoint, CurvePoint] {
+    const from = this.from.add(this.vector.scale(start));
+    const to = this.from.add(this.vector.scale(end));
+    if (move) {
+      moveTo(context, from);
+    }
+    lineTo(context, to);
+
+    return [
+      {
+        position: from,
+        tangent: this.normal.flipped,
+        normal: this.normal,
+      },
+      {
+        position: to,
+        tangent: this.normal,
+        normal: this.normal,
+      },
+    ];
+  }
+
+  public getPoint(distance: number): CurvePoint {
+    const point = this.from.add(this.vector.scale(distance));
+    return {
+      position: point,
+      tangent: this.normal.flipped,
+      normal: this.normal,
+    };
+  }
+}

package/src/lib/curves/Polynomial.ts

@@ -0,0 +1,355 @@
+import {clamp} from '@twick/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 '@twick/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)),
+    );
+  }
+}