@emasoft/svg-matrix 1.0.2 → 1.0.4

package/src/svg-flatten.js

@@ -0,0 +1,335 @@
+/**
+ * SVG Transform Flattening Utility
+ *
+ * Parses SVG transform attributes, builds CTM (Current Transform Matrix) for each element,
+ * and can flatten all transforms by applying them directly to coordinates.
+ *
+ * @module svg-flatten
+ */
+
+import Decimal from 'decimal.js';
+import { Matrix } from './matrix.js';
+import * as Transforms2D from './transforms2d.js';
+
+// Set high precision for all calculations
+Decimal.set({ precision: 80 });
+
+/**
+ * Parse a single SVG transform function and return a 3x3 matrix.
+ * Supports: translate, scale, rotate, skewX, skewY, matrix
+ *
+ * @param {string} func - Transform function name
+ * @param {number[]} args - Numeric arguments
+ * @returns {Matrix} 3x3 transformation matrix
+ */
+export function parseTransformFunction(func, args) {
+  const D = x => new Decimal(x);
+
+  switch (func.toLowerCase()) {
+    case 'translate': {
+      const tx = args[0] || 0;
+      const ty = args[1] || 0;
+      return Transforms2D.translation(tx, ty);
+    }
+
+    case 'scale': {
+      const sx = args[0] || 1;
+      const sy = args[1] !== undefined ? args[1] : sx;
+      return Transforms2D.scale(sx, sy);
+    }
+
+    case 'rotate': {
+      // SVG rotate is in degrees, can have optional cx, cy
+      const angleDeg = args[0] || 0;
+      const angleRad = D(angleDeg).mul(D(Math.PI)).div(180);
+
+      if (args.length >= 3) {
+        // rotate(angle, cx, cy) - rotation around point
+        const cx = args[1];
+        const cy = args[2];
+        return Transforms2D.rotateAroundPoint(angleRad, cx, cy);
+      }
+      return Transforms2D.rotate(angleRad);
+    }
+
+    case 'skewx': {
+      const angleDeg = args[0] || 0;
+      const angleRad = D(angleDeg).mul(D(Math.PI)).div(180);
+      const tanVal = Decimal.tan(angleRad);
+      return Transforms2D.skew(tanVal, 0);
+    }
+
+    case 'skewy': {
+      const angleDeg = args[0] || 0;
+      const angleRad = D(angleDeg).mul(D(Math.PI)).div(180);
+      const tanVal = Decimal.tan(angleRad);
+      return Transforms2D.skew(0, tanVal);
+    }
+
+    case 'matrix': {
+      // matrix(a, b, c, d, e, f) -> | a c e |
+      //                             | b d f |
+      //                             | 0 0 1 |
+      const [a, b, c, d, e, f] = args.map(x => D(x || 0));
+      return Matrix.from([
+        [a, c, e],
+        [b, d, f],
+        [D(0), D(0), D(1)]
+      ]);
+    }
+
+    default:
+      console.warn(`Unknown transform function: ${func}`);
+      return Matrix.identity(3);
+  }
+}
+
+/**
+ * Parse an SVG transform attribute string into a combined matrix.
+ * Handles multiple transforms: "translate(10,20) rotate(45) scale(2)"
+ *
+ * @param {string} transformStr - SVG transform attribute value
+ * @returns {Matrix} Combined 3x3 transformation matrix
+ */
+export function parseTransformAttribute(transformStr) {
+  if (!transformStr || transformStr.trim() === '') {
+    return Matrix.identity(3);
+  }
+
+  // Regex to match transform functions: name(args)
+  const transformRegex = /(\w+)\s*\(([^)]*)\)/g;
+  let match;
+  let result = Matrix.identity(3);
+
+  while ((match = transformRegex.exec(transformStr)) !== null) {
+    const func = match[1];
+    const argsStr = match[2];
+
+    // Parse arguments (comma or space separated)
+    const args = argsStr
+      .split(/[\s,]+/)
+      .filter(s => s.length > 0)
+      .map(s => parseFloat(s));
+
+    const matrix = parseTransformFunction(func, args);
+    // Transforms are applied left-to-right in SVG, so we multiply in order
+    result = result.mul(matrix);
+  }
+
+  return result;
+}
+
+/**
+ * Build the CTM (Current Transform Matrix) for an element by walking up its ancestry.
+ *
+ * @param {Object[]} transformStack - Array of transform strings from root to element
+ * @returns {Matrix} Combined CTM as 3x3 matrix
+ */
+export function buildCTM(transformStack) {
+  let ctm = Matrix.identity(3);
+
+  for (const transformStr of transformStack) {
+    if (transformStr) {
+      const matrix = parseTransformAttribute(transformStr);
+      ctm = ctm.mul(matrix);
+    }
+  }
+
+  return ctm;
+}
+
+/**
+ * Apply a CTM to a 2D point.
+ *
+ * @param {Matrix} ctm - 3x3 transformation matrix
+ * @param {number|string|Decimal} x - X coordinate
+ * @param {number|string|Decimal} y - Y coordinate
+ * @returns {{x: Decimal, y: Decimal}} Transformed coordinates
+ */
+export function applyToPoint(ctm, x, y) {
+  const [tx, ty] = Transforms2D.applyTransform(ctm, x, y);
+  return { x: tx, y: ty };
+}
+
+/**
+ * Convert a CTM back to SVG matrix() notation.
+ *
+ * @param {Matrix} ctm - 3x3 transformation matrix
+ * @param {number} [precision=6] - Decimal places for output
+ * @returns {string} SVG matrix transform string
+ */
+export function toSVGMatrix(ctm, precision = 6) {
+  const a = ctm.data[0][0].toFixed(precision);
+  const b = ctm.data[1][0].toFixed(precision);
+  const c = ctm.data[0][1].toFixed(precision);
+  const d = ctm.data[1][1].toFixed(precision);
+  const e = ctm.data[0][2].toFixed(precision);
+  const f = ctm.data[1][2].toFixed(precision);
+
+  return `matrix(${a}, ${b}, ${c}, ${d}, ${e}, ${f})`;
+}
+
+/**
+ * Check if a matrix is effectively the identity matrix.
+ *
+ * @param {Matrix} m - 3x3 matrix to check
+ * @param {string} [tolerance='1e-10'] - Tolerance for comparison
+ * @returns {boolean} True if matrix is identity within tolerance
+ */
+export function isIdentity(m, tolerance = '1e-10') {
+  const identity = Matrix.identity(3);
+  return m.equals(identity, tolerance);
+}
+
+/**
+ * Transform path data coordinates using a CTM.
+ * Handles M, L, C, Q, S, T, A, Z commands (absolute only for now).
+ *
+ * @param {string} pathData - SVG path d attribute
+ * @param {Matrix} ctm - 3x3 transformation matrix
+ * @returns {string} Transformed path data
+ */
+export function transformPathData(pathData, ctm) {
+  // Simple regex-based path parser for common commands
+  const result = [];
+  const commandRegex = /([MLHVCSQTAZ])([^MLHVCSQTAZ]*)/gi;
+  let match;
+
+  while ((match = commandRegex.exec(pathData)) !== null) {
+    const cmd = match[1];
+    const argsStr = match[2].trim();
+    const args = argsStr
+      .split(/[\s,]+/)
+      .filter(s => s.length > 0)
+      .map(s => parseFloat(s));
+
+    const cmdUpper = cmd.toUpperCase();
+
+    switch (cmdUpper) {
+      case 'M':
+      case 'L':
+      case 'T': {
+        // Pairs of coordinates
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 2) {
+          const { x, y } = applyToPoint(ctm, args[i], args[i + 1]);
+          transformed.push(x.toFixed(6), y.toFixed(6));
+        }
+        result.push(cmd + ' ' + transformed.join(' '));
+        break;
+      }
+
+      case 'H': {
+        // Horizontal line - becomes L after transform
+        const { x, y } = applyToPoint(ctm, args[0], 0);
+        result.push('L ' + x.toFixed(6) + ' ' + y.toFixed(6));
+        break;
+      }
+
+      case 'V': {
+        // Vertical line - becomes L after transform
+        const { x, y } = applyToPoint(ctm, 0, args[0]);
+        result.push('L ' + x.toFixed(6) + ' ' + y.toFixed(6));
+        break;
+      }
+
+      case 'C': {
+        // Cubic bezier: 3 pairs of coordinates
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 2) {
+          const { x, y } = applyToPoint(ctm, args[i], args[i + 1]);
+          transformed.push(x.toFixed(6), y.toFixed(6));
+        }
+        result.push('C ' + transformed.join(' '));
+        break;
+      }
+
+      case 'S': {
+        // Smooth cubic: 2 pairs of coordinates
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 2) {
+          const { x, y } = applyToPoint(ctm, args[i], args[i + 1]);
+          transformed.push(x.toFixed(6), y.toFixed(6));
+        }
+        result.push('S ' + transformed.join(' '));
+        break;
+      }
+
+      case 'Q': {
+        // Quadratic bezier: 2 pairs of coordinates
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 2) {
+          const { x, y } = applyToPoint(ctm, args[i], args[i + 1]);
+          transformed.push(x.toFixed(6), y.toFixed(6));
+        }
+        result.push('Q ' + transformed.join(' '));
+        break;
+      }
+
+      case 'A': {
+        // Arc: rx ry x-axis-rotation large-arc-flag sweep-flag x y
+        // Transform end point, scale radii (approximate for non-uniform scale)
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 7) {
+          const rx = args[i];
+          const ry = args[i + 1];
+          const rotation = args[i + 2];
+          const largeArc = args[i + 3];
+          const sweep = args[i + 4];
+          const x = args[i + 5];
+          const y = args[i + 6];
+
+          const { x: tx, y: ty } = applyToPoint(ctm, x, y);
+
+          // Scale radii approximately (doesn't handle rotation correctly for skew)
+          const scaleX = ctm.data[0][0].abs().plus(ctm.data[0][1].abs()).div(2);
+          const scaleY = ctm.data[1][0].abs().plus(ctm.data[1][1].abs()).div(2);
+
+          transformed.push(
+            (rx * scaleX.toNumber()).toFixed(6),
+            (ry * scaleY.toNumber()).toFixed(6),
+            rotation,
+            largeArc,
+            sweep,
+            tx.toFixed(6),
+            ty.toFixed(6)
+          );
+        }
+        result.push('A ' + transformed.join(' '));
+        break;
+      }
+
+      case 'Z': {
+        result.push('Z');
+        break;
+      }
+
+      default:
+        // Keep unknown commands as-is
+        result.push(cmd + ' ' + argsStr);
+    }
+  }
+
+  return result.join(' ');
+}
+
+/**
+ * Information about precision comparison between float and Decimal.
+ */
+export const PRECISION_INFO = {
+  floatError: 0.0143,  // Typical error: 10 -> 9.9857
+  decimalPrecision: 80,
+  typicalRoundTripError: '2e-79',
+  improvementFactor: '1.43e+77'
+};
+
+export default {
+  parseTransformFunction,
+  parseTransformAttribute,
+  buildCTM,
+  applyToPoint,
+  toSVGMatrix,
+  isIdentity,
+  transformPathData,
+  PRECISION_INFO
+};

package/src/transforms2d.js

@@ -1,7 +1,28 @@
 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));
 
+/**
+ * 2D Affine Transforms using 3x3 homogeneous matrices.
+ *
+ * All transforms return 3x3 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.
+ *
+ * @module Transforms2D
+ */
+
+/**
+ * Create a 2D translation matrix.
+ * @param {number|string|Decimal} tx - Translation in X direction
+ * @param {number|string|Decimal} ty - Translation in Y direction
+ * @returns {Matrix} 3x3 translation matrix
+ */
 export function translation(tx, ty) {
   return Matrix.from([
     [new Decimal(1), new Decimal(0), D(tx)],
@@ -10,6 +31,12 @@ export function translation(tx, ty) {
   ]);
 }
 
+/**
+ * Create a 2D 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 for uniform scaling)
+ * @returns {Matrix} 3x3 scaling matrix
+ */
 export function scale(sx, sy = null) {
   if (sy === null) sy = sx;
   return Matrix.from([
@@ -19,6 +46,17 @@ export function scale(sx, sy = null) {
   ]);
 }
 
+/**
+ * Create a 2D rotation matrix (counterclockwise around origin).
+ *
+ * Uses standard rotation matrix:
+ * | cos(θ)  -sin(θ)  0 |
+ * | sin(θ)   cos(θ)  0 |
+ * |   0        0     1 |
+ *
+ * @param {number|string|Decimal} theta - Rotation angle in radians
+ * @returns {Matrix} 3x3 rotation matrix
+ */
 export function rotate(theta) {
   const t = D(theta);
   const c = new Decimal(Math.cos(t.toNumber()));
@@ -30,10 +68,32 @@ export function rotate(theta) {
   ]);
 }
 
+/**
+ * Create a 2D rotation matrix around a specific point.
+ * Equivalent to: translate(px, py) × rotate(theta) × translate(-px, -py)
+ *
+ * @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
+ * @returns {Matrix} 3x3 rotation matrix around point (px, py)
+ */
 export function rotateAroundPoint(theta, px, py) {
-  return translation(px, py).mul(rotate(theta)).mul(translation(new Decimal(px).neg(), new Decimal(py).neg()));
+  const pxD = D(px);
+  const pyD = D(py);
+  return translation(pxD, pyD).mul(rotate(theta)).mul(translation(pxD.negated(), pyD.negated()));
 }
 
+/**
+ * Create a 2D skew (shear) matrix.
+ *
+ * | 1   ax  0 |
+ * | ay  1   0 |
+ * | 0   0   1 |
+ *
+ * @param {number|string|Decimal} ax - Skew factor in X direction (affects X based on Y)
+ * @param {number|string|Decimal} ay - Skew factor in Y direction (affects Y based on X)
+ * @returns {Matrix} 3x3 skew matrix
+ */
 export function skew(ax, ay) {
   return Matrix.from([
     [new Decimal(1), D(ax), new Decimal(0)],
@@ -42,6 +102,17 @@ export function skew(ax, ay) {
   ]);
 }
 
+/**
+ * Create a stretch matrix along a specified axis direction.
+ * Stretches by factor k along the unit vector (ux, uy).
+ *
+ * The axis should be normalized (ux² + uy² = 1), but this is not enforced.
+ *
+ * @param {number|string|Decimal} ux - X component of axis direction (unit vector)
+ * @param {number|string|Decimal} uy - Y component of axis direction (unit vector)
+ * @param {number|string|Decimal} k - Stretch factor along the axis
+ * @returns {Matrix} 3x3 stretch matrix
+ */
 export function stretchAlongAxis(ux, uy, k) {
   const uxD = D(ux), uyD = D(uy), kD = D(k);
   const one = new Decimal(1);
@@ -57,9 +128,56 @@ export function stretchAlongAxis(ux, uy, k) {
   ]);
 }
 
+/**
+ * Apply a 2D transform matrix to a point.
+ * Uses homogeneous coordinates with perspective division.
+ *
+ * @param {Matrix} M - 3x3 transformation matrix
+ * @param {number|string|Decimal} x - X coordinate of point
+ * @param {number|string|Decimal} y - Y coordinate of point
+ * @returns {Decimal[]} Transformed point as [x', y'] array of Decimals
+ */
 export function applyTransform(M, x, y) {
   const P = Matrix.from([[D(x)], [D(y)], [new Decimal(1)]]);
   const R = M.mul(P);
   const rx = R.data[0][0], ry = R.data[1][0], rw = R.data[2][0];
+  // Perspective division (for affine transforms, rw is always 1)
   return [rx.div(rw), ry.div(rw)];
-}
+}
+
+/**
+ * Create a reflection matrix across the X axis (flips Y).
+ * @returns {Matrix} 3x3 reflection matrix
+ */
+export function reflectX() {
+  return Matrix.from([
+    [new Decimal(1), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(-1), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}
+
+/**
+ * Create a reflection matrix across the Y axis (flips X).
+ * @returns {Matrix} 3x3 reflection matrix
+ */
+export function reflectY() {
+  return Matrix.from([
+    [new Decimal(-1), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(1), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}
+
+/**
+ * Create a reflection matrix across the origin (flips both X and Y).
+ * Equivalent to rotation by π radians.
+ * @returns {Matrix} 3x3 reflection matrix
+ */
+export function reflectOrigin() {
+  return Matrix.from([
+    [new Decimal(-1), new Decimal(0), new Decimal(0)],
+    [new Decimal(0), new Decimal(-1), new Decimal(0)],
+    [new Decimal(0), new Decimal(0), new Decimal(1)]
+  ]);
+}