@itwin/core-geometry 5.0.0-dev.1 → 5.0.0-dev.100

package/lib/esm/curve/Arc3d.js

@@ -7,6 +7,7 @@ import { AxisOrder, Geometry } from "../Geometry";
 import { Angle } from "../geometry3d/Angle";
 import { AngleSweep } from "../geometry3d/AngleSweep";
 import { Matrix3d } from "../geometry3d/Matrix3d";
+import { Plane3dByOriginAndUnitNormal } from "../geometry3d/Plane3dByOriginAndUnitNormal";
 import { Plane3dByOriginAndVectors } from "../geometry3d/Plane3dByOriginAndVectors";
 import { Point3d, Vector3d } from "../geometry3d/Point3dVector3d";
 import { Range1d, Range3d } from "../geometry3d/Range";
@@ -53,6 +54,13 @@ export var EllipticalArcSampleMethod;
  * @public
  */
 export class EllipticalArcApproximationOptions {
+    _sampleMethod;
+    _numSamplesInQuadrant;
+    _maxError;
+    _remapFunction;
+    _forcePath;
+    /** Default error tolerance. */
+    static defaultMaxError = Constant.oneCentimeter;
     constructor(method, numSamplesInQuadrant, maxError, remapFunction, forcePath) {
         this._sampleMethod = method;
         this._numSamplesInQuadrant = numSamplesInQuadrant;
@@ -129,8 +137,6 @@ export class EllipticalArcApproximationOptions {
         this._forcePath = value;
     }
 }
-/** Default error tolerance. */
-EllipticalArcApproximationOptions.defaultMaxError = Constant.oneCentimeter;
 /**
  * Circular or elliptic arc.
  * * The angle to point equation is:
@@ -147,14 +153,32 @@ EllipticalArcApproximationOptions.defaultMaxError = Constant.oneCentimeter;
  * @public
  */
 export class Arc3d extends CurvePrimitive {
+    /** String name for schema properties. */
+    curvePrimitiveType = "arc";
     /** Test if this and other are both instances of Arc3d. */
     isSameGeometryClass(other) {
         return other instanceof Arc3d;
     }
-    /** Read property for (clone of) center. */
+    _center;
+    _matrix; // columns are [vector0, vector90, unitNormal]
+    _sweep; // sweep limits
+    static _workPointA = Point3d.create();
+    static _workPointB = Point3d.create();
+    static _workPointC = Point3d.create();
+    static _workVectorU = Vector3d.create();
+    static _workVectorV = Vector3d.create();
+    static _workVectorW = Vector3d.create();
+    /** 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();
@@ -163,7 +187,19 @@ export class Arc3d extends CurvePrimitive {
     get vector90() {
         return this._matrix.columnY();
     }
-    /** Read property for (clone of) plane normal, with arbitrary length. */
+    /**
+     * Compute an arc binormal vector with arbitrary length.
+     * * The arc parameterization is counter-clockwise with respect to this vector.
+     * * This vector is parallel to [[perpendicularVector]] and possibly opposite.
+     */
+    binormalVector(result) {
+        const plane = this.fractionToPointAnd2Derivatives(0.0);
+        return plane.vectorU.crossProduct(plane.vectorV, result);
+    }
+    /**
+     * Read property for (clone of) plane normal, with arbitrary length.
+     * * Does not take arc sweep direction into account. See also [[binormalVector]].
+     */
     get perpendicularVector() {
         return this._matrix.columnZ();
     }
@@ -175,7 +211,7 @@ export class Arc3d extends CurvePrimitive {
     get matrixRef() {
         return this._matrix;
     }
-    /** Sweep of the angle. */
+    /** Read/write the sweep. Getter returns reference. */
     get sweep() {
         return this._sweep;
     }
@@ -189,11 +225,9 @@ export class Arc3d extends CurvePrimitive {
     // constructor copies the pointers
     constructor(center, matrix, sweep) {
         super();
-        /** String name for schema properties. */
-        this.curvePrimitiveType = "arc";
         this._center = center;
         this._matrix = matrix;
-        this._sweep = sweep;
+        this._sweep = sweep.clampToFullCircle(sweep);
     }
     /**
      * Return a clone of the arc, with transform applied.
@@ -310,7 +344,7 @@ export class Arc3d extends CurvePrimitive {
         const v1DotV90 = vector1.dotProduct(vector90);
         // solve the standard ellipse equation for the unknown axis length, given local coords of middle (v0.v1/||v0||, v90.v1)
         const v90Len = Geometry.safeDivideFraction(v0Len2 * v1DotV90, Math.sqrt(v0Len2 * v0Len2 - v0DotV1 * v0DotV1), 0);
-        if (Geometry.isSmallMetricDistanceSquared(v90Len))
+        if (Geometry.isSmallMetricDistanceSquared(v90Len)) // tighter than smallMetricDistance to allow flatter long elliptical arcs
             return undefined;
         vector90.scaleInPlace(v90Len);
         return Arc3d.create(center, vector0, vector90, sweep, result);
@@ -591,6 +625,12 @@ export class Arc3d extends CurvePrimitive {
     curveLength() {
         return this.curveLengthBetweenFractions(0, 1);
     }
+    // !! misspelled Gauss in the published static !! Declare it ok.
+    // cspell::word Guass
+    /** Gauss point quadrature count for evaluating curve length. (The number of intervals is adjusted to the arc sweep). */
+    static quadratureGuassCount = 5;
+    /** In quadrature for arc length, use this interval (divided by quickEccentricity). */
+    static quadratureIntervalAngleDegrees = 10.0;
     /**
      * * If this is a circular arc, return the simple length derived from radius and sweep.
      * * Otherwise (i.e. if this elliptical) fall through CurvePrimitive integrator.
@@ -760,7 +800,7 @@ export class Arc3d extends CurvePrimitive {
         const axy = this._matrix.columnXDotColumnY();
         return Angle.isPerpendicularDotSet(axx, ayy, axy) && 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);
@@ -902,7 +942,12 @@ export class Arc3d extends 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.dotProductsToHalfAngleTrigValues(this._matrix.columnXMagnitudeSquared(), this._matrix.columnYMagnitudeSquared(), this._matrix.columnXDotColumnY(), true);
         const vector0A = this._matrix.multiplyXY(angleData.c, angleData.s);
@@ -1042,9 +1087,9 @@ export class Arc3d extends 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.
      */
@@ -1057,6 +1102,39 @@ export class Arc3d extends 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.create(this.center, this.perpendicularVector.crossProduct(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(Vector3d.unitZ()) < -Geometry.smallAngleRadians) {
+            if (this.matrixRef.isSingular())
+                return undefined;
+            const flip = 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).
@@ -1193,6 +1271,8 @@ export class Arc3d extends CurvePrimitive {
     }
     /**
      * Construct a circular arc chain approximation to the instance elliptical arc.
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/ArcApproximationGeneral and
+     *  https://www.itwinjs.org/sandbox/SaeedTorabi/ArcApproximation
      * @param options bundle of options for sampling an elliptical arc (use default options if undefined).
      * @returns the approximating curve chain, the circular instance, or undefined if construction fails.
      */
@@ -1206,16 +1286,4 @@ export class Arc3d extends CurvePrimitive {
         return result;
     }
 }
-Arc3d._workPointA = Point3d.create();
-Arc3d._workPointB = Point3d.create();
-Arc3d._workPointC = Point3d.create();
-Arc3d._workVectorU = Vector3d.create();
-Arc3d._workVectorV = Vector3d.create();
-Arc3d._workVectorW = Vector3d.create();
-// !! misspelled Gauss in the published static !! Declare it ok.
-// cspell::word Guass
-/** Gauss point quadrature count for evaluating curve length. (The number of intervals is adjusted to the arc sweep). */
-Arc3d.quadratureGuassCount = 5;
-/** In quadrature for arc length, use this interval (divided by quickEccentricity). */
-Arc3d.quadratureIntervalAngleDegrees = 10.0;
 //# sourceMappingURL=Arc3d.js.map