@itwin/core-geometry 4.0.0-dev.46 → 4.0.0-dev.50

package/lib/cjs/geometry3d/Transform.js

@@ -14,21 +14,25 @@ const Matrix3d_1 = require("./Matrix3d");
 const Point2dVector2d_1 = require("./Point2dVector2d");
 const Point3dVector3d_1 = require("./Point3dVector3d");
 const Range_1 = require("./Range");
-/** A transform is an origin and a Matrix3d.
- *
- * * This describes a coordinate frame with
- * this origin, with the columns of the Matrix3d being the
- * local x,y,z axis directions.
- * *  Beware that for common transformations (e.g. scale about point,
- * rotate around line, mirror across a plane) the "fixed point" that is used
- * when describing the transform is NOT the "origin" stored in the transform.
- * Setup methods (e.g createFixedPointAndMatrix, createScaleAboutPoint)
- * take care of determining the appropriate origin coordinates.
+/**
+ * A Transform consists of an origin and a Matrix3d. This describes a coordinate frame with this origin, with
+ * the columns of the Matrix3d being the local x,y,z axis directions.
+ * * The math for a Transform `T` consisting of a Matrix3d `M` and a Point3d `o` on a Vector3d `p` is: `Tp = M*p + o`.
+ * In other words, `T` is a combination of two operations on `p`: the action of matrix multiplication, followed by a
+ * translation. `Origin` is a traditional term for `o`, because `T` can be interpreted as a change of basis from the
+ * global axes centered at the global origin, to a new set of axes centered at `o`.
+ * * Beware that for common transformations (e.g. scale about point, rotate around an axis, mirror across a
+ * plane) the "fixed point" that is used when describing the transform is NOT the "origin" stored in the
+ * transform. Setup methods (e.g createFixedPointAndMatrix, createScaleAboutPoint) take care of determining
+ * the appropriate origin coordinates.
  * @public
  */
 class Transform {
-    // Constructor accepts and uses POINTER to content .. no copy here.
-    constructor(origin, matrix) { this._origin = origin; this._matrix = matrix; }
+    // Constructor accepts and uses pointer to content (no copy is done here).
+    constructor(origin, matrix) {
+        this._origin = origin;
+        this._matrix = matrix;
+    }
     /** The identity Transform. Value is frozen and cannot be modified. */
     static get identity() {
         if (undefined === this._identity) {
@@ -38,18 +42,31 @@ class Transform {
         return this._identity;
     }
     /** Freeze this instance (and its members) so it is read-only */
-    freeze() { this._origin.freeze(); this._matrix.freeze(); return Object.freeze(this); }
+    freeze() {
+        this._origin.freeze();
+        this._matrix.freeze();
+        return Object.freeze(this);
+    }
     /**
      * Copy contents from other Transform into this Transform
      * @param other source transform
      */
-    setFrom(other) { this._origin.setFrom(other._origin), this._matrix.setFrom(other._matrix); }
+    setFrom(other) {
+        this._origin.setFrom(other._origin);
+        this._matrix.setFrom(other._matrix);
+    }
     /** Set this Transform to be an identity. */
-    setIdentity() { this._origin.setZero(); this._matrix.setIdentity(); }
-    /** Set this Transform instance from flexible inputs:
-     * * Any object (such as another Transform) that has `origin` and `matrix` members accepted by Point3d.setFromJSON and Matrix3d.setFromJSON
+    setIdentity() {
+        this._origin.setZero();
+        this._matrix.setIdentity();
+    }
+    /**
+     * Set this Transform instance from flexible inputs:
+     * * Any object (such as another Transform or TransformProps) that has `origin` and `matrix` members
+     * accepted by `Point3d.setFromJSON` and `Matrix3d.setFromJSON`
      * * An array of 3 number arrays, each with 4 entries which are rows in a 3x4 matrix.
      * * An array of 12 numbers, each block of 4 entries as a row 3x4 matrix.
+     * * If no input is provided, the identity Transform is returned.
      */
     setFromJSON(json) {
         if (json) {
@@ -74,25 +91,24 @@ class Transform {
         this.setIdentity();
     }
     /**
-     * Test for near equality with other Transform.  Comparison uses the isAlmostEqual methods on
-     * the origin and matrix parts.
+     * Test for near equality with `other` Transform. Comparison uses the `isAlmostEqual` methods on the `origin` and
+     * `matrix` parts.
      * @param other Transform to compare to.
      */
-    isAlmostEqual(other) { return this.origin.isAlmostEqual(other.origin) && this.matrix.isAlmostEqual(other.matrix); }
+    isAlmostEqual(other) {
+        return this.origin.isAlmostEqual(other.origin) && this.matrix.isAlmostEqual(other.matrix);
+    }
     /**
-     * Test for near equality with other Transform.  Comparison uses the isAlmostEqualAllowZRotation method of Matrix3d
-     * the origin and matrix parts.
+     * Test for near equality with `other` Transform. Comparison uses the `isAlmostEqual` methods on the `origin` part
+     * and the `isAlmostEqualAllowZRotation` method on the `matrix` part.
      * @param other Transform to compare to.
      */
-    isAlmostEqualAllowZRotation(other) { return this._origin.isAlmostEqual(other._origin) && this._matrix.isAlmostEqualAllowZRotation(other._matrix); }
-    /** Return a 3 by 4 matrix containing the rows of this Transform
-    * * This transform's origin is the [3] entry of the json arrays
-    */
-    toJSON() {
-        return this.toRows();
+    isAlmostEqualAllowZRotation(other) {
+        return this._origin.isAlmostEqual(other._origin) && this._matrix.isAlmostEqualAllowZRotation(other._matrix);
     }
-    /** Return a 3 by 4 matrix containing the rows of this Transform
-     * * This transform's origin is the [3] entry of the json arrays
+    /**
+     * Return a 3 by 4 matrix containing the rows of this Transform.
+     * * The transform's origin coordinates are the last entries of the 3 json arrays
      */
     toRows() {
         return [
@@ -101,13 +117,20 @@ class Transform {
             [this._matrix.coffs[6], this._matrix.coffs[7], this._matrix.coffs[8], this._origin.z],
         ];
     }
-    /** Return a new Transform initialized by `setFromJSON (json)` */
+    /**
+     * Return a 3 by 4 matrix containing the rows of this Transform.
+     * * The transform's origin coordinates are the last entries of the 3 json arrays
+    */
+    toJSON() {
+        return this.toRows();
+    }
+    /** Return a new Transform initialized by `Transform.setFromJSON` */
     static fromJSON(json) {
         const result = Transform.createIdentity();
         result.setFromJSON(json);
         return result;
     }
-    /** Copy the contents of this transform into a new Transform (or to the result, if specified). */
+    /** Copy the contents of `this` transform into a new Transform (or to the result, if specified). */
     clone(result) {
         if (result) {
             result._matrix.setFrom(this._matrix);
@@ -116,18 +139,17 @@ class Transform {
         }
         return new Transform(Point3dVector3d_1.Point3d.createFrom(this._origin), this._matrix.clone());
     }
-    /** Return a copy of this Transform, modified so that its axes are rigid
-     * * The first axis direction named in axisOrder is preserved
-     * * The plane of the first and second directions is preserved, and its vector in the rigid matrix has positive dot product with the corresponding vector if the instance
-     * * The third named column is the cross product of the first and second.
+    /**
+     * Return a modified copy of `this` Transform so that its `matrix` part is rigid (`origin` part is untouched).
+     * * For details of how the matrix is modified to rigid, see documentation of `Matrix3d.axisOrderCrossProductsInPlace`
      */
     cloneRigid(axisOrder = Geometry_1.AxisOrder.XYZ) {
-        const axes0 = Matrix3d_1.Matrix3d.createRigidFromMatrix3d(this.matrix, axisOrder);
-        if (!axes0)
+        const modifiedMatrix = Matrix3d_1.Matrix3d.createRigidFromMatrix3d(this.matrix, axisOrder);
+        if (!modifiedMatrix)
             return undefined;
-        return new Transform(this.origin.cloneAsPoint3d(), axes0);
+        return new Transform(this.origin.cloneAsPoint3d(), modifiedMatrix);
     }
-    /** Create a copy with the given origin and matrix captured as the Transform origin and Matrix3d. */
+    /** Create a Transform with the given `origin` and `matrix`. */
     static createRefs(origin, matrix, result) {
         if (!origin)
             origin = Point3dVector3d_1.Point3d.createZero();
@@ -138,7 +160,7 @@ class Transform {
         }
         return new Transform(origin, matrix);
     }
-    /** Create a transform with complete contents given */
+    /** Create a Transform with complete contents given */
     static createRowValues(qxx, qxy, qxz, ax, qyx, qyy, qyz, ay, qzx, qzy, qzz, az, result) {
         if (result) {
             result._origin.set(ax, ay, az);
@@ -147,42 +169,55 @@ class Transform {
         }
         return new Transform(Point3dVector3d_1.Point3d.create(ax, ay, az), Matrix3d_1.Matrix3d.createRowValues(qxx, qxy, qxz, qyx, qyy, qyz, qzx, qzy, qzz));
     }
-    /** Create a transform with all zeros.
-     */
+    /** Create a Transform with all zeros */
     static createZero(result) {
         return Transform.createRowValues(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, result);
     }
     /**
-     * create a Transform with translation provided by x,y,z parts.
+     * Create a Transform with translation provided by x,y,z parts.
      * @param x x part of translation
      * @param y y part of translation
      * @param z z part of translation
-     * @param result optional result
-     * @returns new or updated transform.
+     * @param result optional pre-allocated Transform
+     * @returns new or updated transform
      */
     static createTranslationXYZ(x = 0, y = 0, z = 0, result) {
         return Transform.createRefs(Point3dVector3d_1.Vector3d.create(x, y, z), Matrix3d_1.Matrix3d.createIdentity(), result);
     }
-    /** Create a matrix with specified translation part.
-     * @param XYZ x,y,z parts of the translation.
-     * @returns new or updated transform.
+    /**
+     * Create a Transform with specified `translation` part.
+     * @param translation x,y,z parts of the translation
+     * @param result optional pre-allocated Transform
+     * @returns new or updated transform
      */
     static createTranslation(translation, result) {
         return Transform.createRefs(translation, Matrix3d_1.Matrix3d.createIdentity(), result);
     }
-    /** Return a reference to the matrix within the transform.  (NOT a copy) */
-    get matrix() { return this._matrix; }
-    /** Return a reference to the origin within the transform.  (NOT a copy) */
-    get origin() { return this._origin; }
-    /** return a (clone of) the origin part of the transform, as a Point3d */
-    getOrigin() { return Point3dVector3d_1.Point3d.createFrom(this._origin); }
-    /** return a (clone of) the origin part of the transform, as a Vector3d */
-    getTranslation() { return Point3dVector3d_1.Vector3d.createFrom(this._origin); }
-    /** test if the transform has 000 origin and identity Matrix3d */
+    /** Return a reference (and NOT a copy) to the `matrix` part of the Transform. */
+    get matrix() {
+        return this._matrix;
+    }
+    /** Return a reference (and NOT a copy) to the `origin` part of the Transform. */
+    get origin() {
+        return this._origin;
+    }
+    /** return a (clone of) the `origin` part of the Transform, as a `Point3d` */
+    getOrigin() {
+        return Point3dVector3d_1.Point3d.createFrom(this._origin);
+    }
+    /** return a (clone of) the `origin` part of the Transform, as a `Vector3d` */
+    getTranslation() {
+        return Point3dVector3d_1.Vector3d.createFrom(this._origin);
+    }
+    /** return a (clone of) the `matrix` part of the Transform, as a `Matrix3d` */
+    getMatrix() {
+        return this._matrix.clone();
+    }
+    /** test if the transform has `origin` = (0,0,0) and identity `matrix` */
     get isIdentity() {
         return this._matrix.isIdentity && this._origin.isAlmostZero;
     }
-    /** Return an identity transform, optionally filling existing transform.  */
+    /** Create an identity transform */
     static createIdentity(result) {
         if (result) {
             result._origin.setZero();
@@ -191,9 +226,12 @@ class Transform {
         }
         return Transform.createRefs(Point3dVector3d_1.Point3d.createZero(), Matrix3d_1.Matrix3d.createIdentity());
     }
-    /** Create by directly installing origin and matrix
-     * this is a the appropriate construction when the columns of the matrix are coordinate axes of a local-to-global mapping
-     * Note there is a closely related createFixedPointAndMatrix whose point input is the fixed point of the global-to-global transformation.
+    /**
+     * Create a Transform using the given `origin` and `matrix`.
+     * * This is a the appropriate construction when the columns of the matrix are coordinate axes of a
+     * local-to-world mapping.
+     * * This function is a closely related to `createFixedPointAndMatrix` whose point input is the fixed point
+     * of the world-to-world transformation.
      */
     static createOriginAndMatrix(origin, matrix, result) {
         if (result) {
@@ -203,8 +241,13 @@ class Transform {
         }
         return Transform.createRefs(origin ? origin.cloneAsPoint3d() : Point3dVector3d_1.Point3d.createZero(), matrix === undefined ? Matrix3d_1.Matrix3d.createIdentity() : matrix.clone(), result);
     }
-    /** Create by directly installing origin and columns of the matrix
-     */
+    /** Create a Transform using the given `origin` and columns of the `matrix`. If `undefined` zero is used. */
+    setOriginAndMatrixColumns(origin, vectorX, vectorY, vectorZ) {
+        if (origin !== undefined)
+            this._origin.setFrom(origin);
+        this._matrix.setColumns(vectorX, vectorY, vectorZ);
+    }
+    /** Create a Transform using the given `origin` and columns of the `matrix` */
     static createOriginAndMatrixColumns(origin, vectorX, vectorY, vectorZ, result) {
         if (result)
             result.setOriginAndMatrixColumns(origin, vectorX, vectorY, vectorZ);
@@ -212,127 +255,177 @@ class Transform {
             result = Transform.createRefs(Point3dVector3d_1.Vector3d.createFrom(origin), Matrix3d_1.Matrix3d.createColumns(vectorX, vectorY, vectorZ));
         return result;
     }
-    /** Create by with matrix from Matrix3d.createRigidFromColumns.
-     * * Has careful logic for building up optional result without allocations.
+    /**
+     * Create a Transform such that its `matrix` part is rigid.
+     * * For details of how the matrix is created to be rigid, see documentation of `Matrix3d.createRigidFromColumns`
      */
     static createRigidFromOriginAndColumns(origin, vectorX, vectorY, axisOrder, result) {
         const matrix = Matrix3d_1.Matrix3d.createRigidFromColumns(vectorX, vectorY, axisOrder, result ? result._matrix : undefined);
         if (!matrix)
             return undefined;
         if (result) {
-            // The matrix was already defined !!!
+            // result._matrix was already modified to become rigid via createRigidFromColumns
             result._origin.setFrom(origin);
             return result;
         }
-        // cleanly capture the matrix and then the point ..
+        /**
+         * We don't want to pass "origin" to createRefs because createRefs does not clone "origin" and use its reference.
+         * That means if "origin" is changed via Transform at any point, the initial "origin" passed by the user is also
+         * changed. To avoid that, we pass undefined to createRefs. This would cause createRefs to create a new "origin"
+         * equals (0,0,0) which then we set it to the "origin" passed by user in the next line.
+         */
         result = Transform.createRefs(undefined, matrix);
         result._origin.setFromPoint3d(origin);
         return result;
     }
-    /** Reinitialize by directly installing origin and columns of the matrix
-     */
-    setOriginAndMatrixColumns(origin, vectorX, vectorY, vectorZ) {
-        if (origin !== undefined)
-            this._origin.setFrom(origin);
-        this._matrix.setColumns(vectorX, vectorY, vectorZ);
-    }
-    /** Create a transform with the specified matrix. Compute an origin (different from the given fixedPoint)
-     * so that the fixedPoint maps back to itself.
+    /**
+     * Create a Transform with the specified `matrix`. Compute an `origin` (different from the given `fixedPoint`)
+     * so that the `fixedPoint` maps back to itself. The returned Transform, transforms a point `p` to `M*p + (f - M*f)`
+     * where `f` is the fixedPoint (i.e., `Tp = M*(p-f) + f`).
      */
     static createFixedPointAndMatrix(fixedPoint, matrix, result) {
         if (fixedPoint) {
+            /**
+             * if f is a fixed point, then Tf = M*f + o = f where M is the matrix and o is the origin.
+             * we define the origin o = f - M*f. Therefore, Tf = Mf + o = M*f + (f - M*f) = f.
+             */
             const origin = Matrix3d_1.Matrix3d.xyzMinusMatrixTimesXYZ(fixedPoint, matrix, fixedPoint);
             return Transform.createRefs(origin, matrix.clone(), result);
         }
         return Transform.createRefs(undefined, matrix.clone());
     }
-    /** Create a transform with the specified matrix, acting on any `pointX `via
-     * `pointY = matrix * (pointX - pointA) + pointB`
-     * so that the fixedPoint maps back to itself.
+    /**
+     * Create a transform with the specified `matrix` and points `a` and `b`. The returned Transform, transforms
+     * point `p` to `M*(p-a) + b` (i.e., `Tp = M*(p-a) + b`) so transforms point `a` to 'b'.
      */
-    static createMatrixPickupPutdown(matrix, pointA, pointB, result) {
-        const origin = Matrix3d_1.Matrix3d.xyzMinusMatrixTimesXYZ(pointB, matrix, pointA);
+    static createMatrixPickupPutdown(matrix, a, b, result) {
+        // we define the origin o = b - M*a so Tp = M*p + o = M*p + (b - M*a) = M*(x-a) + b
+        const origin = Matrix3d_1.Matrix3d.xyzMinusMatrixTimesXYZ(b, matrix, a);
         return Transform.createRefs(origin, matrix.clone(), result);
     }
-    /** Create a Transform which leaves the fixedPoint unchanged and
-     * scales everything else around it by a single scale factor.
+    /**
+     * Create a Transform which leaves the fixedPoint unchanged and scales everything else around it by
+     * a single scale factor. The returned Transform, transforms a point `p` to `M*p + (f - M*f)`
+     * where `f` is the fixedPoint and M is the scale matrix (i.e., `Tp = M*(p-f) + f`).
      */
     static createScaleAboutPoint(fixedPoint, scale, result) {
         const matrix = Matrix3d_1.Matrix3d.createScale(scale, scale, scale);
+        /**
+         * if f is a fixed point, then Tf = M*f + o = f where M is the matrix and o is the origin.
+         * we define the origin o = f - M*f. Therefore, Tf = M*f + o = M*f + (f - M*f) = f.
+         */
         const origin = Matrix3d_1.Matrix3d.xyzMinusMatrixTimesXYZ(fixedPoint, matrix, fixedPoint);
         return Transform.createRefs(origin, matrix, result);
     }
-    /** Transform the input 2d point.  Return as a new point or in the pre-allocated result (if result is given) */
-    multiplyPoint2d(source, result) {
-        return Matrix3d_1.Matrix3d.xyPlusMatrixTimesXY(this._origin, this._matrix, source, result);
+    /** Transform the input 2d point. Return as a new point or in the pre-allocated result (if result is given). */
+    multiplyPoint2d(point, result) {
+        // Tx = Mx + o so we return Mx + o
+        return Matrix3d_1.Matrix3d.xyPlusMatrixTimesXY(this._origin, this._matrix, point, result);
     }
-    /** Transform the input 3d point.  Return as a new point or in the pre-allocated result (if result is given) */
+    /** Transform the input 3d point. Return as a new point or in the pre-allocated result (if result is given). */
     multiplyPoint3d(point, result) {
+        // Tx = Mx + o so we return Mx + o
         return Matrix3d_1.Matrix3d.xyzPlusMatrixTimesXYZ(this._origin, this._matrix, point, result);
     }
-    /** Transform the input object with x,y,z members */
+    /** Transform the input 3d point in place (override the input point by the transformed point). */
     multiplyXYAndZInPlace(point) {
+        // Tx = Mx + o so we override x by Mx + o
         return Matrix3d_1.Matrix3d.xyzPlusMatrixTimesXYZInPlace(this._origin, this._matrix, point);
     }
-    /** Transform the input point.  Return as a new point or in the pre-allocated result (if result is given) */
+    /** Transform the input point. Return as a new point or in the pre-allocated result (if result is given). */
     multiplyXYZ(x, y, z = 0, result) {
+        // Tx = Mx + o so we return Mx + o
         return Matrix3d_1.Matrix3d.xyzPlusMatrixTimesCoordinates(this._origin, this._matrix, x, y, z, result);
     }
-    /** Multiply a specific row of the transform times xyz. Return the (number). */
+    /**
+     * Multiply a specific row (component) of the transform matrix times xyz and add it to the origin element
+     * at the same row. Return the result.
+     */
     multiplyComponentXYZ(componentIndex, x, y, z = 0) {
         const coffs = this._matrix.coffs;
-        const i0 = 3 * componentIndex;
-        return this.origin.at(componentIndex) + coffs[i0] * x + coffs[i0 + 1] * y + coffs[i0 + 2] * z;
+        const idx = 3 * componentIndex;
+        return this.origin.at(componentIndex) + (coffs[idx] * x) + (coffs[idx + 1] * y) + (coffs[idx + 2] * z);
     }
-    /** Multiply a specific row of the transform times (weighted!) xyzw. Return the (number). */
+    /**
+     * Multiply a specific row (component) of the transform matrix times xyz and add it to the origin element
+     * at the same row times w. Return the result.
+     */
     multiplyComponentXYZW(componentIndex, x, y, z, w) {
         const coffs = this._matrix.coffs;
-        const i0 = 3 * componentIndex;
-        return this.origin.at(componentIndex) * w +
-            coffs[i0] * x + coffs[i0 + 1] * y + coffs[i0 + 2] * z;
+        const idx = 3 * componentIndex;
+        return (this.origin.at(componentIndex) * w) + (coffs[idx] * x) + (coffs[idx + 1] * y) + (coffs[idx + 2] * z);
     }
-    /** Transform the input homogeneous point.  Return as a new point or in the pre-allocated result (if result is given) */
+    /**
+     * If `p = (x,y,z)` then transform is `Tp = M*p + o*w`. This function returns the transformed point as a new
+     * point4d (`Tp` as first 3 elements and `w` as last element) or in the pre-allocated result (if result is given).
+     */
     multiplyXYZW(x, y, z, w, result) {
         return Matrix3d_1.Matrix3d.xyzPlusMatrixTimesWeightedCoordinates(this._origin, this._matrix, x, y, z, w, result);
     }
-    /** Transform the input homogeneous point.  Return as a new point or in the pre-allocated result (if result is given) */
+    /**
+     * If `p = (x,y,z)` then transform is `Tp = M*p + o*w`. This function returns the transformed point as a new
+     * Float64Array with size 4 (`Tp` as first 3 elements and `w` as last element) or in the pre-allocated result
+     * (if result is given).
+     */
     multiplyXYZWToFloat64Array(x, y, z, w, result) {
         return Matrix3d_1.Matrix3d.xyzPlusMatrixTimesWeightedCoordinatesToFloat64Array(this._origin, this._matrix, x, y, z, w, result);
     }
-    /** Transform the input homogeneous point.  Return as a new point or in the pre-allocated result (if result is given) */
+    /**
+     * If `p = (x,y,z)` then transform is `Tp = M*p + o`. This function returns the transformed point as a new
+     * Float64Array with size 3 (`Tp` as 3 elements) or in the pre-allocated result (if result is given).
+     */
     multiplyXYZToFloat64Array(x, y, z, result) {
         return Matrix3d_1.Matrix3d.xyzPlusMatrixTimesCoordinatesToFloat64Array(this._origin, this._matrix, x, y, z, result);
     }
-    /** Multiply the transposed transform (as 4x4 with 0001 row) by Point4d given as xyzw..  Return as a new point or in the pre-allocated result (if result is given) */
+    /**
+     * Treat the 3x3 matrix and origin as upper 3x4 part of a 4x4 matrix, with 0001 as the final row. Now multiply
+     * the transposed of this 4x4 matrix by Point4d given as xyzw. Return as a new point4d (`M*p` as first 3 elements
+     * and `o*p + w` as last element where `p = (x,y,z)`) or in the pre-allocated result (if result is given).
+     */
     multiplyTransposeXYZW(x, y, z, w, result) {
         const coffs = this._matrix.coffs;
         const origin = this._origin;
-        return Point4d_1.Point4d.create(x * coffs[0] + y * coffs[3] + z * coffs[6], x * coffs[1] + y * coffs[4] + z * coffs[7], x * coffs[2] + y * coffs[5] + z * coffs[8], x * origin.x + y * origin.y + z * origin.z + w, result);
+        return Point4d_1.Point4d.create((x * coffs[0]) + (y * coffs[3]) + (z * coffs[6]), (x * coffs[1]) + (y * coffs[4]) + (z * coffs[7]), (x * coffs[2]) + (y * coffs[5]) + (z * coffs[8]), (x * origin.x) + (y * origin.y) + (z * origin.z) + w, result);
     }
-    /** for each point:  replace point by Transform*point */
+    /** For each point in the array, replace point by the transformed point (by `Tp = M*p + o`) */
     multiplyPoint3dArrayInPlace(points) {
         let point;
         for (point of points)
             Matrix3d_1.Matrix3d.xyzPlusMatrixTimesXYZ(this._origin, this._matrix, point, point);
     }
-    /** for each point:  replace point by Transform*point */
+    /** For each point in the 2d array, replace point by the transformed point (by `Tp = M*p + o`) */
     multiplyPoint3dArrayArrayInPlace(chains) {
         for (const chain of chains)
             this.multiplyPoint3dArrayInPlace(chain);
     }
-    /** Return product of the transform's inverse times a point. */
+    /**
+     * If for a point `p` we have `Tp = M*p + o = point` (where `point` is the transformed point), then
+     * `p = MInverse * (point - o)`. This function returns the original point `p` if `point` is the
+     * transformed point (`Tp = point`).
+     * * Return as a new point or in the optional `result`.
+     * * Returns `undefined` if the `matrix` part if this Transform is singular.
+     */
     multiplyInversePoint3d(point, result) {
         return this._matrix.multiplyInverseXYZAsPoint3d(point.x - this._origin.x, point.y - this._origin.y, point.z - this._origin.z, result);
     }
-    /** Inverse transform the input homogeneous point.
-     * * Return as a new point or in the optional result.
-     * * returns undefined if the matrix part if this Transform is singular.
+    /**
+     * If for a point `p` we have `Tp = M*p + w*o = weightedPoint` (where `weightedPoint` is the transformed point), then
+     * `p = MInverse * (weightedPoint - w*o)`. This function returns a Point4d where first 3 elements are the original
+     *  point `p` if `weightedPoint` is the transformed point (`Tp = weightedPoint`) and the last element is `w`.
+     * * Return as a new point or in the optional `result`.
+     * * Returns `undefined` if the `matrix` part if this Transform is singular.
      */
     multiplyInversePoint4d(weightedPoint, result) {
         const w = weightedPoint.w;
         return this._matrix.multiplyInverseXYZW(weightedPoint.x - w * this.origin.x, weightedPoint.y - w * this.origin.y, weightedPoint.z - w * this.origin.z, w, result);
     }
-    /** Return product of the transform's inverse times a point (point given as x,y,z) */
+    /**
+     * If for a point `p = (x,y,z)` we have `Tp = M*p + o = point` (where `point` is the transformed point), then
+     * `p = MInverse * (point - o)`. This function returns the original point `p` if `point` is the transformed
+     * point (`Tp = point`).
+     * * Return as a new point or in the optional `result`.
+     * * Returns `undefined` if the `matrix` part if this Transform is singular.
+     */
     multiplyInverseXYZ(x, y, z, result) {
         return this._matrix.multiplyInverseXYZAsPoint3d(x - this._origin.x, y - this._origin.y, z - this._origin.z, result);
     }
@@ -358,8 +451,8 @@ class Transform {
         return result;
     }
     /**
-     * * for each point in source: multiply transformInverse * point in place in the point.
-     * * return false if not invertible.
+     * * For each point in source: multiply transformInverse * point in place in the point.
+     * * Return false if not invertible.
      */
     multiplyInversePoint3dArrayInPlace(source) {
         if (!this._matrix.computeCachedInverse(true))
@@ -403,9 +496,9 @@ class Transform {
         return numSource;
     }
     /**
-     * *  for each point:   multiply    transform * point
-     * *  if result is given, resize to match source and replace each corresponding pi
-     * *  if result is not given, return a new array.
+     * * For each point:   multiply    transform * point
+     * * If result is given, resize to match source and replace each corresponding pi
+     * * If result is not given, return a new array.
      */
     multiplyPoint2dArray(source, result) {
         if (result) {
@@ -420,9 +513,9 @@ class Transform {
         return result;
     }
     /**
-     * *  for each point:   multiply    transform * point
-     * *  if result is given, resize to match source and replace each corresponding pi
-     * *  if result is not given, return a new array.
+     * * For each point:   multiply    transform * point
+     * * If result is given, resize to match source and replace each corresponding pi
+     * * If result is not given, return a new array.
      */
     multiplyPoint3dArray(source, result) {
         if (result) {
@@ -436,30 +529,30 @@ class Transform {
             result.push(Matrix3d_1.Matrix3d.xyzPlusMatrixTimesXYZ(this._origin, this._matrix, p));
         return result;
     }
-    /** Multiply the vector by the Matrix3d part of the transform.
-     *
-     * *  The transform's origin is not used.
-     * *  Return as new or result by usual optional result convention
+    /**
+     * Multiply the vector by the Matrix3d part of the transform.
+     * * The transform's origin is not used.
+     * * Return as new or result by usual optional result convention
      */
     multiplyVector(vector, result) {
         return this._matrix.multiplyVector(vector, result);
     }
-    /** Multiply the vector in place by the Matrix3d part of the transform.
-       *
-       * *  The transform's origin is not used.
-       */
+    /**
+     * Multiply the vector in place by the Matrix3d part of the transform.
+     * * The transform's origin is not used.
+     */
     multiplyVectorInPlace(vector) {
         this._matrix.multiplyVectorInPlace(vector);
     }
-    /** Multiply the vector (x,y,z) by the Matrix3d part of the transform.
-     *
-     * *  The transform's origin is not used.
-     * *  Return as new or result by usual optional result convention
+    /**
+     * Multiply the vector (x,y,z) by the Matrix3d part of the transform.
+     * * The transform's origin is not used.
+     * * Return as new or result by usual optional result convention
      */
     multiplyVectorXYZ(x, y, z, result) {
         return this._matrix.multiplyXYZ(x, y, z, result);
     }
-    /** multiply this Transform times other Transform.
+    /** Multiply this Transform times other Transform.
      * ```
      * equation
      * \begin{matrix}
@@ -478,7 +571,7 @@ class Transform {
         return result;
     }
     /**
-     * multiply transformA * transformB, store to calling instance.
+     * Multiply transformA * transformB, store to calling instance.
      * @param transformA left operand
      * @param transformB right operand
      */
@@ -491,7 +584,8 @@ class Transform {
     }
     //   [Q A][R 0] = [QR A]
     //   [0 1][0 1]   [0  1]
-    /** multiply this Transform times other Matrix3d, with other considered to be a Transform with 0 translation.
+    /**
+     * Multiply this Transform times other Matrix3d, with other considered to be a Transform with 0 translation.
      * ```
      * equation
      * \begin{matrix}
@@ -514,7 +608,7 @@ class Transform {
      * Return the range of the transformed corners.
      * * The 8 corners are transformed individually.
      * * Note that if there is anything other than translation and principal axis scaling in the transform, the volume of the range rotation will increase.
-     *    * Hence to get a "tight" range on rotated geometry, a range computation must be made on the rotated geometry itself.
+     * * Hence to get a "tight" range on rotated geometry, a range computation must be made on the rotated geometry itself.
      */
     multiplyRange(range, result) {
         if (range.isNull)
@@ -539,15 +633,22 @@ class Transform {
     }
     /**
      * * Return a Transform which is the inverse of this transform.
-     * * Return undefined if this Transform's matrix is singular.
+     * @param result optional pre-allocated result
+     * @return the inverse Transform, or undefined if the matrix is singular
      */
-    inverse() {
-        const matrixInverse = this._matrix.inverse();
+    inverse(result) {
+        const matrixInverse = this._matrix.inverse(result ? result._matrix : undefined);
         if (!matrixInverse)
             return undefined;
+        if (result) {
+            // result._matrix is already defined
+            matrixInverse.multiplyXYZ(-this._origin.x, -this._origin.y, -this._origin.z, result._origin);
+            return result;
+        }
         return Transform.createRefs(matrixInverse.multiplyXYZ(-this._origin.x, -this._origin.y, -this._origin.z), matrixInverse);
     }
-    /** Initialize transforms that map each direction of a box (axis aligned) to `[0,1]`.
+    /**
+     * Initialize transforms that map each direction of a box (axis aligned) to `[0,1]`.
      * * The corner coordinates do _not_ need to be in order in any of the x,y,z directions.
      * * The npcToGlobalTransform (if supplied) maps 000 to the point named point000.
      * * The npcToGlobalTransform (if supplied) maps 11 to the point named point000.