@itwin/core-geometry 4.10.0-dev.8 → 5.0.0-dev.0

package/lib/esm/curve/internalContexts/EllipticalArcApproximationContext.js

@@ -113,10 +113,10 @@ export class QuadrantFractions {
     }
     /**
      * Compute quadrant data for the given angles.
-     * @param radians0 first radian angle
-     * @param radians1 second radian angle
+     * @param radians0 first radian angle.
+     * @param radians1 second radian angle.
      * @return quadrant number and start/end radian angles for the quadrant that contains both input angles, or
-     * undefined if no such quadrant.
+     * `undefined` if no such quadrant.
      * * The returned sweep is always counterclockwise: angle0 < angle1.
      */
     static getQuadrantRadians(radians0, radians1) {
@@ -134,13 +134,13 @@ export class QuadrantFractions {
             return { quadrant: 4, angle0: Angle.pi3Over2Radians, angle1: Angle.pi2Radians };
         return undefined;
     }
-    /** Compute the fractional range of Quadrant 1 for the given sweep. */
-    static getQ1FractionalRange(sweep) {
+    /** Compute the fractional range of Quadrant 1 for the given full sweep. */
+    static getQ1FractionalRange(fullSweep) {
         const angle0 = 0;
         const angle90 = 0.5 * Math.PI;
-        let f0 = sweep.radiansToSignedPeriodicFraction(angle0);
-        let f1 = sweep.radiansToSignedPeriodicFraction(angle90);
-        if (!sweep.isCCW)
+        let f0 = fullSweep.radiansToSignedPeriodicFraction(angle0);
+        let f1 = fullSweep.radiansToSignedPeriodicFraction(angle90);
+        if (!fullSweep.isCCW)
             [f0, f1] = [f1, f0];
         if (f1 < f0)
             f1 += 1;
@@ -162,7 +162,7 @@ class QuadrantFractionsProcessor {
      * Announce the beginning of processing for quadrant `q`.
      * @param _reversed whether `q.reverse()` was invoked before this call for symmetry reasons. If so, arcs will be
      * announced in the opposite order and with the opposite orientation.
-     * @return whether to process `q`
+     * @return whether to process `q`.
      */
     announceQuadrantBegin(_q, _reversed) { return true; }
     /**
@@ -173,8 +173,8 @@ class QuadrantFractionsProcessor {
      * @param _fPrev fractional parameter of E used to define the 3-point parent circle through the points at `fPrev`,
      * `f0`, and `f1` from which `arc` was constructed. If undefined, `arc` was generated from the circle defined by
      * the points at `f0` and `f1` and one of their tangents.
-     * @param _f0 fractional parameter of E at which point `arc` starts
-     * @param _f1 fractional parameter of E at which point `arc` ends
+     * @param _f0 fractional parameter of E at which point `arc` starts.
+     * @param _f1 fractional parameter of E at which point `arc` ends.
      */
     announceArc(_arc, _fPrev, _f0, _f1) { }
     /**
@@ -206,21 +206,21 @@ class ArcChainErrorProcessor extends QuadrantFractionsProcessor {
      * * Inputs should be in horizontal plane(s), as z-coordinates are ignored.
      * @param circularArc circular arc approximant. Assumed to start and end on the elliptical arc.
      * @param ellipticalArc elliptical arc being approximated.
-     * For best results, `f0` and `f1` should correspond to the start/end of `circularArc`
-     * @param f0 optional `ellipticalArc` start fraction to restrict its sweep
-     * @param f1 optional `ellipticalArc` end fraction to restrict its sweep
+     * For best results, `f0` and `f1` should correspond to the start/end of `circularArc`.
+     * @param f0 optional `ellipticalArc` start fraction to restrict its sweep.
+     * @param f1 optional `ellipticalArc` end fraction to restrict its sweep.
      * @return details of the perpendicular measuring the max approximation error, or undefined if no such perpendicular.
      * For each of `detailA` (refers to `circularArc`) and `detailB` (refers to unrestricted `ellipticalArc`):
-     * * `point` is the end of the perpendicular on each curve
-     * * `fraction` is the curve parameter of the point
-     * * `a` is the distance between the points
+     * * `point` is the end of the perpendicular on each curve.
+     * * `fraction` is the curve parameter of the point.
+     * * `a` is the distance between the points.
      */
     static computePrimitiveErrorXY(circularArc, ellipticalArc, f0, f1) {
         const handler = new CurveCurveCloseApproachXY();
         handler.maxDistanceToAccept = circularArc.quickLength() / 2;
         const trimEllipse = undefined !== f0 && undefined !== f1;
         const trimmedEllipticalArc = trimEllipse ? ellipticalArc.clonePartialCurve(f0, f1) : ellipticalArc;
-        // We expect only one perpendicular, not near an endpoint.
+        // we expect only one perpendicular, not near an endpoint.
         handler.allPerpendicularsArcArcBounded(circularArc, trimmedEllipticalArc);
         let maxPerp;
         for (const perp of handler.grabPairedResults()) {
@@ -263,7 +263,7 @@ class ArcChainErrorProcessor extends QuadrantFractionsProcessor {
 }
 /**
  * Processor for refining a single Q1 ordered interval [f0,f1] by perturbing an interior fraction f.
- * * This processor expects to repeatedly process a QuadrantFractions `q` wth `q.quadrant` = 1 and fractions array
+ * * This processor expects to repeatedly process a QuadrantFractions `q` with `q.quadrant` = 1 and fractions array
  * [fPrev, f0, f, f1], where fPrev is from the previously processed (possibly refined) adjacent interval; however, if
  * `q.interpolateStartTangent === true`, then no fPrev is necessary and [f0, f, f1] is expected.
  * * This is enough info to compute the two circular arcs spanning [f0,f] and [f,f1] and compare their approximation
@@ -307,8 +307,8 @@ class AdaptiveSubdivisionQ1IntervalErrorProcessor extends QuadrantFractionsProce
     /** Remember the initial value of the fraction f to be perturbed. */
     announceQuadrantBegin(q, reversed) {
         assert(q.quadrant === 1);
-        assert(!reversed); // ASSUME bracket and q.fractions have same ordering
-        // the first fraction might be an extra point for computing the first 3-pt arc.
+        assert(!reversed); // ASSUME [bracket0, bracket1] and q.fractions have the same ordering
+        // the first fraction might be an extra point for computing the first 3-pt arc
         assert(q.fractions.length === 4 || (q.fractions.length === 3 && q.interpolateStartTangent));
         this._error0 = this._error1 = Geometry.largeCoordinateResult;
         return true;
@@ -413,7 +413,7 @@ class AdaptiveSubdivisionQ1ErrorProcessor extends QuadrantFractionsProcessor {
         const interpolateStartTangent = Geometry.isAlmostEqualEitherNumber(f0, this._fractionRangeQ1.low, this._fractionRangeQ1.high, 0);
         const interpolateEndTangent = Geometry.isAlmostEqualEitherNumber(f1, this._fractionRangeQ1.low, this._fractionRangeQ1.high, 0);
         if (!interpolateStartTangent && undefined === fPrev)
-            fPrev = this.getPreviousFraction(f0); // createLastArc caller doesn't supply fPrev
+            fPrev = this.getPreviousFraction(f0); // createLastArc doesn't supply fPrev to announceArc
         const fractions = (undefined === fPrev) ? [f0, f, f1] : [fPrev, f0, f, f1];
         const q1 = [QuadrantFractions.create(1, fractions, interpolateStartTangent, interpolateEndTangent)];
         const processor = AdaptiveSubdivisionQ1IntervalErrorProcessor.create(this.fullEllipseXY, f0, f, f1);
@@ -430,7 +430,7 @@ class AdaptiveSubdivisionQ1ErrorProcessor extends QuadrantFractionsProcessor {
     }
     /**
      * Compute radian angles for the fractions in the current refinement that are strictly inside Q1.
-     * @param result optional preallocated array to clear and populate
+     * @param result optional preallocated array to clear and populate.
      * @return angles suitable for output from [[EllipticalArcSampler.computeRadiansStrictlyInsideQuadrant1]].
      */
     getRefinedInteriorQ1Angles(result) {
@@ -631,11 +631,11 @@ class ArcChainConstructionProcessor extends QuadrantFractionsProcessor {
  * @internal
  */
 export class EllipticalArcApproximationContext {
-    /** Constructor, captures input */
+    /** Constructor, captures input. */
     constructor(ellipticalArc) {
         this._isValidEllipticalArc = false;
         const data = ellipticalArc.toScaledMatrix3d();
-        this._ellipticalArc = Arc3d.createScaledXYColumns(data.center, data.axes, data.r0, data.r90, data.sweep);
+        this._ellipticalArc = Arc3d.createScaledXYColumns(data.center, data.axes, data.r0, data.r90, data.sweep); // work on the major-minor axis version of the arc to take advantage of its symmetry
         this._localToWorld = Transform.createRefs(data.center, data.axes);
         if (this._localToWorld.matrix.isSingular())
             return;
@@ -677,9 +677,9 @@ export class EllipticalArcApproximationContext {
         return this._isValidEllipticalArc;
     }
     /**
-     * Create a clone of the context's arc in local coordinates.
+     * Create a clone of the context's arc in local coordinates (with axes aligned to x-axis and y-axis).
      * @param fullSweep Optionally set full sweep on the returned local arc. Start angle is preserved.
-     * @returns local arc, or undefined if the arc is invalid
+     * @returns local arc, or undefined if the arc is invalid.
      */
     cloneLocalArc(fullSweep) {
         if (!this.isValidEllipticalArc)
@@ -703,9 +703,9 @@ export class EllipticalArcApproximationContext {
      * * A 2-point plus tangent construction is used to create the first and last circular arc in each quadrant.
      * * Symmetry of the announced circular arcs matching that of a multi-quadrant spanning elliptical arc is ensured by
      * processing the samples consistently, starting along the elliptical arc's major axis in each quadrant.
-     * @param ellipticalArc source arc to approximate
-     * @param quadrants structured samples, may be temporarily reversed for symmetry
-     * @param processor callbacks for handling the constructed arcs
+     * @param ellipticalArc source arc to approximate.
+     * @param quadrants structured samples, may be temporarily reversed for symmetry.
+     * @param processor callbacks for handling the constructed arcs.
      * @internal
     */
     static processQuadrantFractions(ellipticalArc, quadrants, processor) {
@@ -731,17 +731,19 @@ export class EllipticalArcApproximationContext {
             arc.sweep.setStartEndRadians(startAngle.radians, arc.sweep.endRadians);
             return arc; // returned arc starts at arcStart, ends at arcEnd
         };
-        const createFirstArc = (f0, f1, reverse) => {
+        const createFirstArc = (f0, f1) => {
             // This arc starts at the first sample f0 and ends at f1.
+            // This arc interpolates point and tangent at f0, but only point at f1.
             ellipticalArc.fractionToPointAndDerivative(f0, ray);
             ellipticalArc.fractionToPoint(f1, pt1);
-            if (reverse)
-                ray.direction.scaleInPlace(-1);
+            if (f0 > f1)
+                ray.direction.scaleInPlace(-1); // computed arc is retrograde
             const arc = arcBetween2Samples(ray, pt1, false);
             if (arc)
                 processor.announceArc(arc, undefined, f0, f1);
         };
         const createInnerArc = (f0, f1, f2) => {
+            // This arc starts at f1 and ends at f2
             let fPrev = f0;
             if (processor.getPreviousFraction)
                 fPrev = processor.getPreviousFraction(f1) ?? f0;
@@ -752,12 +754,14 @@ export class EllipticalArcApproximationContext {
             if (arc)
                 processor.announceArc(arc, fPrev, f1, f2);
         };
-        const createLastArc = (f0, f1, reverse) => {
-            // This arc starts at f0 and ends at the last sample f1. It is the only arc to use f1.
+        const createLastArc = (f0, f1) => {
+            // This arc starts at f0 and ends at the last sample f1.
+            // This arc interpolates point and tangent at f1, but only point at f0.
             ellipticalArc.fractionToPoint(f0, pt0);
             ellipticalArc.fractionToPointAndDerivative(f1, ray);
-            if (!reverse)
-                ray.direction.scaleInPlace(-1);
+            if (f1 > f0)
+                ray.direction.scaleInPlace(-1); // computed arc is retrograde
+            // compute last arc from f1 to f0, then reverse
             const arc = arcBetween2Samples(ray, pt0, true);
             if (arc)
                 processor.announceArc(arc, undefined, f0, f1);
@@ -787,13 +791,13 @@ export class EllipticalArcApproximationContext {
             if (!processor.announceQuadrantBegin(q, reversed))
                 continue;
             if (q.interpolateStartTangent)
-                createFirstArc(q.fractions[0], q.fractions[1], reversed);
+                createFirstArc(q.fractions[0], q.fractions[1]);
             // the first inner arc approximates the ellipse over [f[1],f[2]]; the last inner arc, over [f[n-3],f[n-2]]
             for (let i = 0; i + 2 < n - 1; ++i)
                 createInnerArc(q.fractions[i], q.fractions[i + 1], q.fractions[i + 2]);
             if (n > 2) { // the final arc approximates [f[n-2],f[n-1]]
                 if (q.interpolateEndTangent)
-                    createLastArc(q.fractions[n - 2], q.fractions[n - 1], reversed);
+                    createLastArc(q.fractions[n - 2], q.fractions[n - 1]);
                 else
                     createInnerArc(q.fractions[n - 3], q.fractions[n - 2], q.fractions[n - 1]);
             }
@@ -808,8 +812,8 @@ export class EllipticalArcApproximationContext {
      * @param samples structured sample data from the instance's elliptical arc.
      * @return details of the perpendicular measuring the max approximation error, or undefined if no such perpendicular.
      * For each of `detailA` and `detailB`:
-     * * `point` is the end of the perpendicular on each curve
-     * * `fraction` is the curve parameter of the point
+     * * `point` is the end of the perpendicular on each curve.
+     * * `fraction` is the curve parameter of the point.
      * * `a` is the distance between the points.
      * @internal
      */
@@ -982,8 +986,8 @@ export class EllipticalArcApproximationContext {
             return undefined;
         if (!options)
             options = EllipticalArcApproximationOptions.create();
-        const processor = ArcChainConstructionProcessor.create(this.ellipticalArc, options.forcePath);
         const samples = this.computeSampleFractions(options, true);
+        const processor = ArcChainConstructionProcessor.create(this.ellipticalArc, options.forcePath);
         EllipticalArcApproximationContext.processQuadrantFractions(this.ellipticalArc, samples, processor);
         return processor.chain;
     }