@emasoft/svg-matrix 1.0.4 → 1.0.5

package/README.md

@@ -278,6 +278,19 @@ const [x, y, z] = Transforms3D.applyTransform(M, 1, 0, 0);
 
 | Function | Description |
 |----------|-------------|
+| **viewBox & Viewport** | |
+| `parseViewBox(str)` | Parse viewBox attribute "minX minY width height" |
+| `parsePreserveAspectRatio(str)` | Parse preserveAspectRatio (align, meet/slice) |
+| `computeViewBoxTransform(vb, vpW, vpH, par)` | Compute viewBox to viewport matrix |
+| `SVGViewport` class | Represents viewport with viewBox + preserveAspectRatio |
+| `buildFullCTM(hierarchy)` | Build CTM from SVG/group/element hierarchy |
+| **Units & Percentages** | |
+| `resolveLength(value, ref, dpi?)` | Resolve px, %, em, pt, in, cm, mm, pc units |
+| `resolvePercentages(x, y, vpW, vpH)` | Resolve x/y percentages to viewport |
+| `normalizedDiagonal(w, h)` | Compute sqrt(w^2+h^2)/sqrt(2) for percentages |
+| **Object Bounding Box** | |
+| `objectBoundingBoxTransform(x, y, w, h)` | Transform for objectBoundingBox units |
+| **Transform Parsing** | |
 | `parseTransformFunction(func, args)` | Parse a single SVG transform function |
 | `parseTransformAttribute(str)` | Parse a full SVG transform attribute string |
 | `buildCTM(transformStack)` | Build CTM from array of transform strings |
@@ -396,6 +409,109 @@ import { SVGFlatten } from '@emasoft/svg-matrix';
 // 5. Convert CTM back to SVG: SVGFlatten.toSVGMatrix(ctm, 6)
 ```
 
+### viewBox and preserveAspectRatio
+
+Per the [SVG 2 specification](https://www.w3.org/TR/SVG2/coords.html), the viewBox establishes a new coordinate system that maps to the viewport:
+
+```js
+import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+
+Decimal.set({ precision: 80 });
+
+// Parse viewBox and preserveAspectRatio
+const viewBox = SVGFlatten.parseViewBox('0 0 100 100');
+const par = SVGFlatten.parsePreserveAspectRatio('xMidYMid meet');
+
+// Compute the viewBox-to-viewport transform
+const vbTransform = SVGFlatten.computeViewBoxTransform(viewBox, 800, 600, par);
+
+// Point (50, 50) in viewBox coords maps to viewport
+const point = SVGFlatten.applyToPoint(vbTransform, 50, 50);
+console.log('Viewport coords:', point.x.toFixed(2), point.y.toFixed(2));
+```
+
+### Full CTM with viewBox and Nested Elements
+
+Use `buildFullCTM` for complete SVG hierarchies including viewBox transforms:
+
+```js
+import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+
+Decimal.set({ precision: 80 });
+
+// Real SVG structure with viewBox and nested transforms
+const hierarchy = [
+  { type: 'svg', width: 800, height: 600, viewBox: '0 0 400 300', preserveAspectRatio: 'xMidYMid meet' },
+  { type: 'g', transform: 'translate(50, 50)' },
+  { type: 'g', transform: 'rotate(45)' },
+  { type: 'element', transform: 'scale(2)' }
+];
+
+const ctm = SVGFlatten.buildFullCTM(hierarchy);
+const local = { x: new Decimal('10'), y: new Decimal('10') };
+const viewport = SVGFlatten.applyToPoint(ctm, local.x, local.y);
+
+// Round-trip with perfect precision
+const inverse = ctm.inverse();
+const recovered = SVGFlatten.applyToPoint(inverse, viewport.x, viewport.y);
+// Error: X=2e-78, Y=2e-78
+```
+
+### Nested SVG Viewports
+
+Handle deeply nested `<svg>` elements, each with its own viewBox:
+
+```js
+const nestedHierarchy = [
+  { type: 'svg', width: 1000, height: 800, viewBox: '0 0 500 400' },
+  { type: 'g', transform: 'translate(100, 100)' },
+  { type: 'svg', width: 200, height: 150, viewBox: '0 0 100 75' },
+  { type: 'element' }
+];
+
+const ctm = SVGFlatten.buildFullCTM(nestedHierarchy);
+// Point (10, 10) in innermost viewBox -> (240, 240) in outer viewport
+```
+
+### Unit and Percentage Resolution
+
+Resolve SVG length values with units or percentages:
+
+```js
+import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+
+const viewportWidth = new Decimal(800);
+
+// Percentages resolve relative to reference size
+SVGFlatten.resolveLength('50%', viewportWidth);   // -> 400
+SVGFlatten.resolveLength('25%', viewportWidth);   // -> 200
+
+// Absolute units (at 96 DPI)
+SVGFlatten.resolveLength('1in', viewportWidth);   // -> 96
+SVGFlatten.resolveLength('2.54cm', viewportWidth);// -> 96 (1 inch)
+SVGFlatten.resolveLength('72pt', viewportWidth);  // -> 96 (1 inch)
+SVGFlatten.resolveLength('6pc', viewportWidth);   // -> 96 (1 inch)
+
+// Font-relative units (assumes 16px base)
+SVGFlatten.resolveLength('2em', viewportWidth);   // -> 32
+
+// Normalized diagonal for non-directional percentages
+const diag = SVGFlatten.normalizedDiagonal(800, 600); // -> 707.1
+```
+
+### Object Bounding Box Transform
+
+For gradients/patterns with `objectBoundingBox` units:
+
+```js
+// Element bounding box: x=100, y=50, width=200, height=100
+const bboxTransform = SVGFlatten.objectBoundingBoxTransform(100, 50, 200, 100);
+
+// (0, 0) in bbox -> (100, 50) in user space
+// (1, 1) in bbox -> (300, 150) in user space
+// (0.5, 0.5) in bbox -> (200, 100) in user space (center)
+```
+
 ### CDN Usage
 
 ```html

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emasoft/svg-matrix",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Arbitrary-precision matrix, vector and affine transformation library for JavaScript using decimal.js",
   "type": "module",
   "main": "src/index.js",

package/samples/preserveAspectRatio_SVG.svg

@@ -0,0 +1,63 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000802//EN" 
+  "http://www.w3.org/TR/2000/CR-SVG-20000802/DTD/svg-20000802.dtd" [
+<!ENTITY Smile "
+  <rect x='.5' y='.5' width='29' height='39' style='fill:yellow; stroke:red'/>
+  <g transform='rotate(90)'>
+    <text x='10' y='10' style='font-family:Verdana; 
+          font-weight:bold; font-size:14'>:)</text>
+  </g>">
+<!ENTITY Viewport1 "<rect x='.5' y='.5' width='49' height='29'
+                          style='fill:none; stroke:blue'/>">
+<!ENTITY Viewport2 "<rect x='.5' y='.5' width='29' height='59' 
+                          style='fill:none; stroke:blue'/>">
+]>
+<svg width="480px" height="270px" style="font-family:Verdana; font-size:8">
+  <desc>Example PreserveAspectRatio - demonstrate available options</desc>
+  <text x="10" y="30">SVG to fit</text>
+  <g transform="translate(20,40)">&Smile;</g>
+  <text x="10" y="110">Viewport 1</text>
+  <g transform="translate(10,120)">&Viewport1;</g>
+  <text x="10" y="180">Viewport 2</text>
+  <g transform="translate(20,190)">&Viewport2;</g>
+  <text x="100" y="30">--------------- meet ---------------</text>
+  <g transform="translate(100,60)"><text y="-10">xMin*</text>&Viewport1;
+    <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <g transform="translate(170,60)"><text y="-10">xMid*</text>&Viewport1;
+    <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <g transform="translate(240,60)"><text y="-10">xMax*</text>&Viewport1;
+    <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <text x="330" y="30">---------- meet ----------</text>
+  <g transform="translate(330,60)"><text y="-10">*YMin</text>&Viewport2;
+    <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <g transform="translate(380,60)"><text y="-10">*YMid</text>&Viewport2;
+    <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <g transform="translate(430,60)"><text y="-10">*YMax</text>&Viewport2;
+    <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <text x="100" y="160">---------- slice ----------</text>
+  <g transform="translate(100,190)"><text y="-10">xMin*</text>&Viewport2;
+    <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <g transform="translate(150,190)"><text y="-10">xMid*</text>&Viewport2;
+    <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <g transform="translate(200,190)"><text y="-10">xMax*</text>&Viewport2;
+    <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <text x="270" y="160">--------------- slice ---------------</text>
+  <g transform="translate(270,190)"><text y="-10">*YMin</text>&Viewport1;
+    <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <g transform="translate(340,190)"><text y="-10">*YMid</text>&Viewport1;
+    <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <g transform="translate(410,190)"><text y="-10">*YMax</text>&Viewport1;
+    <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+</svg>

package/src/svg-flatten.js

@@ -14,6 +14,373 @@ import * as Transforms2D from './transforms2d.js';
 // Set high precision for all calculations
 Decimal.set({ precision: 80 });
 
+// ============================================================================
+// viewBox and preserveAspectRatio Parsing
+// ============================================================================
+
+/**
+ * Parse an SVG viewBox attribute.
+ *
+ * @param {string} viewBoxStr - viewBox attribute value "minX minY width height"
+ * @returns {{minX: Decimal, minY: Decimal, width: Decimal, height: Decimal}|null}
+ */
+export function parseViewBox(viewBoxStr) {
+  if (!viewBoxStr || viewBoxStr.trim() === '') {
+    return null;
+  }
+
+  const parts = viewBoxStr.trim().split(/[\s,]+/).map(s => new Decimal(s));
+  if (parts.length !== 4) {
+    console.warn(`Invalid viewBox: ${viewBoxStr}`);
+    return null;
+  }
+
+  return {
+    minX: parts[0],
+    minY: parts[1],
+    width: parts[2],
+    height: parts[3]
+  };
+}
+
+/**
+ * Parse an SVG preserveAspectRatio attribute.
+ * Format: "[defer] <align> [<meetOrSlice>]"
+ *
+ * @param {string} parStr - preserveAspectRatio attribute value
+ * @returns {{defer: boolean, align: string, meetOrSlice: string}}
+ */
+export function parsePreserveAspectRatio(parStr) {
+  const result = {
+    defer: false,
+    align: 'xMidYMid',  // default
+    meetOrSlice: 'meet' // default
+  };
+
+  if (!parStr || parStr.trim() === '') {
+    return result;
+  }
+
+  const parts = parStr.trim().split(/\s+/);
+  let idx = 0;
+
+  // Check for 'defer' (only applies to <image>)
+  if (parts[idx] === 'defer') {
+    result.defer = true;
+    idx++;
+  }
+
+  // Alignment value
+  if (parts[idx]) {
+    result.align = parts[idx];
+    idx++;
+  }
+
+  // meetOrSlice
+  if (parts[idx]) {
+    result.meetOrSlice = parts[idx].toLowerCase();
+  }
+
+  return result;
+}
+
+/**
+ * Compute the transformation matrix from viewBox coordinates to viewport.
+ * Implements the SVG 2 algorithm for viewBox + preserveAspectRatio.
+ *
+ * @param {Object} viewBox - Parsed viewBox {minX, minY, width, height}
+ * @param {number|Decimal} viewportWidth - Viewport width in pixels
+ * @param {number|Decimal} viewportHeight - Viewport height in pixels
+ * @param {Object} par - Parsed preserveAspectRatio {align, meetOrSlice}
+ * @returns {Matrix} 3x3 transformation matrix
+ */
+export function computeViewBoxTransform(viewBox, viewportWidth, viewportHeight, par = null) {
+  const D = x => new Decimal(x);
+
+  if (!viewBox) {
+    return Matrix.identity(3);
+  }
+
+  const vbX = viewBox.minX;
+  const vbY = viewBox.minY;
+  const vbW = viewBox.width;
+  const vbH = viewBox.height;
+  const vpW = D(viewportWidth);
+  const vpH = D(viewportHeight);
+
+  // Default preserveAspectRatio
+  if (!par) {
+    par = { align: 'xMidYMid', meetOrSlice: 'meet' };
+  }
+
+  // Handle 'none' - stretch to fill
+  if (par.align === 'none') {
+    const scaleX = vpW.div(vbW);
+    const scaleY = vpH.div(vbH);
+    // translate(-minX, -minY) then scale
+    const translateM = Transforms2D.translation(vbX.neg(), vbY.neg());
+    const scaleM = Transforms2D.scale(scaleX, scaleY);
+    return scaleM.mul(translateM);
+  }
+
+  // Compute uniform scale factor
+  let scaleX = vpW.div(vbW);
+  let scaleY = vpH.div(vbH);
+  let scale;
+
+  if (par.meetOrSlice === 'slice') {
+    // Use larger scale (content may overflow)
+    scale = Decimal.max(scaleX, scaleY);
+  } else {
+    // 'meet' - use smaller scale (content fits entirely)
+    scale = Decimal.min(scaleX, scaleY);
+  }
+
+  // Compute translation for alignment
+  const scaledW = vbW.mul(scale);
+  const scaledH = vbH.mul(scale);
+
+  let translateX = D(0);
+  let translateY = D(0);
+
+  // Parse alignment string (e.g., 'xMidYMid', 'xMinYMax')
+  const align = par.align;
+
+  // X alignment
+  if (align.includes('xMid')) {
+    translateX = vpW.minus(scaledW).div(2);
+  } else if (align.includes('xMax')) {
+    translateX = vpW.minus(scaledW);
+  }
+  // xMin is default (translateX = 0)
+
+  // Y alignment
+  if (align.includes('YMid')) {
+    translateY = vpH.minus(scaledH).div(2);
+  } else if (align.includes('YMax')) {
+    translateY = vpH.minus(scaledH);
+  }
+  // YMin is default (translateY = 0)
+
+  // Build the transform: translate(translateX, translateY) scale(scale) translate(-minX, -minY)
+  // Applied right-to-left: first translate by -minX,-minY, then scale, then translate for alignment
+  const translateMinM = Transforms2D.translation(vbX.neg(), vbY.neg());
+  const scaleM = Transforms2D.scale(scale, scale);
+  const translateAlignM = Transforms2D.translation(translateX, translateY);
+
+  return translateAlignM.mul(scaleM).mul(translateMinM);
+}
+
+/**
+ * Represents an SVG viewport with its coordinate system parameters.
+ * Used for building the full CTM through nested viewports.
+ */
+export class SVGViewport {
+  /**
+   * @param {number|Decimal} width - Viewport width
+   * @param {number|Decimal} height - Viewport height
+   * @param {string|null} viewBox - viewBox attribute value
+   * @param {string|null} preserveAspectRatio - preserveAspectRatio attribute value
+   * @param {string|null} transform - transform attribute value
+   */
+  constructor(width, height, viewBox = null, preserveAspectRatio = null, transform = null) {
+    this.width = new Decimal(width);
+    this.height = new Decimal(height);
+    this.viewBox = viewBox ? parseViewBox(viewBox) : null;
+    this.preserveAspectRatio = parsePreserveAspectRatio(preserveAspectRatio);
+    this.transform = transform;
+  }
+
+  /**
+   * Compute the transformation matrix for this viewport.
+   * @returns {Matrix} 3x3 transformation matrix
+   */
+  getTransformMatrix() {
+    let result = Matrix.identity(3);
+
+    // Apply viewBox transform first (if present)
+    if (this.viewBox) {
+      const vbTransform = computeViewBoxTransform(
+        this.viewBox,
+        this.width,
+        this.height,
+        this.preserveAspectRatio
+      );
+      result = result.mul(vbTransform);
+    }
+
+    // Then apply the transform attribute (if present)
+    if (this.transform) {
+      const transformMatrix = parseTransformAttribute(this.transform);
+      result = result.mul(transformMatrix);
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Build the complete CTM including viewports, viewBox transforms, and element transforms.
+ *
+ * @param {Array} hierarchy - Array of objects describing the hierarchy from root to element.
+ *   Each object can be:
+ *   - {type: 'svg', width, height, viewBox?, preserveAspectRatio?, transform?}
+ *   - {type: 'g', transform?}
+ *   - {type: 'element', transform?}
+ *   Or simply a transform string for backwards compatibility
+ * @returns {Matrix} Combined CTM as 3x3 matrix
+ */
+export function buildFullCTM(hierarchy) {
+  let ctm = Matrix.identity(3);
+
+  for (const item of hierarchy) {
+    if (typeof item === 'string') {
+      // Backwards compatibility: treat string as transform attribute
+      if (item) {
+        const matrix = parseTransformAttribute(item);
+        ctm = ctm.mul(matrix);
+      }
+    } else if (item.type === 'svg') {
+      // SVG viewport with potential viewBox
+      const viewport = new SVGViewport(
+        item.width,
+        item.height,
+        item.viewBox || null,
+        item.preserveAspectRatio || null,
+        item.transform || null
+      );
+      ctm = ctm.mul(viewport.getTransformMatrix());
+    } else if (item.type === 'g' || item.type === 'element') {
+      // Group or element with optional transform
+      if (item.transform) {
+        const matrix = parseTransformAttribute(item.transform);
+        ctm = ctm.mul(matrix);
+      }
+    }
+  }
+
+  return ctm;
+}
+
+// ============================================================================
+// Unit and Percentage Resolution
+// ============================================================================
+
+/**
+ * Resolve a length value that may include units or percentages.
+ *
+ * @param {string|number} value - Length value (e.g., "50%", "10px", "5em", 100)
+ * @param {Decimal} referenceSize - Reference size for percentage resolution
+ * @param {number} [dpi=96] - DPI for absolute unit conversion
+ * @returns {Decimal} Resolved length in user units (px)
+ */
+export function resolveLength(value, referenceSize, dpi = 96) {
+  const D = x => new Decimal(x);
+
+  if (typeof value === 'number') {
+    return D(value);
+  }
+
+  const str = String(value).trim();
+
+  // Percentage
+  if (str.endsWith('%')) {
+    const pct = D(str.slice(0, -1));
+    return pct.div(100).mul(referenceSize);
+  }
+
+  // Extract numeric value and unit
+  const match = str.match(/^([+-]?[\d.]+(?:e[+-]?\d+)?)(.*)?$/i);
+  if (!match) {
+    return D(0);
+  }
+
+  const num = D(match[1]);
+  const unit = (match[2] || '').toLowerCase().trim();
+
+  // Convert to user units (px)
+  switch (unit) {
+    case '':
+    case 'px':
+      return num;
+    case 'em':
+      return num.mul(16); // Assume 16px font-size
+    case 'rem':
+      return num.mul(16);
+    case 'pt':
+      return num.mul(dpi).div(72);
+    case 'pc':
+      return num.mul(dpi).div(6);
+    case 'in':
+      return num.mul(dpi);
+    case 'cm':
+      return num.mul(dpi).div(2.54);
+    case 'mm':
+      return num.mul(dpi).div(25.4);
+    default:
+      return num; // Unknown unit, treat as px
+  }
+}
+
+/**
+ * Resolve percentage values for x/width (relative to viewport width)
+ * and y/height (relative to viewport height).
+ *
+ * @param {string|number} xOrWidth - X coordinate or width value
+ * @param {string|number} yOrHeight - Y coordinate or height value
+ * @param {Decimal} viewportWidth - Viewport width for reference
+ * @param {Decimal} viewportHeight - Viewport height for reference
+ * @returns {{x: Decimal, y: Decimal}} Resolved coordinates
+ */
+export function resolvePercentages(xOrWidth, yOrHeight, viewportWidth, viewportHeight) {
+  return {
+    x: resolveLength(xOrWidth, viewportWidth),
+    y: resolveLength(yOrHeight, viewportHeight)
+  };
+}
+
+/**
+ * Compute the normalized diagonal for resolving percentages that
+ * aren't clearly x or y oriented (per SVG spec).
+ * Formula: sqrt(width^2 + height^2) / sqrt(2)
+ *
+ * @param {Decimal} width - Viewport width
+ * @param {Decimal} height - Viewport height
+ * @returns {Decimal} Normalized diagonal
+ */
+export function normalizedDiagonal(width, height) {
+  const w = new Decimal(width);
+  const h = new Decimal(height);
+  const sqrt2 = Decimal.sqrt(2);
+  return Decimal.sqrt(w.mul(w).plus(h.mul(h))).div(sqrt2);
+}
+
+// ============================================================================
+// Object Bounding Box Transform
+// ============================================================================
+
+/**
+ * Create a transformation matrix for objectBoundingBox coordinates.
+ * Maps (0,0) to (bboxX, bboxY) and (1,1) to (bboxX+bboxW, bboxY+bboxH).
+ *
+ * @param {number|Decimal} bboxX - Bounding box X
+ * @param {number|Decimal} bboxY - Bounding box Y
+ * @param {number|Decimal} bboxWidth - Bounding box width
+ * @param {number|Decimal} bboxHeight - Bounding box height
+ * @returns {Matrix} 3x3 transformation matrix
+ */
+export function objectBoundingBoxTransform(bboxX, bboxY, bboxWidth, bboxHeight) {
+  const D = x => new Decimal(x);
+  // Transform: scale(bboxWidth, bboxHeight) then translate(bboxX, bboxY)
+  const scaleM = Transforms2D.scale(bboxWidth, bboxHeight);
+  const translateM = Transforms2D.translation(bboxX, bboxY);
+  return translateM.mul(scaleM);
+}
+
+// ============================================================================
+// Transform Parsing (existing code)
+// ============================================================================
+
 /**
  * Parse a single SVG transform function and return a 3x3 matrix.
  * Supports: translate, scale, rotate, skewX, skewY, matrix
@@ -324,6 +691,19 @@ export const PRECISION_INFO = {
 };
 
 export default {
+  // viewBox and preserveAspectRatio
+  parseViewBox,
+  parsePreserveAspectRatio,
+  computeViewBoxTransform,
+  SVGViewport,
+  buildFullCTM,
+  // Unit resolution
+  resolveLength,
+  resolvePercentages,
+  normalizedDiagonal,
+  // Object bounding box
+  objectBoundingBoxTransform,
+  // Transform parsing
   parseTransformFunction,
   parseTransformAttribute,
   buildCTM,