@itwin/core-geometry 5.0.0-dev.2 → 5.0.0-dev.20

package/lib/cjs/curve/Arc3d.js

@@ -10,6 +10,7 @@ const Geometry_1 = require("../Geometry");
 const Angle_1 = require("../geometry3d/Angle");
 const AngleSweep_1 = require("../geometry3d/AngleSweep");
 const Matrix3d_1 = require("../geometry3d/Matrix3d");
+const Plane3dByOriginAndUnitNormal_1 = require("../geometry3d/Plane3dByOriginAndUnitNormal");
 const Plane3dByOriginAndVectors_1 = require("../geometry3d/Plane3dByOriginAndVectors");
 const Point3dVector3d_1 = require("../geometry3d/Point3dVector3d");
 const Range_1 = require("../geometry3d/Range");
@@ -155,10 +156,17 @@ class Arc3d extends CurvePrimitive_1.CurvePrimitive {
     isSameGeometryClass(other) {
         return other instanceof Arc3d;
     }
-    /** Read property for (clone of) center. */
+    /** Read/write the center. Getter returns clone. */
     get center() {
         return this._center.clone();
     }
+    set center(center) {
+        this._center.setFrom(center);
+    }
+    /** Read property for (reference to) center. */
+    get centerRef() {
+        return this._center;
+    }
     /** Read property for (clone of) vector0. */
     get vector0() {
         return this._matrix.columnX();
@@ -179,7 +187,7 @@ class Arc3d extends CurvePrimitive_1.CurvePrimitive {
     get matrixRef() {
         return this._matrix;
     }
-    /** Sweep of the angle. */
+    /** Read/write the sweep. Getter returns reference. */
     get sweep() {
         return this._sweep;
     }
@@ -764,7 +772,7 @@ class Arc3d extends CurvePrimitive_1.CurvePrimitive {
         const axy = this._matrix.columnXDotColumnY();
         return Angle_1.Angle.isPerpendicularDotSet(axx, ayy, axy) && Geometry_1.Geometry.isSameCoordinateSquared(axx, ayy);
     }
-    /** Return radius if the vector0 and vector90 are of equal length and perpendicular. */
+    /** Return radius if the vector0 and vector90 are of equal length and perpendicular. Ignores z. */
     circularRadiusXY() {
         const ux = this._matrix.at(0, 0);
         const uy = this._matrix.at(1, 0);
@@ -906,7 +914,12 @@ class Arc3d extends CurvePrimitive_1.CurvePrimitive {
     setVector0Vector90(vector0, vector90) {
         this._matrix.setColumns(vector0, vector90, vector0.unitCrossProductWithDefault(vector90, 0, 0, 0));
     }
-    /** Return the arc definition with rigid matrix form with axis radii. */
+    /**
+     * Return the symmetric definition of the arc, with rigid axes and radii.
+     * * The caller can send the returned data into [[createScaledXYColumns]] to construct the major-minor axis
+     * version of the instance arc. This formulation of the arc has the same shape, but has perpendicular axes,
+     * from which the arc's symmetry is readily apparent.
+     */
     toScaledMatrix3d() {
         const angleData = Angle_1.Angle.dotProductsToHalfAngleTrigValues(this._matrix.columnXMagnitudeSquared(), this._matrix.columnYMagnitudeSquared(), this._matrix.columnXDotColumnY(), true);
         const vector0A = this._matrix.multiplyXY(angleData.c, angleData.s);
@@ -1046,9 +1059,9 @@ class Arc3d extends CurvePrimitive_1.CurvePrimitive {
     }
     /**
      * Return an arc whose basis vectors are rotated by given angle within the current basis space.
-     * * the result arc will have its zero-degree point (new `vector0`) at the current.
-     * `vector0 * cos(theta) + vector90 * sin(theta)`.
-     * * the result sweep is adjusted so all fractional coordinates (e.g. start and end) evaluate to the same xyz.
+     * * The returned arc will have `vector0 = this.vector0 * cos(theta) + this.vector90 * sin(theta)`.
+     * * The returned arc has the same shape as the instance.
+     *   * In other words, the arc's sweep is adjusted so that all fractional parameters evaluate to the same points.
      *   * Specifically, theta is subtracted from the original start and end angles.
      * @param theta the angle (in the input arc space) which is to become the 0-degree point in the new arc.
      */
@@ -1061,6 +1074,39 @@ class Arc3d extends CurvePrimitive_1.CurvePrimitive {
         const arcB = Arc3d.create(this._center.clone(), vector0, vector90, newSweep);
         return arcB;
     }
+    /**
+     * Return a cloned arc with basis rotated to align with the global axes. The arc's shape is unchanged.
+     * * This method is most useful when the instance is an xy-circular arc, for then the aligned arc's stored sweep
+     * angles can be understood as being measured from the global positive x-axis to the arc's start/end. This is *not*
+     * the case for xy-elliptical arcs: the parameter angle difference between two points on an ellipse is in general
+     * not the same as the angle measured between their radials.
+     * * For an xy instance, the output arc will have:
+     *   * vector0 is in the same direction as the positive x-axis
+     *   * perpendicularVector is in the same direction as the positive z-axis
+     * * For a general instance, the output arc will have:
+     *   * vector0 is in the same direction as the projection of the positive x-axis vector onto the arc plane
+     *   * perpendicularVector lies in the halfspace z >= 0
+     * @returns cloned arc, or undefined (if the instance normal is parallel to the x-axis, or its matrix is singular)
+     */
+    cloneAxisAligned() {
+        const plane = Plane3dByOriginAndUnitNormal_1.Plane3dByOriginAndUnitNormal.create(this.center, this.perpendicularVector.crossProduct(Point3dVector3d_1.Vector3d.unitX()));
+        if (!plane)
+            return undefined;
+        const axisPts = [];
+        if (2 !== this.appendPlaneIntersectionPoints(plane, axisPts))
+            return undefined;
+        const iAxisPt = plane.getNormalRef().dotProduct(this.perpendicularVector.crossProductStartEnd(this.center, axisPts[0].point)) > 0.0 ? 0 : 1;
+        const toUnitX = this.sweep.fractionToAngle(axisPts[iAxisPt].fraction);
+        const arc1 = this.cloneInRotatedBasis(toUnitX); // rotate in arc's plane
+        if (this.perpendicularVector.dotProduct(Point3dVector3d_1.Vector3d.unitZ()) < -Geometry_1.Geometry.smallAngleRadians) {
+            if (this.matrixRef.isSingular())
+                return undefined;
+            const flip = Matrix3d_1.Matrix3d.createRowValues(1, 0, 0, 0, -1, 0, 0, 0, -1); // rotate 180 degrees around arc's local x-axis
+            arc1.matrixRef.multiplyMatrixMatrix(flip, arc1.matrixRef);
+            arc1.sweep.setStartEndDegrees(-arc1.sweep.startDegrees, -arc1.sweep.endDegrees); // rotation alone is insufficient to flip
+        }
+        return arc1;
+    }
     /**
      * Find intervals of this CurvePrimitive that are interior to a clipper.
      * @param clipper clip structure (e.g.clip planes).