@js-draw/math 1.3.0 → 1.3.1

package/dist/cjs/Mat33.d.ts

@@ -107,15 +107,45 @@ export declare class Mat33 {
     mapEntries(mapping: (component: number, rowcol: [number, number]) => number): Mat33;
     /** Estimate the scale factor of this matrix (based on the first row). */
     getScaleFactor(): number;
+    /** Returns the `idx`-th column (`idx` is 0-indexed). */
+    getColumn(idx: number): Vec3;
+    /** Returns the magnitude of the entry with the largest entry */
+    maximumEntryMagnitude(): number;
     /**
      * Constructs a 3x3 translation matrix (for translating `Vec2`s) using
      * **transformVec2**.
+     *
+     * Creates a matrix in the form
+     * $$
+     * 	\begin{pmatrix}
+     * 		1 & 0 & {\tt amount.x}\\
+     * 		0 & 1 & {\tt amount.y}\\
+     * 		0 & 0 & 1
+     * 	\end{pmatrix}
+     * $$
      */
     static translation(amount: Vec2): Mat33;
     static zRotation(radians: number, center?: Point2): Mat33;
     static scaling2D(amount: number | Vec2, center?: Point2): Mat33;
-    /** @see {@link fromCSSMatrix} */
+    /**
+     * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+     *
+     * @see {@link fromCSSMatrix} and {@link toSafeCSSTransformList}
+     */
     toCSSMatrix(): string;
+    /**
+     * @beta May change or even be removed between minor releases.
+     *
+     * Converts this matrix into a list of CSS transforms that attempt to preserve
+     * this matrix's translation.
+     *
+     * In Chrome/Firefox, translation attributes only support 6 digits (likely an artifact
+     * of using lower-precision floating point numbers). This works around
+     * that by expanding this matrix into the product of several CSS transforms.
+     *
+     * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+     */
+    toSafeCSSTransformList(): string;
     /**
      * Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33.
      *

package/dist/cjs/Mat33.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Mat33 = void 0;
 const Vec2_1 = require("./Vec2");
 const Vec3_1 = __importDefault(require("./Vec3"));
+const rounding_1 = require("./rounding");
 /**
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
@@ -259,9 +260,30 @@ class Mat33 {
     getScaleFactor() {
         return Math.hypot(this.a1, this.a2);
     }
+    /** Returns the `idx`-th column (`idx` is 0-indexed). */
+    getColumn(idx) {
+        return Vec3_1.default.of(this.rows[0].at(idx), this.rows[1].at(idx), this.rows[2].at(idx));
+    }
+    /** Returns the magnitude of the entry with the largest entry */
+    maximumEntryMagnitude() {
+        let greatestSoFar = Math.abs(this.a1);
+        for (const entry of this.toArray()) {
+            greatestSoFar = Math.max(greatestSoFar, Math.abs(entry));
+        }
+        return greatestSoFar;
+    }
     /**
      * Constructs a 3x3 translation matrix (for translating `Vec2`s) using
      * **transformVec2**.
+     *
+     * Creates a matrix in the form
+     * $$
+     * 	\begin{pmatrix}
+     * 		1 & 0 & {\tt amount.x}\\
+     * 		0 & 1 & {\tt amount.y}\\
+     * 		0 & 0 & 1
+     * 	\end{pmatrix}
+     * $$
      */
     static translation(amount) {
         // When transforming Vec2s by a 3x3 matrix, we give the input
@@ -296,10 +318,131 @@ class Mat33 {
         // Translate such that [center] goes to (0, 0)
         return result.rightMul(Mat33.translation(center.times(-1)));
     }
-    /** @see {@link fromCSSMatrix} */
+    /**
+     * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+     *
+     * @see {@link fromCSSMatrix} and {@link toSafeCSSTransformList}
+     */
     toCSSMatrix() {
         return `matrix(${this.a1},${this.b1},${this.a2},${this.b2},${this.a3},${this.b3})`;
     }
+    /**
+     * @beta May change or even be removed between minor releases.
+     *
+     * Converts this matrix into a list of CSS transforms that attempt to preserve
+     * this matrix's translation.
+     *
+     * In Chrome/Firefox, translation attributes only support 6 digits (likely an artifact
+     * of using lower-precision floating point numbers). This works around
+     * that by expanding this matrix into the product of several CSS transforms.
+     *
+     * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+     */
+    toSafeCSSTransformList() {
+        // Check whether it's safe to return just the CSS matrix
+        const translation = Vec2_1.Vec2.of(this.a3, this.b3);
+        const translationRoundedX = (0, rounding_1.toRoundedString)(translation.x);
+        const translationRoundedY = (0, rounding_1.toRoundedString)(translation.y);
+        const nonDigitsRegex = /[^0-9]+/g;
+        const translationXDigits = translationRoundedX.replace(nonDigitsRegex, '').length;
+        const translationYDigits = translationRoundedY.replace(nonDigitsRegex, '').length;
+        // Is it safe to just return the default CSS matrix?
+        if (translationXDigits <= 5 && translationYDigits <= 5) {
+            return this.toCSSMatrix();
+        }
+        // Remove the last column (the translation column)
+        let transform = new Mat33(this.a1, this.a2, 0, this.b1, this.b2, 0, 0, 0, 1);
+        const transforms = [];
+        let lastScale = null;
+        // Appends a translate() command to the list of `transforms`.
+        const addTranslate = (translation) => {
+            lastScale = null;
+            if (!translation.eq(Vec2_1.Vec2.zero)) {
+                transforms.push(`translate(${(0, rounding_1.toRoundedString)(translation.x)}px, ${(0, rounding_1.toRoundedString)(translation.y)}px)`);
+            }
+        };
+        // Appends a scale() command to the list of transforms, possibly merging with
+        // the last command, if a scale().
+        const addScale = (scale) => {
+            // Merge with the last scale
+            if (lastScale) {
+                const newScale = lastScale.scale(scale);
+                // Don't merge if the new scale has very large values
+                if (newScale.maximumEntryMagnitude() < 1e7) {
+                    const previousCommand = transforms.pop();
+                    console.assert(previousCommand.startsWith('scale'), 'Invalid state: Merging scale commands');
+                    scale = newScale;
+                }
+            }
+            if (scale.x === scale.y) {
+                transforms.push(`scale(${(0, rounding_1.toRoundedString)(scale.x)})`);
+            }
+            else {
+                transforms.push(`scale(${(0, rounding_1.toRoundedString)(scale.x)}, ${(0, rounding_1.toRoundedString)(scale.y)})`);
+            }
+            lastScale = scale;
+        };
+        // Returns the number of digits before the `.` in the given number string.
+        const digitsPreDecimalCount = (numberString) => {
+            let decimalIndex = numberString.indexOf('.');
+            if (decimalIndex === -1) {
+                decimalIndex = numberString.length;
+            }
+            return numberString.substring(0, decimalIndex).replace(nonDigitsRegex, '').length;
+        };
+        // Returns the number of digits (positive for left shift, negative for right shift)
+        // required to shift the decimal to the middle of the number.
+        const getShift = (numberString) => {
+            const preDecimal = digitsPreDecimalCount(numberString);
+            const postDecimal = (numberString.match(/[.](\d*)/) ?? ['', ''])[1].length;
+            // The shift required to center the decimal point.
+            const toCenter = postDecimal - preDecimal;
+            // toCenter is positive for a left shift (adding more pre-decimals),
+            // so, after applying it,
+            const postShiftPreDecimal = preDecimal + toCenter;
+            // We want the digits before the decimal to have a length at most 4, however.
+            // Thus, right shift until this is the case.
+            const shiftForAtMost5DigitsPreDecimal = 4 - Math.max(postShiftPreDecimal, 4);
+            return toCenter + shiftForAtMost5DigitsPreDecimal;
+        };
+        const addShiftedTranslate = (translate, depth = 0) => {
+            const xString = (0, rounding_1.toRoundedString)(translate.x);
+            const yString = (0, rounding_1.toRoundedString)(translate.y);
+            const xShiftDigits = getShift(xString);
+            const yShiftDigits = getShift(yString);
+            const shift = Vec2_1.Vec2.of(Math.pow(10, xShiftDigits), Math.pow(10, yShiftDigits));
+            const invShift = Vec2_1.Vec2.of(Math.pow(10, -xShiftDigits), Math.pow(10, -yShiftDigits));
+            addScale(invShift);
+            const shiftedTranslate = translate.scale(shift);
+            const roundedShiftedTranslate = Vec2_1.Vec2.of(Math.floor(shiftedTranslate.x), Math.floor(shiftedTranslate.y));
+            addTranslate(roundedShiftedTranslate);
+            // Don't recurse more than 3 times -- the more times we recurse, the more
+            // the scaling is influenced by error.
+            if (!roundedShiftedTranslate.eq(shiftedTranslate) && depth < 3) {
+                addShiftedTranslate(shiftedTranslate.minus(roundedShiftedTranslate), depth + 1);
+            }
+            addScale(shift);
+            return translate;
+        };
+        const adjustTransformFromScale = () => {
+            if (lastScale) {
+                const scaledTransform = transform.rightMul(Mat33.scaling2D(lastScale));
+                // If adding the scale to the transform leads to large values, avoid
+                // doing this.
+                if (scaledTransform.maximumEntryMagnitude() < 1e12) {
+                    transforms.pop();
+                    transform = transform.rightMul(Mat33.scaling2D(lastScale));
+                    lastScale = null;
+                }
+            }
+        };
+        addShiftedTranslate(translation);
+        adjustTransformFromScale();
+        if (!transform.eq(Mat33.identity)) {
+            transforms.push(transform.toCSSMatrix());
+        }
+        return transforms.join(' ');
+    }
     /**
      * Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33.
      *
@@ -314,30 +457,95 @@ class Mat33 {
         if (cssString === '' || cssString === 'none') {
             return Mat33.identity;
         }
-        const numberExp = '([-]?\\d*(?:\\.\\d*)?(?:[eE][-]?\\d+)?)';
-        const numberSepExp = '[, \\t\\n]';
-        const regExpSource = `^\\s*matrix\\s*\\(${[
-            // According to MDN, matrix(a,b,c,d,e,f) has form:
-            // 		⎡ a c e ⎤
-            // 		⎢ b d f ⎥
-            // 		⎣ 0 0 1 ⎦
-            numberExp, numberExp, numberExp,
-            numberExp, numberExp, numberExp, // b, d, f
-        ].join(`${numberSepExp}+`)}${numberSepExp}*\\)\\s*$`;
-        const matrixExp = new RegExp(regExpSource, 'i');
-        const match = matrixExp.exec(cssString);
-        if (!match) {
-            throw new Error(`Unsupported transformation: ${cssString}`);
+        const parseArguments = (argumentString) => {
+            return argumentString.split(/[, \t\n]+/g).map(argString => {
+                let isPercentage = false;
+                if (argString.endsWith('%')) {
+                    isPercentage = true;
+                    argString = argString.substring(0, argString.length - 1);
+                }
+                // Remove trailing px units.
+                argString = argString.replace(/px$/ig, '');
+                const numberExp = /^[-]?\d*(?:\.\d*)?(?:[eE][-+]?\d+)?$/i;
+                if (!numberExp.exec(argString)) {
+                    throw new Error(`All arguments to transform functions must be numeric (state: ${JSON.stringify({
+                        currentArgument: argString,
+                        allArguments: argumentString,
+                    })})`);
+                }
+                let argNumber = parseFloat(argString);
+                if (isPercentage) {
+                    argNumber /= 100;
+                }
+                return argNumber;
+            });
+        };
+        const keywordToAction = {
+            matrix: (matrixData) => {
+                if (matrixData.length !== 6) {
+                    throw new Error(`Invalid matrix argument: ${matrixData}. Must have length 6`);
+                }
+                const a = matrixData[0];
+                const b = matrixData[1];
+                const c = matrixData[2];
+                const d = matrixData[3];
+                const e = matrixData[4];
+                const f = matrixData[5];
+                const transform = new Mat33(a, c, e, b, d, f, 0, 0, 1);
+                return transform;
+            },
+            scale: (scaleArgs) => {
+                let scaleX, scaleY;
+                if (scaleArgs.length === 1) {
+                    scaleX = scaleArgs[0];
+                    scaleY = scaleArgs[0];
+                }
+                else if (scaleArgs.length === 2) {
+                    scaleX = scaleArgs[0];
+                    scaleY = scaleArgs[1];
+                }
+                else {
+                    throw new Error(`The scale() function only supports two arguments. Given: ${scaleArgs}`);
+                }
+                return Mat33.scaling2D(Vec2_1.Vec2.of(scaleX, scaleY));
+            },
+            translate: (translateArgs) => {
+                let translateX = 0;
+                let translateY = 0;
+                if (translateArgs.length === 1) {
+                    // If no y translation is given, assume 0.
+                    translateX = translateArgs[0];
+                }
+                else if (translateArgs.length === 2) {
+                    translateX = translateArgs[0];
+                    translateY = translateArgs[1];
+                }
+                else {
+                    throw new Error(`The translate() function requires either 1 or 2 arguments. Given ${translateArgs}`);
+                }
+                return Mat33.translation(Vec2_1.Vec2.of(translateX, translateY));
+            },
+        };
+        // A command (\w+)
+        // followed by a set of arguments ([ \t\n0-9eE.,\-%]+)
+        const partRegex = /\s*(\w+)\s*\(([^)]*)\)/ig;
+        let match;
+        let matrix = null;
+        while ((match = partRegex.exec(cssString)) !== null) {
+            const action = match[1].toLowerCase();
+            if (!(action in keywordToAction)) {
+                throw new Error(`Unsupported CSS transform action: ${action}`);
+            }
+            const args = parseArguments(match[2]);
+            const currentMatrix = keywordToAction[action](args);
+            if (!matrix) {
+                matrix = currentMatrix;
+            }
+            else {
+                matrix = matrix.rightMul(currentMatrix);
+            }
         }
-        const matrixData = match.slice(1).map(entry => parseFloat(entry));
-        const a = matrixData[0];
-        const b = matrixData[1];
-        const c = matrixData[2];
-        const d = matrixData[3];
-        const e = matrixData[4];
-        const f = matrixData[5];
-        const transform = new Mat33(a, c, e, b, d, f, 0, 0, 1);
-        return transform;
+        return matrix ?? Mat33.identity;
     }
 }
 exports.Mat33 = Mat33;

package/dist/cjs/Vec3.d.ts

@@ -35,6 +35,13 @@ export declare class Vec3 {
     length(): number;
     magnitude(): number;
     magnitudeSquared(): number;
+    /**
+     * Returns the entry of this with the greatest magnitude.
+     *
+     * In other words, returns $\max \{ |x| : x \in {\bf v} \}$, where ${\bf v}$ is the set of
+     * all entries of this vector.
+     */
+    maximumEntryMagnitude(): number;
     /**
      * Return this' angle in the XY plane (treats this as a Vec2).
      *

package/dist/cjs/Vec3.js

@@ -58,6 +58,15 @@ class Vec3 {
     magnitudeSquared() {
         return this.dot(this);
     }
+    /**
+     * Returns the entry of this with the greatest magnitude.
+     *
+     * In other words, returns $\max \{ |x| : x \in {\bf v} \}$, where ${\bf v}$ is the set of
+     * all entries of this vector.
+     */
+    maximumEntryMagnitude() {
+        return Math.max(Math.abs(this.x), Math.max(Math.abs(this.y), Math.abs(this.z)));
+    }
     /**
      * Return this' angle in the XY plane (treats this as a Vec2).
      *

package/dist/mjs/Mat33.d.ts

@@ -107,15 +107,45 @@ export declare class Mat33 {
     mapEntries(mapping: (component: number, rowcol: [number, number]) => number): Mat33;
     /** Estimate the scale factor of this matrix (based on the first row). */
     getScaleFactor(): number;
+    /** Returns the `idx`-th column (`idx` is 0-indexed). */
+    getColumn(idx: number): Vec3;
+    /** Returns the magnitude of the entry with the largest entry */
+    maximumEntryMagnitude(): number;
     /**
      * Constructs a 3x3 translation matrix (for translating `Vec2`s) using
      * **transformVec2**.
+     *
+     * Creates a matrix in the form
+     * $$
+     * 	\begin{pmatrix}
+     * 		1 & 0 & {\tt amount.x}\\
+     * 		0 & 1 & {\tt amount.y}\\
+     * 		0 & 0 & 1
+     * 	\end{pmatrix}
+     * $$
      */
     static translation(amount: Vec2): Mat33;
     static zRotation(radians: number, center?: Point2): Mat33;
     static scaling2D(amount: number | Vec2, center?: Point2): Mat33;
-    /** @see {@link fromCSSMatrix} */
+    /**
+     * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+     *
+     * @see {@link fromCSSMatrix} and {@link toSafeCSSTransformList}
+     */
     toCSSMatrix(): string;
+    /**
+     * @beta May change or even be removed between minor releases.
+     *
+     * Converts this matrix into a list of CSS transforms that attempt to preserve
+     * this matrix's translation.
+     *
+     * In Chrome/Firefox, translation attributes only support 6 digits (likely an artifact
+     * of using lower-precision floating point numbers). This works around
+     * that by expanding this matrix into the product of several CSS transforms.
+     *
+     * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+     */
+    toSafeCSSTransformList(): string;
     /**
      * Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33.
      *

package/dist/mjs/Mat33.mjs

@@ -1,5 +1,6 @@
 import  { Vec2 }  from './Vec2.mjs';
 import  Vec3  from './Vec3.mjs';
+import  { toRoundedString }  from './rounding.mjs';
 /**
  * Represents a three dimensional linear transformation or
  * a two-dimensional affine transformation. (An affine transformation scales/rotates/shears
@@ -253,9 +254,30 @@ export class Mat33 {
     getScaleFactor() {
         return Math.hypot(this.a1, this.a2);
     }
+    /** Returns the `idx`-th column (`idx` is 0-indexed). */
+    getColumn(idx) {
+        return Vec3.of(this.rows[0].at(idx), this.rows[1].at(idx), this.rows[2].at(idx));
+    }
+    /** Returns the magnitude of the entry with the largest entry */
+    maximumEntryMagnitude() {
+        let greatestSoFar = Math.abs(this.a1);
+        for (const entry of this.toArray()) {
+            greatestSoFar = Math.max(greatestSoFar, Math.abs(entry));
+        }
+        return greatestSoFar;
+    }
     /**
      * Constructs a 3x3 translation matrix (for translating `Vec2`s) using
      * **transformVec2**.
+     *
+     * Creates a matrix in the form
+     * $$
+     * 	\begin{pmatrix}
+     * 		1 & 0 & {\tt amount.x}\\
+     * 		0 & 1 & {\tt amount.y}\\
+     * 		0 & 0 & 1
+     * 	\end{pmatrix}
+     * $$
      */
     static translation(amount) {
         // When transforming Vec2s by a 3x3 matrix, we give the input
@@ -290,10 +312,131 @@ export class Mat33 {
         // Translate such that [center] goes to (0, 0)
         return result.rightMul(Mat33.translation(center.times(-1)));
     }
-    /** @see {@link fromCSSMatrix} */
+    /**
+     * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+     *
+     * @see {@link fromCSSMatrix} and {@link toSafeCSSTransformList}
+     */
     toCSSMatrix() {
         return `matrix(${this.a1},${this.b1},${this.a2},${this.b2},${this.a3},${this.b3})`;
     }
+    /**
+     * @beta May change or even be removed between minor releases.
+     *
+     * Converts this matrix into a list of CSS transforms that attempt to preserve
+     * this matrix's translation.
+     *
+     * In Chrome/Firefox, translation attributes only support 6 digits (likely an artifact
+     * of using lower-precision floating point numbers). This works around
+     * that by expanding this matrix into the product of several CSS transforms.
+     *
+     * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+     */
+    toSafeCSSTransformList() {
+        // Check whether it's safe to return just the CSS matrix
+        const translation = Vec2.of(this.a3, this.b3);
+        const translationRoundedX = toRoundedString(translation.x);
+        const translationRoundedY = toRoundedString(translation.y);
+        const nonDigitsRegex = /[^0-9]+/g;
+        const translationXDigits = translationRoundedX.replace(nonDigitsRegex, '').length;
+        const translationYDigits = translationRoundedY.replace(nonDigitsRegex, '').length;
+        // Is it safe to just return the default CSS matrix?
+        if (translationXDigits <= 5 && translationYDigits <= 5) {
+            return this.toCSSMatrix();
+        }
+        // Remove the last column (the translation column)
+        let transform = new Mat33(this.a1, this.a2, 0, this.b1, this.b2, 0, 0, 0, 1);
+        const transforms = [];
+        let lastScale = null;
+        // Appends a translate() command to the list of `transforms`.
+        const addTranslate = (translation) => {
+            lastScale = null;
+            if (!translation.eq(Vec2.zero)) {
+                transforms.push(`translate(${toRoundedString(translation.x)}px, ${toRoundedString(translation.y)}px)`);
+            }
+        };
+        // Appends a scale() command to the list of transforms, possibly merging with
+        // the last command, if a scale().
+        const addScale = (scale) => {
+            // Merge with the last scale
+            if (lastScale) {
+                const newScale = lastScale.scale(scale);
+                // Don't merge if the new scale has very large values
+                if (newScale.maximumEntryMagnitude() < 1e7) {
+                    const previousCommand = transforms.pop();
+                    console.assert(previousCommand.startsWith('scale'), 'Invalid state: Merging scale commands');
+                    scale = newScale;
+                }
+            }
+            if (scale.x === scale.y) {
+                transforms.push(`scale(${toRoundedString(scale.x)})`);
+            }
+            else {
+                transforms.push(`scale(${toRoundedString(scale.x)}, ${toRoundedString(scale.y)})`);
+            }
+            lastScale = scale;
+        };
+        // Returns the number of digits before the `.` in the given number string.
+        const digitsPreDecimalCount = (numberString) => {
+            let decimalIndex = numberString.indexOf('.');
+            if (decimalIndex === -1) {
+                decimalIndex = numberString.length;
+            }
+            return numberString.substring(0, decimalIndex).replace(nonDigitsRegex, '').length;
+        };
+        // Returns the number of digits (positive for left shift, negative for right shift)
+        // required to shift the decimal to the middle of the number.
+        const getShift = (numberString) => {
+            const preDecimal = digitsPreDecimalCount(numberString);
+            const postDecimal = (numberString.match(/[.](\d*)/) ?? ['', ''])[1].length;
+            // The shift required to center the decimal point.
+            const toCenter = postDecimal - preDecimal;
+            // toCenter is positive for a left shift (adding more pre-decimals),
+            // so, after applying it,
+            const postShiftPreDecimal = preDecimal + toCenter;
+            // We want the digits before the decimal to have a length at most 4, however.
+            // Thus, right shift until this is the case.
+            const shiftForAtMost5DigitsPreDecimal = 4 - Math.max(postShiftPreDecimal, 4);
+            return toCenter + shiftForAtMost5DigitsPreDecimal;
+        };
+        const addShiftedTranslate = (translate, depth = 0) => {
+            const xString = toRoundedString(translate.x);
+            const yString = toRoundedString(translate.y);
+            const xShiftDigits = getShift(xString);
+            const yShiftDigits = getShift(yString);
+            const shift = Vec2.of(Math.pow(10, xShiftDigits), Math.pow(10, yShiftDigits));
+            const invShift = Vec2.of(Math.pow(10, -xShiftDigits), Math.pow(10, -yShiftDigits));
+            addScale(invShift);
+            const shiftedTranslate = translate.scale(shift);
+            const roundedShiftedTranslate = Vec2.of(Math.floor(shiftedTranslate.x), Math.floor(shiftedTranslate.y));
+            addTranslate(roundedShiftedTranslate);
+            // Don't recurse more than 3 times -- the more times we recurse, the more
+            // the scaling is influenced by error.
+            if (!roundedShiftedTranslate.eq(shiftedTranslate) && depth < 3) {
+                addShiftedTranslate(shiftedTranslate.minus(roundedShiftedTranslate), depth + 1);
+            }
+            addScale(shift);
+            return translate;
+        };
+        const adjustTransformFromScale = () => {
+            if (lastScale) {
+                const scaledTransform = transform.rightMul(Mat33.scaling2D(lastScale));
+                // If adding the scale to the transform leads to large values, avoid
+                // doing this.
+                if (scaledTransform.maximumEntryMagnitude() < 1e12) {
+                    transforms.pop();
+                    transform = transform.rightMul(Mat33.scaling2D(lastScale));
+                    lastScale = null;
+                }
+            }
+        };
+        addShiftedTranslate(translation);
+        adjustTransformFromScale();
+        if (!transform.eq(Mat33.identity)) {
+            transforms.push(transform.toCSSMatrix());
+        }
+        return transforms.join(' ');
+    }
     /**
      * Converts a CSS-form `matrix(a, b, c, d, e, f)` to a Mat33.
      *
@@ -308,30 +451,95 @@ export class Mat33 {
         if (cssString === '' || cssString === 'none') {
             return Mat33.identity;
         }
-        const numberExp = '([-]?\\d*(?:\\.\\d*)?(?:[eE][-]?\\d+)?)';
-        const numberSepExp = '[, \\t\\n]';
-        const regExpSource = `^\\s*matrix\\s*\\(${[
-            // According to MDN, matrix(a,b,c,d,e,f) has form:
-            // 		⎡ a c e ⎤
-            // 		⎢ b d f ⎥
-            // 		⎣ 0 0 1 ⎦
-            numberExp, numberExp, numberExp,
-            numberExp, numberExp, numberExp, // b, d, f
-        ].join(`${numberSepExp}+`)}${numberSepExp}*\\)\\s*$`;
-        const matrixExp = new RegExp(regExpSource, 'i');
-        const match = matrixExp.exec(cssString);
-        if (!match) {
-            throw new Error(`Unsupported transformation: ${cssString}`);
+        const parseArguments = (argumentString) => {
+            return argumentString.split(/[, \t\n]+/g).map(argString => {
+                let isPercentage = false;
+                if (argString.endsWith('%')) {
+                    isPercentage = true;
+                    argString = argString.substring(0, argString.length - 1);
+                }
+                // Remove trailing px units.
+                argString = argString.replace(/px$/ig, '');
+                const numberExp = /^[-]?\d*(?:\.\d*)?(?:[eE][-+]?\d+)?$/i;
+                if (!numberExp.exec(argString)) {
+                    throw new Error(`All arguments to transform functions must be numeric (state: ${JSON.stringify({
+                        currentArgument: argString,
+                        allArguments: argumentString,
+                    })})`);
+                }
+                let argNumber = parseFloat(argString);
+                if (isPercentage) {
+                    argNumber /= 100;
+                }
+                return argNumber;
+            });
+        };
+        const keywordToAction = {
+            matrix: (matrixData) => {
+                if (matrixData.length !== 6) {
+                    throw new Error(`Invalid matrix argument: ${matrixData}. Must have length 6`);
+                }
+                const a = matrixData[0];
+                const b = matrixData[1];
+                const c = matrixData[2];
+                const d = matrixData[3];
+                const e = matrixData[4];
+                const f = matrixData[5];
+                const transform = new Mat33(a, c, e, b, d, f, 0, 0, 1);
+                return transform;
+            },
+            scale: (scaleArgs) => {
+                let scaleX, scaleY;
+                if (scaleArgs.length === 1) {
+                    scaleX = scaleArgs[0];
+                    scaleY = scaleArgs[0];
+                }
+                else if (scaleArgs.length === 2) {
+                    scaleX = scaleArgs[0];
+                    scaleY = scaleArgs[1];
+                }
+                else {
+                    throw new Error(`The scale() function only supports two arguments. Given: ${scaleArgs}`);
+                }
+                return Mat33.scaling2D(Vec2.of(scaleX, scaleY));
+            },
+            translate: (translateArgs) => {
+                let translateX = 0;
+                let translateY = 0;
+                if (translateArgs.length === 1) {
+                    // If no y translation is given, assume 0.
+                    translateX = translateArgs[0];
+                }
+                else if (translateArgs.length === 2) {
+                    translateX = translateArgs[0];
+                    translateY = translateArgs[1];
+                }
+                else {
+                    throw new Error(`The translate() function requires either 1 or 2 arguments. Given ${translateArgs}`);
+                }
+                return Mat33.translation(Vec2.of(translateX, translateY));
+            },
+        };
+        // A command (\w+)
+        // followed by a set of arguments ([ \t\n0-9eE.,\-%]+)
+        const partRegex = /\s*(\w+)\s*\(([^)]*)\)/ig;
+        let match;
+        let matrix = null;
+        while ((match = partRegex.exec(cssString)) !== null) {
+            const action = match[1].toLowerCase();
+            if (!(action in keywordToAction)) {
+                throw new Error(`Unsupported CSS transform action: ${action}`);
+            }
+            const args = parseArguments(match[2]);
+            const currentMatrix = keywordToAction[action](args);
+            if (!matrix) {
+                matrix = currentMatrix;
+            }
+            else {
+                matrix = matrix.rightMul(currentMatrix);
+            }
         }
-        const matrixData = match.slice(1).map(entry => parseFloat(entry));
-        const a = matrixData[0];
-        const b = matrixData[1];
-        const c = matrixData[2];
-        const d = matrixData[3];
-        const e = matrixData[4];
-        const f = matrixData[5];
-        const transform = new Mat33(a, c, e, b, d, f, 0, 0, 1);
-        return transform;
+        return matrix ?? Mat33.identity;
     }
 }
 Mat33.identity = new Mat33(1, 0, 0, 0, 1, 0, 0, 0, 1);

package/dist/mjs/Vec3.d.ts

@@ -35,6 +35,13 @@ export declare class Vec3 {
     length(): number;
     magnitude(): number;
     magnitudeSquared(): number;
+    /**
+     * Returns the entry of this with the greatest magnitude.
+     *
+     * In other words, returns $\max \{ |x| : x \in {\bf v} \}$, where ${\bf v}$ is the set of
+     * all entries of this vector.
+     */
+    maximumEntryMagnitude(): number;
     /**
      * Return this' angle in the XY plane (treats this as a Vec2).
      *

package/dist/mjs/Vec3.mjs

@@ -55,6 +55,15 @@ export class Vec3 {
     magnitudeSquared() {
         return this.dot(this);
     }
+    /**
+     * Returns the entry of this with the greatest magnitude.
+     *
+     * In other words, returns $\max \{ |x| : x \in {\bf v} \}$, where ${\bf v}$ is the set of
+     * all entries of this vector.
+     */
+    maximumEntryMagnitude() {
+        return Math.max(Math.abs(this.x), Math.max(Math.abs(this.y), Math.abs(this.z)));
+    }
     /**
      * Return this' angle in the XY plane (treats this as a Vec2).
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@js-draw/math",
-	"version": "1.3.0",
+	"version": "1.3.1",
 	"description": "A math library for js-draw. ",
 	"types": "./dist/mjs/lib.d.ts",
 	"main": "./dist/cjs/lib.js",
@@ -22,7 +22,7 @@
 		"dist-test": "npm run build && cd dist-test/test_imports && npm install && npm run test",
 		"dist": "npm run build && npm run dist-test",
 		"build": "rm -rf ./dist && mkdir dist && build-tool build",
-		"watch": "rm -rf ./dist && mkdir dist && build-tool watch"
+		"watch": "rm -rf ./dist/* && mkdir -p dist && build-tool watch"
 	},
 	"dependencies": {
 		"bezier-js": "6.1.3"
@@ -45,5 +45,5 @@
 		"svg",
 		"math"
 	],
-	"gitHead": "46b3d8f819f8e083f6e3e1d01e027e4311355456"
+	"gitHead": "65af7ec944f70b69b2a4b07d98e5bb92eeeca029"
 }

package/src/Mat33.fromCSSMatrix.test.ts

@@ -0,0 +1,90 @@
+import Mat33 from './Mat33';
+import { Vec2 } from './Vec2';
+
+describe('Mat33.fromCSSMatrix', () => {
+	it('should convert CSS matrix(...) strings to matricies', () => {
+		// From MDN:
+		// 		⎡ a c e ⎤
+		// 		⎢ b d f ⎥  =  matrix(a,b,c,d,e,f)
+		// 		⎣ 0 0 1 ⎦
+		const identity = Mat33.fromCSSMatrix('matrix(1, 0, 0, 1, 0, 0)');
+		expect(identity).objEq(Mat33.identity);
+		expect(Mat33.fromCSSMatrix('matrix(1, 2, 3, 4, 5, 6)')).objEq(new Mat33(
+			1, 3, 5,
+			2, 4, 6,
+			0, 0, 1,
+		));
+		expect(Mat33.fromCSSMatrix('matrix(1e2, 2, 3, 4, 5, 6)')).objEq(new Mat33(
+			1e2, 3, 5,
+			2, 4, 6,
+			0, 0, 1,
+		));
+		expect(Mat33.fromCSSMatrix('matrix(1.6, 2, .3, 4, 5, 6)')).objEq(new Mat33(
+			1.6, .3, 5,
+			2, 4, 6,
+			0, 0, 1,
+		));
+		expect(Mat33.fromCSSMatrix('matrix(-1, 2, 3.E-2, 4, -5.123, -6.5)')).objEq(new Mat33(
+			-1, 0.03, -5.123,
+			2, 4, -6.5,
+			0, 0, 1,
+		));
+		expect(Mat33.fromCSSMatrix('matrix(1.6,\n\t2, .3, 4, 5, 6)')).objEq(new Mat33(
+			1.6, .3, 5,
+			2, 4, 6,
+			0, 0, 1,
+		));
+		expect(Mat33.fromCSSMatrix('matrix(1.6,2, .3E-2, 4, 5, 6)')).objEq(new Mat33(
+			1.6, 3e-3, 5,
+			2, 4, 6,
+			0, 0, 1,
+		));
+		expect(Mat33.fromCSSMatrix('matrix(-1, 2e6,	3E-2,-5.123, -6.5e-1, 0.01)')).objEq(new Mat33(
+			-1, 	3E-2,  	-6.5e-1,
+			2e6,	-5.123,	0.01,
+			0,  	0,     	1,
+		));
+	});
+
+	it('should convert multi-matrix arguments into a single CSS matrix', () => {
+		const identity = Mat33.fromCSSMatrix('matrix(1, 0, 0, 1, 0, 0) matrix(1, 0, 0, 1, 0, 0)');
+		expect(identity).objEq(Mat33.identity);
+
+		expect(Mat33.fromCSSMatrix('matrix(1, 0, 0, 1, 0, 0) matrix(1, 2, 3, 4, 5, 6) matrix(1, 0, 0, 1, 0, 0)')).objEq(new Mat33(
+			1, 3, 5,
+			2, 4, 6,
+			0, 0, 1,
+		));
+
+		expect(Mat33.fromCSSMatrix('matrix(2,\n\t 0, 0, 2, 0, 0) matrix(1, 2, 3, 4, 5, 6) matrix(1, 0, 0, 1, 0, 0)')).objEq(new Mat33(
+			2, 6, 10,
+			4, 8, 12,
+			0, 0, 1,
+		));
+	});
+
+	it('should convert scale()s with a single argument', () => {
+		expect(Mat33.fromCSSMatrix('scale(1)')).objEq(Mat33.identity);
+		expect(Mat33.fromCSSMatrix('scale(0.4)')).objEq(Mat33.scaling2D(0.4));
+		expect(Mat33.fromCSSMatrix('scale(-0.4 )')).objEq(Mat33.scaling2D(-0.4));
+		expect(Mat33.fromCSSMatrix('scale(100%)')).objEq(Mat33.identity);
+		expect(Mat33.fromCSSMatrix('scale(20e2%)')).objEq(Mat33.scaling2D(20));
+		expect(Mat33.fromCSSMatrix('scale(200%) scale(50%)')).objEq(Mat33.identity);
+	});
+
+	it('should convert scale()s with two arguments', () => {
+		expect(Mat33.fromCSSMatrix('scale(1\t 1)')).objEq(Mat33.identity);
+		expect(Mat33.fromCSSMatrix('scale(1\t 2)')).objEq(Mat33.scaling2D(Vec2.of(1, 2)));
+		expect(Mat33.fromCSSMatrix('scale(1\t 2) scale(1)')).objEq(Mat33.scaling2D(Vec2.of(1, 2)));
+	});
+
+	it('should convert translate()s', () => {
+		expect(Mat33.fromCSSMatrix('translate(0)')).objEq(Mat33.identity);
+		expect(Mat33.fromCSSMatrix('translate(1, 1)')).objEq(Mat33.translation(Vec2.of(1, 1)));
+		expect(Mat33.fromCSSMatrix('translate(1 200%)')).objEq(Mat33.translation(Vec2.of(1, 2)));
+	});
+
+	it('should support px following numbers', () => {
+		expect(Mat33.fromCSSMatrix('translate(1px, 2px)')).objEq(Mat33.translation(Vec2.of(1, 2)));
+	});
+});

package/src/Mat33.test.ts

@@ -198,47 +198,11 @@ describe('Mat33 tests', () => {
 		));
 	});
 
-	it('should convert CSS matrix(...) strings to matricies', () => {
-		// From MDN:
-		// 		⎡ a c e ⎤
-		// 		⎢ b d f ⎥  =  matrix(a,b,c,d,e,f)
-		// 		⎣ 0 0 1 ⎦
-		const identity = Mat33.fromCSSMatrix('matrix(1, 0, 0, 1, 0, 0)');
-		expect(identity).objEq(Mat33.identity);
-		expect(Mat33.fromCSSMatrix('matrix(1, 2, 3, 4, 5, 6)')).objEq(new Mat33(
-			1, 3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(1e2, 2, 3, 4, 5, 6)')).objEq(new Mat33(
-			1e2, 3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(1.6, 2, .3, 4, 5, 6)')).objEq(new Mat33(
-			1.6, .3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(-1, 2, 3.E-2, 4, -5.123, -6.5)')).objEq(new Mat33(
-			-1, 0.03, -5.123,
-			2, 4, -6.5,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(1.6,\n\t2, .3, 4, 5, 6)')).objEq(new Mat33(
-			1.6, .3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(1.6,2, .3E-2, 4, 5, 6)')).objEq(new Mat33(
-			1.6, 3e-3, 5,
-			2, 4, 6,
-			0, 0, 1,
-		));
-		expect(Mat33.fromCSSMatrix('matrix(-1, 2e6,	3E-2,-5.123, -6.5e-1, 0.01)')).objEq(new Mat33(
-			-1, 	3E-2,  	-6.5e-1,
-			2e6,	-5.123,	0.01,
-			0,  	0,     	1,
-		));
+	it('getColumn should return the given column index', () => {
+		expect(Mat33.identity.getColumn(0)).objEq(Vec3.unitX);
+		expect(Mat33.identity.getColumn(1)).objEq(Vec3.of(0, 1, 0));
+
+		// scaling2D only scales the x/y components of vectors it transforms
+		expect(Mat33.scaling2D(2).getColumn(2)).objEq(Vec3.of(0, 0, 1));
 	});
 });

package/src/Mat33.ts

@@ -335,9 +335,37 @@ export class Mat33 {
 		return Math.hypot(this.a1, this.a2);
 	}
 
+	/** Returns the `idx`-th column (`idx` is 0-indexed). */
+	public getColumn(idx: number) {
+		return Vec3.of(
+			this.rows[0].at(idx),
+			this.rows[1].at(idx),
+			this.rows[2].at(idx),
+		);
+	}
+
+	/** Returns the magnitude of the entry with the largest entry */
+	public maximumEntryMagnitude() {
+		let greatestSoFar = Math.abs(this.a1);
+		for (const entry of this.toArray()) {
+			greatestSoFar = Math.max(greatestSoFar, Math.abs(entry));
+		}
+
+		return greatestSoFar;
+	}
+
 	/**
 	 * Constructs a 3x3 translation matrix (for translating `Vec2`s) using
 	 * **transformVec2**.
+	 *
+	 * Creates a matrix in the form
+	 * $$
+	 * 	\begin{pmatrix}
+	 * 		1 & 0 & {\tt amount.x}\\
+	 * 		0 & 1 & {\tt amount.y}\\
+	 * 		0 & 0 & 1
+	 * 	\end{pmatrix}
+	 * $$
 	 */
 	public static translation(amount: Vec2): Mat33 {
 		// When transforming Vec2s by a 3x3 matrix, we give the input
@@ -392,7 +420,11 @@ export class Mat33 {
 		return result.rightMul(Mat33.translation(center.times(-1)));
 	}
 
-	/** @see {@link fromCSSMatrix} */
+	/**
+	 * **Note**: Assumes `this.c1 = this.c2 = 0` and `this.c3 = 1`.
+	 *
+	 * @see {@link fromCSSMatrix} and {@link toSafeCSSTransformList}
+	 */
 	public toCSSMatrix(): string {
 		return `matrix(${this.a1},${this.b1},${this.a2},${this.b2},${this.a3},${this.b3})`;
 	}
@@ -412,39 +444,118 @@ export class Mat33 {
 			return Mat33.identity;
 		}
 
-		const numberExp = '([-]?\\d*(?:\\.\\d*)?(?:[eE][-]?\\d+)?)';
-		const numberSepExp = '[, \\t\\n]';
-		const regExpSource = `^\\s*matrix\\s*\\(${
-			[
-				// According to MDN, matrix(a,b,c,d,e,f) has form:
-				// 		⎡ a c e ⎤
-				// 		⎢ b d f ⎥
-				// 		⎣ 0 0 1 ⎦
-				numberExp, numberExp, numberExp, // a, c, e
-				numberExp, numberExp, numberExp, // b, d, f
-			].join(`${numberSepExp}+`)
-		}${numberSepExp}*\\)\\s*$`;
-		const matrixExp = new RegExp(regExpSource, 'i');
-		const match = matrixExp.exec(cssString);
-
-		if (!match) {
-			throw new Error(`Unsupported transformation: ${cssString}`);
+		const parseArguments = (argumentString: string) => {
+			return argumentString.split(/[, \t\n]+/g).map(argString => {
+				let isPercentage = false;
+				if (argString.endsWith('%')) {
+					isPercentage = true;
+					argString = argString.substring(0, argString.length - 1);
+				}
+
+				// Remove trailing px units.
+				argString = argString.replace(/px$/ig, '');
+
+				const numberExp = /^[-]?\d*(?:\.\d*)?(?:[eE][-+]?\d+)?$/i;
+
+				if (!numberExp.exec(argString)) {
+					throw new Error(
+						`All arguments to transform functions must be numeric (state: ${
+							JSON.stringify({
+								currentArgument: argString,
+								allArguments: argumentString,
+							})
+						})`
+					);
+				}
+
+				let argNumber = parseFloat(argString);
+
+				if (isPercentage) {
+					argNumber /= 100;
+				}
+
+				return argNumber;
+			});
+		};
+
+
+		const keywordToAction = {
+			matrix: (matrixData: number[]) => {
+				if (matrixData.length !== 6) {
+					throw new Error(`Invalid matrix argument: ${matrixData}. Must have length 6`);
+				}
+
+				const a = matrixData[0];
+				const b = matrixData[1];
+				const c = matrixData[2];
+				const d = matrixData[3];
+				const e = matrixData[4];
+				const f = matrixData[5];
+
+				const transform = new Mat33(
+					a, c, e,
+					b, d, f,
+					0, 0, 1
+				);
+				return transform;
+			},
+
+			scale: (scaleArgs: number[]) => {
+				let scaleX, scaleY;
+				if (scaleArgs.length === 1) {
+					scaleX = scaleArgs[0];
+					scaleY = scaleArgs[0];
+				} else if (scaleArgs.length === 2) {
+					scaleX = scaleArgs[0];
+					scaleY = scaleArgs[1];
+				} else {
+					throw new Error(`The scale() function only supports two arguments. Given: ${scaleArgs}`);
+				}
+
+				return Mat33.scaling2D(Vec2.of(scaleX, scaleY));
+			},
+
+			translate: (translateArgs: number[]) => {
+				let translateX = 0;
+				let translateY = 0;
+
+				if (translateArgs.length === 1) {
+					// If no y translation is given, assume 0.
+					translateX = translateArgs[0];
+				} else if (translateArgs.length === 2) {
+					translateX = translateArgs[0];
+					translateY = translateArgs[1];
+				} else {
+					throw new Error(`The translate() function requires either 1 or 2 arguments. Given ${translateArgs}`);
+				}
+
+				return Mat33.translation(Vec2.of(translateX, translateY));
+			},
+		};
+
+		// A command (\w+)
+		// followed by a set of arguments ([ \t\n0-9eE.,\-%]+)
+		const partRegex = /\s*(\w+)\s*\(([^)]*)\)/ig;
+		let match;
+		let matrix: Mat33|null = null;
+
+		while ((match = partRegex.exec(cssString)) !== null) {
+			const action = match[1].toLowerCase();
+			if (!(action in keywordToAction)) {
+				throw new Error(`Unsupported CSS transform action: ${action}`);
+			}
+
+			const args = parseArguments(match[2]);
+			const currentMatrix = keywordToAction[action as keyof typeof keywordToAction](args);
+
+			if (!matrix) {
+				matrix = currentMatrix;
+			} else {
+				matrix = matrix.rightMul(currentMatrix);
+			}
 		}
 
-		const matrixData = match.slice(1).map(entry => parseFloat(entry));
-		const a = matrixData[0];
-		const b = matrixData[1];
-		const c = matrixData[2];
-		const d = matrixData[3];
-		const e = matrixData[4];
-		const f = matrixData[5];
-
-		const transform = new Mat33(
-			a, c, e,
-			b, d, f,
-			0, 0, 1
-		);
-		return transform;
+		return matrix ?? Mat33.identity;
 	}
 }
 export default Mat33;

package/src/Vec3.ts

@@ -63,6 +63,16 @@ export class Vec3 {
 		return this.dot(this);
 	}
 
+	/**
+	 * Returns the entry of this with the greatest magnitude.
+	 *
+	 * In other words, returns $\max \{ |x| : x \in {\bf v} \}$, where ${\bf v}$ is the set of
+	 * all entries of this vector.
+	 */
+	public maximumEntryMagnitude(): number {
+		return Math.max(Math.abs(this.x), Math.max(Math.abs(this.y), Math.abs(this.z)));
+	}
+
 	/**
 	 * Return this' angle in the XY plane (treats this as a Vec2).
 	 *

package/src/rounding.ts

@@ -165,3 +165,4 @@ export const toStringOfSamePrecision = (num: number, ...references: string[]): s
 	const negativeSign = textMatch[1];
 	return cleanUpNumber(`${negativeSign}${preDecimal}.${postDecimal}`);
 };
+