@itwin/core-geometry 4.9.0-dev.8 → 4.9.0

package/lib/esm/curve/Arc3d.js

@@ -2,6 +2,7 @@
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
+import { Constant } from "../Constant";
 import { AxisOrder, Geometry } from "../Geometry";
 import { Angle } from "../geometry3d/Angle";
 import { AngleSweep } from "../geometry3d/AngleSweep";
@@ -15,24 +16,133 @@ import { CurveExtendMode, CurveExtendOptions } from "./CurveExtendMode";
 import { CurveIntervalRole, CurveLocationDetail, CurveSearchStatus } from "./CurveLocationDetail";
 import { CurvePrimitive } from "./CurvePrimitive";
 import { CurveOffsetXYHandler } from "./internalContexts/CurveOffsetXYHandler";
+import { EllipticalArcApproximationContext } from "./internalContexts/EllipticalArcApproximationContext";
 import { PlaneAltitudeRangeContext } from "./internalContexts/PlaneAltitudeRangeContext";
+import { LineSegment3d } from "./LineSegment3d";
 import { LineString3d } from "./LineString3d";
 import { OffsetOptions } from "./OffsetOptions";
+import { Path } from "./Path";
 import { StrokeOptions } from "./StrokeOptions";
+/**
+ * Enumeration of methods used to sample an elliptical arc in [[Arc3d.constructCircularArcChainApproximation]].
+ * * Because ellipses have two axes of symmetry, samples are computed for one quadrant and reflected across each
+ * axis to the other quadrants. Any samples that fall outside the arc sweep are filtered out.
+ * @public
+ */
+export var EllipticalArcSampleMethod;
+(function (EllipticalArcSampleMethod) {
+    /** Generate n samples uniformly interpolated between the min and max parameters of a full ellipse quadrant. */
+    EllipticalArcSampleMethod[EllipticalArcSampleMethod["UniformParameter"] = 0] = "UniformParameter";
+    /** Generate n samples uniformly interpolated between the min and max curvatures of a full ellipse quadrant. */
+    EllipticalArcSampleMethod[EllipticalArcSampleMethod["UniformCurvature"] = 1] = "UniformCurvature";
+    /**
+     * Generate n samples interpolated between the min and max curvatures of a full ellipse quadrant, using a
+     * [[FractionMapper]] callback to generate the interpolation weights.
+     */
+    EllipticalArcSampleMethod[EllipticalArcSampleMethod["NonUniformCurvature"] = 2] = "NonUniformCurvature";
+    /**
+     * Generate samples by subdividing parameter space until the approximation has less than a given max
+     * distance to the elliptical arc.
+     */
+    EllipticalArcSampleMethod[EllipticalArcSampleMethod["AdaptiveSubdivision"] = 3] = "AdaptiveSubdivision";
+})(EllipticalArcSampleMethod || (EllipticalArcSampleMethod = {}));
+/**
+ * Options for generating samples for the construction of an approximation to an elliptical arc.
+ * * Used by [[Arc3d.constructCircularArcChainApproximation]].
+ * @public
+ */
+export class EllipticalArcApproximationOptions {
+    constructor(method, numSamplesInQuadrant, maxError, remapFunction, forcePath) {
+        this._sampleMethod = method;
+        this._numSamplesInQuadrant = numSamplesInQuadrant;
+        this._maxError = maxError;
+        this._remapFunction = remapFunction;
+        this._forcePath = forcePath;
+    }
+    /**
+     * Construct options with optional defaults.
+     * @param method sample method, default [[EllipticalArcSampleMethod.AdaptiveSubdivision]].
+     * @param numSamplesInQuadrant samples in each full quadrant for interpolation methods, default 4.
+     * @param maxError positive maximum distance to ellipse for the subdivision method, default 1cm.
+     * @param remapFunction optional callback to remap fraction space for [[EllipticalArcSampleMethod.NonUniformCurvature]],
+     * default quadratic. For best results, this function should be a bijection.
+     * @param forcePath whether to return a [[Path]] instead of a [[Loop]] when approximating a full elliptical arc,
+     * default false.
+     */
+    static create(method = EllipticalArcSampleMethod.AdaptiveSubdivision, numSamplesInQuadrant = 4, maxError = this.defaultMaxError, remapFunction = (x) => x * x, forcePath = false) {
+        if (numSamplesInQuadrant < 2)
+            numSamplesInQuadrant = 2;
+        if (maxError <= 0)
+            maxError = this.defaultMaxError;
+        return new EllipticalArcApproximationOptions(method, numSamplesInQuadrant, maxError, remapFunction, forcePath);
+    }
+    /** Clone the options. */
+    clone() {
+        return new EllipticalArcApproximationOptions(this.sampleMethod, this.numSamplesInQuadrant, this.maxError, this.remapFunction, this.forcePath);
+    }
+    /** Method used to sample the elliptical arc. */
+    get sampleMethod() {
+        return this._sampleMethod;
+    }
+    set sampleMethod(method) {
+        this._sampleMethod = method;
+    }
+    /**
+     * Number of samples to return in each full quadrant, including endpoint(s).
+     * * Used by interpolation sample methods.
+     * * In general, for n samples, the approximating [[Path]] consists of n-1 primitives,
+     * and the approximating [[Loop]] consists of n primitives.
+     * * Minimum value is 2.
+     */
+    get numSamplesInQuadrant() {
+        return this._numSamplesInQuadrant;
+    }
+    set numSamplesInQuadrant(numSamples) {
+        this._numSamplesInQuadrant = numSamples;
+    }
+    /**
+     * Maximum distance (in meters) of the computed approximation to the elliptical arc.
+     * * Used by [[EllipticalArcSampleMethod.AdaptiveSubdivision]].
+     */
+    get maxError() {
+        return this._maxError;
+    }
+    set maxError(error) {
+        this._maxError = error;
+    }
+    /**
+     * Callback function to remap fraction space to fraction space.
+     * * Used by [[EllipticalArcSampleMethod.NonUniformCurvature]].
+     */
+    get remapFunction() {
+        return this._remapFunction;
+    }
+    set remapFunction(f) {
+        this._remapFunction = f;
+    }
+    /** Whether to return a [[Path]] instead of a [[Loop]] when approximating a full (closed) ellipse. */
+    get forcePath() {
+        return this._forcePath;
+    }
+    set forcePath(value) {
+        this._forcePath = value;
+    }
+}
+/** Default error tolerance. */
+EllipticalArcApproximationOptions.defaultMaxError = Constant.oneCentimeter;
 /**
  * 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.
  * * 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 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.
+ *   * 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 that constructing these 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
  */
 export class Arc3d extends CurvePrimitive {
@@ -167,7 +277,7 @@ export class Arc3d extends CurvePrimitive {
      * @param center arc center
      * @param vector0 vector to 0 degrees (commonly major axis)
      * @param vector90 vector to 90 degree point (commonly minor axis)
-     * @param sweep sweep limits
+     * @param sweep sweep limits (default full sweep)
      * @param result optional preallocated result
      */
     static create(center, vector0, vector90, sweep, result) {
@@ -176,12 +286,12 @@ export class Arc3d extends CurvePrimitive {
         return Arc3d.createRefs(center !== undefined ? center.clone() : Point3d.create(0, 0, 0), matrix, sweep ? sweep.clone() : AngleSweep.create360(), result);
     }
     /**
-     * Create an arc from three points on the ellipse: two points on an axis and one in between.
+     * Create an elliptical arc from three points on the ellipse: two points on an axis and one in between.
      * @param point0 start of arc, on an axis
      * @param point1 point on arc somewhere between `point0` and `point2`
      * @param point2 point on arc directly opposite `point0`
      * @param sweep angular sweep, measured from `point0` in the direction of `point1`.
-     *  For a semicircle from `point0` to `point2` passing through `point1`, pass `AngleSweep.createStartEndDegrees(0,180)`.
+     *  For a half-ellipse from `point0` to `point2` passing through `point1`, pass `AngleSweep.createStartEndDegrees(0,180)`.
      *  Default value is full sweep to create the entire ellipse.
      * @param result optional preallocated result
      * @returns elliptical arc, or undefined if construction impossible.
@@ -204,6 +314,68 @@ export class Arc3d extends CurvePrimitive {
         vector90.scaleInPlace(v90Len);
         return Arc3d.create(center, vector0, vector90, sweep, result);
     }
+    /**
+     * Create a circular arc defined by start point, tangent at start point, and end point.
+     * If tangent is parallel to line segment from start to end, return the line segment.
+     */
+    static createCircularStartTangentEnd(start, tangentAtStart, end, result) {
+        // To find the circle passing through start and end with tangentAtStart at start:
+        //      - find line 1: the perpendicular bisector of the line from start to end.
+        //      - find line 2: the perpendicular to the tangentAtStart.
+        //      - intersection of the two lines would be the circle center.
+        const vector = Vector3d.createStartEnd(start, end);
+        const normal = tangentAtStart.crossProduct(vector).normalize();
+        if (normal) {
+            const vectorPerp = normal.crossProduct(vector);
+            const tangentPerp = normal.crossProduct(tangentAtStart);
+            const midPoint = start.plusScaled(vector, 0.5);
+            const lineSeg1 = LineSegment3d.create(start, start.plusScaled(tangentPerp, 1));
+            const lineSeg2 = LineSegment3d.create(midPoint, midPoint.plusScaled(vectorPerp, 1));
+            const intersection = LineSegment3d.closestApproach(lineSeg1, true, lineSeg2, true);
+            if (intersection) {
+                const center = intersection.detailA.point;
+                const vector0 = Vector3d.createStartEnd(center, start);
+                const vector90 = normal.crossProduct(vector0);
+                const endVector = Vector3d.createStartEnd(center, end);
+                const sweep = AngleSweep.create(vector0.signedAngleTo(endVector, normal));
+                return Arc3d.create(center, vector0, vector90, sweep, result);
+            }
+        }
+        return LineSegment3d.create(start, end);
+    }
+    /**
+     * Create a circular arc defined by start and end points and radius.
+     * @param start start point of the arc
+     * @param end end point of the arc
+     * @param helper a third point near the arc in its plane, or a vector in the direction of the arc normal
+     * @returns the constructed arc, or undefined if desired arc cannot be constructed
+     */
+    static createCircularStartEndRadius(start, end, radius, helper) {
+        // Construct a line segment from start to end. It is a chord of the circle,
+        // so the circle center is on its perpendicular bisector.
+        const semiChordLen2 = 0.25 * start.distanceSquared(end);
+        const radius2 = radius * radius;
+        if (radius2 < semiChordLen2)
+            return undefined;
+        const height = Math.sqrt(radius2 - semiChordLen2); // Pythagoras gives us distance from chord to center
+        const normal = Vector3d.createZero(this._workVectorU);
+        const vecToCenter = Vector3d.createZero(this._workVectorV);
+        // the helper gives us the circle normal
+        if (helper instanceof Point3d)
+            start.crossProductToPoints(helper, end, normal);
+        else
+            normal.setFrom(helper);
+        // the normal and chord direction give us the side of the chord on which the center resides
+        if (!normal.normalizeInPlace() || !normal.crossProductStartEnd(start, end, vecToCenter).scaleToLength(height, vecToCenter))
+            return undefined;
+        const center = Point3d.createZero();
+        start.interpolate(0.5, end, center).addInPlace(vecToCenter);
+        const vector0 = Vector3d.createStartEnd(center, start, this._workVectorW);
+        const endVector = Vector3d.createStartEnd(center, end, this._workVectorV); // reuse static
+        const sweep = AngleSweep.create(vector0.signedAngleTo(endVector, normal));
+        const vector90 = normal.crossProduct(vector0, this._workVectorV); // has length radius (reuse static)
+        return Arc3d.createRefs(center, Matrix3d.createColumns(vector0, vector90, normal), sweep);
+    }
     /**
      * Return a clone of this arc, projected to given z value.
      * * If `z` is omitted, the clone is at the z of the center.
@@ -247,10 +419,10 @@ export class Arc3d extends CurvePrimitive {
         const ac2 = vectorAC.magnitudeSquared();
         const normal = vectorAB.sizedCrossProduct(vectorAC, Math.sqrt(Math.sqrt(ab2 * ac2)));
         if (normal) {
-            const vectorToCenter = SmallSystem.linearSystem3d(normal.x, normal.y, normal.z, vectorAB.x, vectorAB.y, vectorAB.z, vectorAC.x, vectorAC.y, vectorAC.z, 0, // vectorToCenter DOT normal = 0
-            0.5 * ab2, // vectorToCenter DOT vectorAB = 0.5 * vectorAB DOT vectorAB (Rayleigh quotient)
+            const vectorToCenter = SmallSystem.linearSystem3d(normal.x, normal.y, normal.z, vectorAB.x, vectorAB.y, vectorAB.z, vectorAC.x, vectorAC.y, vectorAC.z, 0, // vectorToCenter DOT normal = 0 (ensure normal is perp to the plane of the 3 points)
+            0.5 * ab2, // vectorToCenter DOT vectorAB = ab2 / 2 (ensure the projection of vectorToCenter on AB bisects AB)
             0.5 * ac2);
-            if (vectorToCenter) {
+            if (vectorToCenter) { // i.e., the negative of vectorX
                 const center = Point3d.create(pointA.x, pointA.y, pointA.z).plus(vectorToCenter);
                 const vectorX = Vector3d.createStartEnd(center, pointA);
                 const vectorY = Vector3d.createRotateVectorAroundVector(vectorX, normal, Angle.createDegrees(90));
@@ -334,7 +506,7 @@ export class Arc3d extends CurvePrimitive {
         return result;
     }
     /**
-     * Evaluate the point and derivative with respect to the angle (in radians)
+     * Evaluate the point with respect to the angle (in radians)
      * @param radians angular position
      * @param result optional preallocated ray.
      */
@@ -376,14 +548,14 @@ export class Arc3d extends CurvePrimitive {
         return result;
     }
     /**
-     * Return the start point tof the arc.
+     * Return the start point of the arc.
      * @param result optional preallocated result
      */
     startPoint(result) {
         return this.fractionToPoint(0.0, result);
     }
     /**
-     * Return the end point tof the arc.
+     * Return the end point of the arc.
      * @param result optional preallocated result
      */
     endPoint(result) {
@@ -471,19 +643,19 @@ export class Arc3d extends CurvePrimitive {
         return CurveLocationDetail.createConditionalMoveSignedDistance(allowExtension, this, startFraction, startFraction + signedFractionMove, signedDistance, result);
     }
     /**
-     * Return all angles (in radians) where the ellipse tangent is perpendicular to the vector to a spacePoint.
+     * Return all radian angles where the ellipse tangent is perpendicular to the vector to a spacePoint.
      * @param spacePoint point of origin of vectors to the ellipse
-     * @param _extend (NOT SUPPORTED -- ALWAYS ACTS AS "true")
-     * @param _endpoints if true, force the end radians into the result.
+     * @param _extend always true. Sweep is ignored: perpendiculars for the full ellipse are returned.
+     * @param endpoints if true, force the end radians into the result.
      */
-    allPerpendicularAngles(spacePoint, _extend = true, _endpoints = false) {
+    allPerpendicularAngles(spacePoint, _extend = true, endpoints = false) {
         const radians = [];
         const vectorQ = spacePoint.vectorTo(this.center);
         const uu = this._matrix.columnXMagnitudeSquared();
         const uv = this._matrix.columnXDotColumnY();
         const vv = this._matrix.columnYMagnitudeSquared();
         TrigPolynomial.solveUnitCircleImplicitQuadricIntersection(uv, vv - uu, -uv, this._matrix.dotColumnY(vectorQ), -this._matrix.dotColumnX(vectorQ), 0.0, radians);
-        if (_endpoints) {
+        if (endpoints) {
             radians.push(this.sweep.startRadians);
             radians.push(this.sweep.endRadians);
         }
@@ -679,7 +851,7 @@ export 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 in the xy-plane centered at the origin. */
     static createUnitCircle() {
         return Arc3d.createRefs(Point3d.create(0, 0, 0), Matrix3d.createIdentity(), AngleSweep.create360());
     }
@@ -690,7 +862,7 @@ export class Arc3d extends CurvePrimitive {
      * @param sweep sweep limits.  defaults to full circle.
      */
     static createXY(center, radius, sweep = AngleSweep.create360()) {
-        return new Arc3d(center.clone(), Matrix3d.createScale(radius, radius, 1.0), sweep);
+        return new Arc3d(center.clone(), Matrix3d.createScale(radius, radius, 1.0), sweep.clone());
     }
     /**
      * Create a new arc which is parallel to the xy plane, with given center and x,y radii, and optional angle sweep
@@ -700,7 +872,7 @@ export class Arc3d extends CurvePrimitive {
      * @param sweep angle sweep
      */
     static createXYEllipse(center, radiusA, radiusB, sweep = AngleSweep.create360()) {
-        return new Arc3d(center.clone(), Matrix3d.createScale(radiusA, radiusB, 1.0), sweep);
+        return new Arc3d(center.clone(), Matrix3d.createScale(radiusA, radiusB, 1.0), sweep.clone());
     }
     /**
      * Replace the arc's 0 and 90 degree vectors.
@@ -717,8 +889,8 @@ export class Arc3d extends CurvePrimitive {
         const vector90A = this._matrix.multiplyXY(-angleData.s, angleData.c);
         const axes = Matrix3d.createRigidFromColumns(vector0A, vector90A, AxisOrder.XYZ);
         return {
+            center: this._center.clone(),
             axes: (axes ? axes : Matrix3d.createIdentity()),
-            center: this._center,
             r0: vector0A.magnitude(),
             r90: vector90A.magnitude(),
             sweep: this.sweep.cloneMinusRadians(angleData.radians),
@@ -727,10 +899,10 @@ export class Arc3d extends CurvePrimitive {
     /** Return the arc definition with center, two vectors, and angle sweep; */
     toVectors() {
         return {
-            center: this.center,
+            center: this.center.clone(),
             vector0: this._matrix.columnX(),
             vector90: this._matrix.columnY(),
-            sweep: this.sweep,
+            sweep: this.sweep.clone(),
         };
     }
     /** Return the arc definition with center, two vectors, and angle sweep, optionally transformed. */
@@ -739,13 +911,13 @@ export class Arc3d extends CurvePrimitive {
             center: transform.multiplyPoint3d(this._center),
             vector0: transform.multiplyVector(this._matrix.columnX()),
             vector90: transform.multiplyVector(this._matrix.columnY()),
-            sweep: this.sweep,
+            sweep: this.sweep.clone(),
         }
             : {
                 center: this._center.clone(),
                 vector0: this._matrix.columnX(),
                 vector90: this._matrix.columnY(),
-                sweep: this.sweep,
+                sweep: this.sweep.clone(),
             };
     }
     /** Return the arc definition with center, two vectors, and angle sweep, transformed to 4d points. */
@@ -754,7 +926,7 @@ export class Arc3d extends CurvePrimitive {
             center: matrix.multiplyPoint3d(this._center, 1.0),
             vector0: matrix.multiplyPoint3d(this._matrix.columnX(), 0.0),
             vector90: matrix.multiplyPoint3d(this._matrix.columnY(), 0.0),
-            sweep: this.sweep,
+            sweep: this.sweep.clone(),
         };
     }
     /**
@@ -994,12 +1166,27 @@ export class Arc3d extends CurvePrimitive {
     projectedParameterRange(ray, lowHigh) {
         return PlaneAltitudeRangeContext.findExtremeFractionsAlongDirection(this, ray, lowHigh);
     }
+    /**
+     * Construct a circular arc chain approximation to the instance elliptical arc.
+     * @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.
+     */
+    constructCircularArcChainApproximation(options) {
+        if (!options)
+            options = EllipticalArcApproximationOptions.create();
+        const context = EllipticalArcApproximationContext.create(this);
+        const result = context.constructCircularArcChainApproximation(options);
+        if (!result && this.isCircular)
+            return (this.sweep.isFullCircle && options.forcePath) ? Path.create(this) : this;
+        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) */