@itwin/core-geometry 3.5.0-dev.7 → 3.6.0-dev.1

package/lib/esm/geometry3d/Angle.js

@@ -7,30 +7,46 @@
  */
 import { Geometry } from "../Geometry";
 /**
- * An `Angle` carries the numeric value of an angle, with methods to allow (require!) callers to be clear about whether their angle is degrees or radians.
- * * The numeric value is private, and callers should not know or care whether it is in degrees or radians.
- * * The various access method are named so that callers can specify whether untyped numbers passed in or out are degrees or radians.
+ * An `Angle` carries the numeric value of an angle, with methods to allow (require!) callers to
+ * be clear about whether their angle is degrees or radians.
+ * * After the Angle object is created, the callers should not know or care whether it is stored in
+ * `degrees` or `radians` because both are available if requested by caller.
+ * * The various access method are named so that callers can specify whether untyped numbers passed in or
+ * out are degrees or radians.
  * @public
  */
 export class Angle {
-    constructor(radians = 0, degrees) { this._radians = radians; this._degrees = degrees; }
+    constructor(radians = 0, degrees) {
+        this._radians = radians;
+        this._degrees = degrees;
+    }
     /** Return a new angle with the same content. */
-    clone() { return new Angle(this._radians, this._degrees); }
+    clone() {
+        return new Angle(this._radians, this._degrees);
+    }
     /** Freeze this instance so it is read-only */
-    freeze() { return Object.freeze(this); }
+    freeze() {
+        return Object.freeze(this);
+    }
     /**
      * Return a new Angle object for angle given in degrees.
      * @param degrees angle in degrees
      */
-    static createDegrees(degrees) { return new Angle(Angle.degreesToRadians(degrees), degrees); }
+    static createDegrees(degrees) {
+        return new Angle(Angle.degreesToRadians(degrees), degrees);
+    }
     /**
      * Return a (new) Angle object for a value given in radians.
      * @param radians angle in radians
      */
-    static createRadians(radians) { return new Angle(radians); }
+    static createRadians(radians) {
+        return new Angle(radians);
+    }
     /**
-     * Return a (new) Angle object that is interpolated between two inputs
-     * @param radians angle in radians
+     * Return a (new) Angle object that is interpolated between two inputs (based on a fraction)
+     * @param angle0 first angle in radians
+     * @param fraction the interpolation fraction
+     * @param angle1 second angle in radians
      */
     static createInterpolate(angle0, fraction, angle1) {
         return new Angle(Geometry.interpolate(angle0.radians, fraction, angle1.radians));
@@ -39,45 +55,49 @@ export class Angle {
      * Return a (new) Angle object, with angle scaled from existing angle.
      * @param scale scale factor to apply to angle.
      */
-    cloneScaled(scale) { return new Angle(this.radians * scale); }
+    cloneScaled(scale) {
+        return new Angle(this.radians * scale);
+    }
     /**
      * Set this angle to a value given in radians.
      * @param radians angle given in radians
      */
-    setRadians(radians) { this._radians = radians; this._degrees = undefined; }
+    setRadians(radians) {
+        this._radians = radians;
+        this._degrees = undefined;
+    }
     /**
      * Set this angle to a value given in degrees.
      * @param degrees angle given in degrees.
      */
-    setDegrees(degrees) { this._radians = Angle.degreesToRadians(degrees); this._degrees = degrees; }
+    setDegrees(degrees) {
+        this._radians = Angle.degreesToRadians(degrees);
+        this._degrees = degrees;
+    }
     /** Create an angle for a full circle. */
-    static create360() { return new Angle(Math.PI * 2.0, 360.0); }
+    static create360() {
+        return new Angle(Math.PI * 2.0, 360.0);
+    }
     /**
-     * @return a (strongly typed) Angle whose tangent is `numerator/denominator`, using the signs of both in determining the (otherwise ambiguous)
-     * quadrant.
+     * Create a (strongly typed) Angle whose tangent is `numerator/denominator`, using the signs of both in
+     * determining the (otherwise ambiguous) quadrant.
      * @param numerator numerator for tangent
      * @param denominator denominator for tangent
      */
-    static createAtan2(numerator, denominator) { return new Angle(Math.atan2(numerator, denominator)); }
+    static createAtan2(numerator, denominator) {
+        return new Angle(Math.atan2(numerator, denominator));
+    }
     /**
      * Copy all contents of `other` to this Angle.
      * @param other source data
      */
-    setFrom(other) { this._radians = other._radians; this._degrees = other._degrees; }
-    /**
-     * Create an Angle from a JSON object
-     * @param json object from JSON.parse. If a number, value is in *DEGREES*
-     * @param defaultValRadians if json is undefined, default value in radians.
-     * @return a new Angle
-     */
-    static fromJSON(json, defaultValRadians) {
-        const val = new Angle();
-        val.setFromJSON(json, defaultValRadians);
-        return val;
+    setFrom(other) {
+        this._radians = other._radians;
+        this._degrees = other._degrees;
     }
     /**
-     * set an Angle from a JSON object
-     * * A simple number is degrees.
+     * Set an Angle from a JSON object
+     * * A simple number is considered as degrees.
      * * specified `json.degrees` or `json._degrees` is degree value.
      * * specified `son.radians` or `json._radians` is radians value.
      * @param json object from JSON.parse. If a number, value is in *DEGREES*
@@ -103,19 +123,40 @@ export class Angle {
             this.setRadians(json._radians);
         }
     }
+    /**
+   * Create an Angle from a JSON object
+   * @param json object from JSON.parse. If a number, value is in *DEGREES*
+   * @param defaultValRadians if json is undefined, default value in radians.
+   * @return a new Angle
+   */
+    static fromJSON(json, defaultValRadians) {
+        const val = new Angle();
+        val.setFromJSON(json, defaultValRadians);
+        return val;
+    }
     /** Convert an Angle to a JSON object as a number in degrees */
-    toJSON() { return this.degrees; }
+    toJSON() {
+        return this.degrees;
+    }
     /** Return a json object with radians keyword, e.g. `{ radians: 0.10}` */
-    toJSONRadians() { return { radians: this.radians }; }
-    /**  Return the angle measured in radians. */
-    get radians() { return this._radians; }
-    /**  Return the angle measured in degrees. */
-    get degrees() { return this._degrees !== undefined ? this._degrees : Angle.radiansToDegrees(this._radians); }
+    toJSONRadians() {
+        return { radians: this.radians };
+    }
+    /** Return the angle measured in radians. */
+    get radians() {
+        return this._radians;
+    }
+    /** Return the angle measured in degrees. */
+    get degrees() {
+        return this._degrees !== undefined ? this._degrees : Angle.radiansToDegrees(this._radians);
+    }
     /**
      * Convert an angle in degrees to radians.
      * @param degrees angle in degrees
      */
-    static degreesToRadians(degrees) { return degrees * Math.PI / 180; }
+    static degreesToRadians(degrees) {
+        return degrees * Math.PI / 180;
+    }
     /**
      * Convert an angle in radians to degrees.
      * @param degrees angle in radians
@@ -126,6 +167,11 @@ export class Angle {
         // Now radians is positive ...
         const pi = Math.PI;
         const factor = 180.0 / pi;
+        /* the following if statements are for round-off reasons. The problem is that no IEEE number is
+          * an exact hit for any primary multiple of pi (90, 180, etc). The following is supposed to have
+          * a better chance that if the input was computed by direct assignment from 90, 180, etc degrees
+          * it will return exactly 90,180 etc.
+          */
         if (radians <= 0.25 * pi)
             return factor * radians;
         if (radians < 0.75 * pi)
@@ -140,27 +186,37 @@ export class Angle {
     /**
      * Return the cosine of this Angle object's angle.
      */
-    cos() { return Math.cos(this._radians); }
+    cos() {
+        return Math.cos(this._radians);
+    }
     /**
      * Return the sine of this Angle object's angle.
      */
-    sin() { return Math.sin(this._radians); }
+    sin() {
+        return Math.sin(this._radians);
+    }
     /**
      * Return the tangent of this Angle object's angle.
      */
-    tan() { return Math.tan(this._radians); }
-    /** Test if a radians (absolute) value is nearly 2PI or larger (!) */
+    tan() {
+        return Math.tan(this._radians);
+    }
+    /** Test if a radians (absolute) value is nearly 2PI or larger! */
     static isFullCircleRadians(radians) {
         return Math.abs(radians) >= Geometry.fullCircleRadiansMinusSmallAngle;
     }
-    /** Test if the radians value  is a complete circle */
+    /** Test if the radians value is a half circle */
     static isHalfCircleRadians(radians) {
         return Math.abs(Math.abs(radians) - Math.PI) <= Geometry.smallAngleRadians;
     }
-    /** test if the angle is aa full circle */
-    get isFullCircle() { return Angle.isFullCircleRadians(this._radians); }
+    /** test if the angle is a full circle */
+    get isFullCircle() {
+        return Angle.isFullCircleRadians(this._radians);
+    }
     /** test if the angle is a half circle (in either direction) */
-    get isHalfCircle() { return Angle.isHalfCircleRadians(this._radians); }
+    get isHalfCircle() {
+        return Angle.isHalfCircleRadians(this._radians);
+    }
     /** Adjust a radians value so it is positive in 0..360 */
     static adjustDegrees0To360(degrees) {
         if (degrees >= 0) {
@@ -172,8 +228,8 @@ export class Angle {
         }
         else if (degrees < 0) {
             // negative angle ...
-            const radians1 = Angle.adjustDegrees0To360(-degrees);
-            return 360.0 - radians1;
+            const radians = Angle.adjustDegrees0To360(-degrees);
+            return 360.0 - radians;
         }
         // fall through for Nan (disaster) !!!
         return 0;
@@ -205,8 +261,7 @@ export class Angle {
         }
         else if (radians < 0) {
             // negative angle ...
-            const radians1 = Angle.adjustRadians0To2Pi(-radians);
-            return Math.PI * 2.0 - radians1;
+            return Math.PI * 2.0 - Angle.adjustRadians0To2Pi(-radians);
         }
         // fall through for NaN disaster.
         return 0;
@@ -228,53 +283,80 @@ export class Angle {
         return 0;
     }
     /** return a (newly allocated) Angle object with value 0 radians */
-    static zero() { return new Angle(0); }
+    static zero() {
+        return new Angle(0);
+    }
     /** Test if the angle is exactly zero. */
-    get isExactZero() { return this.radians === 0; }
+    get isExactZero() {
+        return this.radians === 0;
+    }
     /** Test if the angle is almost zero (within tolerance `Geometry.smallAngleRadians`) */
-    get isAlmostZero() { return Math.abs(this.radians) < Geometry.smallAngleRadians; }
+    get isAlmostZero() {
+        return Math.abs(this.radians) < Geometry.smallAngleRadians;
+    }
     /** Test if the angle is almost a north or south pole (within tolerance `Geometry.smallAngleRadians`) */
-    get isAlmostNorthOrSouthPole() { return Angle.isHalfCircleRadians(this.radians * 2.0); }
+    get isAlmostNorthOrSouthPole() {
+        return Angle.isHalfCircleRadians(this.radians * 2.0);
+    }
     /** Create an angle object with degrees adjusted into 0..360. */
-    static createDegreesAdjustPositive(degrees) { return Angle.createDegrees(Angle.adjustDegrees0To360(degrees)); }
+    static createDegreesAdjustPositive(degrees) {
+        return Angle.createDegrees(Angle.adjustDegrees0To360(degrees));
+    }
     /** Create an angle object with degrees adjusted into -180..180. */
-    static createDegreesAdjustSigned180(degrees) { return Angle.createDegrees(Angle.adjustDegreesSigned180(degrees)); }
+    static createDegreesAdjustSigned180(degrees) {
+        return Angle.createDegrees(Angle.adjustDegreesSigned180(degrees));
+    }
     /**
      * Test if two radians values are equivalent, allowing shift by full circle (i.e. by a multiple of `2*PI`)
      * @param radiansA first radians value
      * @param radiansB second radians value
+     * @param radianTol radian tolerance with default value of Geometry.smallAngleRadians
      */
-    static isAlmostEqualRadiansAllowPeriodShift(radiansA, radiansB) {
-        // try to get simple conclusions with un-shifted radians ...
+    static isAlmostEqualRadiansAllowPeriodShift(radiansA, radiansB, radianTol = Geometry.smallAngleRadians) {
         const delta = Math.abs(radiansA - radiansB);
-        if (delta <= Geometry.smallAngleRadians)
+        if (delta <= radianTol)
             return true;
         const period = Math.PI * 2.0;
-        if (Math.abs(delta - period) <= Geometry.smallAngleRadians)
+        if (Math.abs(delta - period) <= radianTol)
             return true;
         const numPeriod = Math.round(delta / period);
         const delta1 = delta - numPeriod * period;
-        return Math.abs(delta1) <= Geometry.smallAngleRadians;
+        return Math.abs(delta1) <= radianTol;
     }
     /**
-     * Test if this angle and other are equivalent, allowing shift by full circle (i.e. by a multiple of 360 degrees)
+     * Test if this angle and other are equivalent, allowing shift by full circle (i.e., multiples of `2 * PI`).
+     * @param other the other angle
+     * @param radianTol radian tolerance with default value of Geometry.smallAngleRadians
      */
-    isAlmostEqualAllowPeriodShift(other) {
-        return Angle.isAlmostEqualRadiansAllowPeriodShift(this._radians, other._radians);
+    isAlmostEqualAllowPeriodShift(other, radianTol = Geometry.smallAngleRadians) {
+        return Angle.isAlmostEqualRadiansAllowPeriodShift(this._radians, other._radians, radianTol);
     }
     /**
-     * Test if two this angle and other are almost equal, NOT allowing shift by full circle multiples of 360 degrees.
+     * Test if two angle (in radians)  almost equal, NOT allowing shift by full circle (i.e., multiples of `2 * PI`).
+     * @param radiansA first radians value
+     * @param radiansB second radians value
+     * @param radianTol radian tolerance with default value of Geometry.smallAngleRadians
      */
-    isAlmostEqualNoPeriodShift(other) { return Math.abs(this._radians - other._radians) < Geometry.smallAngleRadians; }
+    static isAlmostEqualRadiansNoPeriodShift(radiansA, radiansB, radianTol = Geometry.smallAngleRadians) {
+        return Math.abs(radiansA - radiansB) < radianTol;
+    }
     /**
-     * Test if two angle (in radians)  almost equal, NOT allowing shift by full circle multiples of `2 * PI`.
-     * * (Same test as isAlmostEqualRadiansNoPeriodShift)
+     * Test if two this angle and other are almost equal, NOT allowing shift by full circle (i.e., multiples of `2 * PI`).
+     * @param other the other angle
+     * @param radianTol radian tolerance with default value of Geometry.smallAngleRadians
      */
-    isAlmostEqual(other) { return this.isAlmostEqualNoPeriodShift(other); }
+    isAlmostEqualNoPeriodShift(other, radianTol = Geometry.smallAngleRadians) {
+        return Angle.isAlmostEqualRadiansNoPeriodShift(this._radians, other._radians, radianTol);
+    }
     /**
-     * Test if two angle (in radians)  almost equal, NOT allowing shift by full circle multiples of `2 * PI`.
+     * Test if two this angle and other are almost equal, NOT allowing shift by full circle (i.e., multiples of `2 * PI`).
+     * * This function is same as isAlmostEqualRadiansNoPeriodShift. Please use isAlmostEqualRadiansNoPeriodShift.
+     * @param other the other angle
+     * @param radianTol radian tolerance with default value of Geometry.smallAngleRadians
      */
-    static isAlmostEqualRadiansNoPeriodShift(radiansA, radiansB) { return Math.abs(radiansA - radiansB) < Geometry.smallAngleRadians; }
+    isAlmostEqual(other, radianTol = Geometry.smallAngleRadians) {
+        return this.isAlmostEqualNoPeriodShift(other, radianTol);
+    }
     /**
      * Test if dot product values indicate non-zero length perpendicular vectors.
      * @param dotUU dot product of vectorU with itself
@@ -287,40 +369,55 @@ export class Angle {
             && dotUV * dotUV <= Geometry.smallAngleRadiansSquared * dotUU * dotVV;
     }
     /**
-     * Return cosine, sine, and radians for the half angle of a cosine,sine pair.
+     * Return cosine, sine, and radians for the half angle of a "cosine,sine" pair.
+     * * This function assumes the input arguments are related to an angle between -PI and PI
+     * * This function returns an angle between -PI and PI
      * @param rCos2A cosine value (scaled by radius) for initial angle.
      * @param rSin2A sine value (scaled by radius) for final angle.
      */
     static trigValuesToHalfAngleTrigValues(rCos2A, rSin2A) {
         const r = Geometry.hypotenuseXY(rCos2A, rSin2A);
         if (r < Geometry.smallMetricDistance) {
-            return { c: 1.0, s: 0.0, radians: 0.0 };
+            return { c: 1.0, s: 0.0, radians: 0.0 }; // angle = 0
         }
         else {
-            /* If the caller really gave you sine and cosine values, r should be 1.  However,*/
-            /* to allow scaled values -- e.g. the x and y components of any vector -- we normalize*/
-            /* right here.  This adds an extra sqrt and 2 divides to the whole process, but improves*/
-            /* both the usefulness and robustness of the computation.*/
+            /* If the caller really gave you sine and cosine values, r should be 1.  However,
+             * to allow scaled values -- e.g. the x and y components of any vector -- we normalize
+             * right here. This adds an extra sqrt and 2 divides to the whole process, but improves
+             * both the usefulness and robustness of the computation.
+             */
             let cosA;
             let sinA = 0.0;
             const cos2A = rCos2A / r;
             const sin2A = rSin2A / r;
+            // Original angle in NE and SE quadrants. Half angle in same quadrant
             if (cos2A >= 0.0) {
-                /* Original angle in NE and SE quadrants.  Half angle in same quadrant */
+                /*
+                 * We know cos2A = (cosA)^2 - (sinA)^2 and 1 = (cosA)^2 + (sinA)^2
+                 * so 1 + cos2A = 2(cosA)^2 and therefore, cosA = sqrt((1+cos2A)/2)
+                 * cosine is positive in NE and SE quadrants so we use +sqrt
+                 */
                 cosA = Math.sqrt(0.5 * (1.0 + cos2A));
-                sinA = sin2A / (2.0 * (cosA));
+                // We know sin2A = 2 sinA cosA so sinA = sin2A/(2*cosA)
+                sinA = sin2A / (2.0 * cosA);
             }
             else {
+                // Original angle in NW quadrant. Half angle in NE quadrant
                 if (sin2A > 0.0) {
-                    /* Original angle in NW quadrant. Half angle in NE quadrant */
+                    /*
+                     * We know cos2A = (cosA)^2 - (sinA)^2 and 1 = (cosA)^2 + (sinA)^2
+                     * so 1 - cos2A = 2(sinA)^2 and therefore, sinA = sqrt((1-cos2A)/2)
+                     * sine is positive in NE quadrant so we use +sqrt
+                     */
                     sinA = Math.sqrt(0.5 * (1.0 - cos2A));
+                    // Original angle in SW quadrant. Half angle in SE quadrant
                 }
                 else {
-                    /* Original angle in SW quadrant. Half angle in SE quadrant*/
-                    /* cosA comes out positive because both sines are negative. */
+                    // sine is negative in SE quadrant so we use -sqrt
                     sinA = -Math.sqrt(0.5 * (1.0 - cos2A));
                 }
-                cosA = sin2A / (2.0 * (sinA));
+                // We know sin2A = 2 sinA cosA so cosA = sin2A/(2*sinA)
+                cosA = sin2A / (2.0 * sinA); // always positive
             }
             return { c: cosA, s: sinA, radians: Math.atan2(sinA, cosA) };
         }
@@ -339,17 +436,24 @@ export class Angle {
         return value;
     }
     /**
-     * Return the half angle cosine, sine, and radians for given dot products between vectors.
-     * @param dotUU dot product of vectorU with itself
-     * @param dotVV dot product of vectorV with itself
-     * @param dotUV dot product of vectorU with vectorV
-     */
+       * Return the half angle cosine, sine, and radians for given dot products between vectors. The vectors define
+       * an ellipse using x(t) = c + U cos(t) + V sin(t) so U and V are at angle t=0 degree and t=90 degree. The
+       * half angle t0 is an angle such that x(t0) is one of the ellipse semi-axis.
+       * * This construction arises e.g. in `Arc3d.toScaledMatrix3d`.
+       * * Given ellipse x(t) = c + U cos(t) + V sin(t), find t0 such that radial vector W(t0) = x(t0) - c is
+       * perpendicular to the ellipse.
+       * * Then 0 = W(t0).x'(t0) = (U cos(t0) + V sin(t0)).(V cos(t0) - U sin(t0)) = U.V cos(2t0) + 0.5 (V.V - U.U) sin(2t0)
+       * implies sin(2t0) / cos(2t0) = 2 U.V / (U.U - V.V), i.e., t0 can be computed given the three dot products on the RHS.
+       * @param dotUU dot product of vectorU with itself
+       * @param dotVV dot product of vectorV with itself
+       * @param dotUV dot product of vectorU with vectorV
+       */
     static dotProductsToHalfAngleTrigValues(dotUU, dotVV, dotUV, favorZero = true) {
-        const rCos = dotUU - dotVV;
-        const rSin = 2.0 * dotUV;
-        if (favorZero && Math.abs(rSin) < Geometry.smallAngleRadians * (Math.abs(dotUU) + Math.abs(dotVV)))
+        const cos2t0 = dotUU - dotVV;
+        const sin2t0 = 2.0 * dotUV;
+        if (favorZero && Math.abs(sin2t0) < Geometry.smallAngleRadians * (Math.abs(dotUU) + Math.abs(dotVV)))
             return { c: 1.0, s: 0.0, radians: 0.0 };
-        return Angle.trigValuesToHalfAngleTrigValues(rCos, rSin);
+        return Angle.trigValuesToHalfAngleTrigValues(cos2t0, sin2t0);
     }
     /**
      * * Returns the angle between two vectors, with the vectors given as xyz components
@@ -363,9 +467,7 @@ export class Angle {
      * @param vz z component of vector v
      */
     static radiansBetweenVectorsXYZ(ux, uy, uz, vx, vy, vz) {
-        //  const uu = ux * ux + uy * uy + uz * uz;
-        const uDotV = ux * vx + uy * vy + uz * vz; // magU magV cos(theta)
-        //    const vv = vx * vx + vy * vy + vz * vz;
+        const uDotV = ux * vx + uy * vy + uz * vz;
         return Math.atan2(Geometry.crossProductMagnitude(ux, uy, uz, vx, vy, vz), uDotV);
     }
     /**
@@ -382,11 +484,13 @@ export class Angle {
         }
     }
 }
-/** maximal accuracy value of pi/4 ( 45 degrees), in radians */
+/** maximal accuracy value of pi/12 (15 degrees), in radians */
+Angle.piOver12Radians = 0.26179938779914943653855361527329;
+/** maximal accuracy value of pi/4 (45 degrees), in radians */
 Angle.piOver4Radians = 7.85398163397448280000e-001;
-/** maximal accuracy value of pi/2 ( 90 degrees), in radians */
+/** maximal accuracy value of pi/2 (90 degrees), in radians */
 Angle.piOver2Radians = 1.57079632679489660000e+000;
-/** maximal accuracy value of pi ( 180 degrees), in radians */
+/** maximal accuracy value of pi (180 degrees), in radians */
 Angle.piRadians = 3.14159265358979310000e+000;
 /** maximal accuracy value of 2*pi (360 degrees), in radians */
 Angle.pi2Radians = 6.28318530717958620000e+000;
@@ -394,6 +498,4 @@ Angle.pi2Radians = 6.28318530717958620000e+000;
 Angle.degreesPerRadian = (45.0 / Angle.piOver4Radians);
 /** scale factor for converting degrees to radians */
 Angle.radiansPerDegree = (Angle.piOver4Radians / 45.0);
-/** maximal accuracy value of pi/12 ( 15 degrees), in radians */
-Angle.piOver12Radians = 0.26179938779914943653855361527329;
 //# sourceMappingURL=Angle.js.map