@itwin/core-geometry 4.9.0-dev.8 → 4.10.0-dev.0

package/lib/esm/Geometry.js

@@ -112,13 +112,13 @@ export var PolygonLocation;
  * @public
  */
 export class Geometry {
-    /** Test if absolute value of x is large (larger than `Geometry.largeCoordinateResult`) */
+    /** Test if the absolute value of x is at least [[largeCoordinateResult]]. */
     static isLargeCoordinateResult(x) {
-        return x > this.largeCoordinateResult || x < -this.largeCoordinateResult;
+        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`.
+     * Test if the absolute value of x is at least [[largeCoordinateResult]].
+     * @deprecated in 4.x. Use [[isLargeCoordinateResult]].
      */
     static isHugeCoordinate(x) {
         return Geometry.isLargeCoordinateResult(x);
@@ -128,47 +128,50 @@ export class Geometry {
         return (x & (0x01)) === 1; // bitwise operation
     }
     /**
-     * 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`.
+     * Correct a small distance.
+     * @param distance metric value to test
+     * @param replacement value to return if `distance` is too small. Default is zero.
+     * @returns `distance` if it is defined and has absolute value greater than [[smallMetricDistance]];
+     * otherwise returns `replacement`
      */
     static correctSmallMetricDistance(distance, replacement = 0.0) {
-        if (distance === undefined || Math.abs(distance) < Geometry.smallMetricDistance) {
+        if (distance === undefined || Math.abs(distance) <= Geometry.smallMetricDistance) {
             return replacement;
         }
         return distance;
     }
     /**
-     * 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`
+     * Correct a small fraction.
+     * @param fraction fraction to test
+     * @param replacement value to return if `fraction` is too small. Default is zero.
+     * @returns `fraction` if it is defined and has absolute value greater than [[Geometry.smallFraction]];
+     * otherwise returns `replacement`
      */
     static correctSmallFraction(fraction, replacement = 0.0) {
-        if (fraction === undefined || Math.abs(fraction) < Geometry.smallFraction) {
+        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`.
+     * Compute the inverse of `distance`, checking for safe division.
+     * @returns `1/distance` if the absolute value of `distance` exceeds [[smallMetricDistance]];
+     * otherwise returns `undefined`.
      */
     static inverseMetricDistance(distance) {
         return (Math.abs(distance) <= Geometry.smallMetricDistance) ? undefined : 1.0 / distance;
     }
     /**
-     * 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`.
+     * Return the inverse of `distanceSquared`, checking for safe division.
+     * @returns `1/distanceSquared` if the absolute value of `distanceSquared` exceeds [[smallMetricDistanceSquared]];
+     * otherwise returns `undefined`.
      */
     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) using `tolerance`.
-     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     * * [[smallMetricDistance]] is used if tolerance is `undefined`.
      */
     static isSameCoordinate(x, y, tolerance = Geometry.smallMetricDistance) {
         let d = x - y;
@@ -186,7 +189,7 @@ export class Geometry {
     /**
      * 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`.
+     * * [[smallMetricDistance]] is used if tolerance is `undefined`.
      */
     static isSameCoordinateXY(x0, y0, x1, y1, tolerance = Geometry.smallMetricDistance) {
         let d = x1 - x0;
@@ -202,21 +205,21 @@ export class Geometry {
     /**
      * 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`.
+     * * [[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`.
+     * * [[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`.
+     * * [[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) {
@@ -224,28 +227,28 @@ export class Geometry {
     }
     /**
      * Boolean test for small xy-distance (ignoring z) within `tolerance`.
-     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     * * [[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`.
+     * * [[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`.
+     * * [[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`.
+     * * [[smallMetricDistance]] is used if tolerance is `undefined`.
      */
     static isSameVector2d(dataA, dataB, tolerance = Geometry.smallMetricDistance) {
         return dataA.distance(dataB) <= tolerance;
@@ -297,15 +300,19 @@ export class Geometry {
         return 0;
     }
     /**
-     * Test if `value` is small compared to `smallFraction`.
-     * * This is appropriate if `value` is know to be a typical 0..1 fraction.
+     * Test if `value` is at most [[smallFraction]] in absolute value.
+     * * This is appropriate if `value` is known to be a fraction.
      */
     static isSmallRelative(value) {
-        return Math.abs(value) < Geometry.smallFraction;
+        return Math.abs(value) <= Geometry.smallFraction;
     }
-    /** Test if `value` is small compared to `smallAngleRadians` */
+    /** Test if `value` is at most [[smallAngleRadians]] in absolute value. */
     static isSmallAngleRadians(value) {
-        return Math.abs(value) < Geometry.smallAngleRadians;
+        return Math.abs(value) <= Geometry.smallAngleRadians;
+    }
+    /** Test if `value` is at most [[smallAngleRadiansSquared]] in absolute value. */
+    static isSmallAngleRadiansSquared(value) {
+        return Math.abs(value) <= Geometry.smallAngleRadiansSquared;
     }
     /**
      * Returns `true` if both values are `undefined` or if both are defined and almost equal within tolerance.
@@ -323,16 +330,25 @@ export class Geometry {
         return true;
     }
     /**
-     * Toleranced equality test using tolerance `tolerance * ( 1 + abs(a) + abs(b) )`.
-     * * `Geometry.smallAngleRadians` is used if tolerance is `undefined`.
+     * Toleranced equality test.
+     * @param tolerance relative tolerance. Default value is [[smallAngleRadians]].
+     * @returns true if and only if `a` and `b` are almost equal.
      */
     static isAlmostEqualNumber(a, b, tolerance = Geometry.smallAngleRadians) {
         const sumAbs = 1.0 + Math.abs(a) + Math.abs(b);
         return Math.abs(a - b) <= tolerance * sumAbs;
     }
+    /**
+     * Toleranced test for equality to at least one of two numbers.
+     * @param tolerance relative tolerance. Default value is [[smallAngleRadians]].
+     * @returns true if and only if `a` and `b` are almost equal, or `a` and `c` are almost equal.
+     */
+    static isAlmostEqualEitherNumber(a, b, c, tolerance = Geometry.smallAngleRadians) {
+        return this.isAlmostEqualNumber(a, b, tolerance) || this.isAlmostEqualNumber(a, c, 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`.
+     * * [[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));
@@ -340,16 +356,16 @@ export class Geometry {
     }
     /**
      * Toleranced equality test using caller-supplied `tolerance`.
-     * * `Geometry.smallMetricDistance` is used if tolerance is `undefined`.
+     * * [[smallMetricDistance]] is used if tolerance is `undefined`.
      */
     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 test using `smallMetricDistanceSquared` tolerance. */
+    /** Toleranced equality test using [[smallMetricDistanceSquared]] tolerance. */
     static isSmallMetricDistanceSquared(distanceSquared) {
         return Math.abs(distanceSquared) <= Geometry.smallMetricDistanceSquared;
     }
@@ -752,11 +768,13 @@ export class Geometry {
      * Return `numerator` divided by `denominator`.
      * @param numerator the numerator
      * @param denominator the denominator
-     * @returns return `numerator/denominator` but if the ratio exceeds `Geometry.largeFractionResult`,
+     * @returns return `numerator/denominator` but if the ratio exceeds [[largeFractionResult]],
      * return `undefined`.
      */
     static conditionalDivideFraction(numerator, denominator) {
-        if (Math.abs(denominator) * Geometry.largeFractionResult > Math.abs(numerator))
+        if (0 === denominator)
+            return undefined;
+        if (Math.abs(denominator) * Geometry.largeFractionResult >= Math.abs(numerator))
             return numerator / denominator;
         return undefined;
     }
@@ -764,7 +782,7 @@ export class Geometry {
      * Return `numerator` divided by `denominator`.
      * @param numerator the numerator
      * @param denominator the denominator
-     * @returns return `numerator/denominator` but if the ratio exceeds `Geometry.largeFractionResult`,
+     * @returns return `numerator/denominator` but if the ratio exceeds [[largeFractionResult]],
      * return `defaultResult`.
      */
     static safeDivideFraction(numerator, denominator, defaultResult) {
@@ -781,7 +799,9 @@ export class Geometry {
      * @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))
+        if (0 === denominator)
+            return undefined;
+        if (Math.abs(denominator * largestResult) >= Math.abs(numerator))
             return numerator / denominator;
         return undefined;
     }
@@ -836,7 +856,7 @@ export class Geometry {
     }
     /**
      * 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`.
+     * Return `defaultResult` if `(fTarget - f0) / (f1 - f0)` exceeds [[largeFractionResult]].
      */
     static inverseInterpolate(x0, f0, x1, f1, fTarget = 0, defaultResult) {
         /**
@@ -851,7 +871,7 @@ export class Geometry {
     }
     /**
      * 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`
+     * Return `undefined` if `(fTarget - f0) / (f1 - f0)` exceeds [[largeFractionResult]].
      */
     static inverseInterpolate01(f0, f1, fTarget = 0) {
         // Line equation is fTarget-f0 = (f1-f0)*x so x = (fTarget-f0)/(f1-f0)
@@ -922,12 +942,12 @@ export class Geometry {
         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.
+     * Test if `x` is in the interval [0,1] for a given `tolerance`.
      * @param x value to test.
-     * @param tolerance the tolerance.
+     * @param tolerance allowable distance outside the interval within which to classify `x` as inside.
      */
     static isIn01WithTolerance(x, tolerance) {
+        tolerance = Math.abs(tolerance);
         return x + tolerance >= 0.0 && x - tolerance <= 1.0;
     }
     /**
@@ -1068,11 +1088,11 @@ export class Geometry {
 }
 /** Tolerance for small distances in metric coordinates. */
 Geometry.smallMetricDistance = 1.0e-6;
-/** Square of `smallMetricDistance`. */
+/** Square of [[smallMetricDistance]]. */
 Geometry.smallMetricDistanceSquared = 1.0e-12;
 /** 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. */
 Geometry.smallAngleDegrees = 5.7e-11;
@@ -1082,7 +1102,7 @@ Geometry.smallAngleSeconds = 2e-7;
 Geometry.smallFraction = 1.0e-10;
 /** Tight tolerance near machine precision (unitless). Useful for snapping values, e.g., to 0 or 1. */
 Geometry.smallFloatingPoint = 1.0e-15;
-/** Radians value for full circle 2PI radians minus `smallAngleRadians`. */
+/** 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.
@@ -1091,12 +1111,12 @@ Geometry.fullCircleRadiansMinusSmallAngle = 2.0 * Math.PI - Geometry.smallAngleR
 Geometry.largeFractionResult = 1.0e10;
 /**
  * Numeric value that may considered large for numbers expected to be coordinates.
- * * This allows larger results than `largeFractionResult`.
+ * * This allows larger results than [[largeFractionResult]].
  */
 Geometry.largeCoordinateResult = 1.0e13;
 /**
  * Numeric value that may considered infinite for metric coordinates.
- * @deprecated in 4.x. Use `largeCoordinateResult`.
+ * @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.
  */