@itwin/core-geometry 4.1.0-dev.4 → 4.1.0-dev.40

package/lib/esm/curve/Arc3d.js

@@ -21,58 +21,61 @@ import { LineString3d } from "./LineString3d";
 import { StrokeOptions } from "./StrokeOptions";
 /**
  * Circular or elliptic arc.
- *
  * * The angle to point equation is:
- *
- * *  `X = center + cos(theta) * vector0 + sin(theta) * vector90`
+ * * `X = center + cos(theta) * vector0 + sin(theta) * vector90`
  * * When the two vectors are perpendicular and have equal length, it is a true circle.
  * * Non-perpendicular vectors are always elliptic.
- * *  vectors of unequal length are always elliptic.
+ * * Vectors of unequal length are always elliptic.
  * * To create an ellipse in the common "major and minor axis" form of an ellipse:
  * ** vector0 is the vector from the center to the major axis extreme.
  * ** vector90 is the vector from the center to the minor axis extreme.
- * ** note the constructing the vectors to the extreme points makes them perpendicular.
- * *  The method toScaledMatrix3d () can be called to convert the unrestricted vector0,vector90 to perpendicular form.
- * * The unrestricted form is much easier to work with for common calculations -- stroking, projection to 2d, intersection with plane.
+ * ** note that constructing the vectors to the extreme points makes them perpendicular.
+ * * The method toScaledMatrix3d() can be called to convert the unrestricted vector0,vector90 to perpendicular form.
+ * * The unrestricted form is much easier to work with for common calculations -- stroking, projection to 2d,
+ * intersection with plane.
  * @public
  */
 class Arc3d extends CurvePrimitive {
-    /**
-     * Test if this and other are both instances of Arc3d.
-     */
-    isSameGeometryClass(other) { return other instanceof Arc3d; }
-    /**
-     * read property for (clone of) center
-     */
-    get center() { return this._center.clone(); }
-    /**
-     * read property for (clone of) vector0
-     */
-    get vector0() { return this._matrix.columnX(); }
-    /**
-     * read property for (clone of) vector90
-     */
-    get vector90() { return this._matrix.columnY(); }
-    /**
-     * read property for (clone of) plane normal, with arbitrary length.
-     */
-    get perpendicularVector() { return this._matrix.columnZ(); }
-    /**
-     * read property for (clone of!) matrix of vector0, vector90, unit normal
-     */
-    matrixClone() { return this._matrix.clone(); }
-    /**
-     * read property for (reference to !!) matrix of vector0, vector90, unit normal
-     */
-    get matrixRef() { return this._matrix; }
+    /** Test if this and other are both instances of Arc3d. */
+    isSameGeometryClass(other) {
+        return other instanceof Arc3d;
+    }
+    /** Read property for (clone of) center */
+    get center() {
+        return this._center.clone();
+    }
+    /** Read property for (clone of) vector0 */
+    get vector0() {
+        return this._matrix.columnX();
+    }
+    /** Read property for (clone of) vector90 */
+    get vector90() {
+        return this._matrix.columnY();
+    }
+    /** Read property for (clone of) plane normal, with arbitrary length. */
+    get perpendicularVector() {
+        return this._matrix.columnZ();
+    }
+    /** Read property for (clone of) matrix of vector0, vector90, unit normal */
+    matrixClone() {
+        return this._matrix.clone();
+    }
+    /** Read property for (reference to) matrix of vector0, vector90, unit normal */
+    get matrixRef() {
+        return this._matrix;
+    }
     /** Sweep of the angle. */
-    get sweep() { return this._sweep; }
-    set sweep(value) { this._sweep.setFrom(value); }
-    /**
-     * An Arc3d extends along its complete elliptic arc
-     */
-    get isExtensibleFractionSpace() { return true; }
-    // constructor copies the pointers !!!
+    get sweep() {
+        return this._sweep;
+    }
+    set sweep(value) {
+        this._sweep.setFrom(value);
+    }
+    /** An Arc3d extends along its complete elliptic arc */
+    get isExtensibleFractionSpace() {
+        return true;
+    }
+    // constructor copies the pointers
     constructor(center, matrix, sweep) {
         super();
         /** String name for schema properties */
@@ -82,7 +85,7 @@ class Arc3d extends CurvePrimitive {
         this._sweep = sweep;
     }
     /**
-     *  Return a clone of the arc, with transform applied
+     * Return a clone of the arc, with transform applied
      * @param transform
      */
     cloneTransformed(transform) {
@@ -110,9 +113,7 @@ class Arc3d extends CurvePrimitive {
     set(center, matrix, sweep) {
         this.setRefs(center.clone(), matrix.clone(), sweep ? sweep.clone() : AngleSweep.create360());
     }
-    /**
-     * Copy center, matrix, and sweep from other Arc3d.
-     */
+    /** Copy center, matrix, and sweep from other Arc3d */
     setFrom(other) {
         this._center.setFrom(other._center);
         this._matrix.setFrom(other._matrix);
@@ -170,12 +171,14 @@ class Arc3d extends CurvePrimitive {
      * @param result optional preallocated result
      */
     static create(center, vector0, vector90, sweep, result) {
-        const normal = vector0.unitCrossProductWithDefault(vector90, 0, 0, 0); // normal will be 000 for degenerate case ! !!
+        const normal = vector0.unitCrossProductWithDefault(vector90, 0, 0, 0); // normal will be 000 for degenerate case
         const matrix = Matrix3d.createColumns(vector0, vector90, normal);
         return Arc3d.createRefs(center !== undefined ? center.clone() : Point3d.create(0, 0, 0), matrix, sweep ? sweep.clone() : AngleSweep.create360(), result);
     }
-    /** Return a clone of this arc, projected to given z value.
+    /**
+     * Return a clone of this arc, projected to given z value.
      * * If `z` is omitted, the clone is at the z of the center.
+     * * This function projects the arc into a plane parallel to xy-plane.
      * * Note that projection to fixed z can change circle into ellipse (and (rarely) ellipse to circle)
      */
     cloneAtZ(z) {
@@ -184,7 +187,8 @@ class Arc3d extends CurvePrimitive {
         return Arc3d.createXYZXYZXYZ(this._center.x, this._center.y, this._center.z, this._matrix.coffs[0], this._matrix.coffs[3], 0, this._matrix.coffs[1], this._matrix.coffs[4], 0, this._sweep);
     }
     /**
-     * Create an arc by center (cx,cy,xz) with vectors (ux,uy,uz) and (vx,vy,vz) to points at 0 and 90 degrees in parameter space.
+     * Create an arc by center (cx,cy,xz) with vectors (ux,uy,uz) and (vx,vy,vz) to points at 0 and 90 degrees in
+     * parameter space.
      * @param result optional preallocated result
      */
     static createXYZXYZXYZ(cx, cy, cz, ux, uy, uz, vx, vy, vz, sweep, result) {
@@ -203,7 +207,8 @@ class Arc3d extends CurvePrimitive {
         const largeAxis = Geometry.maxXY(magX, magY);
         return jacobian / (largeAxis * largeAxis);
     }
-    /** Create a circular arc defined by start point, any intermediate point, and end point.
+    /**
+     * Create a circular arc defined by start point, any intermediate point, and end point.
      * If the points are colinear, assemble them into a linestring.
      */
     static createCircularStartMiddleEnd(pointA, pointB, pointC, result) {
@@ -266,7 +271,8 @@ class Arc3d extends CurvePrimitive {
         result.direction.scaleInPlace(this._sweep.sweepRadians);
         return result;
     }
-    /** Construct a plane with
+    /**
+     * Construct a plane with
      * * origin at the fractional position along the arc
      * * x axis is the first derivative, i.e. tangent along the arc
      * * y axis is the second derivative, i.e. in the plane and on the center side of the tangent.
@@ -344,12 +350,16 @@ class Arc3d extends CurvePrimitive {
      * Return the start point tof the arc.
      * @param result optional preallocated result
      */
-    startPoint(result) { return this.fractionToPoint(0.0, result); }
+    startPoint(result) {
+        return this.fractionToPoint(0.0, result);
+    }
     /**
      * Return the end point tof the arc.
      * @param result optional preallocated result
      */
-    endPoint(result) { return this.fractionToPoint(1.0, result); }
+    endPoint(result) {
+        return this.fractionToPoint(1.0, result);
+    }
     /** * If this is a circular arc, return the simple length derived from radius and sweep.
      * * Otherwise (i.e. if this elliptical) fall through to CurvePrimitive base implementation which
      *     Uses quadrature.
@@ -357,7 +367,8 @@ class Arc3d extends CurvePrimitive {
     curveLength() {
         return this.curveLengthBetweenFractions(0, 1);
     }
-    /** * If this is a circular arc, return the simple length derived from radius and sweep.
+    /**
+     * * 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.
      */
     curveLengthBetweenFractions(fraction0, fraction1) {
@@ -385,9 +396,9 @@ class Arc3d extends CurvePrimitive {
     /**
      * Return an approximate (but easy to compute) arc length.
      * The estimate is:
-     * * Form 8 chords on full circle, proportionally fewer for partials.  (But 2 extras if less than half circle.)
-     * * sum the chord lengths
-     * * For a circle, we know this crude approximation has to be increased by a factor (theta/(2 sin (theta/2)))
+     * * Form 8 chords on full circle, proportionally fewer for partials (but 2 extras if less than half circle).
+     * * Sum the chord lengths.
+     * * For a circle, we know this crude approximation has to be increased by a factor (theta/(2*sin(theta/2))).
      * * Apply that factor.
      * * Experiments confirm that this is within 3 percent for a variety of eccentricities and arc sweeps.
      */
@@ -452,7 +463,8 @@ class Arc3d extends CurvePrimitive {
     /**
      * Return details of the closest point on the arc, optionally extending to full ellipse.
      * @param spacePoint search for point closest to this point.
-     * @param extend if true, consider projections to the complete ellipse.   If false, consider only endpoints and projections within the arc sweep.
+     * @param extend if true, consider projections to the complete ellipse. If false, consider only endpoints and
+     * projections within the arc sweep.
      * @param result optional preallocated result.
      */
     closestPoint(spacePoint, extend, result) {
@@ -494,8 +506,11 @@ class Arc3d extends CurvePrimitive {
         return result;
     }
     /** Reverse the sweep  of the arc. */
-    reverseInPlace() { this._sweep.reverseInPlace(); }
-    /** apply a transform to the arc basis vectors.
+    reverseInPlace() {
+        this._sweep.reverseInPlace();
+    }
+    /**
+     * Apply a transform to the arc basis vectors.
      * * nonuniform (i.e. skewing) transforms are allowed.
      * * The transformed vector0 and vector90 are NOT squared up as major minor axes.  (This is a good feature!!)
      */
@@ -517,18 +532,14 @@ class Arc3d extends CurvePrimitive {
             && Geometry.isSmallMetricDistance(this._matrix.dotColumnX(normal))
             && Geometry.isSmallMetricDistance(this._matrix.dotColumnY(normal));
     }
-    /**
-     * Return true if the vector0 and vector90 are of equal length and perpendicular.
-     */
+    /** Return true if the vector0 and vector90 are of equal length and perpendicular. */
     get isCircular() {
         const axx = this._matrix.columnXMagnitudeSquared();
         const ayy = this._matrix.columnYMagnitudeSquared();
         const axy = this._matrix.columnXDotColumnY();
         return Angle.isPerpendicularDotSet(axx, ayy, axy) && Geometry.isSameCoordinateSquared(axx, ayy);
     }
-    /**
-     * Return true if the vector0 and vector90 are of equal length and perpendicular.
-     */
+    /** Return true if the vector0 and vector90 are of equal length and perpendicular. */
     circularRadiusXY() {
         const ux = this._matrix.at(0, 0);
         const uy = this._matrix.at(1, 0);
@@ -545,9 +556,11 @@ class Arc3d extends CurvePrimitive {
         return this.isCircular ? this._matrix.columnXMagnitude() : undefined;
     }
     /** Return the larger of the two defining vectors. */
-    maxVectorLength() { return Math.max(this._matrix.columnXMagnitude(), this._matrix.columnYMagnitude()); }
+    maxVectorLength() {
+        return Math.max(this._matrix.columnXMagnitude(), this._matrix.columnYMagnitude());
+    }
     /**
-     * compute intersections with a plane.
+     * Compute intersections with a plane.
      * @param plane plane to intersect
      * @param result array of locations on the curve.
      */
@@ -611,9 +624,9 @@ class Arc3d extends CurvePrimitive {
         range.extend(highPoint);
     }
     /**
-   * Returns a (high accuracy) range of the curve between fractional positions
-   * * Default implementation returns teh range of the curve from clonePartialCurve
-   */
+     * Returns a (high accuracy) range of the curve between fractional positions
+     * * Default implementation returns teh range of the curve from clonePartialCurve
+     */
     rangeBetweenFractions(fraction0, fraction1, transform) {
         const sweep = AngleSweep.createStartEndRadians(this.sweep.fractionToRadians(fraction0), this.sweep.fractionToRadians(fraction1));
         const range = Range3d.create();
@@ -636,9 +649,7 @@ class Arc3d extends CurvePrimitive {
         result.set(plane.altitude(this._center), plane.velocityXYZ(this._matrix.coffs[0], this._matrix.coffs[3], this._matrix.coffs[6]), plane.velocityXYZ(this._matrix.coffs[1], this._matrix.coffs[4], this._matrix.coffs[7]));
         return result;
     }
-    /**
-     * Create a new arc which is a unit circle centered at the origin.
-     */
+    /** Create a new arc which is a unit circle centered at the origin. */
     static createUnitCircle() {
         return Arc3d.createRefs(Point3d.create(0, 0, 0), Matrix3d.createIdentity(), AngleSweep.create360());
     }
@@ -669,8 +680,7 @@ 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 arc definition with rigid matrix form with axis radii */
     toScaledMatrix3d() {
         const angleData = Angle.dotProductsToHalfAngleTrigValues(this._matrix.columnXMagnitudeSquared(), this._matrix.columnYMagnitudeSquared(), this._matrix.columnXDotColumnY(), true);
         const vector0A = this._matrix.multiplyXY(angleData.c, angleData.s);
@@ -684,8 +694,7 @@ class Arc3d extends CurvePrimitive {
             sweep: this.sweep.cloneMinusRadians(angleData.radians),
         };
     }
-    /** Return the arc definition with center, two vectors, and angle sweep;
-     */
+    /** Return the arc definition with center, two vectors, and angle sweep; */
     toVectors() {
         return {
             center: this.center,
@@ -694,8 +703,7 @@ class Arc3d extends CurvePrimitive {
             sweep: this.sweep,
         };
     }
-    /** Return the arc definition with center, two vectors, and angle sweep, optionally transformed.
-     */
+    /** Return the arc definition with center, two vectors, and angle sweep, optionally transformed. */
     toTransformedVectors(transform) {
         return transform ? {
             center: transform.multiplyPoint3d(this._center),
@@ -710,8 +718,7 @@ class Arc3d extends CurvePrimitive {
                 sweep: this.sweep,
             };
     }
-    /** Return the arc definition with center, two vectors, and angle sweep, transformed to 4d points.
-     */
+    /** Return the arc definition with center, two vectors, and angle sweep, transformed to 4d points. */
     toTransformedPoint4d(matrix) {
         return {
             center: matrix.multiplyPoint3d(this._center, 1.0),
@@ -755,9 +762,7 @@ class Arc3d extends CurvePrimitive {
             vector90: this._matrix.columnY().toJSON(),
         };
     }
-    /**
-     * Test if this arc is almost equal to another GeometryQuery object
-     */
+    /** Test if this arc is almost equal to another GeometryQuery object */
     isAlmostEqual(otherGeometry) {
         if (otherGeometry instanceof Arc3d) {
             const other = otherGeometry;
@@ -780,7 +785,7 @@ class Arc3d extends CurvePrimitive {
         handler.endCurvePrimitive(this);
     }
     /**
-     * return the stroke count required for given options.
+     * Return the stroke count required for given options.
      * @param options StrokeOptions that determine count
      */
     computeStrokeCountForOptions(options) {
@@ -798,7 +803,8 @@ class Arc3d extends CurvePrimitive {
     dispatchToGeometryHandler(handler) {
         return handler.handleArc3d(this);
     }
-    /** Return (if possible) an arc which is a portion of this curve.
+    /**
+     * Return (if possible) an arc which is a portion of this curve.
      * @param fractionA [in] start fraction
      * @param fractionB [in] end fraction
      */
@@ -812,8 +818,10 @@ class Arc3d extends CurvePrimitive {
         arcB.sweep.setStartEndRadians(this.sweep.fractionToRadians(fractionA), this.sweep.fractionToRadians(fractionB));
         return arcB;
     }
-    /** 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)`
+    /**
+     * 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.
      *   * 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.
@@ -830,7 +838,8 @@ class Arc3d extends CurvePrimitive {
     /**
      * Find intervals of this CurvePrimitive that are interior to a clipper
      * @param clipper clip structure (e.g.clip planes)
-     * @param announce(optional) function to be called announcing fractional intervals"  ` announce(fraction0, fraction1, curvePrimitive)`
+     * @param announce(optional) function to be called announcing fractional intervals"
+     * ` announce(fraction0, fraction1, curvePrimitive)`
      * @returns true if any "in" segments are announced.
      */
     announceClipIntervals(clipper, announce) {
@@ -851,8 +860,10 @@ class Arc3d extends CurvePrimitive {
      * * Return the arc along with the fractional positions of the tangency points.
      * * In the returned object:
      *   * `arc` is the (bounded) arc
-     *   * `fraction10` is the tangency point's position as an interpolating fraction of the line segment from `point1` (backwards) to `point0`
-     *   * `fraction12` is the tangency point's position as an interpolating fraction of the line segment from `point1` (forward) to `point2`
+     *   * `fraction10` is the tangency point's position as an interpolating fraction of the line segment from
+     * `point1` (backwards) to `point0`
+     *   * `fraction12` is the tangency point's position as an interpolating fraction of the line segment from
+     * `point1` (forward) to `point2`
      *   * `point` is the `point1` input.
      * * If unable to construct the arc:
      *   * `point` is the `point1` input.
@@ -926,7 +937,9 @@ class Arc3d extends CurvePrimitive {
             const r0new = r0 - sign * options.leftOffsetDistance;
             const r90 = this.isCircular ? r0 : arcXY.matrixRef.columnYMagnitude();
             const r90new = this.isCircular ? r0new : r90 - sign * options.leftOffsetDistance;
-            if (!Geometry.isSmallMetricDistance(r0new) && (r0 * r0new > 0.0) && (this.isCircular || (!Geometry.isSmallMetricDistance(r90new) && (r90 * r90new > 0.0)))) {
+            if (!Geometry.isSmallMetricDistance(r0new)
+                && (r0 * r0new > 0.0)
+                && (this.isCircular || (!Geometry.isSmallMetricDistance(r90new) && (r90 * r90new > 0.0)))) {
                 const factor0 = r0new / r0;
                 const factor90 = this.isCircular ? factor0 : r90new / r90;
                 const matrix = arcXY.matrixClone();
@@ -942,7 +955,8 @@ class Arc3d extends CurvePrimitive {
         this.emitStrokableParts(handler, options.strokeOptions);
         return handler.claimResult();
     }
-    /** Project instance geometry (via dispatch) onto the given ray, and return the extreme fractional parameters of projection.
+    /**
+     * Project instance geometry (via dispatch) onto the given ray, and return the extreme fractional parameters of projection.
      * @param ray ray onto which the instance is projected. A `Vector3d` is treated as a `Ray3d` with zero origin.
      * @param lowHigh optional receiver for output
      * @returns range of fractional projection parameters onto the ray, where 0.0 is start of the ray and 1.0 is the end of the ray.
@@ -956,9 +970,9 @@ Arc3d._workPointB = Point3d.create();
 Arc3d._workPointC = Point3d.create();
 Arc3d._workVectorU = Vector3d.create();
 Arc3d._workVectorV = Vector3d.create();
-// !! misspelled Gauss in the published static !!!   Declare it ok.
+// !! 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) */
+/** 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;