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

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

@@ -5,19 +5,28 @@ import { AxisOrder } from "../Geometry";
 import { Angle } from "./Angle";
 import { Matrix3d } from "./Matrix3d";
 /**
- * * OrderedRotationAngles represents a non-trivial rotation using three simple axis rotation angles, and an order in which to apply them.
- * * This class accommodates application-specific interpretation of "Multiplying 3 rotation matrices" with regard to
+ * represents a non-trivial rotation using three simple axis rotation angles and an order in which to apply them.
+ * * This class accommodates application-specific interpretation of "multiplying 3 rotation matrices" with regard to
  *   * Whether a "vector" is a "row" or a "column"
- *   * The order in which the X,Y, Z rotations are applied.
+ *   * The order in which the X,Y,Z rotations are applied.
+ * * This class bakes in angle rotation directions via create functions (i.e., createRadians, createDegrees, and
+ * createAngles) so you can define each of the 3 rotations to be clockwise or counterclockwise. The default
+ * rotation is counterclockwise.
  * * Within the imodel geometry library, the preferred rotation order is encapsulated in `YawPitchRollAngles`.
  * @alpha
  */
 export declare class OrderedRotationAngles {
+    /** rotation around x */
     private _x;
+    /** rotation around y */
     private _y;
+    /** rotation around z */
     private _z;
+    /** rotation order. For example XYZ means to rotate around x axis first, then y axis, and finally Z axis */
     private _order;
+    /** treat vectors as matrix columns */
     private static _sTreatVectorsAsColumns;
+    /** constructor */
     private constructor();
     /** (Property accessor) Return the `AxisOrder` controlling matrix multiplication order. */
     get order(): AxisOrder;
@@ -39,23 +48,71 @@ export declare class OrderedRotationAngles {
     get zDegrees(): number;
     /** (Property accessor) Return the angle of rotation around z, in radians */
     get zRadians(): number;
-    /** Flag controlling whether vectors are treated as rows or as columns */
+    /** the flag controlling whether vectors are treated as rows or as columns */
     static get treatVectorsAsColumns(): boolean;
     static set treatVectorsAsColumns(value: boolean);
-    /** Create an OrderedRotationAngles from three angles and an ordering in which to apply them when rotating.
+    /**
+     * Create an OrderedRotationAngles from three angles (in radians), an ordering in which to apply them when
+     * rotating, and a flag triple controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * @param xRadians rotation around x
+     * @param yRadians rotation around y
+     * @param zRadians rotation around z
+     * @param order left to right order of axis names identifies the order that rotations are applied.
+     * For example XYZ means to rotate around x axis first, then y axis, and finally Z axis.
+     * * Note that rotation order is reverse of rotation matrix multiplication so for XYZ the rotation
+     * matrix multiplication would be zRot*yRot*xRot
+     * @param xyzRotationIsClockwise the flags controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * rotation direction of x,y,z: true ---> clockwise - false ---> counterclockwise.
+     * * if xyzRotationIsClockwise is undefined it's set to [false, false, false].
+     * @param result caller-allocated OrderedRotationAngles
+     */
+    static createRadians(xRadians: number, yRadians: number, zRadians: number, order: AxisOrder, xyzRotationIsClockwise?: [boolean, boolean, boolean], result?: OrderedRotationAngles): OrderedRotationAngles;
+    /**
+     * Create an OrderedRotationAngles from three angles (in degrees) and an ordering in which to apply
+     * them when rotating.
+     * @param xDegrees rotation around x
+     * @param yDegrees rotation around y
+     * @param zDegrees rotation around z
+     * @param order left to right order of axis names identifies the order that rotations are applied.
+     * For example XYZ means to rotate around x axis first, then y axis, and finally Z axis.
+     * * Note that rotation order is reverse of rotation matrix multiplication so for XYZ the rotation
+     * matrix multiplication would be zRot*yRot*xRot
+     * @param xyzRotationIsClockwise the flags controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * rotation direction of x,y,z: true ---> clockwise - false ---> counterclockwise.
+     * * if xyzRotationIsClockwise is undefined it's set to [false, false, false].
+     * @param result caller-allocated OrderedRotationAngles
+     */
+    static createDegrees(xDegrees: number, yDegrees: number, zDegrees: number, order: AxisOrder, xyzRotationIsClockwise?: [boolean, boolean, boolean], result?: OrderedRotationAngles): OrderedRotationAngles;
+    /**
+     * Create an OrderedRotationAngles from three angles, an ordering in which to apply them when rotating,
+     * and a flag triple controlling whether direction of x,y,z is clockwise or counterclockwise.
      * @param xRotation rotation around x
      * @param yRotation rotation around y
      * @param zRotation rotation around z
-     * @param axisOrder right to left order of axis names identifies the order that rotations are applied to xyz data.
+     * @param order left to right order of axis names identifies the order that rotations are applied
+     * For example XYZ means to rotate around x axis first, then y axis, and finally Z axis.
+     * * Note that rotation order is reverse of rotation matrix multiplication so for XYZ the rotation
+     * matrix multiplication would be zRot*yRot*xRot
+     * @param xyzRotationIsClockwise the flags controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * rotation direction of x,y,z: true ---> clockwise - false ---> counterclockwise.
+     * * if xyzRotationIsClockwise is undefined it's set to [false, false, false].
+     * @param result caller-allocated OrderedRotationAngles
      */
-    static createAngles(xRotation: Angle, yRotation: Angle, zRotation: Angle, order: AxisOrder, result?: OrderedRotationAngles): OrderedRotationAngles;
-    /** Create an OrderedRotationAngles from three angles (in radians) and an ordering in which to apply them when rotating. */
-    static createRadians(xRadians: number, yRadians: number, zRadians: number, order: AxisOrder, result?: OrderedRotationAngles): OrderedRotationAngles;
-    /** Create an OrderedRotationAngles from three angles (in degrees) and an ordering in which to apply them when rotating. */
-    static createDegrees(xDegrees: number, yDegrees: number, zDegrees: number, order: AxisOrder, result?: OrderedRotationAngles): OrderedRotationAngles;
-    /** Create an OrderedRotationAngles from a 3x3 rotational matrix, given the ordering of axis rotations that the matrix derives from. */
-    static createFromMatrix3d(matrix: Matrix3d, order: AxisOrder, result?: OrderedRotationAngles): OrderedRotationAngles;
-    /** Create a 3x3 rotational matrix from this OrderedRotationAngles. */
+    static createAngles(xRotation: Angle, yRotation: Angle, zRotation: Angle, order: AxisOrder, xyzRotationIsClockwise?: [boolean, boolean, boolean], result?: OrderedRotationAngles): OrderedRotationAngles;
+    /**
+     * Create an OrderedRotationAngles from a 3x3 rotational matrix, given the ordering of axis rotations
+     * that the matrix derives from.
+     * * This function creates an OrderedRotationAngles with default angle rotation directions, i.e.,
+     * it assumes all x, y, and z rotations are counterclockwise.
+     * * 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.
+     * */
+    static createFromMatrix3d(matrix: Matrix3d, order: AxisOrder, result?: OrderedRotationAngles): OrderedRotationAngles | undefined;
+    /**
+     * Create a 3x3 rotational matrix from this OrderedRotationAngles.
+     ** math details can be found at docs/learning/geometry/Angle.md
+     **/
     toMatrix3d(result?: Matrix3d): Matrix3d;
 }
 //# sourceMappingURL=OrderedRotationAngles.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"OrderedRotationAngles.d.ts","sourceRoot":"","sources":["../../../src/geometry3d/OrderedRotationAngles.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;GAOG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,EAAE,CAAQ;IAClB,OAAO,CAAC,EAAE,CAAQ;IAClB,OAAO,CAAC,EAAE,CAAQ;IAClB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAAkB;IAExD,OAAO;IAOP,0FAA0F;IAC1F,IAAW,KAAK,IAAI,SAAS,CAAwB;IACrD,gFAAgF;IAChF,IAAW,MAAM,IAAI,KAAK,CAA4B;IACtD,gFAAgF;IAChF,IAAW,MAAM,IAAI,KAAK,CAA4B;IACtD,gFAAgF;IAChF,IAAW,MAAM,IAAI,KAAK,CAA4B;IACtD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAA4B;IACzD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAA4B;IACzD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAA4B;IACzD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAA4B;IACzD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAA4B;IACzD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAA4B;IACzD,yEAAyE;IACzE,WAAkB,qBAAqB,IAAI,OAAO,CAA0D;IAC5G,WAAkB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAA4D;IAElH;;;;;OAKG;WACW,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,qBAAqB;IAWzJ,2HAA2H;WAC7G,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,qBAAqB;IAW1J,2HAA2H;WAC7G,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,qBAAqB;IAW1J,uIAAuI;WACzH,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,qBAAqB;IA+F3H,sEAAsE;IAC/D,UAAU,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ;CA6D/C"}
+{"version":3,"file":"OrderedRotationAngles.d.ts","sourceRoot":"","sources":["../../../src/geometry3d/OrderedRotationAngles.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,EAAE,SAAS,EAAY,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC;;;;;;;;;;GAUG;AACH,qBAAa,qBAAqB;IAChC,wBAAwB;IACxB,OAAO,CAAC,EAAE,CAAQ;IAClB,wBAAwB;IACxB,OAAO,CAAC,EAAE,CAAQ;IAClB,wBAAwB;IACxB,OAAO,CAAC,EAAE,CAAQ;IAClB,2GAA2G;IAC3G,OAAO,CAAC,MAAM,CAAY;IAC1B,sCAAsC;IACtC,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAAkB;IACxD,kBAAkB;IAClB,OAAO;IAMP,0FAA0F;IAC1F,IAAW,KAAK,IAAI,SAAS,CAE5B;IACD,gFAAgF;IAChF,IAAW,MAAM,IAAI,KAAK,CAEzB;IACD,gFAAgF;IAChF,IAAW,MAAM,IAAI,KAAK,CAEzB;IACD,gFAAgF;IAChF,IAAW,MAAM,IAAI,KAAK,CAEzB;IACD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAE5B;IACD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAE5B;IACD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAE5B;IACD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAE5B;IACD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAE5B;IACD,4EAA4E;IAC5E,IAAW,QAAQ,IAAI,MAAM,CAE5B;IACD,6EAA6E;IAC7E,WAAkB,qBAAqB,IAAI,OAAO,CAEjD;IACD,WAAkB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAErD;IACD;;;;;;;;;;;;;;OAcG;WACW,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAChG,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,qBAAqB;IAqB9G;;;;;;;;;;;;;;OAcG;WACW,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAChG,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,qBAAqB;IAU9G;;;;;;;;;;;;;;OAcG;WACW,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAC/F,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,qBAAqB;IAU9G;;;;;;;;SAQK;WACS,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,qBAAqB,GACjG,qBAAqB,GAAG,SAAS;IAoHnC;;;QAGI;IACG,UAAU,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ;CA2D/C"}

package/lib/cjs/geometry3d/OrderedRotationAngles.js

@@ -11,15 +11,20 @@ exports.OrderedRotationAngles = void 0;
 const Geometry_1 = require("../Geometry");
 const Angle_1 = require("./Angle");
 const Matrix3d_1 = require("./Matrix3d");
+/* cspell:word cxcz, cxsz, cxcy, cxsy, sxcz, sxsz, sxcy, sxsy, cycz, cysz, sycz, sysz */
 /**
- * * OrderedRotationAngles represents a non-trivial rotation using three simple axis rotation angles, and an order in which to apply them.
- * * This class accommodates application-specific interpretation of "Multiplying 3 rotation matrices" with regard to
+ * represents a non-trivial rotation using three simple axis rotation angles and an order in which to apply them.
+ * * This class accommodates application-specific interpretation of "multiplying 3 rotation matrices" with regard to
  *   * Whether a "vector" is a "row" or a "column"
- *   * The order in which the X,Y, Z rotations are applied.
+ *   * The order in which the X,Y,Z rotations are applied.
+ * * This class bakes in angle rotation directions via create functions (i.e., createRadians, createDegrees, and
+ * createAngles) so you can define each of the 3 rotations to be clockwise or counterclockwise. The default
+ * rotation is counterclockwise.
  * * Within the imodel geometry library, the preferred rotation order is encapsulated in `YawPitchRollAngles`.
  * @alpha
  */
 class OrderedRotationAngles {
+    /** constructor */
     constructor(x, y, z, axisOrder) {
         this._x = x;
         this._y = y;
@@ -27,149 +32,224 @@ class OrderedRotationAngles {
         this._order = axisOrder;
     }
     /** (Property accessor) Return the `AxisOrder` controlling matrix multiplication order. */
-    get order() { return this._order; }
+    get order() {
+        return this._order;
+    }
     /** (Property accessor) Return the strongly typed angle of rotation around x. */
-    get xAngle() { return this._x.clone(); }
+    get xAngle() {
+        return this._x.clone();
+    }
     /** (Property accessor) Return the strongly typed angle of rotation around y. */
-    get yAngle() { return this._y.clone(); }
+    get yAngle() {
+        return this._y.clone();
+    }
     /** (Property accessor) Return the strongly typed angle of rotation around z. */
-    get zAngle() { return this._z.clone(); }
+    get zAngle() {
+        return this._z.clone();
+    }
     /** (Property accessor) Return the angle of rotation around x, in degrees */
-    get xDegrees() { return this._x.degrees; }
+    get xDegrees() {
+        return this._x.degrees;
+    }
     /** (Property accessor) Return the angle of rotation around y, in degrees */
-    get xRadians() { return this._x.radians; }
+    get xRadians() {
+        return this._x.radians;
+    }
     /** (Property accessor) Return the angle of rotation around z, in degrees */
-    get yDegrees() { return this._y.degrees; }
+    get yDegrees() {
+        return this._y.degrees;
+    }
     /** (Property accessor) Return the angle of rotation around x, in radians */
-    get yRadians() { return this._y.radians; }
+    get yRadians() {
+        return this._y.radians;
+    }
     /** (Property accessor) Return the angle of rotation around y, in radians */
-    get zDegrees() { return this._z.degrees; }
+    get zDegrees() {
+        return this._z.degrees;
+    }
     /** (Property accessor) Return the angle of rotation around z, in radians */
-    get zRadians() { return this._z.radians; }
-    /** Flag controlling whether vectors are treated as rows or as columns */
-    static get treatVectorsAsColumns() { return OrderedRotationAngles._sTreatVectorsAsColumns; }
-    static set treatVectorsAsColumns(value) { OrderedRotationAngles._sTreatVectorsAsColumns = value; }
-    /** Create an OrderedRotationAngles from three angles and an ordering in which to apply them when rotating.
-     * @param xRotation rotation around x
-     * @param yRotation rotation around y
-     * @param zRotation rotation around z
-     * @param axisOrder right to left order of axis names identifies the order that rotations are applied to xyz data.
+    get zRadians() {
+        return this._z.radians;
+    }
+    /** the flag controlling whether vectors are treated as rows or as columns */
+    static get treatVectorsAsColumns() {
+        return OrderedRotationAngles._sTreatVectorsAsColumns;
+    }
+    static set treatVectorsAsColumns(value) {
+        OrderedRotationAngles._sTreatVectorsAsColumns = value;
+    }
+    /**
+     * Create an OrderedRotationAngles from three angles (in radians), an ordering in which to apply them when
+     * rotating, and a flag triple controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * @param xRadians rotation around x
+     * @param yRadians rotation around y
+     * @param zRadians rotation around z
+     * @param order left to right order of axis names identifies the order that rotations are applied.
+     * For example XYZ means to rotate around x axis first, then y axis, and finally Z axis.
+     * * Note that rotation order is reverse of rotation matrix multiplication so for XYZ the rotation
+     * matrix multiplication would be zRot*yRot*xRot
+     * @param xyzRotationIsClockwise the flags controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * rotation direction of x,y,z: true ---> clockwise - false ---> counterclockwise.
+     * * if xyzRotationIsClockwise is undefined it's set to [false, false, false].
+     * @param result caller-allocated OrderedRotationAngles
      */
-    static createAngles(xRotation, yRotation, zRotation, order, result) {
-        if (result) {
-            result._x.setFrom(xRotation);
-            result._y.setFrom(yRotation);
-            result._z.setFrom(zRotation);
-            result._order = order;
-            return result;
+    static createRadians(xRadians, yRadians, zRadians, order, xyzRotationIsClockwise, result) {
+        if (!xyzRotationIsClockwise) {
+            xyzRotationIsClockwise = [false, false, false];
         }
-        return new OrderedRotationAngles(xRotation.clone(), yRotation.clone(), zRotation.clone(), order);
-    }
-    /** Create an OrderedRotationAngles from three angles (in radians) and an ordering in which to apply them when rotating. */
-    static createRadians(xRadians, yRadians, zRadians, order, result) {
+        const xRadian = xyzRotationIsClockwise[0] ? -xRadians : xRadians;
+        const yRadian = xyzRotationIsClockwise[1] ? -yRadians : yRadians;
+        const zRadian = xyzRotationIsClockwise[2] ? -zRadians : zRadians;
         if (result) {
-            result._x.setRadians(xRadians);
-            result._y.setRadians(yRadians);
-            result._z.setRadians(zRadians);
+            result._x.setRadians(xRadian);
+            result._y.setRadians(yRadian);
+            result._z.setRadians(zRadian);
             result._order = order;
             return result;
         }
-        return new OrderedRotationAngles(Angle_1.Angle.createRadians(xRadians), Angle_1.Angle.createRadians(yRadians), Angle_1.Angle.createRadians(zRadians), order);
+        return new OrderedRotationAngles(Angle_1.Angle.createRadians(xRadian), Angle_1.Angle.createRadians(yRadian), Angle_1.Angle.createRadians(zRadian), order);
     }
-    /** Create an OrderedRotationAngles from three angles (in degrees) and an ordering in which to apply them when rotating. */
-    static createDegrees(xDegrees, yDegrees, zDegrees, order, result) {
-        if (result) {
-            result._x.setDegrees(xDegrees);
-            result._y.setDegrees(yDegrees);
-            result._z.setDegrees(zDegrees);
-            result._order = order;
-            return result;
-        }
-        return new OrderedRotationAngles(Angle_1.Angle.createDegrees(xDegrees), Angle_1.Angle.createDegrees(yDegrees), Angle_1.Angle.createDegrees(zDegrees), order);
+    /**
+     * Create an OrderedRotationAngles from three angles (in degrees) and an ordering in which to apply
+     * them when rotating.
+     * @param xDegrees rotation around x
+     * @param yDegrees rotation around y
+     * @param zDegrees rotation around z
+     * @param order left to right order of axis names identifies the order that rotations are applied.
+     * For example XYZ means to rotate around x axis first, then y axis, and finally Z axis.
+     * * Note that rotation order is reverse of rotation matrix multiplication so for XYZ the rotation
+     * matrix multiplication would be zRot*yRot*xRot
+     * @param xyzRotationIsClockwise the flags controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * rotation direction of x,y,z: true ---> clockwise - false ---> counterclockwise.
+     * * if xyzRotationIsClockwise is undefined it's set to [false, false, false].
+     * @param result caller-allocated OrderedRotationAngles
+     */
+    static createDegrees(xDegrees, yDegrees, zDegrees, order, xyzRotationIsClockwise, result) {
+        return OrderedRotationAngles.createRadians(Angle_1.Angle.degreesToRadians(xDegrees), Angle_1.Angle.degreesToRadians(yDegrees), Angle_1.Angle.degreesToRadians(zDegrees), order, xyzRotationIsClockwise, result);
+    }
+    /**
+     * Create an OrderedRotationAngles from three angles, an ordering in which to apply them when rotating,
+     * and a flag triple controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * @param xRotation rotation around x
+     * @param yRotation rotation around y
+     * @param zRotation rotation around z
+     * @param order left to right order of axis names identifies the order that rotations are applied
+     * For example XYZ means to rotate around x axis first, then y axis, and finally Z axis.
+     * * Note that rotation order is reverse of rotation matrix multiplication so for XYZ the rotation
+     * matrix multiplication would be zRot*yRot*xRot
+     * @param xyzRotationIsClockwise the flags controlling whether direction of x,y,z is clockwise or counterclockwise.
+     * rotation direction of x,y,z: true ---> clockwise - false ---> counterclockwise.
+     * * if xyzRotationIsClockwise is undefined it's set to [false, false, false].
+     * @param result caller-allocated OrderedRotationAngles
+     */
+    static createAngles(xRotation, yRotation, zRotation, order, xyzRotationIsClockwise, result) {
+        return OrderedRotationAngles.createRadians(xRotation.radians, yRotation.radians, zRotation.radians, order, xyzRotationIsClockwise, result);
     }
-    /** Create an OrderedRotationAngles from a 3x3 rotational matrix, given the ordering of axis rotations that the matrix derives from. */
+    /**
+     * Create an OrderedRotationAngles from a 3x3 rotational matrix, given the ordering of axis rotations
+     * that the matrix derives from.
+     * * This function creates an OrderedRotationAngles with default angle rotation directions, i.e.,
+     * it assumes all x, y, and z rotations are counterclockwise.
+     * * 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.
+     * */
     static createFromMatrix3d(matrix, order, result) {
-        let m11 = matrix.coffs[0], m12 = matrix.coffs[3], m13 = matrix.coffs[6];
-        let m21 = matrix.coffs[1], m22 = matrix.coffs[4], m23 = matrix.coffs[7];
-        let m31 = matrix.coffs[2], m32 = matrix.coffs[5], m33 = matrix.coffs[8];
-        if (OrderedRotationAngles.treatVectorsAsColumns) {
-            // the formulas are from row order .. flip the mIJ
-            m11 = matrix.coffs[0], m12 = matrix.coffs[1], m13 = matrix.coffs[2];
-            m21 = matrix.coffs[3], m22 = matrix.coffs[4], m23 = matrix.coffs[5];
-            m31 = matrix.coffs[6], m32 = matrix.coffs[7], m33 = matrix.coffs[8];
+        // treat vector as columns
+        let m11 = matrix.coffs[0], m12 = matrix.coffs[1], m13 = matrix.coffs[2];
+        let m21 = matrix.coffs[3], m22 = matrix.coffs[4], m23 = matrix.coffs[5];
+        let m31 = matrix.coffs[6], m32 = matrix.coffs[7], m33 = matrix.coffs[8];
+        // treat vector as rows
+        if (!OrderedRotationAngles.treatVectorsAsColumns) {
+            m11 = matrix.coffs[0], m12 = matrix.coffs[3], m13 = matrix.coffs[6];
+            m21 = matrix.coffs[1], m22 = matrix.coffs[4], m23 = matrix.coffs[7];
+            m31 = matrix.coffs[2], m32 = matrix.coffs[5], m33 = matrix.coffs[8];
         }
         let xRad;
         let yRad;
         let zRad;
         switch (order) {
             case Geometry_1.AxisOrder.XYZ: {
-                yRad = Math.asin(Math.max(-1, Math.min(1, m13)));
-                if (Math.abs(m13) < 0.99999) {
-                    xRad = Math.atan2(-m23, m33);
-                    zRad = Math.atan2(-m12, m11);
+                yRad = Math.asin(Math.max(-1, Math.min(1, -m31))); // limit asin domain to [-1,1]
+                if (Math.abs(m31) < 0.99999) {
+                    xRad = Math.atan2(m32, m33);
+                    zRad = Math.atan2(m21, m11);
                 }
                 else {
-                    xRad = Math.atan2(m32, m22);
+                    /**
+                     * If Math.abs(m31) = 1 then yRad = +-90 degrees and therefore, we have a gimbal lock.
+                     * This means xRad and zRad can be anything as long as their sum xRad + zRad is constant.
+                     * so we can pick zRad = 0 and calculate xRad (or pick xRad = 0 and calculate zRad).
+                     * Therefore, rotation matrix becomes
+                     *        Matrix3d.createRowValues(
+                     *             0, +-sx, +-cx,
+                     *             0, cx, -sx,
+                     *             -+1, 0, 0
+                     *        );
+                     * Math details can be found
+                     * https://en.wikipedia.org/wiki/Gimbal_lock#Loss_of_a_degree_of_freedom_with_Euler_angles
+                     */
+                    xRad = Math.atan2(-m23, m22);
                     zRad = 0;
                 }
                 break;
             }
             case Geometry_1.AxisOrder.YXZ: {
-                xRad = Math.asin(-Math.max(-1, Math.min(1, m23)));
-                if (Math.abs(m23) < 0.99999) {
-                    yRad = Math.atan2(m13, m33);
-                    zRad = Math.atan2(m21, m22);
+                xRad = Math.asin(Math.max(-1, Math.min(1, m32))); // limit asin domain to [-1,1]
+                if (Math.abs(m32) < 0.99999) {
+                    yRad = Math.atan2(-m31, m33);
+                    zRad = Math.atan2(-m12, m22);
                 }
                 else {
-                    yRad = Math.atan2(-m31, m11);
+                    yRad = Math.atan2(m13, m11);
                     zRad = 0;
                 }
                 break;
             }
             case Geometry_1.AxisOrder.ZXY: {
-                xRad = Math.asin(Math.max(-1, Math.min(1, m32)));
-                if (Math.abs(m32) < 0.99999) {
-                    yRad = Math.atan2(-m31, m33);
-                    zRad = Math.atan2(-m12, m22);
+                xRad = Math.asin(Math.max(-1, Math.min(1, -m23))); // limit asin domain to [-1,1]
+                if (Math.abs(m23) < 0.99999) {
+                    yRad = Math.atan2(m13, m33);
+                    zRad = Math.atan2(m21, m22);
                 }
                 else {
                     yRad = 0;
-                    zRad = Math.atan2(m21, m11);
+                    zRad = Math.atan2(-m12, m11);
                 }
                 break;
             }
             case Geometry_1.AxisOrder.ZYX: {
-                yRad = -Math.asin(Math.max(-1, Math.min(1, m31)));
-                if (Math.abs(m31) < 0.99999) {
-                    xRad = Math.atan2(m32, m33);
-                    zRad = Math.atan2(m21, m11);
+                yRad = Math.asin(Math.max(-1, Math.min(1, m13))); // limit asin domain to [-1,1]
+                if (Math.abs(m13) < 0.99999) {
+                    xRad = Math.atan2(-m23, m33);
+                    zRad = Math.atan2(-m12, m11);
                 }
                 else {
                     xRad = 0;
-                    zRad = Math.atan2(-m12, m22);
+                    zRad = Math.atan2(m21, m22);
                 }
                 break;
             }
             case Geometry_1.AxisOrder.YZX: {
-                zRad = Math.asin(Math.max(-1, Math.min(1, m21)));
-                if (Math.abs(m21) < 0.99999) {
-                    xRad = Math.atan2(-m23, m22);
-                    yRad = Math.atan2(-m31, m11);
+                zRad = Math.asin(Math.max(-1, Math.min(1, -m12))); // limit asin domain to [-1,1]
+                if (Math.abs(m12) < 0.99999) {
+                    xRad = Math.atan2(m32, m22);
+                    yRad = Math.atan2(m13, m11);
                 }
                 else {
                     xRad = 0;
-                    yRad = Math.atan2(m13, m33);
+                    yRad = Math.atan2(-m31, m33);
                 }
                 break;
             }
             case Geometry_1.AxisOrder.XZY: {
-                zRad = -Math.asin(Math.max(-1, Math.min(1, m12)));
-                if (Math.abs(m12) < 0.99999) {
-                    xRad = Math.atan2(m32, m22);
-                    yRad = Math.atan2(m13, m11);
+                zRad = Math.asin(Math.max(-1, Math.min(1, m21))); // limit asin domain to [-1,1]
+                if (Math.abs(m21) < 0.99999) {
+                    xRad = Math.atan2(-m23, m22);
+                    yRad = Math.atan2(-m31, m11);
                 }
                 else {
-                    xRad = Math.atan2(-m23, m33);
+                    xRad = Math.atan2(m32, m33);
                     yRad = 0;
                 }
                 break;
@@ -178,55 +258,65 @@ class OrderedRotationAngles {
                 xRad = yRad = zRad = 0;
             }
         }
-        if (OrderedRotationAngles.treatVectorsAsColumns)
-            return OrderedRotationAngles.createRadians(-xRad, -yRad, -zRad, order, result);
-        return OrderedRotationAngles.createRadians(xRad, yRad, zRad, order, result);
+        const xyzRotationIsClockwise = [false, false, false];
+        const angles = OrderedRotationAngles.createRadians(xRad, yRad, zRad, order, xyzRotationIsClockwise, result);
+        // sanity check
+        const matrix1 = angles.toMatrix3d();
+        /**
+         * Below tolerance loosened to allow sanity check to pass for
+         *
+         * OrderedRotationAngles.createFromMatrix3d(
+         *       OrderedRotationAngles.createDegrees(0, 89.999, 0.001, AxisOrder.XYZ).toMatrix3d(),
+         *       AxisOrder.XYZ
+         * );
+         *
+         * with treatVectorsAsColumns = true.
+         */
+        return (matrix.maxDiff(matrix1) < 10 * Geometry_1.Geometry.smallFraction) ? angles : undefined;
     }
-    /** Create a 3x3 rotational matrix from this OrderedRotationAngles. */
+    /**
+     * Create a 3x3 rotational matrix from this OrderedRotationAngles.
+     ** math details can be found at docs/learning/geometry/Angle.md
+     **/
     toMatrix3d(result) {
-        const rot = result !== undefined ? result : new Matrix3d_1.Matrix3d();
+        const rot = (result !== undefined) ? result : new Matrix3d_1.Matrix3d();
         const axisOrder = this.order;
         const x = this.xAngle, y = this.yAngle, z = this.zAngle;
-        const a = x.cos();
-        let b = x.sin();
-        const c = y.cos();
-        let d = y.sin();
-        const e = z.cos();
-        let f = z.sin();
-        if (OrderedRotationAngles.treatVectorsAsColumns) {
-            b = -b;
-            d = -d;
-            f = -f;
-        }
+        const cx = x.cos(), sx = x.sin();
+        const cy = y.cos(), sy = y.sin();
+        const cz = z.cos(), sz = z.sin();
+        const cxcz = cx * cz, cxsz = cx * sz, cxcy = cx * cy, cxsy = cx * sy;
+        const sxcz = sx * cz, sxsz = sx * sz, sxcy = sx * cy, sxsy = sx * sy;
+        const cycz = cy * cz, cysz = cy * sz, sycz = sy * cz, sysz = sy * sz;
+        // the rotation matrix we build below is created using column-based base rotation matrixes
         if (axisOrder === Geometry_1.AxisOrder.XYZ) {
-            const ae = a * e, af = a * f, be = b * e, bf = b * f;
-            rot.setRowValues(c * e, af + be * d, bf - ae * d, -c * f, ae - bf * d, be + af * d, d, -b * c, a * c);
+            rot.setRowValues(cy * cz, sxcz * sy - cxsz, cxcz * sy + sxsz, cy * sz, cxcz + sxsz * sy, cxsz * sy - sxcz, -sy, sx * cy, cx * cy);
         }
         else if (axisOrder === Geometry_1.AxisOrder.YXZ) {
-            const ce = c * e, cf = c * f, de = d * e, df = d * f;
-            rot.setRowValues(ce + df * b, a * f, cf * b - de, de * b - cf, a * e, df + ce * b, a * d, -b, a * c);
+            rot.setRowValues(cycz - sysz * sx, -cx * sz, cysz * sx + sycz, sycz * sx + cysz, cx * cz, sysz - cycz * sx, -cx * sy, sx, cx * cy);
         }
         else if (axisOrder === Geometry_1.AxisOrder.ZXY) {
-            const ce = c * e, cf = c * f, de = d * e, df = d * f;
-            rot.setRowValues(ce - df * b, cf + de * b, -a * d, -a * f, a * e, b, de + cf * b, df - ce * b, a * c);
+            rot.setRowValues(cycz + sysz * sx, sycz * sx - cysz, cx * sy, cx * sz, cx * cz, -sx, cysz * sx - sycz, cycz * sx + sysz, cx * cy);
         }
         else if (axisOrder === Geometry_1.AxisOrder.ZYX) {
-            const ae = a * e, af = a * f, be = b * e, bf = b * f;
-            rot.setRowValues(c * e, c * f, -d, be * d - af, bf * d + ae, b * c, ae * d + bf, af * d - be, a * c);
+            rot.setRowValues(cy * cz, -cy * sz, sy, sxcz * sy + cxsz, cxcz - sxsz * sy, -sx * cy, sxsz - cxcz * sy, sxcz + cxsz * sy, cx * cy);
         }
         else if (axisOrder === Geometry_1.AxisOrder.YZX) {
-            const ac = a * c, ad = a * d, bc = b * c, bd = b * d;
-            rot.setRowValues(c * e, f, -d * e, bd - ac * f, a * e, ad * f + bc, bc * f + ad, -b * e, ac - bd * f);
+            rot.setRowValues(cy * cz, -sz, sy * cz, sxsy + cxcy * sz, cx * cz, cxsy * sz - sxcy, sxcy * sz - cxsy, sx * cz, cxcy + sxsy * sz);
         }
         else if (axisOrder === Geometry_1.AxisOrder.XZY) {
-            const ac = a * c, ad = a * d, bc = b * c, bd = b * d;
-            rot.setRowValues(c * e, ac * f + bd, bc * f - ad, -f, a * e, b * e, d * e, ad * f - bc, bd * f + ac);
+            rot.setRowValues(cy * cz, sxsy - cxcy * sz, cxsy + sxcy * sz, sz, cx * cz, -sx * cz, -sy * cz, sxcy + cxsy * sz, cxcy - sxsy * sz);
+        }
+        else {
+            rot.setIdentity();
         }
-        if (OrderedRotationAngles.treatVectorsAsColumns)
+        // if we need row-based rotation matrix, we transpose the rotation matrix
+        if (!OrderedRotationAngles.treatVectorsAsColumns)
             rot.transposeInPlace();
         return rot;
     }
 }
 exports.OrderedRotationAngles = OrderedRotationAngles;
+/** treat vectors as matrix columns */
 OrderedRotationAngles._sTreatVectorsAsColumns = false;
 //# sourceMappingURL=OrderedRotationAngles.js.map