@itwin/core-geometry 4.0.0-dev.66 → 4.0.0-dev.68

package/lib/esm/Geometry.js

@@ -8,7 +8,7 @@ import { Vector3d } from "./geometry3d/Point3dVector3d";
 /**
  * Enumeration of the 6 possible orderings of XYZ axis order
  * * **Note:** There are 3 axis order with right hand system (XYZ = 0, YZX = 1, ZXY = 2) and 3 axis order with
- * left hand system (XZY = 4, YXZ = 5, ZYX = 6). Note that AxisOrder is encoding the handedness as well. Cross
+ * left hand system (XZY = 4, YXZ = 5, ZYX = 6). Note that `AxisOrder` is encoding the handedness as well. Cross
  * product of the i_th axis in an ordering (i=0,1,2), with the i+1_th in that ordering, will produce the i+2_th
  * axis in that ordering.
  * @public
@@ -41,7 +41,8 @@ export var AxisIndex;
     /** 2 axis is index 2 */
     AxisIndex[AxisIndex["Z"] = 2] = "Z";
 })(AxisIndex || (AxisIndex = {}));
-/** Standard views. Used in `Matrix3d.createStandardViewAxes(index: StandardViewIndex, invert: boolean)`
+/**
+ * Standard views. Used in `Matrix3d.createStandardViewAxes(index: StandardViewIndex, invert: boolean)`
  * @public
  */
 export var StandardViewIndex;
@@ -50,20 +51,21 @@ export var StandardViewIndex;
     StandardViewIndex[StandardViewIndex["Top"] = 1] = "Top";
     /** X to right, negative Y up */
     StandardViewIndex[StandardViewIndex["Bottom"] = 2] = "Bottom";
-    /** negative Y to right, Z up */
+    /** Negative Y to right, Z up */
     StandardViewIndex[StandardViewIndex["Left"] = 3] = "Left";
-    /**  Y to right, Z up */
+    /** Y to right, Z up */
     StandardViewIndex[StandardViewIndex["Right"] = 4] = "Right";
     /** X to right, Z up */
     StandardViewIndex[StandardViewIndex["Front"] = 5] = "Front";
-    /** negative X to right, Z up */
+    /** Negative X to right, Z up */
     StandardViewIndex[StandardViewIndex["Back"] = 6] = "Back";
-    /** isometric: view towards origin from (-1,-1,1) */
+    /** Isometric: view towards origin from (-1,-1,1) */
     StandardViewIndex[StandardViewIndex["Iso"] = 7] = "Iso";
-    /** right isometric: view towards origin from (1,-1,1) */
+    /** Right isometric: view towards origin from (1,-1,1) */
     StandardViewIndex[StandardViewIndex["RightIso"] = 8] = "RightIso";
 })(StandardViewIndex || (StandardViewIndex = {}));
-/** Enumeration among choice for how a coordinate transformation should incorporate scaling.
+/**
+ * Enumeration among choice for how a coordinate transformation should incorporate scaling.
  * @public
  */
 export var AxisScaleSelect;
@@ -75,7 +77,8 @@ export var AxisScaleSelect;
     /** On each axis, the vector length matches he length of the corresponding edge of the range. */
     AxisScaleSelect[AxisScaleSelect["NonUniformRangeContainment"] = 2] = "NonUniformRangeContainment";
 })(AxisScaleSelect || (AxisScaleSelect = {}));
-/** Enumeration of possible locations of a point in the plane of a polygon.
+/**
+ * Enumeration of possible locations of a point in the plane of a polygon.
  * @public
  */
 export var PolygonLocation;
@@ -108,18 +111,26 @@ export var PolygonLocation;
  * @public
  */
 class Geometry {
-    /** Test if absolute value of x is huge.
-     * * See `Geometry.hugeCoordinate`
+    /** Test if absolute value of x is large (larger than `Geometry.largeCoordinateResult`) */
+    static isLargeCoordinateResult(x) {
+        return x > this.largeCoordinateResult || x < -this.largeCoordinateResult;
+    }
+    /**
+     * Test if absolute value of x is large (larger than `Geometry.largeCoordinateResult`).
+     * @deprecated in 4.x. Use `isLargeCoordinateResult`.
      */
     static isHugeCoordinate(x) {
-        return x > this.hugeCoordinate || x < -this.hugeCoordinate;
+        return Geometry.isLargeCoordinateResult(x);
     }
-    /** Test if a number is odd.
-     */
+    /** Test if a number is odd */
     static isOdd(x) {
-        return (x & (0x01)) === 1;
+        return (x & (0x01)) === 1; // bitwise operation
     }
-    /** Correct `distance` to zero if undefined or smaller than metric tolerance.   Otherwise return it unchanged. */
+    /**
+     * Correct distance to zero.
+     * * If `distance` magnitude is `undefined` or smaller than `smallMetricDistance`, then return `replacement`
+     * (or 0 if replacement is not passed). Otherwise return `distance`.
+     */
     static correctSmallMetricDistance(distance, replacement = 0.0) {
         if (distance === undefined || Math.abs(distance) < Geometry.smallMetricDistance) {
             return replacement;
@@ -127,64 +138,119 @@ class Geometry {
         return distance;
     }
     /**
-   * If `a` is large enough for safe division, return `1/a`, using Geometry.smallMetricDistance as the tolerance for declaring it as divide by zero.  Otherwise return `undefined`.
-   * @param a denominator of division
-   */
-    static inverseMetricDistance(a) {
-        return (Math.abs(a) <= Geometry.smallMetricDistance) ? undefined : 1.0 / a;
+     * Correct `fraction` to `replacement` if `fraction` is undefined or too small.
+     * @param fraction number to test
+     * @param replacement value to return if `fraction` is too small
+     * @returns `fraction` if its absolute value is at least `Geometry.smallFraction`; otherwise returns `replacement`
+     */
+    static correctSmallFraction(fraction, replacement = 0.0) {
+        if (fraction === undefined || Math.abs(fraction) < Geometry.smallFraction) {
+            return replacement;
+        }
+        return fraction;
+    }
+    /**
+     * Return the inverse of `distance`.
+     * * If `distance` magnitude is smaller than `smallMetricDistance` (i.e. distance is large enough for safe division),
+     * then return `1/distance`. Otherwise return `undefined`.
+     */
+    static inverseMetricDistance(distance) {
+        return (Math.abs(distance) <= Geometry.smallMetricDistance) ? undefined : 1.0 / distance;
     }
     /**
-     * If `a` is large enough, return `1/a`, using the square of Geometry.smallMetricDistance as the tolerance for declaring it as divide by zero.  Otherwise return `undefined`.
-     * @param a denominator of division
+     * Return the inverse of `distanceSquared`.
+     * * If `distanceSquared ` magnitude is smaller than `smallMetricDistanceSquared` (i.e. distanceSquared  is large
+     * enough for safe division), then return `1/distanceSquared `. Otherwise return `undefined`.
      */
-    static inverseMetricDistanceSquared(a) {
-        return (Math.abs(a) <= Geometry.smallMetricDistanceSquared) ? undefined : 1.0 / a;
+    static inverseMetricDistanceSquared(distanceSquared) {
+        return (Math.abs(distanceSquared) <= Geometry.smallMetricDistanceSquared) ? undefined : 1.0 / distanceSquared;
     }
     /**
-     * Boolean test for metric coordinate near-equality (i.e., if x and y are almost equal). If tolerance is not passed,
-     * `Geometry.smallMetricDistance` is used as tolerance.
+     * Boolean test for metric coordinate near-equality (i.e., if `x` and `y` are almost equal) using `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
      */
-    static isSameCoordinate(x, y, tol) {
-        if (tol)
-            return Math.abs(x - y) < Math.abs(tol);
-        return Math.abs(x - y) < Geometry.smallMetricDistance;
+    static isSameCoordinate(x, y, tolerance = Geometry.smallMetricDistance) {
+        let d = x - y;
+        if (d < 0)
+            d = -d;
+        return d <= tolerance;
     }
-    /** Boolean test for metric coordinate near-equality, with toleranceFactor applied to the usual smallMetricDistance */
+    /**
+     * Boolean test for metric coordinate near-equality (i.e., if `x` and `y` are almost equal) using
+     * `tolerance = toleranceFactor * smallMetricDistance`
+     * */
     static isSameCoordinateWithToleranceFactor(x, y, toleranceFactor) {
         return Geometry.isSameCoordinate(x, y, toleranceFactor * Geometry.smallMetricDistance);
     }
-    /** Boolean test for metric coordinate near-equality of x, y pair */
-    static isSameCoordinateXY(x0, y0, x1, y1, tol = Geometry.smallMetricDistance) {
+    /**
+     * Boolean test for metric coordinate pair near-equality (i.e., if `x0` and `x1` are almost equal
+     * and `y0` and `y1` are almost equal) using `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     */
+    static isSameCoordinateXY(x0, y0, x1, y1, tolerance = Geometry.smallMetricDistance) {
         let d = x1 - x0;
         if (d < 0)
             d = -d;
-        if (d > tol)
+        if (d > tolerance)
             return false;
         d = y1 - y0;
         if (d < 0)
             d = -d;
-        return d < tol;
-    }
-    /** Boolean test for squared metric coordinate near-equality */
-    static isSameCoordinateSquared(x, y) {
-        return Math.abs(Math.sqrt(x) - Math.sqrt(y)) < Geometry.smallMetricDistance;
-    }
-    /** boolean test for small `dataA.distance (dataB)`  within `smallMetricDistance` */
-    static isSamePoint3d(dataA, dataB) { return dataA.distance(dataB) < Geometry.smallMetricDistance; }
-    /** boolean test for distance between `XYZ` objects within `smallMetricDistance`
-     *  * Note that Point3d and Vector3d are both derived from XYZ, so this method tolerates mixed types.
-     */
-    static isSameXYZ(dataA, dataB) { return dataA.distance(dataB) < Geometry.smallMetricDistance; }
-    /** boolean test for small `dataA.distanceXY (dataB)`  within `smallMetricDistance` */
-    static isSamePoint3dXY(dataA, dataB) { return dataA.distanceXY(dataB) < Geometry.smallMetricDistance; }
-    /** boolean test for small `dataA.distanceXY (dataB)`  within `smallMetricDistance` */
-    static isSameVector3d(dataA, dataB) { return dataA.distance(dataB) < Geometry.smallMetricDistance; }
-    /** boolean test for small `dataA.distanceXY (dataB)`  within `smallMetricDistance` */
-    static isSamePoint2d(dataA, dataB) { return dataA.distance(dataB) < Geometry.smallMetricDistance; }
-    /** boolean test for small `dataA.distanceXY (dataB)`  within `smallMetricDistance` */
-    static isSameVector2d(dataA, dataB) { return dataA.distance(dataB) < Geometry.smallMetricDistance; }
-    /**
-     * Lexical comparison of (a.x,a.y) (b.x,b.y) with x as first test, y second.
+        return d <= tolerance;
+    }
+    /**
+     * Boolean test for squared metric coordinate near-equality (i.e., if `sqrt(x)` and `sqrt(y)` are
+     * almost equal) using `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     */
+    static isSameCoordinateSquared(x, y, tolerance = Geometry.smallMetricDistance) {
+        return Math.abs(Math.sqrt(x) - Math.sqrt(y)) <= tolerance;
+    }
+    /**
+     * Boolean test for small `dataA.distance(dataB)` within `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     */
+    static isSamePoint3d(dataA, dataB, tolerance = Geometry.smallMetricDistance) {
+        return dataA.distance(dataB) <= tolerance;
+    }
+    /**
+     * Boolean test for small xyz-distance within `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     * * Note that Point3d and Vector3d are both derived from XYZ, so this method tolerates mixed types.
+     */
+    static isSameXYZ(dataA, dataB, tolerance = Geometry.smallMetricDistance) {
+        return dataA.distance(dataB) <= tolerance;
+    }
+    /**
+     * Boolean test for small xy-distance (ignoring z) within `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     */
+    static isSamePoint3dXY(dataA, dataB, tolerance = Geometry.smallMetricDistance) {
+        return dataA.distanceXY(dataB) <= tolerance;
+    }
+    /**
+     * Boolean test for small xyz-distance within `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     */
+    static isSameVector3d(dataA, dataB, tolerance = Geometry.smallMetricDistance) {
+        return dataA.distance(dataB) <= tolerance;
+    }
+    /**
+     * Boolean test for small xy-distance within `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     */
+    static isSamePoint2d(dataA, dataB, tolerance = Geometry.smallMetricDistance) {
+        return dataA.distance(dataB) <= tolerance;
+    }
+    /**
+     * Boolean test for small xy-distance within `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     */
+    static isSameVector2d(dataA, dataB, tolerance = Geometry.smallMetricDistance) {
+        return dataA.distance(dataB) <= tolerance;
+    }
+    /**
+     * Lexical comparison of (a.x, a.y) and (b.x, b.y) with x as first test and y as second (z is ignored).
      * * This is appropriate for a horizontal sweep in the plane.
      */
     static lexicalXYLessThan(a, b) {
@@ -199,7 +265,7 @@ class Geometry {
         return 0;
     }
     /**
-     * Lexical comparison of (a.x,a.y) (b.x,b.y) with y as first test, x second.
+     * Lexical comparison of (a.x, a.y) and (b.x, b.y) with y as first test and x as second (z is ignored).
      * * This is appropriate for a vertical sweep in the plane.
      */
     static lexicalYXLessThan(a, b) {
@@ -213,9 +279,7 @@ class Geometry {
             return 1;
         return 0;
     }
-    /**
-     * Lexical test, based on x first, y second, z third.
-     */
+    /** Lexical comparison of (a.x, a.y, a.z) and (b.x, b.y, b.z) with x as first test, y as second, and z as third. */
     static lexicalXYZLessThan(a, b) {
         if (a.x < b.x)
             return -1;
@@ -231,19 +295,21 @@ class Geometry {
             return 1;
         return 0;
     }
-    /** Test if `value` is small compared to `smallAngleRadians`.
+    /**
+     * Test if `value` is small compared to `smallFraction`.
      * * This is appropriate if `value` is know to be a typical 0..1 fraction.
      */
     static isSmallRelative(value) {
-        return Math.abs(value) < Geometry.smallAngleRadians;
+        return Math.abs(value) < Geometry.smallFraction;
     }
     /** Test if `value` is small compared to `smallAngleRadians` */
     static isSmallAngleRadians(value) {
         return Math.abs(value) < Geometry.smallAngleRadians;
     }
-    /** Returns true if both values are undefined or if both are defined and almost equal within tolerance.
-     * If one is undefined and the other is not then false is returned.
-    */
+    /**
+     * Returns `true` if both values are `undefined` or if both are defined and almost equal within tolerance.
+     * If one is `undefined` and the other is not, then `false` is returned.
+     */
     static isAlmostEqualOptional(a, b, tolerance) {
         if (a !== undefined && b !== undefined) {
             if (Math.abs(a - b) > tolerance)
@@ -255,44 +321,43 @@ class Geometry {
         }
         return true;
     }
-    /** Toleranced equality test, using tolerance `smallAngleRadians * ( 1 + abs(a) + (abs(b)))`
-     * * Effectively an absolute tolerance of `smallAngleRadians`, with tolerance increasing for larger values of a and b.
-    */
-    static isAlmostEqualNumber(a, b) {
+    /**
+     * Toleranced equality test using tolerance `tolerance * ( 1 + abs(a) + abs(b) )`.
+     * * `Geometry.smallAngleRadians` is used if tolerance is `undefined`.
+     */
+    static isAlmostEqualNumber(a, b, tolerance = Geometry.smallAngleRadians) {
         const sumAbs = 1.0 + Math.abs(a) + Math.abs(b);
-        return Math.abs(a - b) <= Geometry.smallAngleRadians * sumAbs;
+        return Math.abs(a - b) <= tolerance * sumAbs;
     }
-    /** Toleranced equality test, using tolerance `smallAngleRadians * ( 1 + abs(a) + (abs(b)))`
-     * * Effectively an absolute tolerance of `smallAngleRadians`, with tolerance increasing for larger values of a and b.
-    */
-    static isAlmostEqualXAndY(a, b) {
-        const sumAbs = 1.0 + Math.abs(a.x) + Math.abs(b.x) + Math.abs(a.y) + Math.abs(b.y);
-        const tolerance = Geometry.smallAngleRadians * sumAbs;
-        return Math.abs(a.x - b.x) <= tolerance && Math.abs(a.y - b.y) <= tolerance;
+    /**
+     * Toleranced equality test using tolerance `tolerance * ( 1 + abs(a.x) + abs(a.y) + abs(b.x) + abs(b.y) )`.
+     * * `Geometry.smallAngleRadians` is used if tolerance is `undefined`.
+     */
+    static isAlmostEqualXAndY(a, b, tolerance = Geometry.smallAngleRadians) {
+        const tol = tolerance * (1.0 + Math.abs(a.x) + Math.abs(b.x) + Math.abs(a.y) + Math.abs(b.y));
+        return (Math.abs(a.x - b.x) <= tol) && (Math.abs(a.y - b.y) <= tol);
     }
     /**
-     * Toleranced equality test, using caller-supplied tolerance.
-     * If no tolerance is given, use smallMetricDistance.
+     * Toleranced equality test using caller-supplied `tolerance`.
+     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
      */
-    static isDistanceWithinTol(distance, tol) {
-        if (tol !== undefined)
-            return Math.abs(distance) <= Math.abs(tol);
-        return Math.abs(distance) <= Geometry.smallMetricDistance;
+    static isDistanceWithinTol(distance, tolerance = Geometry.smallMetricDistance) {
+        return Math.abs(distance) <= tolerance;
     }
-    /** Toleranced equality test, using `smallMetricDistance` tolerance. */
+    /** Toleranced equality test using `smallMetricDistance` tolerance. */
     static isSmallMetricDistance(distance) {
         return Math.abs(distance) <= Geometry.smallMetricDistance;
     }
-    /** Toleranced equality, using `smallMetricDistanceSquared` tolerance. */
+    /** Toleranced equality test using `smallMetricDistanceSquared` tolerance. */
     static isSmallMetricDistanceSquared(distanceSquared) {
         return Math.abs(distanceSquared) <= Geometry.smallMetricDistanceSquared;
     }
     /**
      * Return `axis modulo 3` with proper handling of negative indices
      * ..., -3:x, -2:y, -1:z, 0:x, 1:y, 2:z, 3:x, 4:y, 5:z, 6:x, 7:y, 8:z, ...
-     *  */
+     */
     static cyclic3dAxis(axis) {
-        /* Direct test for the most common cases, avoid modulo */
+        /* Direct test for the most common cases to avoid more expensive modulo operation */
         if (axis >= 0) {
             if (axis < 3)
                 return axis;
@@ -305,7 +370,8 @@ class Geometry {
             return j;
         return 2 - ((-axis - 1) % 3);
     }
-    /** Return the AxisOrder for which axisIndex is the first named axis.
+    /**
+     * Return the `AxisOrder` for which `axisIndex` is the first named axis.
      * * `axisIndex === 0` returns `AxisOrder.XYZ`
      * * `axisIndex === 1` returns `AxisOrder.YZX`
      * * `axisIndex === 2` returns `AxisOrder.ZXY`
@@ -319,32 +385,55 @@ class Geometry {
             return AxisOrder.ZXY;
         return Geometry.axisIndexToRightHandedAxisOrder(Geometry.cyclic3dAxis(axisIndex));
     }
-    /** Return the largest absolute distance from a to either of b0 or b1 */
-    static maxAbsDiff(a, b0, b1) {
-        return Math.max(Math.abs(a - b0), Math.abs(a - b1));
+    /** Return the largest signed value among `a`, `b`, and `c` */
+    static maxXYZ(a, b, c) {
+        let max = a;
+        if (b > max)
+            max = b;
+        if (c > max)
+            max = c;
+        return max;
+    }
+    /** Return the smallest signed value among `a`, `b`, and `c` */
+    static minXYZ(a, b, c) {
+        let min = a;
+        if (b < min)
+            min = b;
+        if (c < min)
+            min = c;
+        return min;
+    }
+    /** Return the largest signed value among `a` and `b` */
+    static maxXY(a, b) {
+        let max = a;
+        if (b > max)
+            max = b;
+        return max;
     }
-    /** Return the largest absolute absolute value among x,y,z */
+    /** Return the smallest signed value among `a` and `b` */
+    static minXY(a, b) {
+        let min = a;
+        if (b < min)
+            min = b;
+        return min;
+    }
+    /** Return the largest absolute value among `x`, `y`, and `z` */
     static maxAbsXYZ(x, y, z) {
         return Geometry.maxXYZ(Math.abs(x), Math.abs(y), Math.abs(z));
     }
-    /** Return the largest absolute absolute value among x,y */
+    /** Return the largest absolute value among `x` and `y` */
     static maxAbsXY(x, y) {
         return Geometry.maxXY(Math.abs(x), Math.abs(y));
     }
-    /** Return the largest signed value among a, b, c */
-    static maxXYZ(a, b, c) {
-        let q = a;
-        if (b > q)
-            q = b;
-        if (c > q)
-            q = c;
-        return q;
+    /** Return the largest absolute distance from `a` to either of `b0` or `b1` */
+    static maxAbsDiff(a, b0, b1) {
+        return Math.max(Math.abs(a - b0), Math.abs(a - b1));
     }
     /**
-     * Examine the value (particularly sign) of x.
-     * * If x is negative, return outNegative.
-     * * If x is true zero, return outZero
-     * * If x is positive, return outPositive
+     * Examine the sign of `x`.
+     * * If `x` is negative, return `outNegative`
+     * * If `x` is true zero, return `outZero`
+     * * If `x` is positive, return `outPositive`
      */
     static split3WaySign(x, outNegative, outZero, outPositive) {
         if (x < 0)
@@ -366,45 +455,40 @@ class Geometry {
             return -1;
         return 0;
     }
-    /** Return the largest signed value among a, b */
-    static maxXY(a, b) {
-        let q = a;
-        if (b > q)
-            q = b;
-        return q;
-    }
-    /** Return the smallest signed value among a, b */
-    static minXY(a, b) {
-        let q = a;
-        if (b < q)
-            q = b;
-        return q;
+    /** Return the square of x */
+    static square(x) {
+        return x * x;
     }
-    /** Return the hypotenuse `sqrt(x*x + y*y)`. This is much faster than `Math.hypot(x,y)`. */
+    /**
+     * Return the hypotenuse (i.e., `sqrt(x*x + y*y)`).
+     * * This is much faster than `Math.hypot(x,y)`.
+     */
     static hypotenuseXY(x, y) {
         return Math.sqrt(x * x + y * y);
     }
-    /** Return the squared `hypotenuse (x*x + y*y)`. */
+    /** Return the squared hypotenuse (i.e., `x*x + y*y`). */
     static hypotenuseSquaredXY(x, y) {
         return x * x + y * y;
     }
-    /** Return the square of x */
-    static square(x) {
-        return x * x;
-    }
-    /** Return the hypotenuse `sqrt(x*x + y*y + z*z)`. This is much faster than `Math.hypot(x,y,z)`. */
+    /**
+     * Return the hypotenuse (i.e., `sqrt(x*x + y*y + z*z)`).
+     * * This is much faster than `Math.hypot(x,y,z)`.
+     */
     static hypotenuseXYZ(x, y, z) {
         return Math.sqrt(x * x + y * y + z * z);
     }
-    /** Return the squared hypotenuse `(x*x + y*y + z*z)`. This is much faster than `Math.hypot(x,y,z)`. */
+    /** Return the squared hypotenuse (i.e., `x*x + y*y + z*z`). */
     static hypotenuseSquaredXYZ(x, y, z) {
         return x * x + y * y + z * z;
     }
-    /** Return the (full 4d) hypotenuse `sqrt(x*x + y*y + z*z + w*w)`. This is much faster than `Math.hypot(x,y,z,w)`. */
+    /**
+     * Return the full 4d hypotenuse (i.e., `sqrt(x*x + y*y + z*z + w*w)`).
+     * * This is much faster than `Math.hypot(x,y,z,w)`.
+     */
     static hypotenuseXYZW(x, y, z, w) {
         return Math.sqrt(x * x + y * y + z * z + w * w);
     }
-    /** Return the squared hypotenuse `(x*x + y*y + z*z+w*w)`. This is much faster than `Math.hypot(x,y,z)`. */
+    /** Return the squared hypotenuse (i.e., `x*x + y*y + z*z + w*w`). */
     static hypotenuseSquaredXYZW(x, y, z, w) {
         return x * x + y * y + z * z + w * w;
     }
@@ -430,8 +514,8 @@ class Geometry {
     static distanceXYZXYZ(x0, y0, z0, x1, y1, z1) {
         return Geometry.hypotenuseXYZ(x1 - x0, y1 - y0, z1 - z0);
     }
-    /** Returns Returns the triple product of 3 vectors provided as x,y,z number sequences.
-     *
+    /**
+     * Returns the triple product of 3 vectors provided as x,y,z number sequences.
      * * The triple product is the determinant of the 3x3 matrix with the 9 numbers (3 vectors placed in 3 rows).
      * * The triple product is positive if the 3 vectors form a right handed coordinate system.
      * * The triple product is negative if the 3 vectors form a left handed coordinate system.
@@ -439,170 +523,196 @@ class Geometry {
      *     * U dot (V cross W)
      *     * V dot (W cross U)
      *     * W dot (U cross V)
-     *     * (-U dot (W cross V))  -- (note the negative -- reversing cross product order changes the sign)
-     *     * (-V dot (U cross W)) -- (note the negative -- reversing cross product order changes the sign)
-     *     * (-W dot (V cross U)) -- (note the negative -- reversing cross product order changes the sign)
-     * * the triple product is 6 times the (signed) volume of the tetrahedron with the three vectors as edges from a common vertex.
+     *     * -U dot (W cross V)
+     *     * -V dot (U cross W)
+     *     * -W dot (V cross U)
+     * * Note the negative in the last 3 formulas. Reversing cross product order changes the sign.
+     * * The triple product is 6 times the (signed) volume of the tetrahedron with the three vectors as edges from a
+     * common vertex.
      */
     static tripleProduct(ux, uy, uz, vx, vy, vz, wx, wy, wz) {
         return ux * (vy * wz - vz * wy)
             + uy * (vz * wx - vx * wz)
             + uz * (vx * wy - vy * wx);
     }
-    /** Returns the determinant of the 4x4 matrix unrolled as the 16 parameters.
-     */
+    /** Returns the determinant of the 4x4 matrix unrolled as the 16 parameters */
     static determinant4x4(xx, xy, xz, xw, yx, yy, yz, yw, zx, zy, zz, zw, wx, wy, wz, ww) {
         return xx * this.tripleProduct(yy, yz, yw, zy, zz, zw, wy, wz, ww)
             - yx * this.tripleProduct(xy, xz, xw, zy, zz, zw, wy, wz, ww)
             + zx * this.tripleProduct(xy, xz, xw, yy, yz, yw, wy, wz, ww)
             - wx * this.tripleProduct(xy, xz, xw, yy, yz, yw, zy, zz, zw);
     }
-    /** Return the mean curvature for two radii, with 0 radius implying 0 curvature */
-    static meanCurvatureOfRadii(r0, r1) {
-        return 0.5 * (this.safeDivideFraction(1, r0, 0) + this.safeDivideFraction(1, r1, 0));
-    }
     /**
-   * Returns curvature magnitude from a first and second derivative vector.
-   * @param ux  first derivative x component
-   * @param uy first derivative y component
-   * @param uz first derivative z component
-   * @param vx second derivative x component
-   * @param vy second derivative y component
-   * @param vz second derivative z component
-   */
-    static curvatureMagnitude(ux, uy, uz, vx, vy, vz) {
-        let q = uy * vz - uz * vy;
-        let sum = q * q;
-        q = uz * vx - ux * vz;
-        sum += q * q;
-        q = ux * vy - uy * vx;
-        sum += q * q;
-        const a = Math.sqrt(ux * ux + uy * uy + uz * uz);
-        const b = Math.sqrt(sum);
-        // (sum and a are both nonnegative)
-        const aaa = a * a * a;
-        // radius of curvature = aaa / b;
-        // curvature = b/aaa
-        const tol = Geometry.smallAngleRadians;
-        if (aaa > tol * b)
-            return b / aaa;
-        return 0; // hm.. maybe should be infinite?
-    }
-    /** Returns the determinant of 3x3 matrix with x and y rows taken from 3 points, third row from corresponding numbers.
-     *
+     * Returns the determinant of 3x3 matrix with first and second rows created from the 3 xy points and the third
+     * row created from the 3 numbers:
+     *      [columnA.x   columnB.x   columnC.x]
+     *      [columnA.y   columnB.y   columnC.y]
+     *      [ weightA     weightB     weightC ]
      */
     static tripleProductXYW(columnA, weightA, columnB, weightB, columnC, weightC) {
         return Geometry.tripleProduct(columnA.x, columnB.x, columnC.x, columnA.y, columnB.y, columnC.y, weightA, weightB, weightC);
     }
-    /** Returns the determinant of 3x3 matrix with x and y rows taken from 3 points, third row from corresponding numbers.
-     *
+    /**
+     * Returns the determinant of 3x3 matrix columns created by the given `Point4d` ignoring the z part:
+     *      [columnA.x   columnB.x   columnC.x]
+     *      [columnA.y   columnB.y   columnC.y]
+     *      [columnA.w   columnB.w   columnC.w]
      */
     static tripleProductPoint4dXYW(columnA, columnB, columnC) {
         return Geometry.tripleProduct(columnA.x, columnB.x, columnC.x, columnA.y, columnB.y, columnC.y, columnA.w, columnB.w, columnC.w);
     }
-    /** 2D cross product of vectors layed out as scalars. */
+    /** 2D cross product of vectors with the vectors presented as numbers. */
     static crossProductXYXY(ux, uy, vx, vy) {
         return ux * vy - uy * vx;
     }
-    /** 3D cross product of vectors layed out as scalars. */
+    /** 3D cross product of vectors with the vectors presented as numbers. */
     static crossProductXYZXYZ(ux, uy, uz, vx, vy, vz, result) {
         return Vector3d.create(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx, result);
     }
-    /** magnitude of 3D cross product of vectors, with the vectors presented as */
+    /** Magnitude of 3D cross product of vectors with the vectors presented as numbers. */
     static crossProductMagnitude(ux, uy, uz, vx, vy, vz) {
         return Geometry.hypotenuseXYZ(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx);
     }
-    /** 3D dot product of vectors layed out as scalars. */
+    /** 2D dot product of vectors with the vectors presented as numbers. */
+    static dotProductXYXY(ux, uy, vx, vy) {
+        return ux * vx + uy * vy;
+    }
+    /** 3D dot product of vectors with the vectors presented as numbers. */
     static dotProductXYZXYZ(ux, uy, uz, vx, vy, vz) {
         return ux * vx + uy * vy + uz * vz;
     }
-    /** 2D dot product of vectors layed out as scalars. */
-    static dotProductXYXY(ux, uy, vx, vy) {
-        return ux * vx + uy * vy;
+    /**
+     * Return the mean curvature for two radii.
+     * * Curvature is the reciprocal of radius.
+     * * 0 radius implies 0 curvature.
+     * @param r0 first radius
+     * @param r1 second radius
+     */
+    static meanCurvatureOfRadii(r0, r1) {
+        return 0.5 * (this.safeDivideFraction(1, r0, 0) + this.safeDivideFraction(1, r1, 0));
     }
     /**
-     * Clamp to (min(a,b), max(a,b))
-     * * always returns a number between a and b
-     * @param x
-     * @param a
-     * @param b
+     * Returns curvature from the first and second derivative vectors.
+     * * If U is the first derivative and V is the second derivative, the curvature is defined as:
+     *     * `|| U x V || / || U ||^3`.
+     * * Math details can be found at https://en.wikipedia.org/wiki/Curvature#General_expressions
+     * @param ux first derivative x component
+     * @param uy first derivative y component
+     * @param uz first derivative z component
+     * @param vx second derivative x component
+     * @param vy second derivative y component
+     * @param vz second derivative z component
+     */
+    static curvatureMagnitude(ux, uy, uz, vx, vy, vz) {
+        let q = uy * vz - uz * vy;
+        let sum = q * q;
+        q = uz * vx - ux * vz;
+        sum += q * q;
+        q = ux * vy - uy * vx;
+        sum += q * q;
+        const magUxV = Math.sqrt(sum);
+        const magU = Math.sqrt(ux * ux + uy * uy + uz * uz);
+        const magUCubed = magU * magU * magU;
+        if (magUCubed > Geometry.smallAngleRadians * magUxV)
+            return magUxV / magUCubed;
+        return 0;
+    }
+    /**
+     * Clamp to (min(a,b), max(a,b)).
+     * * Always returns a number between `a` and `b`.
+     * @param value value to clamp
+     * @param a smallest allowed output if `a < b` or largest allowed output if `a > b`
+     * @param b largest allowed output if `a < b` or smallest allowed output if `a > b`
      */
-    static clampToStartEnd(x, a, b) {
+    static clampToStartEnd(value, a, b) {
         if (a > b)
-            return Geometry.clampToStartEnd(x, b, a);
-        if (x < a)
+            return Geometry.clampToStartEnd(value, b, a);
+        if (value < a)
             return a;
-        if (b < x)
+        if (b < value)
             return b;
-        return x;
+        return value;
     }
     /**
-     * Clamp value to (min,max) with no test for order of (min,max)
+     * Clamp value to (min, max) with no test for order of (min, max).
+     * * Always returns a number between `min` and `max`.
      * @param value value to clamp
      * @param min smallest allowed output
-     * @param max largest allowed result.
+     * @param max largest allowed output
      */
-    static clamp(value, min, max) { return Math.max(min, Math.min(max, value)); }
-    /** If given a number, return it.   If given undefined, return `defaultValue`. */
+    static clamp(value, min, max) {
+        return Math.max(min, Math.min(max, value));
+    }
+    /** If given a `value`, return it. If given `undefined`, return `defaultValue`. */
     static resolveNumber(value, defaultValue = 0) {
         return value !== undefined ? value : defaultValue;
     }
-    /** If given a value, return it.   If given undefined, return `defaultValue`. */
+    /** If given a `value`, return it. If given `undefined`, return `defaultValue`. */
     static resolveValue(value, defaultValue) {
         return value !== undefined ? value : defaultValue;
     }
-    /** If given value matches a target, return undefined.   Otherwise return the value. */
+    /** If given `value` matches the `targetValue`, return `undefined`. Otherwise return the `value`. */
     static resolveToUndefined(value, targetValue) {
         return value === targetValue ? undefined : value;
     }
     /**
-     * Simple interpolation between values, but choosing (based on fraction) a or b as starting
-     * point for maximum accuracy.
+     * Simple interpolation between values `a` and `b` with fraction `f`.
      * * If `f = 0`, then `a` is returned and if `f = 1`, then `b` is returned.
+     * * For maximum accuracy, we choose `a` or `b` as starting point based on fraction `f`.
      */
     static interpolate(a, f, b) {
         return f <= 0.5 ? a + f * (b - a) : b - (1.0 - f) * (b - a);
     }
     /**
-     * Given an axisOrder (e.g. XYZ, YZX, etc) and an index, returns the axis index at the given index.
-     * * For example, if axisOrder = XYZ, then for index 0 returns X (or axis index 0), for index 1 returns
-     * Y (or axis index 1), and for index 2 returns Z (or axis index 2). For indexes greater than 2 or smaller
-     * than 0, it returns cyclic axis index. See Geometry.cyclic3dAxis for more info.
-     * * Another example: if axisOrder = ZYX, then for index 0 returns Z (or axis index 2), for index 1 returns
-     * Y (or axis index 1), and for index 2 returns X (or axis index 0).
-     * */
+     * Given an `axisOrder` (e.g. XYZ, YZX, etc) and an `index`, return the `axis` at the given index.
+     * * For example, if `axisOrder = XYZ`, then for index 0 return `X` (or axis 0), for index 1 return
+     * `Y` (or axis 1), and for index 2 return `Z` (or axis 2).
+     * * Another example: if `axisOrder = ZXY`, then for index 0 return `Z` (or axis 2), for index 1 return
+     * `X` (or axis 0), and for index 2 return `Y` (or axis 1).
+     * * For indexes greater than 2 or smaller than 0, it return cyclic axis. See [[Geometry.cyclic3dAxis]]
+     * for more info.
+     */
     static axisOrderToAxis(order, index) {
         const axis = order <= AxisOrder.ZXY ? order + index : (order - AxisOrder.XZY) - index;
         return Geometry.cyclic3dAxis(axis);
     }
-    /** Return (a modulo period), e.g. for use as a cyclic index.  Both a and period may be negative. */
+    /**
+     * Return `a` modulo `period`.
+     * * Both `a` and `period` can be negative.
+     * * This function can be faster than the `%` operator for the common case when `p > 0` and `-p < a < 2p`.
+     */
     static modulo(a, period) {
+        // period is negative
         if (period <= 0) {
             if (period === 0)
                 return a;
             return -Geometry.modulo(-a, -period);
         }
+        // period is positive
         if (a >= 0) {
-            if (a < period)
+            if (a < period) // "0 < a < period"
                 return a;
-            if (a < 2 * period)
+            if (a < 2 * period) // "0 < period < a < 2*period"
                 return a - period;
         }
-        else {
-            a += period; // hopefully move into primary period without division and floor
+        else { // "-period < a < 0"
+            a += period;
             if (a > 0)
                 return a;
         }
+        // "0 < 2*period < a" or "a < -period < 0"
         const m = Math.floor(a / period);
         return a - m * period;
     }
-    /** return 0 if the value is undefined, 1 if defined. */
-    static defined01(value) { return value === undefined ? 0 : 1; }
+    /** Return 0 if the value is `undefined` and 1 if the value is defined. */
+    static defined01(value) {
+        return value === undefined ? 0 : 1;
+    }
     /**
-     * Return `numerator` divided by `denominator`, or `undefined`.
+     * Return `numerator` divided by `denominator`.
      * @param numerator the numerator
      * @param denominator the denominator
-     * @returns return `numerator/denominator` but if the ratio would exceed `Geometry.largeFractionResult`,
+     * @returns return `numerator/denominator` but if the ratio exceeds `Geometry.largeFractionResult`,
      * return `undefined`.
      */
     static conditionalDivideFraction(numerator, denominator) {
@@ -614,76 +724,105 @@ class Geometry {
      * Return `numerator` divided by `denominator`.
      * @param numerator the numerator
      * @param denominator the denominator
-     * @returns return `numerator/denominator` but if the ratio would exceed `Geometry.largeFractionResult`,
+     * @returns return `numerator/denominator` but if the ratio exceeds `Geometry.largeFractionResult`,
      * return `defaultResult`.
      */
     static safeDivideFraction(numerator, denominator, defaultResult) {
-        const a = Geometry.conditionalDivideFraction(numerator, denominator);
-        if (a !== undefined)
-            return a;
+        const ratio = Geometry.conditionalDivideFraction(numerator, denominator);
+        if (ratio !== undefined)
+            return ratio;
         return defaultResult;
     }
     /**
-     * Return `numerator` divided by `denominator` (with a given `largestResult`), or `undefined`.
+     * Return `numerator` divided by `denominator` (with a given `largestResult`).
      * @param numerator the numerator
      * @param denominator the denominator
-     * @param largestResult the ratio threshold.
-     * @returns return `numerator/denominator` but if the ratio would exceed `largestResult`, return `undefined`.
+     * @param largestResult the ratio threshold
+     * @returns return `numerator/denominator` but if the ratio exceeds `largestResult`, return `undefined`.
      */
     static conditionalDivideCoordinate(numerator, denominator, largestResult = Geometry.largeCoordinateResult) {
         if (Math.abs(denominator * largestResult) > Math.abs(numerator))
             return numerator / denominator;
         return undefined;
     }
-    /** return the 0, 1, or 2 pairs of (c,s) values that solve
-     * {constCoff + cosCoff * c + sinCoff * s = 0}
-     * with the constraint {c*c+s*s = 1}
+    /**
+     * Return solution(s) of equation `constCoff + cosCoff*c + sinCoff*s = 0` for `c` and `s` with the
+     * constraint `c*c + s*s = 1`.
+     * * There could be 0, 1, or 2 solutions. Return `undefined` if there is no solution.
      */
     static solveTrigForm(constCoff, cosCoff, sinCoff) {
-        {
-            const delta2 = cosCoff * cosCoff + sinCoff * sinCoff;
-            const constCoff2 = constCoff * constCoff;
-            // nSolution = 0
-            let result;
-            if (delta2 > 0.0) {
-                const lambda = -constCoff / delta2;
-                const a2 = constCoff2 / delta2;
-                const D2 = 1.0 - a2;
-                if (-Geometry.smallMetricDistanceSquared < D2 && D2 <= 0.0) { // observed D2 = -2.22e-16 in rotated system
-                    // nSolution = 1
-                    const c0 = lambda * cosCoff;
-                    const s0 = lambda * sinCoff;
-                    result = [Vector2d.create(c0, s0)];
-                }
-                else if (D2 > 0.0) {
-                    const mu = Math.sqrt(D2 / delta2);
-                    /* c0,s0 = closest approach of line to origin */
-                    const c0 = lambda * cosCoff;
-                    const s0 = lambda * sinCoff;
-                    // nSolution = 2
-                    result = [Vector2d.create(c0 - mu * sinCoff, s0 + mu * cosCoff), Vector2d.create(c0 + mu * sinCoff, s0 - mu * cosCoff)];
-                }
+        /**
+         * Solutions can be found by finding the intersection of line "ax + by + d = 0" and unit circle "x^2 + y^2 = 1".
+         * From the line equation we have "y = (-ax - d) / b". By replacing this into the circle equation we get
+         * "x^2 + (ax+d)^2/b^2 = 1". If we solve this by quadratic formula we get
+         *      x = (-ad +- b*sqrt(a^2+b^2-d^2)) / (a^2+b^2)
+         *      y = (-ad -+ a*sqrt(a^2+b^2-d^2)) / (a^2+b^2)
+         *
+         * If "a^2+b^2-d^2 > 0" then there are two solutions (above).
+         * If "a^2+b^2-d^2 = 0" then there is one solution which is (-ad/(a^2+b^2), -bd/(a^2+b^2)).
+         * If "a^2+b^2-d^2 < 0" then there is no solution.
+         *
+         * Below in the code we have "a = cosCoff", "b = sinCoff", and "d = constCoff". Also equivalent criterion
+         * is used in the code. For example, "a^2+b^2-d^2 > 0" is equivalent of "1 - d^2/(a^2+b^2) > 0".
+         */
+        const a2b2 = cosCoff * cosCoff + sinCoff * sinCoff; // a^2+b^2
+        const d2 = constCoff * constCoff; // d^2
+        let result;
+        if (a2b2 > 0.0) {
+            const a2b2r = 1.0 / a2b2; // 1/(a^2+b^2)
+            const d2a2b2 = d2 * a2b2r; // d^2/(a^2+b^2)
+            const criteria = 1.0 - d2a2b2; // 1 - d^2/(a^2+b^2); the criteria to specify how many solutions we got
+            if (criteria < -Geometry.smallMetricDistanceSquared) // nSolution = 0
+                return result;
+            const da2b2 = -constCoff * a2b2r; // -d/(a^2+b^2)
+            const c0 = da2b2 * cosCoff; // -ad/(a^2+b^2)
+            const s0 = da2b2 * sinCoff; // -bd/(a^2+b^2)
+            if (criteria <= 0.0) { // nSolution = 1 (observed criteria = -2.22e-16 in rotated system)
+                result = [Vector2d.create(c0, s0)];
+            }
+            else if (criteria > 0.0) { // nSolution = 2
+                const s = Math.sqrt(criteria * a2b2r); // sqrt(a^2+b^2-d^2)) / (a^2+b^2)
+                result = [
+                    Vector2d.create(c0 - s * sinCoff, s0 + s * cosCoff),
+                    Vector2d.create(c0 + s * sinCoff, s0 - s * cosCoff),
+                ];
             }
-            return result;
         }
+        return result;
     }
-    /** For a line f(x) whose function values at x0 and x1 are f0 and f1, return the x value at which f(x)=fTarget; */
-    static inverseInterpolate(x0, f0, x1, f1, targetF = 0, defaultResult) {
-        const g = Geometry.conditionalDivideFraction(targetF - f0, f1 - f0);
-        if (g)
-            return Geometry.interpolate(x0, g, x1);
+    /**
+     * For a line `f(x)` where `f(x0) = f0` and `f(x1) = f1`, return the `x` value at which `f(x) = fTarget`
+     * Return `defaultResult` if `(fTarget - f0) / (f1 - f0)` exceeds `Geometry.largeFractionResult`
+     */
+    static inverseInterpolate(x0, f0, x1, f1, fTarget = 0, defaultResult) {
+        /**
+         * Line equation is "fTarget-f0 = (f1-f0)/(x1-x0) * (x-x0)" or "(fTarget-f0)/(f1-f0) = (x-x0)/(x1-x0)".
+         * The left hand side is known so if we call it "fr" (short for "fraction") we get "fr = (x-x0)/(x1-x0)".
+         * Therefore, "x = x0*(1-fr) + x1*fr". This is same as interpolation between "x0" and "x1" with fraction "fr".
+         */
+        const fr = Geometry.conditionalDivideFraction(fTarget - f0, f1 - f0); // (fTarget-f0)/(f1-f0)
+        if (fr !== undefined)
+            return Geometry.interpolate(x0, fr, x1); // x = x0*(1-fr) + x1*fr
         return defaultResult;
     }
-    /** For a line f(x) whose function values at x=0 and x=1 are f0 and f1, return the x value at which f(x)=fTarget; */
-    static inverseInterpolate01(f0, f1, targetF = 0) {
-        return Geometry.conditionalDivideFraction(targetF - f0, f1 - f0);
+    /**
+     * For a line `f(x)` where `f(0) = f0` and `f(1) = f1`, return the `x` value at which `f(x) = fTarget`
+     * Return `undefined` if `(fTarget - f0) / (f1 - f0)` exceeds `Geometry.largeFractionResult`
+     */
+    static inverseInterpolate01(f0, f1, fTarget = 0) {
+        /**
+         * Line equation is "fTarget-f0 = (f1-f0)*x" so "x = (fTarget-f0)/(f1-f0)"
+         */
+        return Geometry.conditionalDivideFraction(fTarget - f0, f1 - f0); // x = (fTarget-f0)/(f1-f0)
     }
-    /** Return true if json is an array with at least minEntries, and all entries are numbers (including those beyond minEntries) */
+    /**
+     * Return `true` if `json` is an array with at least `minEntries` entries and all entries are numbers (including
+     * those beyond minEntries).
+     */
     static isNumberArray(json, minEntries = 0) {
         if (Array.isArray(json) && json.length >= minEntries) {
             let entry;
             for (entry of json) {
-                //        if (!(entry as number) && entry !== 0.0)
                 if (!Number.isFinite(entry))
                     return false;
             }
@@ -691,10 +830,12 @@ class Geometry {
         }
         return false;
     }
-    /** Return true if json is an array of at least numNumberArrays, with at least minEntries in each number array.
+    /**
+     * Return `true` if `json` is an array of at least `minArrays` arrays with at least `minEntries` entries in
+     * each array and all entries are numbers (including those beyond minEntries).
      */
-    static isArrayOfNumberArray(json, numNumberArray, minEntries = 0) {
-        if (Array.isArray(json) && json.length >= numNumberArray) {
+    static isArrayOfNumberArray(json, minArrays, minEntries = 0) {
+        if (Array.isArray(json) && json.length >= minArrays) {
             let entry;
             for (entry of json)
                 if (!Geometry.isNumberArray(entry, minEntries))
@@ -703,36 +844,53 @@ class Geometry {
         }
         return false;
     }
-    /** return the number of steps to take so that numSteps * stepSize >= total.
-     * minCount is returned for both (a) setSize 0 or less and (b) stepSize > total.
-     * A small tolerance is applied for almost
-    */
+    /**
+     * Return the number of steps to take so that `numSteps * stepSize >= total`.
+     * * `minCount` is returned in the following 3 cases:
+     *   * (a) `stepSize <= 0`
+     *   * (b) `stepSize >= total`
+     *   * (b) `numSteps < minCount`
+     * * `maxCount` is returned if `numSteps > maxCount`.
+     */
     static stepCount(stepSize, total, minCount = 1, maxCount = 101) {
         if (stepSize <= 0)
             return minCount;
         total = Math.abs(total);
         if (stepSize >= total)
             return minCount;
-        const stepCount = Math.floor((total + 0.999999 * stepSize) / stepSize);
-        if (stepCount < minCount)
+        /**
+         * 0.999999 is multiplied so we return the same "numSteps" if
+         * stepSize*(numSteps-1) < total <= stepSize*numSteps.
+         * For example, if "stepSize = 2" then we return "numSteps = 5" if 8 < total <= 10.
+         */
+        const numSteps = Math.floor((total + 0.999999 * stepSize) / stepSize);
+        if (numSteps < minCount)
             return minCount;
-        if (stepCount > maxCount)
+        if (numSteps > maxCount)
             return maxCount;
-        return stepCount;
+        return numSteps;
     }
-    /** Test if x is in simple 0..1 interval.  But optionally skip the test.  (this odd behavior is very convenient for code that sometimes does not do the filtering.)
+    /**
+     * Test if `x` is in the interval [0,1] (but skip the test if `apply01 = false`).
+     * * This odd behavior is very convenient for code that sometimes does not do the filtering.
      * @param x value to test.
-     * @param apply01 if false, accept all x.
+     * @param apply01 if false, return `true` for all values of `x`.
      */
-    static isIn01(x, apply01 = true) { return apply01 ? x >= 0.0 && x <= 1.0 : true; }
-    /** Test if x is in simple 0..1 interval.  But optionally skip the test.  (this odd behavior is very convenient for code that sometimes does not do the filtering.)
+    static isIn01(x, apply01 = true) {
+        return apply01 ? x >= 0.0 && x <= 1.0 : true;
+    }
+    /**
+     * Test if `x` is in the interval [0,1] for a given positive `tolerance`.
+     * * Make sure to pass a positive `tolerance` because there is no check for that in the code.
      * @param x value to test.
-     * @param apply01 if false, accept all x.
+     * @param tolerance the tolerance.
      */
-    static isIn01WithTolerance(x, tolerance) { return x + tolerance >= 0.0 && x - tolerance <= 1.0; }
+    static isIn01WithTolerance(x, tolerance) {
+        return x + tolerance >= 0.0 && x - tolerance <= 1.0;
+    }
     /**
-     * restrict x so it is in the interval `[a,b]`, allowing a,b to be in either order.
-     * @param x
+     * Restrict x so it is in the interval `[a,b]` (allowing `a` and `b` to be in either order).
+     * @param x value to restrict
      * @param a (usually the lower) interval limit
      * @param b (usually the upper) interval limit
      */
@@ -744,7 +902,7 @@ class Geometry {
                 return b;
             return x;
         }
-        // reversed interval ....
+        // reversed interval
         if (x < b)
             return b;
         if (x > a)
@@ -753,12 +911,15 @@ class Geometry {
     }
     /**
      * Case-insensitive string comparison.
-     * * Return true if the toUpperCase values match.
+     * * Return `true` if the `toUpperCase` values of `string1` and `string2` match.
      */
     static equalStringNoCase(string1, string2) {
         return string1.toUpperCase() === string2.toUpperCase();
     }
-    /** test for EXACT match of number arrays. */
+    /**
+     * Test for exact match of two number arrays.
+     * Returns `true` if both arrays have the same length and entries, or if both arrays are empty or `undefined`.
+     */
     static exactEqualNumberArrays(a, b) {
         if (Array.isArray(a) && a.length === 0)
             a = undefined;
@@ -776,7 +937,10 @@ class Geometry {
         }
         return false;
     }
-    /** test for  match of XYZ arrays. */
+    /**
+     * Test for match of two arrays of type `T`.
+     * Returns `true` if both arrays have the same length and have the same entries (or both are empty arrays).
+     */
     static almostEqualArrays(a, b, testFunction) {
         if (Array.isArray(a) && a.length === 0)
             a = undefined;
@@ -795,7 +959,10 @@ class Geometry {
         }
         return false;
     }
-    /** test for  match of typed arrays (e.g. Float64Array). */
+    /**
+     * Test for match of two arrays of type number or Float64Array.
+     * Returns `true` if both arrays have the same length and have the same entries (or both are empty arrays).
+     */
     static almostEqualNumberArrays(a, b, testFunction) {
         if (Array.isArray(a) && a.length === 0)
             a = undefined;
@@ -815,15 +982,12 @@ class Geometry {
         return false;
     }
     /**
-     * Return
-     * * true if both values are defined and equal (with ===).
-     * * false if both defined by not equal
-     * * return (option arg) resultIfBothUndefined when both are undefined.
-     * * return false if one is defined and the other undefined
+     * Test for match of two values of type `T`.
      * @param a first value
      * @param b second value
-     * @param resultIfBothUndefined return value when both are undefined.
-     * @returns
+     * @param resultIfBothUndefined returned value when both are `undefined`
+     * @returns `true` if both values are defined and equal (with ===) and `false` if both values are defined
+     * but not equal or if one is defined and the other undefined.
      */
     static areEqualAllowUndefined(a, b, resultIfBothUndefined = true) {
         if (a === undefined && b === undefined)
@@ -832,46 +996,52 @@ class Geometry {
             return a === b;
         return false;
     }
-    /** clone an array whose members have a clone method.
-     * * undefined return from clone is forced into the output array.
-    */
-    static cloneMembers(a) {
-        if (a === undefined)
+    /**
+     * Clone an array whose members have type `T`, which implements the clone method.
+     * * If the clone method returns `undefined`, then `undefined` is forced into the cloned array.
+     */
+    static cloneMembers(array) {
+        if (array === undefined)
             return undefined;
-        const b = [];
-        for (const p of a) {
-            b.push(p.clone());
+        const clonedArray = [];
+        for (const element of array) {
+            clonedArray.push(element.clone());
         }
-        return b;
+        return clonedArray;
     }
 }
-/** Tolerance for small distances in metric coordinates */
+/** Tolerance for small distances in metric coordinates. */
 Geometry.smallMetricDistance = 1.0e-6;
-/** Square of `smallMetricTolerance` */
+/** Square of `smallMetricDistance`. */
 Geometry.smallMetricDistanceSquared = 1.0e-12;
-/** tolerance for small angle measured in radians. */
+/** Tolerance for small angle measured in radians. */
 Geometry.smallAngleRadians = 1.0e-12;
-/** square of `smallAngleRadians` */
+/** Square of `smallAngleRadians`. */
 Geometry.smallAngleRadiansSquared = 1.0e-24;
-/** tolerance for small angle measured in degrees. */
+/** Tolerance for small angle measured in degrees. */
 Geometry.smallAngleDegrees = 5.7e-11;
-/** tolerance for small angle measured in arc-seconds. */
+/** Tolerance for small angle measured in arc-seconds. */
 Geometry.smallAngleSeconds = 2e-7;
-/** numeric value that may be considered huge for a ratio of numbers.
- * * Note that the "allowed" result value is vastly larger than 1.
+/** Numeric value that may be considered zero for fractions between 0 and 1. */
+Geometry.smallFraction = 1.0e-10;
+/** Radians value for full circle 2PI radians minus `smallAngleRadians`. */
+Geometry.fullCircleRadiansMinusSmallAngle = 2.0 * Math.PI - Geometry.smallAngleRadians;
+/**
+ * Numeric value that may be considered large for a ratio of numbers.
+ * * Note that the allowed result value is vastly larger than 1.
  */
 Geometry.largeFractionResult = 1.0e10;
-/** numeric value that may be considered zero for fractions between 0 and 1. */
-Geometry.smallFraction = 1.0e-10;
-/** numeric value that may considered huge for numbers expected to be coordinates.
+/**
+ * Numeric value that may considered large for numbers expected to be coordinates.
  * * This allows larger results than `largeFractionResult`.
  */
 Geometry.largeCoordinateResult = 1.0e13;
-/** numeric value that may considered infinite for metric coordinates.
- * * This coordinate should be used only as a placeholder indicating "at infinity" -- computing actual points at this coordinate invites numerical problems.
+/**
+ * Numeric value that may considered infinite for metric coordinates.
+ * @deprecated in 4.x. Use `largeCoordinateResult`.
+ * * This coordinate should be used only as a placeholder indicating "at infinity" -- computing actual
+ * points at this coordinate invites numerical problems.
  */
 Geometry.hugeCoordinate = 1.0e12;
-/** Radians value for full circle 2PI radians minus `smallAngleRadians` */
-Geometry.fullCircleRadiansMinusSmallAngle = 2.0 * Math.PI - 1.0e-12; // smallAngleRadians less than 360degrees
 export { Geometry };
 //# sourceMappingURL=Geometry.js.map