@emasoft/svg-matrix 1.0.27 → 1.0.29

package/src/transforms3d.js

@@ -1,12 +1,27 @@
-import Decimal from 'decimal.js';
-import { Matrix } from './matrix.js';
+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));
+const D = (x) => (x instanceof Decimal ? x : new Decimal(x));
+
+/**
+ * Validates that a value is a valid numeric type (number, string, or Decimal).
+ * @param {*} value - The value to validate
+ * @param {string} name - The parameter name for error messages
+ * @throws {Error} If value is null, undefined, or not a valid numeric type
+ */
+function validateNumeric(value, name) {
+  if (value === undefined || value === null) {
+    throw new Error(`${name} is required`);
+  }
+  if (typeof value !== 'number' && typeof value !== 'string' && !(value instanceof Decimal)) {
+    throw new Error(`${name} must be a number, string, or Decimal`);
+  }
+}
 
 /**
  * 3D Affine Transforms using 4x4 homogeneous matrices.
@@ -85,11 +100,14 @@ const D = x => (x instanceof Decimal ? x : new Decimal(x));
  * // First translates by (10,0,0), then rotates around Z
  */
 export function translation(tx, ty, tz) {
+  validateNumeric(tx, 'tx');
+  validateNumeric(ty, 'ty');
+  validateNumeric(tz, 'tz');
   return Matrix.from([
     [new Decimal(1), new Decimal(0), new Decimal(0), D(tx)],
     [new Decimal(0), new Decimal(1), new Decimal(0), D(ty)],
     [new Decimal(0), new Decimal(0), new Decimal(1), D(tz)],
-    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -131,13 +149,20 @@ export function translation(tx, ty, tz) {
  * const mirror = scale(-1, 1, 1); // Flip X axis
  */
 export function scale(sx, sy = null, sz = null) {
-  if (sy === null) sy = sx;
-  if (sz === null) sz = sx;
+  validateNumeric(sx, 'sx');
+  if (sy !== null) {
+    validateNumeric(sy, 'sy');
+  }
+  if (sz !== null) {
+    validateNumeric(sz, 'sz');
+  }
+  const syValue = sy === null ? sx : sy;
+  const szValue = sz === null ? sx : sz;
   return Matrix.from([
     [D(sx), new Decimal(0), new Decimal(0), new Decimal(0)],
-    [new Decimal(0), D(sy), new Decimal(0), new Decimal(0)],
-    [new Decimal(0), new Decimal(0), D(sz), new Decimal(0)],
-    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)]
+    [new Decimal(0), D(syValue), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), D(szValue), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -180,7 +205,7 @@ export function rotateX(theta) {
     [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)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -224,7 +249,7 @@ export function rotateY(theta) {
     [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)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -269,7 +294,7 @@ export function rotateZ(theta) {
     [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)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -328,9 +353,13 @@ export function rotateZ(theta) {
  * // Equivalent to rotateX(Math.PI / 2)
  */
 export function rotateAroundAxis(ux, uy, uz, theta) {
+  validateNumeric(ux, 'ux');
+  validateNumeric(uy, 'uy');
+  validateNumeric(uz, 'uz');
+  validateNumeric(theta, '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 vector');
+  const 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 vector");
   // Normalize axis
   u[0] = u[0].div(norm);
   u[1] = u[1].div(norm);
@@ -342,7 +371,9 @@ export function rotateAroundAxis(ux, uy, uz, theta) {
   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 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));
   const m02 = u[0].mul(u[2]).mul(one.minus(c)).plus(u[1].mul(s));
@@ -357,7 +388,7 @@ export function rotateAroundAxis(ux, uy, uz, theta) {
     [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)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -404,7 +435,9 @@ export function rotateAroundAxis(ux, uy, uz, theta) {
  * // Complex rotation around axis (1,1,1) passing through (10,20,30)
  */
 export function rotateAroundPoint(ux, uy, uz, theta, px, py, pz) {
-  const pxD = D(px), pyD = D(py), pzD = D(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()));
@@ -458,7 +491,10 @@ export function rotateAroundPoint(ux, uy, uz, theta, px, py, pz) {
 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];
+  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)];
 }
@@ -499,7 +535,7 @@ export function reflectXY() {
     [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)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -538,7 +574,7 @@ export function reflectXZ() {
     [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)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -577,7 +613,7 @@ export function reflectYZ() {
     [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)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }
 
@@ -627,6 +663,6 @@ export function reflectOrigin() {
     [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)]
+    [new Decimal(0), new Decimal(0), new Decimal(0), new Decimal(1)],
   ]);
 }