@emasoft/svg-matrix 1.0.2 → 1.0.3

package/src/transforms3d.js

@@ -1,7 +1,32 @@
 import Decimal from 'decimal.js';
 import { Matrix } from './matrix.js';
+
+/**
+ * Helper to convert any numeric input to Decimal.
+ * @param {number|string|Decimal} x - The value to convert
+ * @returns {Decimal} The Decimal representation
+ */
 const D = x => (x instanceof Decimal ? x : new Decimal(x));
 
+/**
+ * 3D Affine Transforms using 4x4 homogeneous matrices.
+ *
+ * All transforms return 4x4 Matrix objects that can be composed via multiplication.
+ * Transform composition is right-to-left: T.mul(R).mul(S) applies S first, then R, then T.
+ *
+ * Rotation matrices use the right-hand rule: positive angles rotate counterclockwise
+ * when looking down the axis toward the origin.
+ *
+ * @module Transforms3D
+ */
+
+/**
+ * Create a 3D translation matrix.
+ * @param {number|string|Decimal} tx - Translation in X direction
+ * @param {number|string|Decimal} ty - Translation in Y direction
+ * @param {number|string|Decimal} tz - Translation in Z direction
+ * @returns {Matrix} 4x4 translation matrix
+ */
 export function translation(tx, ty, tz) {
   return Matrix.from([
     [new Decimal(1), new Decimal(0), new Decimal(0), D(tx)],
@@ -11,6 +36,13 @@ export function translation(tx, ty, tz) {
   ]);
 }
 
+/**
+ * Create a 3D scaling matrix.
+ * @param {number|string|Decimal} sx - Scale factor in X direction
+ * @param {number|string|Decimal} [sy=sx] - Scale factor in Y direction (defaults to sx)
+ * @param {number|string|Decimal} [sz=sx] - Scale factor in Z direction (defaults to sx)
+ * @returns {Matrix} 4x4 scaling matrix
+ */
 export function scale(sx, sy = null, sz = null) {
   if (sy === null) sy = sx;
   if (sz === null) sz = sx;
@@ -22,16 +54,103 @@ export function scale(sx, sy = null, sz = null) {
   ]);
 }
 
-// rotation around arbitrary axis (ux,uy,uz) through origin by angle theta (radians)
+/**
+ * Create a rotation matrix around the X axis.
+ *
+ * | 1    0        0     0 |
+ * | 0  cos(θ)  -sin(θ)  0 |
+ * | 0  sin(θ)   cos(θ)  0 |
+ * | 0    0        0     1 |
+ *
+ * @param {number|string|Decimal} theta - Rotation angle in radians
+ * @returns {Matrix} 4x4 rotation matrix
+ */
+export function rotateX(theta) {
+  const t = D(theta);
+  const c = new Decimal(Math.cos(t.toNumber()));
+  const s = new Decimal(Math.sin(t.toNumber()));
+  return Matrix.from([
+    [new Decimal(1), new Decimal(0), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), c, s.negated(), new Decimal(0)],
+    [new Decimal(0), s, c, new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}
+
+/**
+ * Create a rotation matrix around the Y axis.
+ *
+ * |  cos(θ)  0  sin(θ)  0 |
+ * |    0     1    0     0 |
+ * | -sin(θ)  0  cos(θ)  0 |
+ * |    0     0    0     1 |
+ *
+ * @param {number|string|Decimal} theta - Rotation angle in radians
+ * @returns {Matrix} 4x4 rotation matrix
+ */
+export function rotateY(theta) {
+  const t = D(theta);
+  const c = new Decimal(Math.cos(t.toNumber()));
+  const s = new Decimal(Math.sin(t.toNumber()));
+  return Matrix.from([
+    [c, new Decimal(0), s, new Decimal(0)],
+    [new Decimal(0), new Decimal(1), new Decimal(0), new Decimal(0)],
+    [s.negated(), new Decimal(0), c, new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}
+
+/**
+ * Create a rotation matrix around the Z axis.
+ *
+ * | cos(θ)  -sin(θ)  0  0 |
+ * | sin(θ)   cos(θ)  0  0 |
+ * |   0        0     1  0 |
+ * |   0        0     0  1 |
+ *
+ * @param {number|string|Decimal} theta - Rotation angle in radians
+ * @returns {Matrix} 4x4 rotation matrix
+ */
+export function rotateZ(theta) {
+  const t = D(theta);
+  const c = new Decimal(Math.cos(t.toNumber()));
+  const s = new Decimal(Math.sin(t.toNumber()));
+  return Matrix.from([
+    [c, s.negated(), new Decimal(0), new Decimal(0)],
+    [s, c, new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(1), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}
+
+/**
+ * Create a rotation matrix around an arbitrary axis through the origin.
+ * Uses Rodrigues' rotation formula.
+ *
+ * The axis vector (ux, uy, uz) is automatically normalized.
+ *
+ * @param {number|string|Decimal} ux - X component of rotation axis
+ * @param {number|string|Decimal} uy - Y component of rotation axis
+ * @param {number|string|Decimal} uz - Z component of rotation axis
+ * @param {number|string|Decimal} theta - Rotation angle in radians
+ * @returns {Matrix} 4x4 rotation matrix
+ * @throws {Error} If axis is zero vector
+ */
 export function rotateAroundAxis(ux, uy, uz, theta) {
   const u = [D(ux), D(uy), D(uz)];
   let norm = u[0].mul(u[0]).plus(u[1].mul(u[1])).plus(u[2].mul(u[2])).sqrt();
-  if (norm.isZero()) throw new Error('Rotation axis cannot be zero');
-  u[0] = u[0].div(norm); u[1] = u[1].div(norm); u[2] = u[2].div(norm);
+  if (norm.isZero()) throw new Error('Rotation axis cannot be zero vector');
+  // Normalize axis
+  u[0] = u[0].div(norm);
+  u[1] = u[1].div(norm);
+  u[2] = u[2].div(norm);
+
   const t = D(theta);
   const c = new Decimal(Math.cos(t.toNumber()));
   const s = new Decimal(Math.sin(t.toNumber()));
   const one = new Decimal(1);
+
+  // Rodrigues' rotation formula components
   const ux2 = u[0].mul(u[0]), uy2 = u[1].mul(u[1]), uz2 = u[2].mul(u[2]);
   const m00 = ux2.plus(c.mul(one.minus(ux2)));
   const m01 = u[0].mul(u[1]).mul(one.minus(c)).minus(u[2].mul(s));
@@ -42,10 +161,101 @@ export function rotateAroundAxis(ux, uy, uz, theta) {
   const m20 = u[2].mul(u[0]).mul(one.minus(c)).minus(u[1].mul(s));
   const m21 = u[2].mul(u[1]).mul(one.minus(c)).plus(u[0].mul(s));
   const m22 = uz2.plus(c.mul(one.minus(uz2)));
+
   return Matrix.from([
     [m00, m01, m02, new Decimal(0)],
     [m10, m11, m12, new Decimal(0)],
     [m20, m21, m22, new Decimal(0)],
     [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
   ]);
-}
+}
+
+/**
+ * Create a rotation matrix around an arbitrary axis through a specific point.
+ * Equivalent to: translate(px, py, pz) × rotateAroundAxis(...) × translate(-px, -py, -pz)
+ *
+ * @param {number|string|Decimal} ux - X component of rotation axis
+ * @param {number|string|Decimal} uy - Y component of rotation axis
+ * @param {number|string|Decimal} uz - Z component of rotation axis
+ * @param {number|string|Decimal} theta - Rotation angle in radians
+ * @param {number|string|Decimal} px - X coordinate of rotation center
+ * @param {number|string|Decimal} py - Y coordinate of rotation center
+ * @param {number|string|Decimal} pz - Z coordinate of rotation center
+ * @returns {Matrix} 4x4 rotation matrix around point (px, py, pz)
+ */
+export function rotateAroundPoint(ux, uy, uz, theta, px, py, pz) {
+  const pxD = D(px), pyD = D(py), pzD = D(pz);
+  return translation(pxD, pyD, pzD)
+    .mul(rotateAroundAxis(ux, uy, uz, theta))
+    .mul(translation(pxD.negated(), pyD.negated(), pzD.negated()));
+}
+
+/**
+ * Apply a 3D transform matrix to a point.
+ * Uses homogeneous coordinates with perspective division.
+ *
+ * @param {Matrix} M - 4x4 transformation matrix
+ * @param {number|string|Decimal} x - X coordinate of point
+ * @param {number|string|Decimal} y - Y coordinate of point
+ * @param {number|string|Decimal} z - Z coordinate of point
+ * @returns {Decimal[]} Transformed point as [x', y', z'] array of Decimals
+ */
+export function applyTransform(M, x, y, z) {
+  const P = Matrix.from([[D(x)], [D(y)], [D(z)], [new Decimal(1)]]);
+  const R = M.mul(P);
+  const rx = R.data[0][0], ry = R.data[1][0], rz = R.data[2][0], rw = R.data[3][0];
+  // Perspective division (for affine transforms, rw is always 1)
+  return [rx.div(rw), ry.div(rw), rz.div(rw)];
+}
+
+/**
+ * Create a reflection matrix across the XY plane (flips Z).
+ * @returns {Matrix} 4x4 reflection matrix
+ */
+export function reflectXY() {
+  return Matrix.from([
+    [new Decimal(1), new Decimal(0), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(1), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(-1), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}
+
+/**
+ * Create a reflection matrix across the XZ plane (flips Y).
+ * @returns {Matrix} 4x4 reflection matrix
+ */
+export function reflectXZ() {
+  return Matrix.from([
+    [new Decimal(1), new Decimal(0), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(-1), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(1), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}
+
+/**
+ * Create a reflection matrix across the YZ plane (flips X).
+ * @returns {Matrix} 4x4 reflection matrix
+ */
+export function reflectYZ() {
+  return Matrix.from([
+    [new Decimal(-1), new Decimal(0), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(1), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(1), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}
+
+/**
+ * Create a reflection matrix across the origin (flips X, Y, and Z).
+ * @returns {Matrix} 4x4 reflection matrix
+ */
+export function reflectOrigin() {
+  return Matrix.from([
+    [new Decimal(-1), new Decimal(0), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(-1), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(-1), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}

package/src/vector.js

@@ -1,60 +1,147 @@
 import Decimal from 'decimal.js';
+
+/**
+ * Helper to convert any numeric input to Decimal.
+ * Accepts numbers, strings, or Decimal instances.
+ * @param {number|string|Decimal} x - The value to convert
+ * @returns {Decimal} The Decimal representation
+ */
 const D = x => (x instanceof Decimal ? x : new Decimal(x));
 
+/**
+ * Vector - Decimal-backed vector class for arbitrary-precision vector operations.
+ *
+ * All numeric inputs are automatically converted to Decimal for high precision.
+ * Supports basic operations (add, sub, scale), products (dot, cross, outer),
+ * and geometric operations (norm, normalize, angle, projection).
+ *
+ * @example
+ * const v = Vector.from([1, 2, 3]);
+ * const w = Vector.from(['1.5', '2.5', '3.5']);
+ * console.log(v.dot(w).toString()); // dot product as Decimal
+ */
 export class Vector {
+  /**
+   * Create a new Vector from an array of components.
+   * @param {Array<number|string|Decimal>} components - Array of vector components
+   * @throws {Error} If components is not an array
+   */
   constructor(components) {
     if (!Array.isArray(components)) throw new Error('Vector requires array');
     this.data = components.map(c => D(c));
     this.length = this.data.length;
   }
 
+  /**
+   * Factory method to create a Vector from an array.
+   * @param {Array<number|string|Decimal>} arr - Array of vector components
+   * @returns {Vector} New Vector instance
+   */
   static from(arr) {
     return new Vector(arr);
   }
 
+  /**
+   * Create a deep copy of this vector.
+   * @returns {Vector} New Vector with copied values
+   */
   clone() {
     return new Vector(this.data.map(v => new Decimal(v)));
   }
 
+  /**
+   * Return the internal Decimal array (shallow copy).
+   * Use toNumberArray() or toStringArray() for converted values.
+   * @returns {Decimal[]} Array of Decimal values
+   */
   toArray() {
-    return this.data.map(v => v);
+    return this.data.slice();
   }
 
+  /**
+   * Convert vector to array of JavaScript numbers.
+   * Note: May lose precision for very large or precise values.
+   * @returns {number[]} Array of number values
+   */
   toNumberArray() {
     return this.data.map(v => v.toNumber());
   }
 
+  /**
+   * Convert vector to array of string representations.
+   * Preserves full precision of Decimal values.
+   * @returns {string[]} Array of string values
+   */
   toStringArray() {
     return this.data.map(v => v.toString());
   }
 
-  // elementwise add/sub
+  /**
+   * Element-wise addition with another vector.
+   * @param {Vector} other - Vector to add
+   * @returns {Vector} New Vector with sum
+   * @throws {Error} If other is not a Vector or dimensions mismatch
+   */
   add(other) {
     if (!(other instanceof Vector)) throw new Error('add expects Vector');
-    if (other.length !== this.length) throw new Error('shape mismatch');
+    if (other.length !== this.length) throw new Error('shape mismatch: vectors must have same length');
     return new Vector(this.data.map((v, i) => v.plus(other.data[i])));
   }
 
+  /**
+   * Element-wise subtraction with another vector.
+   * @param {Vector} other - Vector to subtract
+   * @returns {Vector} New Vector with difference
+   * @throws {Error} If other is not a Vector or dimensions mismatch
+   */
   sub(other) {
     if (!(other instanceof Vector)) throw new Error('sub expects Vector');
-    if (other.length !== this.length) throw new Error('shape mismatch');
+    if (other.length !== this.length) throw new Error('shape mismatch: vectors must have same length');
     return new Vector(this.data.map((v, i) => v.minus(other.data[i])));
   }
 
-  // scalar multiplication
+  /**
+   * Scalar multiplication.
+   * @param {number|string|Decimal} scalar - Scalar to multiply by
+   * @returns {Vector} New scaled Vector
+   */
   scale(scalar) {
     const s = D(scalar);
     return new Vector(this.data.map(v => v.mul(s)));
   }
 
-  // dot product
+  /**
+   * Negate the vector (multiply by -1).
+   * @returns {Vector} New Vector with negated components
+   */
+  negate() {
+    return new Vector(this.data.map(v => v.negated()));
+  }
+
+  /**
+   * Dot product (inner product) with another vector.
+   * @param {Vector} other - Vector to compute dot product with
+   * @returns {Decimal} The dot product as a Decimal
+   * @throws {Error} If other is not a Vector or dimensions mismatch
+   */
   dot(other) {
     if (!(other instanceof Vector)) throw new Error('dot expects Vector');
-    if (other.length !== this.length) throw new Error('shape mismatch');
+    if (other.length !== this.length) throw new Error('shape mismatch: vectors must have same length');
     return this.data.reduce((acc, v, i) => acc.plus(v.mul(other.data[i])), new Decimal(0));
   }
 
-  // outer / tensor product returns Matrix-like 2D array (Decimal)
+  /**
+   * Outer product (tensor product) with another vector.
+   * Returns a 2D array of Decimals representing an m×n matrix,
+   * where m is this vector's length and n is other's length.
+   *
+   * Note: Returns raw 2D array, not Matrix, to avoid circular dependency.
+   * Use Matrix.from(v.outer(w)) to get a Matrix object.
+   *
+   * @param {Vector} other - Vector to compute outer product with
+   * @returns {Decimal[][]} 2D array of Decimals (can be passed to Matrix.from())
+   * @throws {Error} If other is not a Vector
+   */
   outer(other) {
     if (!(other instanceof Vector)) throw new Error('outer expects Vector');
     const rows = this.length, cols = other.length;
@@ -64,9 +151,14 @@ export class Vector {
     return out;
   }
 
-  // cross product for 3D vectors
+  /**
+   * Cross product for 3D vectors only.
+   * @param {Vector} other - 3D Vector to compute cross product with
+   * @returns {Vector} New 3D Vector perpendicular to both inputs
+   * @throws {Error} If either vector is not 3D
+   */
   cross(other) {
-    if (this.length !== 3 || other.length !== 3) throw new Error('cross requires 3D vectors');
+    if (this.length !== 3 || other.length !== 3) throw new Error('cross product requires 3D vectors');
     const [a1, a2, a3] = this.data;
     const [b1, b2, b3] = other.data;
     return new Vector([
@@ -76,35 +168,51 @@ export class Vector {
     ]);
   }
 
-  // norm (Euclidean)
+  /**
+   * Euclidean norm (L2 norm, magnitude) of the vector.
+   * @returns {Decimal} The norm as a Decimal
+   */
   norm() {
     let sum = new Decimal(0);
     for (const v of this.data) sum = sum.plus(v.mul(v));
     return sum.sqrt();
   }
 
-  // normalize: returns a new Vector
+  /**
+   * Return a normalized (unit length) version of this vector.
+   * @returns {Vector} New unit Vector in same direction
+   * @throws {Error} If vector is zero (cannot normalize)
+   */
   normalize() {
     const n = this.norm();
     if (n.isZero()) throw new Error('Cannot normalize zero vector');
     return this.scale(new Decimal(1).div(n));
   }
 
-  // angle between vectors (radians)
+  /**
+   * Angle between this vector and another (in radians).
+   * @param {Vector} other - Vector to compute angle with
+   * @returns {Decimal} Angle in radians as a Decimal
+   * @throws {Error} If either vector is zero
+   */
   angleBetween(other) {
-    const dot = this.dot(other);
+    const dotProduct = this.dot(other);
     const n1 = this.norm();
     const n2 = other.norm();
-    if (n1.isZero() || n2.isZero()) throw new Error('Angle with zero vector undefined');
-    // clamp cosine to [-1,1] for numerical safety
-    let cosv = dot.div(n1.mul(n2));
-    // toNumber clamping fallback:
+    if (n1.isZero() || n2.isZero()) throw new Error('Angle with zero vector is undefined');
+    // Clamp cosine to [-1, 1] for numerical safety
+    let cosv = dotProduct.div(n1.mul(n2));
     const cosNum = cosv.toNumber();
     const clamped = Math.min(1, Math.max(-1, cosNum));
     return new Decimal(Math.acos(clamped));
   }
 
-  // projection of this onto other (vector)
+  /**
+   * Project this vector onto another vector.
+   * @param {Vector} other - Vector to project onto
+   * @returns {Vector} The projection of this onto other
+   * @throws {Error} If other is zero vector
+   */
   projectOnto(other) {
     const denom = other.dot(other);
     if (denom.isZero()) throw new Error('Cannot project onto zero vector');
@@ -112,29 +220,65 @@ export class Vector {
     return other.scale(coef);
   }
 
-  // compute an orthogonal vector (for 2D returns perpendicular; for higher dims returns Gram-Schmidt complement)
+  /**
+   * Compute a vector orthogonal to this one.
+   * For 2D: returns the perpendicular [-y, x].
+   * For nD: uses Gram-Schmidt with standard basis vectors.
+   * @returns {Vector} A normalized vector orthogonal to this
+   * @throws {Error} If unable to find orthogonal vector (e.g., zero vector)
+   */
   orthogonal() {
     if (this.length === 2) {
-      // perp: [-y, x]
+      // 2D perpendicular: rotate 90 degrees counterclockwise
       return new Vector([this.data[1].negated(), this.data[0]]);
     }
-    // for n>2: find a vector not colinear with this and make orthogonal via Gram-Schmidt with standard basis
+    // For n > 2: find a standard basis vector not parallel to this,
+    // then use Gram-Schmidt orthogonalization
     for (let i = 0; i < this.length; i++) {
       const ei = Array.from({ length: this.length }, (_, j) => new Decimal(j === i ? 1 : 0));
-      let candidate = new Vector(ei);
-      // check not parallel
-      const crossDim = Math.min(3, this.length);
-      // project candidate out of this
+      const candidate = new Vector(ei);
+      // Project candidate out of this vector's direction
       const proj = candidate.projectOnto(this);
       const orth = candidate.sub(proj);
-      const norm = orth.norm();
-      if (!norm.isZero()) return orth.normalize();
+      const orthNorm = orth.norm();
+      if (!orthNorm.isZero()) return orth.normalize();
     }
     throw new Error('Unable to find orthogonal vector');
   }
 
-  // check orthogonality with other
+  /**
+   * Check if this vector is orthogonal to another.
+   * @param {Vector} other - Vector to check orthogonality with
+   * @returns {boolean} True if vectors are orthogonal (dot product is zero)
+   */
   isOrthogonalTo(other) {
     return this.dot(other).isZero();
   }
-}
+
+  /**
+   * Euclidean distance to another vector.
+   * @param {Vector} other - Vector to compute distance to
+   * @returns {Decimal} The Euclidean distance
+   * @throws {Error} If dimensions mismatch
+   */
+  distance(other) {
+    return this.sub(other).norm();
+  }
+
+  /**
+   * Check equality with another vector within optional tolerance.
+   * @param {Vector} other - Vector to compare with
+   * @param {number|string|Decimal} [tolerance=0] - Maximum allowed difference per component
+   * @returns {boolean} True if vectors are equal within tolerance
+   */
+  equals(other, tolerance = 0) {
+    if (!(other instanceof Vector)) return false;
+    if (other.length !== this.length) return false;
+    const tol = D(tolerance);
+    for (let i = 0; i < this.length; i++) {
+      const diff = this.data[i].minus(other.data[i]).abs();
+      if (diff.greaterThan(tol)) return false;
+    }
+    return true;
+  }
+}