forma-dsl 0.1.1

package/src/values/transform.js

@@ -0,0 +1,159 @@
+/** @import { Dimensionality } from '../index.js' */
+/** @import { VectorLike } from './vector.js' */
+
+import { Vector } from './vector.js';
+import { Angle } from './angle.js';
+
+/**
+ * An affine transform, held as a column-major matrix of the size the kernel wants: 3x3 for
+ * 2D and 4x4 for 3D, both with the last row ignored on the way in.
+ *
+ * Column-major throughout, because that is what Manifold reads. Storing row-major here and
+ * transposing at the boundary would put a silent transpose in the one place a wrong model
+ * still renders.
+ */
+export class Transform {
+  /**
+   * @param {Dimensionality} dim Whether this transforms 2D or 3D geometry.
+   * @param {ReadonlyArray<number>} m The matrix, column-major, `(dim + 1)²` entries.
+   */
+  constructor(dim, m) {
+    /** @type {Dimensionality} Whether this transforms 2D or 3D geometry. */
+    this.dim = dim;
+    /** @type {ReadonlyArray<number>} The matrix, column-major and frozen. */
+    this.m = Object.freeze(m.map(Number));
+    Object.freeze(this);
+  }
+
+  /**
+   * @param {Dimensionality} dim Whether this transforms 2D or 3D geometry.
+   * @returns {Transform} The transform that changes nothing.
+   */
+  static identity(dim) {
+    const n = dim + 1;
+    const m = new Array(n * n).fill(0);
+    for (let i = 0; i < n; i++) m[i * n + i] = 1;
+    return new Transform(dim, m);
+  }
+
+  /** @returns {number} The side length of the matrix, one more than the dimensionality. */
+  get order() { return this.dim + 1; }
+
+  /**
+   * @param {number} row Row index.
+   * @param {number} col Column index.
+   * @returns {number} The entry, read out of the column-major storage.
+   */
+  at(row, col) { return this.m[col * this.order + row]; }
+
+  /**
+   * Composes two transforms as `this ∘ other`, so `other` runs first.
+   *
+   * That order matches how the blocks nest: the transform block closer to the shape is
+   * applied to it first.
+   *
+   * @param {Transform} other The transform to apply before this one.
+   * @returns {Transform} The combined transform.
+   */
+  concat(other) {
+    const n = this.order;
+    const out = new Array(n * n).fill(0);
+    for (let c = 0; c < n; c++) {
+      for (let r = 0; r < n; r++) {
+        let sum = 0;
+        for (let k = 0; k < n; k++) sum += this.at(r, k) * other.at(k, c);
+        out[c * n + r] = sum;
+      }
+    }
+    return new Transform(this.dim, out);
+  }
+
+  /**
+   * @param {VectorLike} offset How far to move, per axis.
+   * @param {Dimensionality} dim Whether this transforms 2D or 3D geometry.
+   * @returns {Transform} The translation.
+   */
+  static translation(offset, dim) {
+    const v = Vector.of(offset, dim);
+    const t = Transform.identity(dim);
+    const m = [...t.m];
+    const n = dim + 1;
+    for (let i = 0; i < dim; i++) m[dim * n + i] = v.components[i];
+    return new Transform(dim, m);
+  }
+
+  /**
+   * @param {VectorLike} factor The scale per axis; a number scales every axis alike.
+   * @param {Dimensionality} dim Whether this transforms 2D or 3D geometry.
+   * @returns {Transform} The scaling.
+   */
+  static scaling(factor, dim) {
+    const v = Vector.of(factor, dim);
+    const n = dim + 1;
+    const m = new Array(n * n).fill(0);
+    for (let i = 0; i < dim; i++) m[i * n + i] = v.components[i];
+    m[dim * n + dim] = 1;
+    return new Transform(dim, m);
+  }
+
+  /**
+   * @param {Angle | number} angle The rotation; a bare number is read as degrees.
+   * @returns {Transform} The 2D rotation about the origin.
+   */
+  static rotation2D(angle) {
+    const a = Angle.of(angle);
+    const c = a.cos, s = a.sin;
+    return new Transform(2, [c, s, 0, -s, c, 0, 0, 0, 1]);
+  }
+
+  /**
+   * Rotates about x, then y, then z — the order OpenSCAD and Cadova both use, so a model
+   * ported from either lands in the same orientation.
+   *
+   * @param {Vector | ReadonlyArray<number>} angles Degrees about x, y and z.
+   * @returns {Transform} The 3D rotation about the origin.
+   */
+  static rotation3D(angles) {
+    const v = Vector.of(angles, 3);
+    const [x, y, z] = v.components.map((d) => Angle.of(d));
+    const rx = new Transform(3, [1, 0, 0, 0, 0, x.cos, x.sin, 0, 0, -x.sin, x.cos, 0, 0, 0, 0, 1]);
+    const ry = new Transform(3, [y.cos, 0, -y.sin, 0, 0, 1, 0, 0, y.sin, 0, y.cos, 0, 0, 0, 0, 1]);
+    const rz = new Transform(3, [z.cos, z.sin, 0, 0, -z.sin, z.cos, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+    return rz.concat(ry).concat(rx);
+  }
+
+  /**
+   * @param {Angle | number | Vector | ReadonlyArray<number>} angles Degrees. A single
+   *   angle in 2D, three in 3D; passing the wrong shape for `dim` is the caller's error.
+   * @param {Dimensionality} dim Whether this transforms 2D or 3D geometry.
+   * @returns {Transform} The rotation about the origin.
+   */
+  static rotation(angles, dim) {
+    return dim === 2
+      ? Transform.rotation2D(/** @type {Angle | number} */ (angles))
+      : Transform.rotation3D(/** @type {Vector | ReadonlyArray<number>} */ (angles));
+  }
+
+  /**
+   * Reflects in the plane (or line) through the origin with this normal. The normal is
+   * normalised first, so its length does not change the result.
+   *
+   * @param {Vector | ReadonlyArray<number>} normal The normal of the mirror plane.
+   * @param {Dimensionality} dim Whether this transforms 2D or 3D geometry.
+   * @returns {Transform} The reflection.
+   */
+  static mirroring(normal, dim) {
+    const n = Vector.of(normal, dim).normalized();
+    const order = dim + 1;
+    const m = Transform.identity(dim).m.slice();
+    for (let c = 0; c < dim; c++) {
+      for (let r = 0; r < dim; r++) {
+        m[c * order + r] = (r === c ? 1 : 0) - 2 * n.components[r] * n.components[c];
+      }
+    }
+    return new Transform(dim, m);
+  }
+
+  /** @returns {number[]} A copy of the matrix, safe for the caller to keep. */
+  toArray() { return [...this.m]; }
+}

package/src/values/vector.js

@@ -0,0 +1,169 @@
+/**
+ * Anything a model can write where a vector is wanted.
+ *
+ * A bare number is accepted as shorthand for every component, which is what lets
+ * `scale { factor = 2 }` read as naturally as `factor = [2, 1, 1]`.
+ *
+ * @typedef {Vector | number | ReadonlyArray<number> | Record<string, number>} VectorLike
+ */
+
+/**
+ * A 2D or 3D vector.
+ *
+ * One class covers both, because every operation below is componentwise and a separate 3D
+ * class would be the same code with one more letter.
+ */
+export class Vector {
+  /**
+   * @param {ReadonlyArray<number>} components Two or three components.
+   */
+  constructor(components) {
+    /** @type {ReadonlyArray<number>} The components, frozen. */
+    this.components = Object.freeze(components.map(Number));
+    Object.freeze(this);
+  }
+
+  /**
+   * Reads a vector out of whatever the caller had.
+   *
+   * @param {VectorLike} value A vector, a scalar to broadcast, an array, or an `{x, y, z}`
+   *   object whose missing keys are read as zero.
+   * @param {number} dimensions How many components the result must have.
+   * @returns {Vector} The vector.
+   * @throws {TypeError} If the value is the wrong size, or not a shape a vector can be read from.
+   */
+  static of(value, dimensions) {
+    if (value instanceof Vector) {
+      if (value.size !== dimensions) {
+        throw new TypeError(`expected a ${dimensions}D vector, got ${value.size}D`);
+      }
+      return value;
+    }
+    if (typeof value === 'number') {
+      return new Vector(new Array(dimensions).fill(value));
+    }
+    if (Array.isArray(value)) {
+      if (value.length !== dimensions) {
+        throw new TypeError(`expected ${dimensions} components, got ${value.length}`);
+      }
+      return new Vector(value);
+    }
+    if (value && typeof value === 'object') {
+      const keys = dimensions === 2 ? ['x', 'y'] : ['x', 'y', 'z'];
+      return new Vector(keys.map((k) => value[k] ?? 0));
+    }
+    throw new TypeError(`cannot read a ${dimensions}D vector from ${typeof value}`);
+  }
+
+  /**
+   * @param {number} dimensions How many components.
+   * @returns {Vector} The origin.
+   */
+  static zero(dimensions) {
+    return new Vector(new Array(dimensions).fill(0));
+  }
+
+  /** @returns {number} How many components the vector has. */
+  get size() { return this.components.length; }
+
+  /** @returns {number} The first component. */
+  get x() { return this.components[0]; }
+
+  /** @returns {number} The second component. */
+  get y() { return this.components[1]; }
+
+  /** @returns {number} The third component, or `undefined` in 2D. */
+  get z() { return this.components[2]; }
+
+  /**
+   * @param {VectorLike} other The right-hand side.
+   * @param {(a: number, b: number) => number} f Applied to each pair of components.
+   * @returns {Vector} The result.
+   */
+  #zip(other, f) {
+    const rhs = Vector.of(other, this.size);
+    return new Vector(this.components.map((v, i) => f(v, rhs.components[i])));
+  }
+
+  /**
+   * @param {VectorLike} other The right-hand side.
+   * @returns {Vector} The componentwise sum.
+   */
+  plus(other) { return this.#zip(other, (a, b) => a + b); }
+
+  /**
+   * @param {VectorLike} other The right-hand side.
+   * @returns {Vector} The componentwise difference.
+   */
+  minus(other) { return this.#zip(other, (a, b) => a - b); }
+
+  /**
+   * @param {VectorLike} other The right-hand side; a number scales every component.
+   * @returns {Vector} The componentwise product.
+   */
+  times(other) { return this.#zip(other, (a, b) => a * b); }
+
+  /**
+   * @param {VectorLike} other The right-hand side; a number divides every component.
+   * @returns {Vector} The componentwise quotient.
+   */
+  dividedBy(other) { return this.#zip(other, (a, b) => a / b); }
+
+  /** @returns {Vector} The vector pointing the other way. */
+  negated() { return new Vector(this.components.map((v) => -v)); }
+
+  /**
+   * @param {VectorLike} other The right-hand side.
+   * @returns {number} The dot product.
+   */
+  dot(other) {
+    const rhs = Vector.of(other, this.size);
+    return this.components.reduce((sum, v, i) => sum + v * rhs.components[i], 0);
+  }
+
+  /** @returns {number} The length of the vector. */
+  get magnitude() { return Math.sqrt(this.dot(this)); }
+
+  /**
+   * A zero vector normalises to itself rather than to NaN, so a degenerate normal cannot
+   * quietly poison a transform downstream.
+   *
+   * @returns {Vector} The vector scaled to unit length.
+   */
+  normalized() {
+    const m = this.magnitude;
+    return m === 0 ? this : new Vector(this.components.map((v) => v / m));
+  }
+
+  /**
+   * @param {Vector | ReadonlyArray<number>} other The right-hand side; must be 3D.
+   * @returns {Vector} The cross product.
+   */
+  cross(other) {
+    const b = Vector.of(other, 3);
+    const [ax, ay, az] = this.components;
+    const [bx, by, bz] = b.components;
+    return new Vector([ay * bz - az * by, az * bx - ax * bz, ax * by - ay * bx]);
+  }
+
+  /** @returns {number[]} A copy of the components, safe for the caller to keep. */
+  toArray() { return [...this.components]; }
+
+  /** @returns {string} The components in parentheses, for diagnostics. */
+  toString() { return `(${this.components.join(', ')})`; }
+}
+
+/**
+ * @param {number} x The first component.
+ * @param {number} y The second component.
+ * @returns {Vector} A 2D vector.
+ */
+export const vector2 = (x, y) => new Vector([x, y]);
+
+/**
+ * @param {number} x The first component.
+ * @param {number} y The second component.
+ * @param {number} z The third component.
+ * @returns {Vector} A 3D vector.
+ */
+export const vector3 = (x, y, z) => new Vector([x, y, z]);