@itwin/core-geometry 3.6.0-dev.8 → 4.0.0-dev.2

package/lib/cjs/geometry3d/YawPitchRollAngles.d.ts

@@ -6,7 +6,6 @@ import { Angle } from "./Angle";
 import { Matrix3d } from "./Matrix3d";
 import { Point3d } from "./Point3dVector3d";
 import { Transform } from "./Transform";
-/** The properties that define [[YawPitchRollAngles]]. */
 /**
  * angle properties of a `YawPitchRoll` orientation
  * @public
@@ -19,44 +18,66 @@ export interface YawPitchRollProps {
     /** roll field */
     roll?: AngleProps;
 }
-/** Three angles that determine the orientation of an object in space. Sometimes referred to as [Tait–Bryan angles](https://en.wikipedia.org/wiki/Euler_angles).
+/**
+ * Three angles that determine the orientation of an object in space, sometimes referred to as [Tait–Bryan angles]
+ * (https://en.wikipedia.org/wiki/Euler_angles).
  * * The matrix construction can be replicated by this logic:
  * * xyz coordinates have
  *   * x forward
  *   * y to left
  *   * z up
- *   * Note that this is a right handed coordinate system.
- *   * yaw is a rotation of x towards y, i.e. around positive z:
+ * * Note that this is a right handed coordinate system.
+ * * yaw is a rotation of x towards y, i.e. around positive z (counterclockwise):
  *     * `yawMatrix = Matrix3d.createRotationAroundAxisIndex(2, Angle.createDegrees(yawDegrees));`
- *   * pitch is a rotation that raises x towards z, i.e. rotation around negative y:
+ * * pitch is a rotation that raises x towards z, i.e. rotation around **negative y** (**clockwise**):
  *     * `pitchMatrix = Matrix3d.createRotationAroundAxisIndex(1, Angle.createDegrees(-pitchDegrees));`
- *   * roll is rotation of y towards z, i.e. rotation around positive x:
+ * * roll is rotation of y towards z, i.e. rotation around positive x (counterclockwise):
  *     * `rollMatrix = Matrix3d.createRotationAroundAxisIndex(0, Angle.createDegrees(rollDegrees));`
- *   * The YPR matrix is the product
+ * * The YPR matrix is the product
  *     * `result = yawMatrix.multiplyMatrixMatrix(pitchMatrix.multiplyMatrixMatrix(rollMatrix));`
- *   * Note that this is for "column based" matrix, with vectors appearing to the right
- *     * Hence a vector is first rotated by roll, then the pitch, finally yaw.
+ * * Note that this is for "column based" matrix with vectors multiplying on the right of the matrix.
+ * Hence a vector is first rotated by roll, then the pitch, finally yaw. So multiplication order in
+ * the sense of AxisOrder is `RPY` (i.e., XYZ), in contrast to the familiar name `YPR`.
  * @public
  */
 export declare class YawPitchRollAngles {
-    /** The yaw angle. */
+    /** The yaw angle: counterclockwise rotation angle around z  */
     yaw: Angle;
-    /** The pitch angle. */
+    /** The pitch angle: **clockwise** rotation angle around y */
     pitch: Angle;
-    /** The roll angle. */
+    /** The roll angle: counterclockwise rotation angle around x */
     roll: Angle;
+    /**
+     * constructor
+     * @param yaw counterclockwise rotation angle around z
+     * @param pitch **clockwise** rotation angle around y
+     * @param roll counterclockwise rotation angle around x
+     * */
     constructor(yaw?: Angle, pitch?: Angle, roll?: Angle);
     /** Freeze this YawPitchRollAngles */
     freeze(): Readonly<this>;
-    /** constructor for YawPitchRollAngles with angles in degrees. */
+    /**
+     * constructor for YawPitchRollAngles with angles in degrees.
+     * @param yawDegrees counterclockwise rotation angle (in degrees) around z
+     * @param pitchDegrees **clockwise** rotation angle (in degrees) around y
+     * @param rollDegrees counterclockwise rotation angle (in degrees) around x
+     * */
     static createDegrees(yawDegrees: number, pitchDegrees: number, rollDegrees: number): YawPitchRollAngles;
-    /** constructor for YawPitchRollAngles with angles in radians. */
+    /**
+     * constructor for YawPitchRollAngles with angles in radians.
+     * @param yawRadians counterclockwise rotation angle (in radians) around z
+     * @param pitchRadians **clockwise** rotation angle (in radians) around y
+     * @param rollRadians counterclockwise rotation angle (in radians) around x
+     * */
     static createRadians(yawRadians: number, pitchRadians: number, rollRadians: number): YawPitchRollAngles;
     /** construct a `YawPitchRoll` object from an object with 3 named angles */
     static fromJSON(json?: YawPitchRollProps): YawPitchRollAngles;
     /** populate yaw, pitch and roll fields using `Angle.fromJSON` */
     setFromJSON(json?: YawPitchRollProps): void;
-    /** Convert to a JSON object of form { pitch: 20 , roll: 29.999999999999996 , yaw: 10 }. Any values that are exactly zero (with tolerance `Geometry.smallAngleRadians`) are omitted. */
+    /**
+     * Convert to a JSON object of form { pitch: 20 , roll: 30 , yaw: 10 }. Angles are in degrees.
+     * Any values that are exactly zero (with tolerance `Geometry.smallAngleRadians`) are omitted.
+     **/
     toJSON(): YawPitchRollProps;
     /**
      * Install all rotations from `other` into `this`.
@@ -64,7 +85,7 @@ export declare class YawPitchRollAngles {
      */
     setFrom(other: YawPitchRollAngles): void;
     /**
-     * * Compare angles between `this` and `other`.
+     * Compare angles between `this` and `other`.
      * * Comparisons are via `isAlmostEqualAllowPeriodShift`.
      * @param other YawPitchRollAngles source
      */
@@ -76,35 +97,38 @@ export declare class YawPitchRollAngles {
     /**
      * Expand the angles into a (rigid rotation) matrix.
      *
-     * * The returned matrix is "rigid" -- unit length rows and columns, and its transpose is its inverse.
-     * * The "rigid" matrix is always a right handed coordinate system.
+     * * The returned matrix is "rigid" (i.e., it has unit length rows and columns, and its transpose is its inverse).
+     * * The rigid matrix is always a right handed coordinate system.
      * @param result optional pre-allocated `Matrix3d`
      */
     toMatrix3d(result?: Matrix3d): Matrix3d;
-    /** Return the largest angle in radians */
-    maxAbsRadians(): number;
-    /** Return the sum of the angles in squared radians */
-    sumSquaredRadians(): number;
     /** Returns true if this rotation does nothing.
      * * If allowPeriodShift is false, any nonzero angle is considered a non-identity
      * * If allowPeriodShift is true, all angles are individually allowed to be any multiple of 360 degrees.
      */
     isIdentity(allowPeriodShift?: boolean): boolean;
+    /** Return the largest angle in radians */
+    maxAbsRadians(): number;
+    /** Return the sum of the angles in squared radians */
+    sumSquaredRadians(): number;
     /** Return the largest difference of angles (in radians) between this and other */
     maxDiffRadians(other: YawPitchRollAngles): number;
     /** Return the largest angle in degrees. */
     maxAbsDegrees(): number;
     /** Return the sum of squared angles in degrees. */
     sumSquaredDegrees(): number;
+    /** Return the largest difference of angles (in degrees) between this and other */
+    maxDiffDegrees(other: YawPitchRollAngles): number;
     /** Return an object from a Transform as an origin and YawPitchRollAngles. */
     static tryFromTransform(transform: Transform): {
         origin: Point3d;
         angles: YawPitchRollAngles | undefined;
     };
-    /** Attempts to create a YawPitchRollAngles object from an Matrix3d
-     * * This conversion fails if the matrix is not rigid (unit rows and columns, transpose is inverse)
+    /** Attempts to create a YawPitchRollAngles object from a Matrix3d
+     * * This conversion fails if the matrix is not rigid (unit rows and columns, and transpose is inverse)
      * * In the failure case the method's return value is `undefined`.
-     * * In the failure case, if the optional result was supplied, that result will nonetheless be filled with a set of angles.
+     * * In the failure case, if the optional result was supplied, that result will nonetheless be filled with
+     * a set of angles.
      */
     static createFromMatrix3d(matrix: Matrix3d, result?: YawPitchRollAngles): YawPitchRollAngles | undefined;
 }

package/lib/cjs/geometry3d/YawPitchRollAngles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"YawPitchRollAngles.d.ts","sourceRoot":"","sources":["../../../src/geometry3d/YawPitchRollAngles.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAY,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,yDAAyD;AACzD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,kBAAkB;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,iBAAiB;IACjB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,kBAAkB;IAC7B,qBAAqB;IACd,GAAG,EAAE,KAAK,CAAC;IAClB,uBAAuB;IAChB,KAAK,EAAE,KAAK,CAAC;IACpB,sBAAsB;IACf,IAAI,EAAE,KAAK,CAAC;gBAEP,GAAG,GAAE,KAAoB,EAAE,KAAK,GAAE,KAAoB,EAAE,IAAI,GAAE,KAAoB;IAK9F,qCAAqC;IAC9B,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC;IAC/B,iEAAiE;WACnD,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB;IAG9G,iEAAiE;WACnD,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB;IAG9G,2EAA2E;WAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,kBAAkB;IAIpE,iEAAiE;IAC1D,WAAW,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAMlD,uLAAuL;IAChL,MAAM,IAAI,iBAAiB;IAUlC;;;OAGG;IACI,OAAO,CAAC,KAAK,EAAE,kBAAkB;IAKxC;;;;OAIG;IACI,aAAa,CAAC,KAAK,EAAE,kBAAkB;IAK9C;;OAEG;IACI,KAAK;IACZ;;;;;;OAMG;IACI,UAAU,CAAC,MAAM,CAAC,EAAE,QAAQ;IASnC,0CAA0C;IACnC,aAAa,IAAI,MAAM;IAG9B,sDAAsD;IAC/C,iBAAiB,IAAI,MAAM;IAGlC;;;OAGG;IACI,UAAU,CAAC,gBAAgB,GAAE,OAAc,GAAG,OAAO;IAU5D,kFAAkF;IAC3E,cAAc,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM;IAGxD,2CAA2C;IACpC,aAAa,IAAI,MAAM;IAC9B,mDAAmD;IAC5C,iBAAiB,IAAI,MAAM;IAClC,6EAA6E;WAC/D,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG;QACpD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAC;KACxC;IAOD;;;;OAIG;WACW,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,GAAG,SAAS;CAqChH"}
+{"version":3,"file":"YawPitchRollAngles.d.ts","sourceRoot":"","sources":["../../../src/geometry3d/YawPitchRollAngles.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAY,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,kBAAkB;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,iBAAiB;IACjB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,kBAAkB;IAC7B,+DAA+D;IACxD,GAAG,EAAE,KAAK,CAAC;IAClB,6DAA6D;IACtD,KAAK,EAAE,KAAK,CAAC;IACpB,+DAA+D;IACxD,IAAI,EAAE,KAAK,CAAC;IACnB;;;;;SAKK;gBACO,GAAG,GAAE,KAAoB,EAAE,KAAK,GAAE,KAAoB,EAAE,IAAI,GAAE,KAAoB;IAK9F,qCAAqC;IAC9B,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC;IAM/B;;;;;SAKK;WACS,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB;IAO9G;;;;;SAKK;WACS,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,kBAAkB;IAO9G,2EAA2E;WAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,kBAAkB;IAQpE,iEAAiE;IAC1D,WAAW,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAMlD;;;QAGI;IACG,MAAM,IAAI,iBAAiB;IAUlC;;;OAGG;IACI,OAAO,CAAC,KAAK,EAAE,kBAAkB;IAKxC;;;;OAIG;IACI,aAAa,CAAC,KAAK,EAAE,kBAAkB;IAK9C;;OAEG;IACI,KAAK;IAOZ;;;;;;OAMG;IACI,UAAU,CAAC,MAAM,CAAC,EAAE,QAAQ;IAqCnC;;;OAGG;IACI,UAAU,CAAC,gBAAgB,GAAE,OAAc,GAAG,OAAO;IAU5D,0CAA0C;IACnC,aAAa,IAAI,MAAM;IAG9B,sDAAsD;IAC/C,iBAAiB,IAAI,MAAM;IAGlC,kFAAkF;IAC3E,cAAc,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM;IAOxD,2CAA2C;IACpC,aAAa,IAAI,MAAM;IAG9B,mDAAmD;IAC5C,iBAAiB,IAAI,MAAM;IAGlC,kFAAkF;IAC3E,cAAc,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM;IAOxD,6EAA6E;WAC/D,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG;QACpD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAC;KACxC;IAMD;;;;;OAKG;WACW,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,GAAG,SAAS;CA0EhH"}

package/lib/cjs/geometry3d/YawPitchRollAngles.js

@@ -12,39 +12,62 @@ const Geometry_1 = require("../Geometry");
 const Angle_1 = require("./Angle");
 const Matrix3d_1 = require("./Matrix3d");
 const Point3dVector3d_1 = require("./Point3dVector3d");
-// cspell:word Tait
-/** Three angles that determine the orientation of an object in space. Sometimes referred to as [Tait–Bryan angles](https://en.wikipedia.org/wiki/Euler_angles).
+/**
+ * Three angles that determine the orientation of an object in space, sometimes referred to as [Tait–Bryan angles]
+ * (https://en.wikipedia.org/wiki/Euler_angles).
  * * The matrix construction can be replicated by this logic:
  * * xyz coordinates have
  *   * x forward
  *   * y to left
  *   * z up
- *   * Note that this is a right handed coordinate system.
- *   * yaw is a rotation of x towards y, i.e. around positive z:
+ * * Note that this is a right handed coordinate system.
+ * * yaw is a rotation of x towards y, i.e. around positive z (counterclockwise):
  *     * `yawMatrix = Matrix3d.createRotationAroundAxisIndex(2, Angle.createDegrees(yawDegrees));`
- *   * pitch is a rotation that raises x towards z, i.e. rotation around negative y:
+ * * pitch is a rotation that raises x towards z, i.e. rotation around **negative y** (**clockwise**):
  *     * `pitchMatrix = Matrix3d.createRotationAroundAxisIndex(1, Angle.createDegrees(-pitchDegrees));`
- *   * roll is rotation of y towards z, i.e. rotation around positive x:
+ * * roll is rotation of y towards z, i.e. rotation around positive x (counterclockwise):
  *     * `rollMatrix = Matrix3d.createRotationAroundAxisIndex(0, Angle.createDegrees(rollDegrees));`
- *   * The YPR matrix is the product
+ * * The YPR matrix is the product
  *     * `result = yawMatrix.multiplyMatrixMatrix(pitchMatrix.multiplyMatrixMatrix(rollMatrix));`
- *   * Note that this is for "column based" matrix, with vectors appearing to the right
- *     * Hence a vector is first rotated by roll, then the pitch, finally yaw.
+ * * Note that this is for "column based" matrix with vectors multiplying on the right of the matrix.
+ * Hence a vector is first rotated by roll, then the pitch, finally yaw. So multiplication order in
+ * the sense of AxisOrder is `RPY` (i.e., XYZ), in contrast to the familiar name `YPR`.
  * @public
  */
 class YawPitchRollAngles {
+    /**
+     * constructor
+     * @param yaw counterclockwise rotation angle around z
+     * @param pitch **clockwise** rotation angle around y
+     * @param roll counterclockwise rotation angle around x
+     * */
     constructor(yaw = Angle_1.Angle.zero(), pitch = Angle_1.Angle.zero(), roll = Angle_1.Angle.zero()) {
         this.yaw = yaw;
         this.pitch = pitch;
         this.roll = roll;
     }
     /** Freeze this YawPitchRollAngles */
-    freeze() { this.yaw.freeze(); this.pitch.freeze(); this.roll.freeze(); return Object.freeze(this); }
-    /** constructor for YawPitchRollAngles with angles in degrees. */
+    freeze() {
+        this.yaw.freeze();
+        this.pitch.freeze();
+        this.roll.freeze();
+        return Object.freeze(this);
+    }
+    /**
+     * constructor for YawPitchRollAngles with angles in degrees.
+     * @param yawDegrees counterclockwise rotation angle (in degrees) around z
+     * @param pitchDegrees **clockwise** rotation angle (in degrees) around y
+     * @param rollDegrees counterclockwise rotation angle (in degrees) around x
+     * */
     static createDegrees(yawDegrees, pitchDegrees, rollDegrees) {
         return new YawPitchRollAngles(Angle_1.Angle.createDegrees(yawDegrees), Angle_1.Angle.createDegrees(pitchDegrees), Angle_1.Angle.createDegrees(rollDegrees));
     }
-    /** constructor for YawPitchRollAngles with angles in radians. */
+    /**
+     * constructor for YawPitchRollAngles with angles in radians.
+     * @param yawRadians counterclockwise rotation angle (in radians) around z
+     * @param pitchRadians **clockwise** rotation angle (in radians) around y
+     * @param rollRadians counterclockwise rotation angle (in radians) around x
+     * */
     static createRadians(yawRadians, pitchRadians, rollRadians) {
         return new YawPitchRollAngles(Angle_1.Angle.createRadians(yawRadians), Angle_1.Angle.createRadians(pitchRadians), Angle_1.Angle.createRadians(rollRadians));
     }
@@ -60,7 +83,10 @@ class YawPitchRollAngles {
         this.pitch = Angle_1.Angle.fromJSON(json.pitch);
         this.roll = Angle_1.Angle.fromJSON(json.roll);
     }
-    /** Convert to a JSON object of form { pitch: 20 , roll: 29.999999999999996 , yaw: 10 }. Any values that are exactly zero (with tolerance `Geometry.smallAngleRadians`) are omitted. */
+    /**
+     * Convert to a JSON object of form { pitch: 20 , roll: 30 , yaw: 10 }. Angles are in degrees.
+     * Any values that are exactly zero (with tolerance `Geometry.smallAngleRadians`) are omitted.
+     **/
     toJSON() {
         const val = {};
         if (!this.pitch.isAlmostZero)
@@ -81,7 +107,7 @@ class YawPitchRollAngles {
         this.roll.setFrom(other.roll);
     }
     /**
-     * * Compare angles between `this` and `other`.
+     * Compare angles between `this` and `other`.
      * * Comparisons are via `isAlmostEqualAllowPeriodShift`.
      * @param other YawPitchRollAngles source
      */
@@ -93,30 +119,47 @@ class YawPitchRollAngles {
     /**
      * Make a copy of this YawPitchRollAngles.
      */
-    clone() { return new YawPitchRollAngles(this.yaw.clone(), this.pitch.clone(), this.roll.clone()); }
+    clone() {
+        return new YawPitchRollAngles(this.yaw.clone(), this.pitch.clone(), this.roll.clone());
+    }
     /**
      * Expand the angles into a (rigid rotation) matrix.
      *
-     * * The returned matrix is "rigid" -- unit length rows and columns, and its transpose is its inverse.
-     * * The "rigid" matrix is always a right handed coordinate system.
+     * * The returned matrix is "rigid" (i.e., it has unit length rows and columns, and its transpose is its inverse).
+     * * The rigid matrix is always a right handed coordinate system.
      * @param result optional pre-allocated `Matrix3d`
      */
     toMatrix3d(result) {
-        const c0 = Math.cos(this.yaw.radians);
-        const s0 = Math.sin(this.yaw.radians);
-        const c1 = Math.cos(this.pitch.radians);
-        const s1 = Math.sin(this.pitch.radians);
-        const c2 = Math.cos(this.roll.radians);
-        const s2 = Math.sin(this.roll.radians);
-        return Matrix3d_1.Matrix3d.createRowValues(c0 * c1, -(s0 * c2 + c0 * s1 * s2), (s0 * s2 - c0 * s1 * c2), s0 * c1, (c0 * c2 - s0 * s1 * s2), -(c0 * s2 + s0 * s1 * c2), s1, c1 * s2, c1 * c2, result);
-    }
-    /** Return the largest angle in radians */
-    maxAbsRadians() {
-        return Geometry_1.Geometry.maxAbsXYZ(this.yaw.radians, this.pitch.radians, this.roll.radians);
-    }
-    /** Return the sum of the angles in squared radians */
-    sumSquaredRadians() {
-        return Geometry_1.Geometry.hypotenuseSquaredXYZ(this.yaw.radians, this.pitch.radians, this.roll.radians);
+        const cz = Math.cos(this.yaw.radians);
+        const sz = Math.sin(this.yaw.radians);
+        const cy = Math.cos(this.pitch.radians);
+        const sy = Math.sin(this.pitch.radians);
+        const cx = Math.cos(this.roll.radians);
+        const sx = Math.sin(this.roll.radians);
+        /**
+        * The axis order is XYZ (i.e., RPY) so the rotation matrix is calculated via rZ*rY*rX where
+        * rX, rY, and rZ are base rotation matrixes:
+        *
+        *     const rX = Matrix3d.createRowValues(
+        *        1, 0, 0,
+        *        0, Math.cos(x), -Math.sin(x),
+        *        0, Math.sin(x), Math.cos(x),
+        *      );
+        *      const rY = Matrix3d.createRowValues(
+        *        Math.cos(y), 0, Math.sin(y),
+        *        0, 1, 0,
+        *        -Math.sin(y), 0, Math.cos(y),
+        *      );
+        *      const rZ = Matrix3d.createRowValues(
+        *        Math.cos(z), -Math.sin(z), 0,
+        *        Math.sin(z), Math.cos(z), 0,
+        *        0, 0, 1,
+        *      );
+        *
+        * Then we replace sin(y) with -sin(y) because y rotation (i.e., pitch) is clockwise (alternatively, you
+        * can use transpose of rY in the matrix multiplication to get the same result)
+        */
+        return Matrix3d_1.Matrix3d.createRowValues(cz * cy, -(sz * cx + cz * sy * sx), (sz * sx - cz * sy * cx), sz * cy, (cz * cx - sz * sy * sx), -(cz * sx + sz * sy * cx), sy, cy * sx, cy * cx, result);
     }
     /** Returns true if this rotation does nothing.
      * * If allowPeriodShift is false, any nonzero angle is considered a non-identity
@@ -132,52 +175,104 @@ class YawPitchRollAngles {
                 && Angle_1.Angle.isAlmostEqualRadiansNoPeriodShift(0.0, this.pitch.radians)
                 && Angle_1.Angle.isAlmostEqualRadiansNoPeriodShift(0.0, this.roll.radians);
     }
+    /** Return the largest angle in radians */
+    maxAbsRadians() {
+        return Geometry_1.Geometry.maxAbsXYZ(this.yaw.radians, this.pitch.radians, this.roll.radians);
+    }
+    /** Return the sum of the angles in squared radians */
+    sumSquaredRadians() {
+        return Geometry_1.Geometry.hypotenuseSquaredXYZ(this.yaw.radians, this.pitch.radians, this.roll.radians);
+    }
     /** Return the largest difference of angles (in radians) between this and other */
     maxDiffRadians(other) {
         return Math.max(this.yaw.radians - other.yaw.radians, this.pitch.radians - other.pitch.radians, this.roll.radians - other.roll.radians);
     }
     /** Return the largest angle in degrees. */
-    maxAbsDegrees() { return Geometry_1.Geometry.maxAbsXYZ(this.yaw.degrees, this.pitch.degrees, this.roll.degrees); }
+    maxAbsDegrees() {
+        return Geometry_1.Geometry.maxAbsXYZ(this.yaw.degrees, this.pitch.degrees, this.roll.degrees);
+    }
     /** Return the sum of squared angles in degrees. */
-    sumSquaredDegrees() { return Geometry_1.Geometry.hypotenuseSquaredXYZ(this.yaw.degrees, this.pitch.degrees, this.roll.degrees); }
+    sumSquaredDegrees() {
+        return Geometry_1.Geometry.hypotenuseSquaredXYZ(this.yaw.degrees, this.pitch.degrees, this.roll.degrees);
+    }
+    /** Return the largest difference of angles (in degrees) between this and other */
+    maxDiffDegrees(other) {
+        return Math.max(this.yaw.degrees - other.yaw.degrees, this.pitch.degrees - other.pitch.degrees, this.roll.degrees - other.roll.degrees);
+    }
     /** Return an object from a Transform as an origin and YawPitchRollAngles. */
     static tryFromTransform(transform) {
-        // bundle up the transform's origin with the angle data extracted from the transform
         return {
-            angles: YawPitchRollAngles.createFromMatrix3d(transform.matrix),
             origin: Point3dVector3d_1.Point3d.createFrom(transform.origin),
+            angles: YawPitchRollAngles.createFromMatrix3d(transform.matrix),
         };
     }
-    /** Attempts to create a YawPitchRollAngles object from an Matrix3d
-     * * This conversion fails if the matrix is not rigid (unit rows and columns, transpose is inverse)
+    /** Attempts to create a YawPitchRollAngles object from a Matrix3d
+     * * This conversion fails if the matrix is not rigid (unit rows and columns, and transpose is inverse)
      * * In the failure case the method's return value is `undefined`.
-     * * In the failure case, if the optional result was supplied, that result will nonetheless be filled with a set of angles.
+     * * In the failure case, if the optional result was supplied, that result will nonetheless be filled with
+     * a set of angles.
      */
     static createFromMatrix3d(matrix, result) {
-        const s1 = matrix.at(2, 0);
-        const c1 = Math.sqrt(matrix.at(2, 1) * matrix.at(2, 1) + matrix.at(2, 2) * matrix.at(2, 2));
-        const pitchA = Angle_1.Angle.createAtan2(s1, c1); // with positive cosine
-        const pitchB = Angle_1.Angle.createAtan2(s1, -c1); // with negative cosine
-        const angles = result ? result : new YawPitchRollAngles(); // default undefined . . .
-        if (c1 < Geometry_1.Geometry.smallAngleRadians) { // This is a radians test !!!
+        /**
+         * The rotation matrix for is
+         *
+         * Matrix3d.createRowValues(
+         *      cz * cy, -(sz * cx + cz * sy * sx), (sz * sx - cz * sy * cx),
+         *      sz * cy, (cz * cx - sz * sy * sx), -(cz * sx + sz * sy * cx),
+         *      sy, cy * sx, cy * cx
+         * );
+         *
+         * where cx = cos(x), sx = sin(x), cy = cos(y), sy = sin(y), cz = cos(z), and sz = sin(z)
+         */
+        const sy = matrix.at(2, 0); // sin(y)
+        const cy = Math.sqrt(matrix.at(2, 1) * matrix.at(2, 1) + matrix.at(2, 2) * matrix.at(2, 2)); // |cos(y)|
+        const pitchA = Angle_1.Angle.createAtan2(sy, cy); // with positive cosine
+        const pitchB = Angle_1.Angle.createAtan2(sy, -cy); // with negative cosine
+        const angles = result ? result : new YawPitchRollAngles();
+        /**
+         * If cos(y) = 0 then y = +-90 degrees so we have a gimbal lock.
+         * This means x and z can be anything as long as their sum x + z is constant.
+         * so we can pick z = 0 and calculate x (or pick x = 0 and calculate z).
+         * Math details can be found
+         * https://en.wikipedia.org/wiki/Gimbal_lock#Loss_of_a_degree_of_freedom_with_Euler_angles
+         *
+         * The rotation matrix for y = +-90 degrees and x = 0 becomes
+         *
+         * Matrix3d.createRowValues(
+         *      0, -sz, -+cz,
+         *      0, cz, -+sz,
+         *      +-1, 0, 0
+         * );
+         *
+         * so z = atan(sz/cz) = atan(-matrix.at(0, 1), matrix.at(1, 1))
+         */
+        if (cy < Geometry_1.Geometry.smallAngleRadians) {
             angles.yaw = Angle_1.Angle.createAtan2(-matrix.at(0, 1), matrix.at(1, 1));
-            angles.pitch = pitchA;
+            angles.pitch = pitchA; // this is an arbitrary choice. can pick pitchB instead.
             angles.roll = Angle_1.Angle.createRadians(0.0);
         }
         else {
+            /**
+             * positive cosine
+             * z = atan(sz/cz) = atan(matrix.at(1, 0), matrix.at(0, 0))
+             * x = atan(sx/cx) = atan(matrix.at(2, 1), matrix.at(2, 2))
+             */
             const yawA = Angle_1.Angle.createAtan2(matrix.at(1, 0), matrix.at(0, 0));
             const rollA = Angle_1.Angle.createAtan2(matrix.at(2, 1), matrix.at(2, 2));
+            // similar with negative cosine
             const yawB = Angle_1.Angle.createAtan2(-matrix.at(1, 0), -matrix.at(0, 0));
             const rollB = Angle_1.Angle.createAtan2(-matrix.at(2, 1), -matrix.at(2, 2));
+            // create YPR
             const yprA = new YawPitchRollAngles(yawA, pitchA, rollA);
             const yprB = new YawPitchRollAngles(yawB, pitchB, rollB);
+            // decide to pick yprA or yprB with smallest magnitude angles
             const absFactor = 0.95;
-            const radiansA = yprA.maxAbsRadians();
-            const radiansB = yprB.maxAbsRadians();
-            if (radiansA < absFactor * radiansB) {
+            const maxRadiansA = yprA.maxAbsRadians();
+            const maxRadiansB = yprB.maxAbsRadians();
+            if (maxRadiansA < absFactor * maxRadiansB) {
                 angles.setFrom(yprA);
             }
-            else if (radiansB < absFactor * radiansA) {
+            else if (maxRadiansB < absFactor * maxRadiansA) {
                 angles.setFrom(yprB);
             }
             else {
@@ -191,6 +286,7 @@ class YawPitchRollAngles {
                 }
             }
         }
+        // sanity check
         const matrix1 = angles.toMatrix3d();
         return matrix.maxDiff(matrix1) < Geometry_1.Geometry.smallAngleRadians ? angles : undefined;
     }

package/lib/cjs/geometry3d/YawPitchRollAngles.js.map

@@ -1 +1 @@
-{"version":3,"file":"YawPitchRollAngles.js","sourceRoot":"","sources":["../../../src/geometry3d/YawPitchRollAngles.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n\r\n/** @packageDocumentation\r\n * @module CartesianGeometry\r\n */\r\n\r\nimport { AngleProps, Geometry } from \"../Geometry\";\r\nimport { Angle } from \"./Angle\";\r\nimport { Matrix3d } from \"./Matrix3d\";\r\nimport { Point3d } from \"./Point3dVector3d\";\r\nimport { Transform } from \"./Transform\";\r\n\r\n/** The properties that define [[YawPitchRollAngles]]. */\r\n/**\r\n * angle properties of a `YawPitchRoll` orientation\r\n * @public\r\n */\r\nexport interface YawPitchRollProps {\r\n  /** yaw field */\r\n  yaw?: AngleProps;\r\n  /** pitch field */\r\n  pitch?: AngleProps;\r\n  /** roll field */\r\n  roll?: AngleProps;\r\n}\r\n// cspell:word Tait\r\n/** Three angles that determine the orientation of an object in space. Sometimes referred to as [Tait–Bryan angles](https://en.wikipedia.org/wiki/Euler_angles).\r\n * * The matrix construction can be replicated by this logic:\r\n * * xyz coordinates have\r\n *   * x forward\r\n *   * y to left\r\n *   * z up\r\n *   * Note that this is a right handed coordinate system.\r\n *   * yaw is a rotation of x towards y, i.e. around positive z:\r\n *     * `yawMatrix = Matrix3d.createRotationAroundAxisIndex(2, Angle.createDegrees(yawDegrees));`\r\n *   * pitch is a rotation that raises x towards z, i.e. rotation around negative y:\r\n *     * `pitchMatrix = Matrix3d.createRotationAroundAxisIndex(1, Angle.createDegrees(-pitchDegrees));`\r\n *   * roll is rotation of y towards z, i.e. rotation around positive x:\r\n *     * `rollMatrix = Matrix3d.createRotationAroundAxisIndex(0, Angle.createDegrees(rollDegrees));`\r\n *   * The YPR matrix is the product\r\n *     * `result = yawMatrix.multiplyMatrixMatrix(pitchMatrix.multiplyMatrixMatrix(rollMatrix));`\r\n *   * Note that this is for \"column based\" matrix, with vectors appearing to the right\r\n *     * Hence a vector is first rotated by roll, then the pitch, finally yaw.\r\n * @public\r\n */\r\nexport class YawPitchRollAngles {\r\n  /** The yaw angle. */\r\n  public yaw: Angle;\r\n  /** The pitch angle. */\r\n  public pitch: Angle;\r\n  /** The roll angle. */\r\n  public roll: Angle;\r\n\r\n  constructor(yaw: Angle = Angle.zero(), pitch: Angle = Angle.zero(), roll: Angle = Angle.zero()) {\r\n    this.yaw = yaw;\r\n    this.pitch = pitch;\r\n    this.roll = roll;\r\n  }\r\n  /** Freeze this YawPitchRollAngles */\r\n  public freeze(): Readonly<this> { this.yaw.freeze(); this.pitch.freeze(); this.roll.freeze(); return Object.freeze(this); }\r\n  /** constructor for YawPitchRollAngles with angles in degrees. */\r\n  public static createDegrees(yawDegrees: number, pitchDegrees: number, rollDegrees: number): YawPitchRollAngles {\r\n    return new YawPitchRollAngles(Angle.createDegrees(yawDegrees), Angle.createDegrees(pitchDegrees), Angle.createDegrees(rollDegrees));\r\n  }\r\n  /** constructor for YawPitchRollAngles with angles in radians. */\r\n  public static createRadians(yawRadians: number, pitchRadians: number, rollRadians: number): YawPitchRollAngles {\r\n    return new YawPitchRollAngles(Angle.createRadians(yawRadians), Angle.createRadians(pitchRadians), Angle.createRadians(rollRadians));\r\n  }\r\n  /** construct a `YawPitchRoll` object from an object with 3 named angles */\r\n  public static fromJSON(json?: YawPitchRollProps): YawPitchRollAngles {\r\n    json = json ? json : {};\r\n    return new YawPitchRollAngles(Angle.fromJSON(json.yaw), Angle.fromJSON(json.pitch), Angle.fromJSON(json.roll));\r\n  }\r\n  /** populate yaw, pitch and roll fields using `Angle.fromJSON` */\r\n  public setFromJSON(json?: YawPitchRollProps): void {\r\n    json = json ? json : {};\r\n    this.yaw = Angle.fromJSON(json.yaw);\r\n    this.pitch = Angle.fromJSON(json.pitch);\r\n    this.roll = Angle.fromJSON(json.roll);\r\n  }\r\n  /** Convert to a JSON object of form { pitch: 20 , roll: 29.999999999999996 , yaw: 10 }. Any values that are exactly zero (with tolerance `Geometry.smallAngleRadians`) are omitted. */\r\n  public toJSON(): YawPitchRollProps {\r\n    const val: YawPitchRollProps = {};\r\n    if (!this.pitch.isAlmostZero)\r\n      val.pitch = this.pitch.toJSON();\r\n    if (!this.roll.isAlmostZero)\r\n      val.roll = this.roll.toJSON();\r\n    if (!this.yaw.isAlmostZero)\r\n      val.yaw = this.yaw.toJSON();\r\n    return val;\r\n  }\r\n  /**\r\n   * Install all rotations from `other` into `this`.\r\n   * @param other YawPitchRollAngles source\r\n   */\r\n  public setFrom(other: YawPitchRollAngles) {\r\n    this.yaw.setFrom(other.yaw);\r\n    this.pitch.setFrom(other.pitch);\r\n    this.roll.setFrom(other.roll);\r\n  }\r\n  /**\r\n   * * Compare angles between `this` and `other`.\r\n   * * Comparisons are via `isAlmostEqualAllowPeriodShift`.\r\n   * @param other YawPitchRollAngles source\r\n   */\r\n  public isAlmostEqual(other: YawPitchRollAngles) {\r\n    return this.yaw.isAlmostEqualAllowPeriodShift(other.yaw)\r\n      && this.pitch.isAlmostEqualAllowPeriodShift(other.pitch)\r\n      && this.roll.isAlmostEqualAllowPeriodShift(other.roll);\r\n  }\r\n  /**\r\n   * Make a copy of this YawPitchRollAngles.\r\n   */\r\n  public clone() { return new YawPitchRollAngles(this.yaw.clone(), this.pitch.clone(), this.roll.clone()); }\r\n  /**\r\n   * Expand the angles into a (rigid rotation) matrix.\r\n   *\r\n   * * The returned matrix is \"rigid\" -- unit length rows and columns, and its transpose is its inverse.\r\n   * * The \"rigid\" matrix is always a right handed coordinate system.\r\n   * @param result optional pre-allocated `Matrix3d`\r\n   */\r\n  public toMatrix3d(result?: Matrix3d) {\r\n    const c0 = Math.cos(this.yaw.radians);\r\n    const s0 = Math.sin(this.yaw.radians);\r\n    const c1 = Math.cos(this.pitch.radians);\r\n    const s1 = Math.sin(this.pitch.radians);\r\n    const c2 = Math.cos(this.roll.radians);\r\n    const s2 = Math.sin(this.roll.radians);\r\n    return Matrix3d.createRowValues(c0 * c1, -(s0 * c2 + c0 * s1 * s2), (s0 * s2 - c0 * s1 * c2), s0 * c1, (c0 * c2 - s0 * s1 * s2), -(c0 * s2 + s0 * s1 * c2), s1, c1 * s2, c1 * c2, result);\r\n  }\r\n  /** Return the largest angle in radians */\r\n  public maxAbsRadians(): number {\r\n    return Geometry.maxAbsXYZ(this.yaw.radians, this.pitch.radians, this.roll.radians);\r\n  }\r\n  /** Return the sum of the angles in squared radians */\r\n  public sumSquaredRadians(): number {\r\n    return Geometry.hypotenuseSquaredXYZ(this.yaw.radians, this.pitch.radians, this.roll.radians);\r\n  }\r\n  /** Returns true if this rotation does nothing.\r\n   * * If allowPeriodShift is false, any nonzero angle is considered a non-identity\r\n   * * If allowPeriodShift is true, all angles are individually allowed to be any multiple of 360 degrees.\r\n   */\r\n  public isIdentity(allowPeriodShift: boolean = true): boolean {\r\n    if (allowPeriodShift)\r\n      return Angle.isAlmostEqualRadiansAllowPeriodShift(0.0, this.yaw.radians)\r\n        && Angle.isAlmostEqualRadiansAllowPeriodShift(0.0, this.pitch.radians)\r\n        && Angle.isAlmostEqualRadiansAllowPeriodShift(0.0, this.roll.radians);\r\n    else\r\n      return Angle.isAlmostEqualRadiansNoPeriodShift(0.0, this.yaw.radians)\r\n        && Angle.isAlmostEqualRadiansNoPeriodShift(0.0, this.pitch.radians)\r\n        && Angle.isAlmostEqualRadiansNoPeriodShift(0.0, this.roll.radians);\r\n  }\r\n  /** Return the largest difference of angles (in radians) between this and other */\r\n  public maxDiffRadians(other: YawPitchRollAngles): number {\r\n    return Math.max(this.yaw.radians - other.yaw.radians, this.pitch.radians - other.pitch.radians, this.roll.radians - other.roll.radians);\r\n  }\r\n  /** Return the largest angle in degrees. */\r\n  public maxAbsDegrees(): number { return Geometry.maxAbsXYZ(this.yaw.degrees, this.pitch.degrees, this.roll.degrees); }\r\n  /** Return the sum of squared angles in degrees. */\r\n  public sumSquaredDegrees(): number { return Geometry.hypotenuseSquaredXYZ(this.yaw.degrees, this.pitch.degrees, this.roll.degrees); }\r\n  /** Return an object from a Transform as an origin and YawPitchRollAngles. */\r\n  public static tryFromTransform(transform: Transform): {\r\n    origin: Point3d;\r\n    angles: YawPitchRollAngles | undefined;\r\n  } {\r\n    // bundle up the transform's origin with the angle data extracted from the transform\r\n    return {\r\n      angles: YawPitchRollAngles.createFromMatrix3d(transform.matrix),\r\n      origin: Point3d.createFrom(transform.origin),\r\n    };\r\n  }\r\n  /** Attempts to create a YawPitchRollAngles object from an Matrix3d\r\n   * * This conversion fails if the matrix is not rigid (unit rows and columns, transpose is inverse)\r\n   * * In the failure case the method's return value is `undefined`.\r\n   * * In the failure case, if the optional result was supplied, that result will nonetheless be filled with a set of angles.\r\n   */\r\n  public static createFromMatrix3d(matrix: Matrix3d, result?: YawPitchRollAngles): YawPitchRollAngles | undefined {\r\n    const s1 = matrix.at(2, 0);\r\n    const c1 = Math.sqrt(matrix.at(2, 1) * matrix.at(2, 1) + matrix.at(2, 2) * matrix.at(2, 2));\r\n    const pitchA = Angle.createAtan2(s1, c1); // with positive cosine\r\n    const pitchB = Angle.createAtan2(s1, -c1); // with negative cosine\r\n    const angles = result ? result : new YawPitchRollAngles(); // default undefined . . .\r\n    if (c1 < Geometry.smallAngleRadians) { // This is a radians test !!!\r\n      angles.yaw = Angle.createAtan2(-matrix.at(0, 1), matrix.at(1, 1));\r\n      angles.pitch = pitchA;\r\n      angles.roll = Angle.createRadians(0.0);\r\n    } else {\r\n      const yawA = Angle.createAtan2(matrix.at(1, 0), matrix.at(0, 0));\r\n      const rollA = Angle.createAtan2(matrix.at(2, 1), matrix.at(2, 2));\r\n      const yawB = Angle.createAtan2(-matrix.at(1, 0), -matrix.at(0, 0));\r\n      const rollB = Angle.createAtan2(-matrix.at(2, 1), -matrix.at(2, 2));\r\n      const yprA = new YawPitchRollAngles(yawA, pitchA, rollA);\r\n      const yprB = new YawPitchRollAngles(yawB, pitchB, rollB);\r\n      const absFactor = 0.95;\r\n      const radiansA = yprA.maxAbsRadians();\r\n      const radiansB = yprB.maxAbsRadians();\r\n      if (radiansA < absFactor * radiansB) {\r\n        angles.setFrom(yprA);\r\n      } else if (radiansB < absFactor * radiansA) {\r\n        angles.setFrom(yprB);\r\n      } else {\r\n        const sumA = yprA.sumSquaredRadians();\r\n        const sumB = yprB.sumSquaredRadians();\r\n        if (sumA <= sumB) {\r\n          angles.setFrom(yprA);\r\n        } else {\r\n          angles.setFrom(yprB);\r\n        }\r\n      }\r\n    }\r\n    const matrix1 = angles.toMatrix3d();\r\n    return matrix.maxDiff(matrix1) < Geometry.smallAngleRadians ? angles : undefined;\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"YawPitchRollAngles.js","sourceRoot":"","sources":["../../../src/geometry3d/YawPitchRollAngles.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;;;AAE/F;;GAEG;AAEH,0CAAmD;AACnD,mCAAgC;AAChC,yCAAsC;AACtC,uDAA4C;AAkB5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,kBAAkB;IAO7B;;;;;SAKK;IACL,YAAY,MAAa,aAAK,CAAC,IAAI,EAAE,EAAE,QAAe,aAAK,CAAC,IAAI,EAAE,EAAE,OAAc,aAAK,CAAC,IAAI,EAAE;QAC5F,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,qCAAqC;IAC9B,MAAM;QACX,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IACD;;;;;SAKK;IACE,MAAM,CAAC,aAAa,CAAC,UAAkB,EAAE,YAAoB,EAAE,WAAmB;QACvF,OAAO,IAAI,kBAAkB,CAC3B,aAAK,CAAC,aAAa,CAAC,UAAU,CAAC,EAC/B,aAAK,CAAC,aAAa,CAAC,YAAY,CAAC,EACjC,aAAK,CAAC,aAAa,CAAC,WAAW,CAAC,CACjC,CAAC;IACJ,CAAC;IACD;;;;;SAKK;IACE,MAAM,CAAC,aAAa,CAAC,UAAkB,EAAE,YAAoB,EAAE,WAAmB;QACvF,OAAO,IAAI,kBAAkB,CAC3B,aAAK,CAAC,aAAa,CAAC,UAAU,CAAC,EAC/B,aAAK,CAAC,aAAa,CAAC,YAAY,CAAC,EACjC,aAAK,CAAC,aAAa,CAAC,WAAW,CAAC,CACjC,CAAC;IACJ,CAAC;IACD,2EAA2E;IACpE,MAAM,CAAC,QAAQ,CAAC,IAAwB;QAC7C,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,kBAAkB,CAC3B,aAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EACxB,aAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAC1B,aAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAC1B,CAAC;IACJ,CAAC;IACD,iEAAiE;IAC1D,WAAW,CAAC,IAAwB;QACzC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACxB,IAAI,CAAC,GAAG,GAAG,aAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,aAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,aAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IACD;;;QAGI;IACG,MAAM;QACX,MAAM,GAAG,GAAsB,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY;YAC1B,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY;YACzB,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY;YACxB,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QAC9B,OAAO,GAAG,CAAC;IACb,CAAC;IACD;;;OAGG;IACI,OAAO,CAAC,KAAyB;QACtC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IACD;;;;OAIG;IACI,aAAa,CAAC,KAAyB;QAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,6BAA6B,CAAC,KAAK,CAAC,GAAG,CAAC;eACnD,IAAI,CAAC,KAAK,CAAC,6BAA6B,CAAC,KAAK,CAAC,KAAK,CAAC;eACrD,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD;;OAEG;IACI,KAAK;QACV,OAAO,IAAI,kBAAkB,CAC3B,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,EAChB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAClB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAClB,CAAC;IACJ,CAAC;IACD;;;;;;OAMG;IACI,UAAU,CAAC,MAAiB;QACjC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACtC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC;;;;;;;;;;;;;;;;;;;;;;UAsBE;QACF,OAAO,mBAAQ,CAAC,eAAe,CAC7B,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAC5D,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAC5D,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EACpB,MAAM,CACP,CAAC;IACJ,CAAC;IACD;;;OAGG;IACI,UAAU,CAAC,mBAA4B,IAAI;QAChD,IAAI,gBAAgB;YAClB,OAAO,aAAK,CAAC,oCAAoC,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;mBACnE,aAAK,CAAC,oCAAoC,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;mBACnE,aAAK,CAAC,oCAAoC,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;;YAExE,OAAO,aAAK,CAAC,iCAAiC,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;mBAChE,aAAK,CAAC,iCAAiC,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;mBAChE,aAAK,CAAC,iCAAiC,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzE,CAAC;IACD,0CAA0C;IACnC,aAAa;QAClB,OAAO,mBAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrF,CAAC;IACD,sDAAsD;IAC/C,iBAAiB;QACtB,OAAO,mBAAQ,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChG,CAAC;IACD,kFAAkF;IAC3E,cAAc,CAAC,KAAyB;QAC7C,OAAO,IAAI,CAAC,GAAG,CACb,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,EACpC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EACxC,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CACvC,CAAC;IACJ,CAAC;IACD,2CAA2C;IACpC,aAAa;QAClB,OAAO,mBAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrF,CAAC;IACD,mDAAmD;IAC5C,iBAAiB;QACtB,OAAO,mBAAQ,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChG,CAAC;IACD,kFAAkF;IAC3E,cAAc,CAAC,KAAyB;QAC7C,OAAO,IAAI,CAAC,GAAG,CACb,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,EACpC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EACxC,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CACvC,CAAC;IACJ,CAAC;IACD,6EAA6E;IACtE,MAAM,CAAC,gBAAgB,CAAC,SAAoB;QAIjD,OAAO;YACL,MAAM,EAAE,yBAAO,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC;YAC5C,MAAM,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,SAAS,CAAC,MAAM,CAAC;SAChE,CAAC;IACJ,CAAC;IACD;;;;;OAKG;IACI,MAAM,CAAC,kBAAkB,CAAC,MAAgB,EAAE,MAA2B;QAC5E;;;;;;;;;;WAUG;QACH,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;QACrC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW;QACxG,MAAM,MAAM,GAAG,aAAK,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,uBAAuB;QACjE,MAAM,MAAM,GAAG,aAAK,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,uBAAuB;QAClE,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,kBAAkB,EAAE,CAAC;QAC1D;;;;;;;;;;;;;;;;WAgBG;QACH,IAAI,EAAE,GAAG,mBAAQ,CAAC,iBAAiB,EAAE;YACnC,MAAM,CAAC,GAAG,GAAG,aAAK,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAClE,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC,wDAAwD;YAC/E,MAAM,CAAC,IAAI,GAAG,aAAK,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;SACxC;aAAM;YACL;;;;eAIG;YACH,MAAM,IAAI,GAAG,aAAK,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACjE,MAAM,KAAK,GAAG,aAAK,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAClE,+BAA+B;YAC/B,MAAM,IAAI,GAAG,aAAK,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACnE,MAAM,KAAK,GAAG,aAAK,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACpE,aAAa;YACb,MAAM,IAAI,GAAG,IAAI,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;YACzD,MAAM,IAAI,GAAG,IAAI,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;YACzD,6DAA6D;YAC7D,MAAM,SAAS,GAAG,IAAI,CAAC;YACvB,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACzC,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACzC,IAAI,WAAW,GAAG,SAAS,GAAG,WAAW,EAAE;gBACzC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;aACtB;iBAAM,IAAI,WAAW,GAAG,SAAS,GAAG,WAAW,EAAE;gBAChD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;aACtB;iBAAM;gBACL,MAAM,IAAI,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACtC,MAAM,IAAI,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACtC,IAAI,IAAI,IAAI,IAAI,EAAE;oBAChB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;iBACtB;qBAAM;oBACL,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;iBACtB;aACF;SACF;QACD,eAAe;QACf,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,mBAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACnF,CAAC;CACF;AAlSD,gDAkSC","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n\r\n/** @packageDocumentation\r\n * @module CartesianGeometry\r\n */\r\n\r\nimport { AngleProps, Geometry } from \"../Geometry\";\r\nimport { Angle } from \"./Angle\";\r\nimport { Matrix3d } from \"./Matrix3d\";\r\nimport { Point3d } from \"./Point3dVector3d\";\r\nimport { Transform } from \"./Transform\";\r\n\r\n// cspell:word Tait\r\n\r\n/**\r\n * angle properties of a `YawPitchRoll` orientation\r\n * @public\r\n */\r\nexport interface YawPitchRollProps {\r\n  /** yaw field */\r\n  yaw?: AngleProps;\r\n  /** pitch field */\r\n  pitch?: AngleProps;\r\n  /** roll field */\r\n  roll?: AngleProps;\r\n}\r\n\r\n/**\r\n * Three angles that determine the orientation of an object in space, sometimes referred to as [Tait–Bryan angles]\r\n * (https://en.wikipedia.org/wiki/Euler_angles).\r\n * * The matrix construction can be replicated by this logic:\r\n * * xyz coordinates have\r\n *   * x forward\r\n *   * y to left\r\n *   * z up\r\n * * Note that this is a right handed coordinate system.\r\n * * yaw is a rotation of x towards y, i.e. around positive z (counterclockwise):\r\n *     * `yawMatrix = Matrix3d.createRotationAroundAxisIndex(2, Angle.createDegrees(yawDegrees));`\r\n * * pitch is a rotation that raises x towards z, i.e. rotation around **negative y** (**clockwise**):\r\n *     * `pitchMatrix = Matrix3d.createRotationAroundAxisIndex(1, Angle.createDegrees(-pitchDegrees));`\r\n * * roll is rotation of y towards z, i.e. rotation around positive x (counterclockwise):\r\n *     * `rollMatrix = Matrix3d.createRotationAroundAxisIndex(0, Angle.createDegrees(rollDegrees));`\r\n * * The YPR matrix is the product\r\n *     * `result = yawMatrix.multiplyMatrixMatrix(pitchMatrix.multiplyMatrixMatrix(rollMatrix));`\r\n * * Note that this is for \"column based\" matrix with vectors multiplying on the right of the matrix.\r\n * Hence a vector is first rotated by roll, then the pitch, finally yaw. So multiplication order in\r\n * the sense of AxisOrder is `RPY` (i.e., XYZ), in contrast to the familiar name `YPR`.\r\n * @public\r\n */\r\nexport class YawPitchRollAngles {\r\n  /** The yaw angle: counterclockwise rotation angle around z  */\r\n  public yaw: Angle;\r\n  /** The pitch angle: **clockwise** rotation angle around y */\r\n  public pitch: Angle;\r\n  /** The roll angle: counterclockwise rotation angle around x */\r\n  public roll: Angle;\r\n  /**\r\n   * constructor\r\n   * @param yaw counterclockwise rotation angle around z\r\n   * @param pitch **clockwise** rotation angle around y\r\n   * @param roll counterclockwise rotation angle around x\r\n   * */\r\n  constructor(yaw: Angle = Angle.zero(), pitch: Angle = Angle.zero(), roll: Angle = Angle.zero()) {\r\n    this.yaw = yaw;\r\n    this.pitch = pitch;\r\n    this.roll = roll;\r\n  }\r\n  /** Freeze this YawPitchRollAngles */\r\n  public freeze(): Readonly<this> {\r\n    this.yaw.freeze();\r\n    this.pitch.freeze();\r\n    this.roll.freeze();\r\n    return Object.freeze(this);\r\n  }\r\n  /**\r\n   * constructor for YawPitchRollAngles with angles in degrees.\r\n   * @param yawDegrees counterclockwise rotation angle (in degrees) around z\r\n   * @param pitchDegrees **clockwise** rotation angle (in degrees) around y\r\n   * @param rollDegrees counterclockwise rotation angle (in degrees) around x\r\n   * */\r\n  public static createDegrees(yawDegrees: number, pitchDegrees: number, rollDegrees: number): YawPitchRollAngles {\r\n    return new YawPitchRollAngles(\r\n      Angle.createDegrees(yawDegrees),\r\n      Angle.createDegrees(pitchDegrees),\r\n      Angle.createDegrees(rollDegrees)\r\n    );\r\n  }\r\n  /**\r\n   * constructor for YawPitchRollAngles with angles in radians.\r\n   * @param yawRadians counterclockwise rotation angle (in radians) around z\r\n   * @param pitchRadians **clockwise** rotation angle (in radians) around y\r\n   * @param rollRadians counterclockwise rotation angle (in radians) around x\r\n   * */\r\n  public static createRadians(yawRadians: number, pitchRadians: number, rollRadians: number): YawPitchRollAngles {\r\n    return new YawPitchRollAngles(\r\n      Angle.createRadians(yawRadians),\r\n      Angle.createRadians(pitchRadians),\r\n      Angle.createRadians(rollRadians)\r\n    );\r\n  }\r\n  /** construct a `YawPitchRoll` object from an object with 3 named angles */\r\n  public static fromJSON(json?: YawPitchRollProps): YawPitchRollAngles {\r\n    json = json ? json : {};\r\n    return new YawPitchRollAngles(\r\n      Angle.fromJSON(json.yaw),\r\n      Angle.fromJSON(json.pitch),\r\n      Angle.fromJSON(json.roll)\r\n    );\r\n  }\r\n  /** populate yaw, pitch and roll fields using `Angle.fromJSON` */\r\n  public setFromJSON(json?: YawPitchRollProps): void {\r\n    json = json ? json : {};\r\n    this.yaw = Angle.fromJSON(json.yaw);\r\n    this.pitch = Angle.fromJSON(json.pitch);\r\n    this.roll = Angle.fromJSON(json.roll);\r\n  }\r\n  /**\r\n   * Convert to a JSON object of form { pitch: 20 , roll: 30 , yaw: 10 }. Angles are in degrees.\r\n   * Any values that are exactly zero (with tolerance `Geometry.smallAngleRadians`) are omitted.\r\n   **/\r\n  public toJSON(): YawPitchRollProps {\r\n    const val: YawPitchRollProps = {};\r\n    if (!this.pitch.isAlmostZero)\r\n      val.pitch = this.pitch.toJSON();\r\n    if (!this.roll.isAlmostZero)\r\n      val.roll = this.roll.toJSON();\r\n    if (!this.yaw.isAlmostZero)\r\n      val.yaw = this.yaw.toJSON();\r\n    return val;\r\n  }\r\n  /**\r\n   * Install all rotations from `other` into `this`.\r\n   * @param other YawPitchRollAngles source\r\n   */\r\n  public setFrom(other: YawPitchRollAngles) {\r\n    this.yaw.setFrom(other.yaw);\r\n    this.pitch.setFrom(other.pitch);\r\n    this.roll.setFrom(other.roll);\r\n  }\r\n  /**\r\n   * Compare angles between `this` and `other`.\r\n   * * Comparisons are via `isAlmostEqualAllowPeriodShift`.\r\n   * @param other YawPitchRollAngles source\r\n   */\r\n  public isAlmostEqual(other: YawPitchRollAngles) {\r\n    return this.yaw.isAlmostEqualAllowPeriodShift(other.yaw)\r\n      && this.pitch.isAlmostEqualAllowPeriodShift(other.pitch)\r\n      && this.roll.isAlmostEqualAllowPeriodShift(other.roll);\r\n  }\r\n  /**\r\n   * Make a copy of this YawPitchRollAngles.\r\n   */\r\n  public clone() {\r\n    return new YawPitchRollAngles(\r\n      this.yaw.clone(),\r\n      this.pitch.clone(),\r\n      this.roll.clone()\r\n    );\r\n  }\r\n  /**\r\n   * Expand the angles into a (rigid rotation) matrix.\r\n   *\r\n   * * The returned matrix is \"rigid\" (i.e., it has unit length rows and columns, and its transpose is its inverse).\r\n   * * The rigid matrix is always a right handed coordinate system.\r\n   * @param result optional pre-allocated `Matrix3d`\r\n   */\r\n  public toMatrix3d(result?: Matrix3d) {\r\n    const cz = Math.cos(this.yaw.radians);\r\n    const sz = Math.sin(this.yaw.radians);\r\n    const cy = Math.cos(this.pitch.radians);\r\n    const sy = Math.sin(this.pitch.radians);\r\n    const cx = Math.cos(this.roll.radians);\r\n    const sx = Math.sin(this.roll.radians);\r\n    /**\r\n    * The axis order is XYZ (i.e., RPY) so the rotation matrix is calculated via rZ*rY*rX where\r\n    * rX, rY, and rZ are base rotation matrixes:\r\n    *\r\n    *     const rX = Matrix3d.createRowValues(\r\n    *        1, 0, 0,\r\n    *        0, Math.cos(x), -Math.sin(x),\r\n    *        0, Math.sin(x), Math.cos(x),\r\n    *      );\r\n    *      const rY = Matrix3d.createRowValues(\r\n    *        Math.cos(y), 0, Math.sin(y),\r\n    *        0, 1, 0,\r\n    *        -Math.sin(y), 0, Math.cos(y),\r\n    *      );\r\n    *      const rZ = Matrix3d.createRowValues(\r\n    *        Math.cos(z), -Math.sin(z), 0,\r\n    *        Math.sin(z), Math.cos(z), 0,\r\n    *        0, 0, 1,\r\n    *      );\r\n    *\r\n    * Then we replace sin(y) with -sin(y) because y rotation (i.e., pitch) is clockwise (alternatively, you\r\n    * can use transpose of rY in the matrix multiplication to get the same result)\r\n    */\r\n    return Matrix3d.createRowValues(\r\n      cz * cy, -(sz * cx + cz * sy * sx), (sz * sx - cz * sy * cx),\r\n      sz * cy, (cz * cx - sz * sy * sx), -(cz * sx + sz * sy * cx),\r\n      sy, cy * sx, cy * cx,\r\n      result\r\n    );\r\n  }\r\n  /** Returns true if this rotation does nothing.\r\n   * * If allowPeriodShift is false, any nonzero angle is considered a non-identity\r\n   * * If allowPeriodShift is true, all angles are individually allowed to be any multiple of 360 degrees.\r\n   */\r\n  public isIdentity(allowPeriodShift: boolean = true): boolean {\r\n    if (allowPeriodShift)\r\n      return Angle.isAlmostEqualRadiansAllowPeriodShift(0.0, this.yaw.radians)\r\n        && Angle.isAlmostEqualRadiansAllowPeriodShift(0.0, this.pitch.radians)\r\n        && Angle.isAlmostEqualRadiansAllowPeriodShift(0.0, this.roll.radians);\r\n    else\r\n      return Angle.isAlmostEqualRadiansNoPeriodShift(0.0, this.yaw.radians)\r\n        && Angle.isAlmostEqualRadiansNoPeriodShift(0.0, this.pitch.radians)\r\n        && Angle.isAlmostEqualRadiansNoPeriodShift(0.0, this.roll.radians);\r\n  }\r\n  /** Return the largest angle in radians */\r\n  public maxAbsRadians(): number {\r\n    return Geometry.maxAbsXYZ(this.yaw.radians, this.pitch.radians, this.roll.radians);\r\n  }\r\n  /** Return the sum of the angles in squared radians */\r\n  public sumSquaredRadians(): number {\r\n    return Geometry.hypotenuseSquaredXYZ(this.yaw.radians, this.pitch.radians, this.roll.radians);\r\n  }\r\n  /** Return the largest difference of angles (in radians) between this and other */\r\n  public maxDiffRadians(other: YawPitchRollAngles): number {\r\n    return Math.max(\r\n      this.yaw.radians - other.yaw.radians,\r\n      this.pitch.radians - other.pitch.radians,\r\n      this.roll.radians - other.roll.radians\r\n    );\r\n  }\r\n  /** Return the largest angle in degrees. */\r\n  public maxAbsDegrees(): number {\r\n    return Geometry.maxAbsXYZ(this.yaw.degrees, this.pitch.degrees, this.roll.degrees);\r\n  }\r\n  /** Return the sum of squared angles in degrees. */\r\n  public sumSquaredDegrees(): number {\r\n    return Geometry.hypotenuseSquaredXYZ(this.yaw.degrees, this.pitch.degrees, this.roll.degrees);\r\n  }\r\n  /** Return the largest difference of angles (in degrees) between this and other */\r\n  public maxDiffDegrees(other: YawPitchRollAngles): number {\r\n    return Math.max(\r\n      this.yaw.degrees - other.yaw.degrees,\r\n      this.pitch.degrees - other.pitch.degrees,\r\n      this.roll.degrees - other.roll.degrees\r\n    );\r\n  }\r\n  /** Return an object from a Transform as an origin and YawPitchRollAngles. */\r\n  public static tryFromTransform(transform: Transform): {\r\n    origin: Point3d;\r\n    angles: YawPitchRollAngles | undefined;\r\n  } {\r\n    return {\r\n      origin: Point3d.createFrom(transform.origin),\r\n      angles: YawPitchRollAngles.createFromMatrix3d(transform.matrix),\r\n    };\r\n  }\r\n  /** Attempts to create a YawPitchRollAngles object from a Matrix3d\r\n   * * This conversion fails if the matrix is not rigid (unit rows and columns, and transpose is inverse)\r\n   * * In the failure case the method's return value is `undefined`.\r\n   * * In the failure case, if the optional result was supplied, that result will nonetheless be filled with\r\n   * a set of angles.\r\n   */\r\n  public static createFromMatrix3d(matrix: Matrix3d, result?: YawPitchRollAngles): YawPitchRollAngles | undefined {\r\n    /**\r\n     * The rotation matrix for is\r\n     *\r\n     * Matrix3d.createRowValues(\r\n     *      cz * cy, -(sz * cx + cz * sy * sx), (sz * sx - cz * sy * cx),\r\n     *      sz * cy, (cz * cx - sz * sy * sx), -(cz * sx + sz * sy * cx),\r\n     *      sy, cy * sx, cy * cx\r\n     * );\r\n     *\r\n     * where cx = cos(x), sx = sin(x), cy = cos(y), sy = sin(y), cz = cos(z), and sz = sin(z)\r\n     */\r\n    const sy = matrix.at(2, 0); // sin(y)\r\n    const cy = Math.sqrt(matrix.at(2, 1) * matrix.at(2, 1) + matrix.at(2, 2) * matrix.at(2, 2)); // |cos(y)|\r\n    const pitchA = Angle.createAtan2(sy, cy); // with positive cosine\r\n    const pitchB = Angle.createAtan2(sy, -cy); // with negative cosine\r\n    const angles = result ? result : new YawPitchRollAngles();\r\n    /**\r\n     * If cos(y) = 0 then y = +-90 degrees so we have a gimbal lock.\r\n     * This means x and z can be anything as long as their sum x + z is constant.\r\n     * so we can pick z = 0 and calculate x (or pick x = 0 and calculate z).\r\n     * Math details can be found\r\n     * https://en.wikipedia.org/wiki/Gimbal_lock#Loss_of_a_degree_of_freedom_with_Euler_angles\r\n     *\r\n     * The rotation matrix for y = +-90 degrees and x = 0 becomes\r\n     *\r\n     * Matrix3d.createRowValues(\r\n     *      0, -sz, -+cz,\r\n     *      0, cz, -+sz,\r\n     *      +-1, 0, 0\r\n     * );\r\n     *\r\n     * so z = atan(sz/cz) = atan(-matrix.at(0, 1), matrix.at(1, 1))\r\n     */\r\n    if (cy < Geometry.smallAngleRadians) {\r\n      angles.yaw = Angle.createAtan2(-matrix.at(0, 1), matrix.at(1, 1));\r\n      angles.pitch = pitchA; // this is an arbitrary choice. can pick pitchB instead.\r\n      angles.roll = Angle.createRadians(0.0);\r\n    } else {\r\n      /**\r\n       * positive cosine\r\n       * z = atan(sz/cz) = atan(matrix.at(1, 0), matrix.at(0, 0))\r\n       * x = atan(sx/cx) = atan(matrix.at(2, 1), matrix.at(2, 2))\r\n       */\r\n      const yawA = Angle.createAtan2(matrix.at(1, 0), matrix.at(0, 0));\r\n      const rollA = Angle.createAtan2(matrix.at(2, 1), matrix.at(2, 2));\r\n      // similar with negative cosine\r\n      const yawB = Angle.createAtan2(-matrix.at(1, 0), -matrix.at(0, 0));\r\n      const rollB = Angle.createAtan2(-matrix.at(2, 1), -matrix.at(2, 2));\r\n      // create YPR\r\n      const yprA = new YawPitchRollAngles(yawA, pitchA, rollA);\r\n      const yprB = new YawPitchRollAngles(yawB, pitchB, rollB);\r\n      // decide to pick yprA or yprB with smallest magnitude angles\r\n      const absFactor = 0.95;\r\n      const maxRadiansA = yprA.maxAbsRadians();\r\n      const maxRadiansB = yprB.maxAbsRadians();\r\n      if (maxRadiansA < absFactor * maxRadiansB) {\r\n        angles.setFrom(yprA);\r\n      } else if (maxRadiansB < absFactor * maxRadiansA) {\r\n        angles.setFrom(yprB);\r\n      } else {\r\n        const sumA = yprA.sumSquaredRadians();\r\n        const sumB = yprB.sumSquaredRadians();\r\n        if (sumA <= sumB) {\r\n          angles.setFrom(yprA);\r\n        } else {\r\n          angles.setFrom(yprB);\r\n        }\r\n      }\r\n    }\r\n    // sanity check\r\n    const matrix1 = angles.toMatrix3d();\r\n    return matrix.maxDiff(matrix1) < Geometry.smallAngleRadians ? angles : undefined;\r\n  }\r\n}\r\n"]}

package/lib/cjs/polyface/PolyfaceBuilder.d.ts

@@ -114,7 +114,7 @@ export declare class PolyfaceBuilder extends NullGeometryHandler {
     addPoint(xyz: Point3d): number;
     /**
      * Announce point coordinates.
-     * @deprecated Use addPoint instead.
+     * @deprecated in 3.x. Use addPoint instead.
      */
     findOrAddPoint(xyz: Point3d): number;
     /**
@@ -123,7 +123,7 @@ export declare class PolyfaceBuilder extends NullGeometryHandler {
     addParamXY(x: number, y: number): number;
     /**
      * Announce uv parameter coordinates.
-     * @deprecated Use addParamXY instead.
+     * @deprecated in 3.x. Use addParamXY instead.
      */
     findOrAddParamXY(x: number, y: number): number;
     private static _workPointFindOrAddA;
@@ -155,7 +155,7 @@ export declare class PolyfaceBuilder extends NullGeometryHandler {
     addParamInGrowableXYArray(data: GrowableXYArray, index: number): number | undefined;
     /**
      * Announce uv parameter coordinates.
-     * @deprecated Use addParamInGrowableXYArray instead.
+     * @deprecated in 3.x. Use addParamInGrowableXYArray instead.
      */
     findOrAddParamInGrowableXYArray(data: GrowableXYArray, index: number): number | undefined;
     /**
@@ -177,7 +177,7 @@ export declare class PolyfaceBuilder extends NullGeometryHandler {
     addPointXYZ(x: number, y: number, z: number): number;
     /**
      * Announce point coordinates.
-     * @deprecated Use addPointXYZ instead.
+     * @deprecated in 3.x. Use addPointXYZ instead.
      */
     findOrAddPointXYZ(x: number, y: number, z: number): number;
     /** Returns a transform who can be applied to points on a triangular facet in order to obtain UV parameters. */

package/lib/cjs/polyface/PolyfaceBuilder.js

@@ -302,7 +302,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     }
     /**
      * Announce point coordinates.
-     * @deprecated Use addPoint instead.
+     * @deprecated in 3.x. Use addPoint instead.
      */
     findOrAddPoint(xyz) {
         return this.addPoint(xyz);
@@ -315,7 +315,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     }
     /**
      * Announce uv parameter coordinates.
-     * @deprecated Use addParamXY instead.
+     * @deprecated in 3.x. Use addParamXY instead.
      */
     findOrAddParamXY(x, y) {
         return this.addParamXY(x, y);
@@ -378,7 +378,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     }
     /**
      * Announce uv parameter coordinates.
-     * @deprecated Use addParamInGrowableXYArray instead.
+     * @deprecated in 3.x. Use addParamInGrowableXYArray instead.
      */
     findOrAddParamInGrowableXYArray(data, index) {
         return this.addParamInGrowableXYArray(data, index);
@@ -418,7 +418,7 @@ class PolyfaceBuilder extends GeometryHandler_1.NullGeometryHandler {
     }
     /**
      * Announce point coordinates.
-     * @deprecated Use addPointXYZ instead.
+     * @deprecated in 3.x. Use addPointXYZ instead.
      */
     findOrAddPointXYZ(x, y, z) {
         return this.addPointXYZ(x, y, z);