@itwin/core-geometry 4.0.0-dev.55 → 4.0.0-dev.58

package/lib/esm/geometry3d/Transform.js

@@ -142,7 +142,7 @@ export class Transform {
     }
     /**
      * 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`
+     * * @see [[Matrix3d.axisOrderCrossProductsInPlace]] documentation for details of how the matrix is modified to rigid.
      */
     cloneRigid(axisOrder = AxisOrder.XYZ) {
         const modifiedMatrix = Matrix3d.createRigidFromMatrix3d(this.matrix, axisOrder);
@@ -150,7 +150,7 @@ export class Transform {
             return undefined;
         return new Transform(this.origin.cloneAsPoint3d(), modifiedMatrix);
     }
-    /** Create a Transform with the given `origin` and `matrix`. */
+    /** Create a Transform with the given `origin` and `matrix`. Inputs are captured, not cloned. */
     static createRefs(origin, matrix, result) {
         if (!origin)
             origin = Point3d.createZero();
@@ -161,7 +161,7 @@ export class Transform {
         }
         return new Transform(origin, matrix);
     }
-    /** Create a Transform with complete contents given */
+    /** Create a Transform with complete contents given. `q` inputs make the matrix and `a` inputs make the origin */
     static createRowValues(qxx, qxy, qxz, ax, qyx, qyy, qyz, ay, qzx, qzy, qzz, az, result) {
         if (result) {
             result._origin.set(ax, ay, az);
@@ -176,6 +176,8 @@ export class Transform {
     }
     /**
      * Create a Transform with translation provided by x,y,z parts.
+     * * Translation Transform maps any vector `v` to `v + p` where `p = (x,y,z)`
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/MoveCube
      * @param x x part of translation
      * @param y y part of translation
      * @param z z part of translation
@@ -187,6 +189,8 @@ export class Transform {
     }
     /**
      * Create a Transform with specified `translation` part.
+     * * Translation Transform maps any vector `v` to `v + translation`
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/MoveCube
      * @param translation x,y,z parts of the translation
      * @param result optional pre-allocated Transform
      * @returns new or updated transform
@@ -233,6 +237,7 @@ export class Transform {
      * 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.
+     * * If origin is `undefined`, (0,0,0) is used. If matrix is `undefined` the identity matrix is used.
      */
     static createOriginAndMatrix(origin, matrix, result) {
         if (result) {
@@ -258,7 +263,7 @@ export class Transform {
     }
     /**
      * 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`
+     * @see [[Matrix3d.createRigidFromColumns]] for details of how the matrix is created to be rigid.
      */
     static createRigidFromOriginAndColumns(origin, vectorX, vectorY, axisOrder, result) {
         const matrix = Matrix3d.createRigidFromColumns(vectorX, vectorY, axisOrder, result ? result._matrix : undefined);
@@ -270,10 +275,10 @@ export class Transform {
             return result;
         }
         /**
-         * 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.
+         * We don't want to pass "origin" to createRefs because createRefs does not clone "origin". 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 so that it allocates a new point which then we set it to the "origin" which
+         * is passed by user in the next line.
          */
         result = Transform.createRefs(undefined, matrix);
         result._origin.setFromPoint3d(origin);
@@ -296,18 +301,19 @@ export class Transform {
         return Transform.createRefs(undefined, matrix.clone());
     }
     /**
-     * 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'.
+     * Create a transform with the specified `matrix` and points `a` and `b`. The returned Transform maps
+     * point `p` to `M*(p-a) + b` (i.e., `Tp = M*(p-a) + b`), so maps `a` to 'b'.
      */
     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
+        // we define the origin o = b - M*a so Tp = M*p + o = M*p + (b - M*a) = M*(p-a) + b
         const origin = 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. The returned Transform, transforms a point `p` to `M*p + (f - M*f)`
+     * a single scale factor. The returned Transform maps 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`).
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/ScaleCube
      */
     static createScaleAboutPoint(fixedPoint, scale, result) {
         const matrix = Matrix3d.createScale(scale, scale, scale);
@@ -349,8 +355,7 @@ export class Transform {
         return Matrix3d.xyzPlusMatrixTimesCoordinates(this._origin, this._matrix, x, y, z, result);
     }
     /**
-     * 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.
+     * Multiply a specific row (component) of the 3x4 instance times (x,y,z,1). Return the result.
      */
     multiplyComponentXYZ(componentIndex, x, y, z = 0) {
         const coffs = this._matrix.coffs;
@@ -358,8 +363,7 @@ export class Transform {
         return this.origin.at(componentIndex) + (coffs[idx] * x) + (coffs[idx + 1] * y) + (coffs[idx + 2] * z);
     }
     /**
-     * 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.
+     * Multiply a specific row (component) of the 3x4 instance times (x,y,z,w). Return the result.
      */
     multiplyComponentXYZW(componentIndex, x, y, z, w) {
         const coffs = this._matrix.coffs;
@@ -367,31 +371,38 @@ export class Transform {
         return (this.origin.at(componentIndex) * w) + (coffs[idx] * x) + (coffs[idx + 1] * y) + (coffs[idx + 2] * z);
     }
     /**
-     * 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).
+     * Transform the homogeneous point. Return as a new `Point4d`, or in the pre-allocated result (if result is given).
+     * * If `p = (x,y,z)` then this method computes `Tp = M*p + o*w` and returns the `Point4d` formed by `Tp` in the
+     * first three coordinates, and `w` in the fourth.
+     * * Logically, this is multiplication by the 4x4 matrix formed from the 3x4 instance augmented with fourth row 0001.
      */
     multiplyXYZW(x, y, z, w, result) {
         return Matrix3d.xyzPlusMatrixTimesWeightedCoordinates(this._origin, this._matrix, x, y, z, w, result);
     }
     /**
-     * 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).
+     * Transform the homogeneous point. Return as new `Float64Array` with size 4, or in the pre-allocated result (if
+     * result is given).
+     * * If `p = (x,y,z)` then this method computes `Tp = M*p + o*w` and returns the `Float64Array` formed by `Tp`
+     * in the first 3 numbers of the array and `w` as the fourth.
+     * * Logically, this is multiplication by the 4x4 matrix formed from the 3x4 instance augmented with fourth row 0001.
      */
     multiplyXYZWToFloat64Array(x, y, z, w, result) {
         return Matrix3d.xyzPlusMatrixTimesWeightedCoordinatesToFloat64Array(this._origin, this._matrix, x, y, z, w, result);
     }
     /**
-     * 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).
+     * * Transform the point. Return as new `Float64Array` with size 3, or in the pre-allocated result (if result is given).
+     * * If `p = (x,y,z)` then this method computes `Tp = M*p + o` and returns it as the first 3 elements of the array.
      */
     multiplyXYZToFloat64Array(x, y, z, result) {
         return Matrix3d.xyzPlusMatrixTimesCoordinatesToFloat64Array(this._origin, this._matrix, x, y, z, result);
     }
     /**
-     * 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).
+     * Multiply the homogeneous point by the transpose of `this` Transform. Return as a new `Point4d` or in the
+     * pre-allocated result (if result is given).
+     * * If `p = (x,y,z)` then this method computes `M^t*p` and returns it in the first three coordinates of the `Point4d`,
+     * and `o*p + w` in the fourth.
+     * * Logically, this is multiplication by the transpose of the 4x4 matrix formed from the 3x4 instance augmented with
+     * fourth row 0001.
      */
     multiplyTransposeXYZW(x, y, z, w, result) {
         const coffs = this._matrix.coffs;
@@ -410,9 +421,9 @@ export class Transform {
             this.multiplyPoint3dArrayInPlace(chain);
     }
     /**
-     * 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`).
+     * Multiply the point by the inverse Transform.
+     * * If for a point `p` we have `Tp = M*p + o = q`, then `p = MInverse*(q - o) = TInverse q` so `TInverse`
+     * Transform has matrix part `MInverse` and origin part `-MInverse*o`.
      * * Return as a new point or in the optional `result`.
      * * Returns `undefined` if the `matrix` part if this Transform is singular.
      */
@@ -420,9 +431,13 @@ export class Transform {
         return this._matrix.multiplyInverseXYZAsPoint3d(point.x - this._origin.x, point.y - this._origin.y, point.z - this._origin.z, result);
     }
     /**
-     * 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`.
+     * Multiply the homogenous point by the inverse Transform.
+     * * If for a point `p` we have `Tp = M*p + o = q`, then `p = MInverse*(q - o) = TInverse q` so `TInverse` Transform
+     * has matrix part `MInverse` and origin part `-MInverse*o`.
+     * * This method computes `TInverse p = MInverse*p - w*MInverse*o` and returns the `Point4d` formed by `TInverse*p`
+     * in the first three coordinates, and `w` in the fourth.
+     * * Logically, this is multiplication by the inverse of the 4x4 matrix formed from the 3x4 instance augmented with
+     * fourth row 0001. This is equivalent to the 4x4 matrix formed in similar fashion from the inverse of this instance.
      * * Return as a new point or in the optional `result`.
      * * Returns `undefined` if the `matrix` part if this Transform is singular.
      */
@@ -431,9 +446,9 @@ export class Transform {
         return this._matrix.multiplyInverseXYZW(weightedPoint.x - w * this.origin.x, weightedPoint.y - w * this.origin.y, weightedPoint.z - w * this.origin.z, w, result);
     }
     /**
-     * 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`).
+     * Multiply the point by the inverse Transform.
+     * * If for a point `p` we have `Tp = M*p + o = q`, then `p = MInverse*(q - o) = TInverse q` so `TInverse` Transform
+     * has matrix part `MInverse` and origin part `-MInverse*o`.
      * * Return as a new point or in the optional `result`.
      * * Returns `undefined` if the `matrix` part if this Transform is singular.
      */
@@ -472,35 +487,35 @@ export class Transform {
         return numSource;
     }
     /**
-     * If for each point `p` we have `Tp = M*p + o = point` (where `point` is the transformed point), then
-     * `p = MInverse * (point - o)`. This function returns the array of original points `p[]` if `points`
-     * is the array of transformed point (`Tp = point` for each `p` and `point`).
-     * * If `results` is given, resize it to match the input `points` array and update it with original points `p[]`.
-     * * If `results` is not given, return a new array.
+     * Multiply each point in the array by the inverse of `this` Transform.
+     * * For a transform `T = [M o]` the inverse transform `T' = [M' -M'o]` exists if and only if `M` has an inverse
+     * `M'`. Indeed, for any point `p`, we have `T'Tp = T'(Mp + o) = M'(Mp + o) - M'o = M'Mp + M'o - M'o = p.`
+     * * If `result` is given, resize it to match the input `points` array and update it with original points `p[]`.
+     * * If `result` is not given, return a new array.
      * * Returns `undefined` if the `matrix` part if this Transform is singular.
      */
-    multiplyInversePoint3dArray(points, results) {
+    multiplyInversePoint3dArray(points, result) {
         if (!this._matrix.computeCachedInverse(true))
             return undefined;
         const originX = this.origin.x;
         const originY = this.origin.y;
         const originZ = this.origin.z;
-        if (results) {
-            const n = Transform.matchArrayLengths(points, results, Point3d.createZero);
+        if (result) {
+            const n = Transform.matchArrayLengths(points, result, Point3d.createZero);
             for (let i = 0; i < n; i++)
-                this._matrix.multiplyInverseXYZAsPoint3d(points[i].x - originX, points[i].y - originY, points[i].z - originZ, results[i]);
+                this._matrix.multiplyInverseXYZAsPoint3d(points[i].x - originX, points[i].y - originY, points[i].z - originZ, result[i]);
+            return result;
         }
-        results = [];
+        result = [];
         for (const point of points)
-            results.push(this._matrix.multiplyInverseXYZAsPoint3d(point.x - originX, point.y - originY, point.z - originZ));
-        return results;
+            result.push(this._matrix.multiplyInverseXYZAsPoint3d(point.x - originX, point.y - originY, point.z - originZ));
+        return result;
     }
     /**
-     * If for each point `p` we have `Tp = M*p + o = point` (where `point` is the transformed point), then
-     * `p = MInverse * (point - o)`. This function calculates the array of original points `p[]` if `points`
-     * is the array of transformed point (`Tp = point` for each `p` and `point`) and replaces `points`
-     * with the array of original points.
-     * * Returns `true` if the `matrix` part if this Transform is invertible and `false if singular.
+     * Multiply each point in the array by the inverse of `this` Transform in place.
+     * * For a transform `T = [M o]` the inverse transform `T' = [M' -M'o]` exists if and only if `M` has an inverse
+     * `M'`. Indeed, for any point `p`, we have `T'Tp = T'(Mp + o) = M'(Mp + o) - M'o = M'Mp + M'o - M'o = p.`
+     * * Returns `true` if the `matrix` part if this Transform is invertible and `false` if singular.
      */
     multiplyInversePoint3dArrayInPlace(points) {
         if (!this._matrix.computeCachedInverse(true))
@@ -569,7 +584,8 @@ export class Transform {
     /**
      * Calculate `transformA * transformB` and store it into the calling instance (`this`).
      * * **Note:** If `transformA = [A   a]` and `transformB = [B   b]` then `transformA * transformB` is defined as
-     * `[A*B   Ab+a]`. See `multiplyTransformTransform` doc for math details.
+     * `[A*B   Ab+a]`.
+     * * @see [[multiplyTransformTransform]] documentation for math details.
      * @param transformA first operand
      * @param transformB second operand
      */
@@ -579,19 +595,17 @@ export class Transform {
     }
     /**
      * Multiply `this` Transform times `other` Transform.
-     * **Note:** If `this = [A   a]` and `other = [B   b]` then `this * other` is defined as [A*B   Ab+a].
-     * That's because we create a 4x4 matrix for each Transform with the 3x3 `matrix` and `origin`
-     * as upper 3x4 part of a 4x4 matrix and 0001 as the final row. Then we multiply those two 4x4 matrixes:
+     * * **Note:** If `this = [A   a]` and `other = [B   b]` then `this * other` is defined as [A*B   Ab+a] because:
      * ```
      * equation
      * \begin{matrix}
-     *    \text{`this` Transform with `matrix` part }\bold{A}\text{ and `origin` part }\bold{a} & \blockTransform{A}{a}\\
-     *    \text{`other` Transform with `matrix` part }\bold{B}\text{ and `origin` part }\bold{b} & \blockTransform{B}{b} \\
+     *    \text{this Transform with matrix part }\bold{A}\text{ and origin part }\bold{a} & \blockTransform{A}{a}\\
+     *    \text{other Transform with matrix part }\bold{B}\text{ and origin part }\bold{b} & \blockTransform{B}{b} \\
      * \text{product}& \blockTransform{A}{a}\blockTransform{B}{b}=\blockTransform{AB}{Ab + a}
      * \end{matrix}
      * ```
      * @param other the 'other` Transform to be multiplied to `this` Transform.
-     * @param result optional preallocated result to reuse.
+     * @param result optional preallocated `result` to reuse.
      */
     multiplyTransformTransform(other, result) {
         if (!result)
@@ -601,20 +615,17 @@ export class Transform {
     }
     /**
      * Multiply `this` Transform times `other` Matrix3d (considered to be a Transform with 0 `origin`).
-     * **Note:** If `this = [A   a]`, then we promote `other` matrix to be a Transform [B   0].
-     * Then `this * other` is defined as [A*B   a]. That's because we create a 4x4 matrix for each Transform
-     * with the 3x3 `matrix` and `origin` as upper 3x4 part of a 4x4 matrix and 0001 as the final row. Then we
-     * multiply those two 4x4 matrixes:
+     * * **Note:** If `this = [A   a]` and `other = [B   0]`, then `this * other` is defined as [A*B   a] because:
      * ```
      * equation
      * \begin{matrix}
-     *    \text{`this` Transform with `matrix` part }\bold{A}\text{ and `origin` part }\bold{a} & \blockTransform{A}{a}\\
-     *    \text{`other` matrix }\bold{B}\text{ promoted to block Transform} & \blockTransform{B}{0} \\
+     *    \text{this Transform with matrix part }\bold{A}\text{ and origin part }\bold{a} & \blockTransform{A}{a}\\
+     *    \text{other matrix }\bold{B}\text{ promoted to block Transform} & \blockTransform{B}{0} \\
      * \text{product}& \blockTransform{A}{a}\blockTransform{B}{0}=\blockTransform{AB}{a}
      * \end{matrix}
      * ```
      * @param other the `other` Matrix3d to be multiplied to `this` Transform.
-     * @param result optional preallocated result to reuse.
+     * @param result optional preallocated `result` to reuse.
      */
     multiplyTransformMatrix3d(other, result) {
         if (!result)
@@ -624,13 +635,13 @@ export class Transform {
         return result;
     }
     /**
-     * Return the Range of the transformed corners.
+     * Return the range of the transformed corners.
      * * The 8 corners are transformed individually.
      * * **Note:** Suppose you have a geometry, a range box around that geometry, and your Transform is a rotation.
      * If you rotate the range box and recompute a new range box around the rotated range box, then the new range
      * box will have a larger volume than the original range box. However, if you rotate the geometry itself and
      * then recompute the range box, it will be a tighter range box around the rotated geometry. `multiplyRange`
-     * function creates the larger range box because it only has access to the range box and the geometry itself.
+     * function creates the larger range box because it only has access to the range box and not the geometry itself.
      */
     multiplyRange(range, result) {
         if (range.isNull)
@@ -654,7 +665,7 @@ export class Transform {
     }
     /**
      * Return a Transform which is the inverse of `this` Transform.
-     * * If `transform = [M   o]` then `transformInverse = [MInverse   MInverse*-o]`
+     * * If `transform = [M   o]` then `transformInverse = [MInverse   -MInverse*o]`
      * * Return `undefined` if this Transform's matrix is singular.
      */
     inverse(result) {
@@ -669,14 +680,14 @@ export class Transform {
         return Transform.createRefs(matrixInverse.multiplyXYZ(-this._origin.x, -this._origin.y, -this._origin.z), matrixInverse);
     }
     /**
-     * Initialize 2 Transforms: First Transform maps a box (axis aligned) specified by `min` and `max` to
-     * the unit box specified by 000 and 111 and inverse of it. Second Transform is the reverse of first.
-     * @param min the min corner of the box
-     * @param max the max corner of the box
-     * @param npcToGlobal maps global (the unit box specified by 000 and 111) to NPC (a box specified by `min`
-     * and `max`). Object created by caller, re-initialized here.
-     * @param globalToNpc maps NPC (a box specified by `min` and `max`) to global (the unit box specified by
-     * 000 and 111). Object created by caller, re-initialized here.
+     * Initialize 2 Transforms that map between the unit box (specified by 000 and 111) and the range box specified
+     * by the input points.
+     * @param min the min corner of the range box
+     * @param max the max corner of the range box
+     * @param npcToGlobal maps NPC coordinates into range box coordinates. Specifically, maps 000 to `min` and maps
+     * 111 to `max`. This Transform is the inverse of `globalToNpc`. Object created by caller, re-initialized here.
+     * @param globalToNpc maps range box coordinates into NPC coordinates. Specifically, maps `min` to 000 and maps
+     * `max` to 111. This Transform is the inverse of `npcToGlobal`. Object created by caller, re-initialized here.
      * * NPC stands for `Normalized Projection Coordinate`
      */
     static initFromRange(min, max, npcToGlobal, globalToNpc) {