@itwin/core-geometry 5.3.0-dev.9 → 5.4.0-dev.2

package/lib/esm/curve/spiral/DirectSpiral3d.js

@@ -18,10 +18,10 @@ import { MXCubicAlongArcEvaluator } from "./MXCubicAlongArcSpiralEvaluator";
 import { PolishCubicEvaluator } from "./PolishCubicSpiralEvaluator";
 import { TransitionSpiral3d } from "./TransitionSpiral3d";
 /**
-* DirectSpiral3d acts like a TransitionSpiral3d for serialization purposes, but implements spiral types that have "direct" xy calculations without the integrations required
-* for IntegratedSpiral3d.
+* DirectSpiral3d acts like a TransitionSpiral3d for serialization purposes, but implements spiral types that have
+* "direct" xy calculations without the integrations required for IntegratedSpiral3d.
 * * Each DirectSpiral3d carries an XYCurveEvaluator to give it specialized behavior.
-* * Direct spirals that flow through serialization to native imodel02 are create with these static methods:
+* * Direct spirals that flow through serialization to native imodel02 are created with these static methods:
 *   * createArema
 *   * createJapaneseCubic
 *   * createAustralianRail
@@ -34,32 +34,45 @@ import { TransitionSpiral3d } from "./TransitionSpiral3d";
 * @public
 */
 export class DirectSpiral3d extends TransitionSpiral3d {
-    /** String name for schema properties */
+    /** String name for schema properties. */
     curvePrimitiveType = "transitionSpiral";
-    /** stroked approximation of entire spiral. This is AFTER the localToWorld transform ... */
+    /** Stroked approximation of entire spiral. This is AFTER the localToWorld transform. */
     _globalStrokes;
-    /** stroked approximation of active spiral.  This is AFTER the localToWorld transfomr ...
-     * * Same count as global -- possibly overly fine, but it gives some consistency between same clothoid constructed as partial versus complete.
-     * * If no trimming, this points to the same place as the _globalStrokes !!!  Don't double transform!!!
+    /**
+     * Stroked approximation of active spiral. This is AFTER the localToWorld transform.
+     * * Same count as global; possibly overly fine, but it gives some consistency between same clothoid constructed as
+     * partial versus complete.
+     * * If no trimming, this points to the same place as the _globalStrokes. DO NOT double transform.
      */
     _activeStrokes;
-    /** Return the internal stroked form of the (possibly partial) spiral   */
-    get activeStrokes() { return this._activeStrokes !== undefined ? this._activeStrokes : this._globalStrokes; }
+    /** Return the internal stroked form of the (possibly partial) spiral. */
+    get activeStrokes() {
+        return this._activeStrokes !== undefined ? this._activeStrokes : this._globalStrokes;
+    }
     _nominalL1;
     _nominalR1;
     _evaluator;
     /** Return the nominal end radius. */
-    get nominalR1() { return this._nominalR1; }
+    get nominalR1() {
+        return this._nominalR1;
+    }
     /** Return the nominal distance from inflection to endpoint. */
-    get nominalL1() { return this._nominalL1; }
+    get nominalL1() {
+        return this._nominalL1;
+    }
     /** Return the nominal end curvature */
-    get nominalCurvature1() { return TransitionSpiral3d.radiusToCurvature(this._nominalR1); }
-    /** Return the low level evaluator
+    get nominalCurvature1() {
+        return TransitionSpiral3d.radiusToCurvature(this._nominalR1);
+    }
+    /**
+     * Return the low level evaluator.
      * @internal
      */
-    get evaluator() { return this._evaluator; }
+    get evaluator() {
+        return this._evaluator;
+    }
     // constructor demands radius1 and distance1 for nominal construction.
-    // caller is responsible for managing intervals of partial spiral
+    // caller is responsible for managing intervals of partial spiral.
     constructor(localToWorld, spiralType, originalProperties, nominalL1, nominalR1, activeFractionInterval, evaluator) {
         super(spiralType, localToWorld, activeFractionInterval, originalProperties);
         this._nominalL1 = nominalL1;
@@ -67,14 +80,16 @@ export class DirectSpiral3d extends TransitionSpiral3d {
         this._evaluator = evaluator;
         this._globalStrokes = LineString3d.create();
         this._activeStrokes = LineString3d.create();
-        // initialize for compiler -- but this will be recomputed in refreshComputeProperties ...
+        // initialize for compiler; but this will be recomputed in refreshComputeProperties
         this.refreshComputedProperties();
     }
     /**
      * Compute stroke data in an interval.
      * @param strokes strokes to clear and refill.
-     * @param fraction0 start fraction
-     * @param fraction1 end fraction
+     * @param fractionA start fraction.
+     * @param fractionB end fraction.
+     * @param numInterval number of intervals.
+     * @param applyLocalToWorld if true, apply the localToWorld transform.
      */
     computeStrokes(strokes, fractionA, fractionB, numInterval, applyLocalToWorld = true) {
         if (numInterval < 1)
@@ -103,7 +118,7 @@ export class DirectSpiral3d extends TransitionSpiral3d {
             trueDistance0 = trueDistance1;
         }
     }
-    /** Recompute strokes */
+    /** Recompute strokes. */
     refreshComputedProperties() {
         const sweepRadians = this.nominalL1 / (2.0 * this.nominalR1);
         const radiansStep = 0.02;
@@ -115,12 +130,14 @@ export class DirectSpiral3d extends TransitionSpiral3d {
     }
     /**
      * Create a spiral object which uses numXTerm terms from the clothoid X series and numYTerm from the clothoid Y series.
-     * @param numXTerm  number of terms to use from X series
+     * @param spiralType type of spiral.
+     * @param localToWorld placement frame. Inflection point is at origin, initial direction is along x axis.
+     * @param numXTerm number of terms to use from X series
      * @param numYTerm number of terms to use from Y series
-     * @param localToWorld placement frame.  Inflection point is at origin, initial direction is along x axis.
+     * @param originalProperties (optional) transition conditional properties.
      * @param nominalL1 design distance from inflection to end point.
      * @param nominalR1 design radius at end point.
-     * @param activeInterval active interval (as fractions of nominalL1 !!!)
+     * @param activeInterval (optional) active interval (as fractions of nominalL1)
      */
     static createTruncatedClothoid(spiralType, localToWorld, numXTerm, numYTerm, originalProperties, nominalL1, nominalR1, activeInterval) {
         if (numXTerm < 1)
@@ -130,29 +147,16 @@ export class DirectSpiral3d extends TransitionSpiral3d {
         const evaluator = new ClothoidSeriesRLEvaluator(nominalL1, 1.0 / (2.0 * nominalL1 * nominalR1), numXTerm, numYTerm);
         return new DirectSpiral3d(localToWorld.clone(), spiralType, originalProperties, nominalL1, nominalR1, activeInterval ? activeInterval.clone() : Segment1d.create(0, 1), evaluator);
     }
-    /**
-     * Create an Japanese spiral clothoid approximation
-     *   * X is 1 terms of the clothoid series as a function of nominal distance along.
-     *   * Y is 1 terms f the clothoid series as a function of nominal distance along.
-     *   * Remark: This is identical to the ChineseCubic
-     * @param localToWorld axes with inflection at origin, tangent along x axis
-     * @param nominalL1 nominal length as used in series LR terms.
-     * @param nominalR1 nominal final radius as used in series LR terms
-     * @param activeInterval fractional interval with (0, nominalL1) range for nominal distance along
-     */
-    static createJapaneseCubic(localToWorld, nominalL1, nominalR1, activeInterval) {
-        return this.createTruncatedClothoid("JapaneseCubic", localToWorld, 1, 1, undefined, nominalL1, nominalR1, activeInterval);
-    }
     /**
      * Create a czech cubic.
-     * This is y= m*x^3 with
-     * * x any point on the x axis
-     * * `fraction` along the spiral goes to `x = fraction * L`
-     * * m is gamma / (6RL)
+     * This is y = m*x^3 with
+     * * x any point on the x axis.
+     * * `fraction` along the spiral goes to `x = fraction * L`.
+     * * m is gamma/(6RL).
      *    * 1/(6RL) is the leading term of the sine series.
-     *    * `gamma = 2R/sqrt (4RR-LL)` pushes y up a little bit to simulate the lost series terms.
+     *    * `gamma = 2R/sqrt(4RR-LL)` pushes y up a little bit to simulate the lost series terms.
      * @param localToWorld
-     * @param nominalLx nominal length along x axis
+     * @param nominalLx nominal length along x axis.
      * @param nominalR1
      * @param activeInterval
      */
@@ -164,15 +168,14 @@ export class DirectSpiral3d extends TransitionSpiral3d {
     }
     /**
      * Create an italian spiral
-     * This is y= m*x^3 with
-     * * x any point on the x axis
-     * * `fraction` along the spiral goes to `x = fraction * L`
-     * * m is gamma / (6RL)
+     * This is y = m*x^3 with
+     * * x any point on the x axis.
+     * * `fraction` along the spiral goes to `x = fraction * L`.
+     * * m is gamma/(6RL).
      *    * 1/(6RL) is the leading term of the sine series.
-     *    * `gamma = 2R/sqrt (4RR-LL)` pushes y up a little bit to simulate the lost series terms.
-     * * L in gamma and m is the
+     *    * `gamma = 2R/sqrt(4RR-LL)` pushes y up a little bit to simulate the lost series terms.
      * @param localToWorld
-     * @param nominalL1 nominal length along the spiral
+     * @param nominalL1 nominal length along the spiral.
      * @param nominalR1
      * @param activeInterval
      */
@@ -184,12 +187,12 @@ export class DirectSpiral3d extends TransitionSpiral3d {
     }
     /**
      * Create an MX Cubic whose nominal length is close to along the curve.
-     * This is y= m*x^3 with
-     * * m is 1/ (6RL1)
+     * This is y = m*x^3 with
+     * * m is 1/(6RL1).
      *    * 1/(6RL) is the leading term of the sine series.
-     * * L1 is an along-the-x-axis distance that is slightly LESS THAN the nominal length
-     * * x is axis position that is slightly LESS than nominal distance along
-     * * L1, x use the approximation   `x = s * ( 1 - s^4/ (40 R R L L))
+     * * L1 is an along-the-x-axis distance that is slightly LESS THAN the nominal length.
+     * * x is axis position that is slightly LESS than nominal distance along.
+     * * L1, x use the approximation `x = s * ( 1 - s^4/ (40 R R L L))
      * @param localToWorld
      * @param nominalL1
      * @param nominalR1
@@ -203,12 +206,12 @@ export class DirectSpiral3d extends TransitionSpiral3d {
     }
     /**
      * Create a polish cubic
-     * This is y= m*x^3 with
-     * * m is 1/ (6RL)
+     * This is y = m*x^3 with
+     * * m is 1/(6RL).
      *    * 1/(6RL) is the leading term of the sine series.
-     * * L is nominal length
+     * * L is nominal length.
      * * R is nominal end radius.
-     * * x ranges up to the x axis distance for which the polish distance series produces f(x)=L
+     * * x ranges up to the x axis distance for which the polish distance series produces f(x) = L.
      * * The support class PolishCubicEvaluator has static methods for the distance series and its inversion.
      */
     static createPolishCubic(localToWorld, nominalL1, nominalR1, activeInterval) {
@@ -219,12 +222,12 @@ export class DirectSpiral3d extends TransitionSpiral3d {
     }
     /**
      * Create an AustralianRailCorp spiral
-     * This is y= m*x^3 with
-     * * x any point on the x axis
-     * * `fraction` along the spiral goes to `x = fraction * L`
-     * * m is gamma / (6RL)
+     * This is y = m*x^3 with
+     * * x any point on the x axis.
+     * * `fraction` along the spiral goes to `x = fraction * L`.
+     * * m is gamma/(6RL).
      *    * 1/(6RL) is the leading term of the sine series.
-     *    * `gamma = 2R/sqrt (4RR-LL)` pushes y up a little bit to simulate the lost series terms.
+     *    * `gamma = 2R/sqrt(4RR-LL)` pushes y up a little bit to simulate the lost series terms.
      * @param localToWorld
      * @param nominalL1
      * @param nominalR1
@@ -237,64 +240,78 @@ export class DirectSpiral3d extends TransitionSpiral3d {
         return new DirectSpiral3d(localToWorld.clone(), "AustralianRailCorp", undefined, nominalL1, nominalR1, activeInterval ? activeInterval.clone() : Segment1d.create(0, 1), evaluator);
     }
     static createDirectHalfCosine(localToWorld, nominalL1, nominalR1, activeInterval) {
-        return new this(localToWorld, "HalfCosine", undefined, nominalL1, nominalR1, activeInterval, new DirectHalfCosineSpiralEvaluator(nominalL1, nominalR1));
+        return new DirectSpiral3d(localToWorld, "HalfCosine", undefined, nominalL1, nominalR1, activeInterval, new DirectHalfCosineSpiralEvaluator(nominalL1, nominalR1));
     }
     /**
      * Create an Arema spiral clothoid approximation
-     *   * X is 2 terms of the clothoid series as a function of nominal distance along
-     *   * Y is 2 terms f the clothoid series as a function of nominal distance along
-     *   * Remark: This is identical to the ChineseCubic
-     * @param localToWorld axes with inflection at origin, tangent along x axis
+     *   * X is 2 terms of the clothoid series as a function of nominal distance along.
+     *   * Y is 2 terms f the clothoid series as a function of nominal distance along.
+     *   * Remark: This is identical to the ChineseCubic.
+     * @param localToWorld axes with inflection at origin, tangent along x axis.
      * @param nominalL1 nominal length as used in series LR terms.
-     * @param nominalR1 nominal final radius as used in series LR terms
-     * @param activeInterval fractional interval with (0, nominalL1) range for nominal distance along
+     * @param nominalR1 nominal final radius as used in series LR terms.
+     * @param activeInterval fractional interval with (0, nominalL1) range for nominal distance along.
      */
     static createArema(localToWorld, nominalL1, nominalR1, activeInterval) {
         return this.createTruncatedClothoid("Arema", localToWorld, 2, 2, undefined, nominalL1, nominalR1, activeInterval);
     }
     /**
-     * Create a Chinese clothoid approximation
-     *   * X is 2 terms of the clothoid series as a function of nominal distance along
-     *   * Y is 2 terms f the clothoid series as a function of nominal distance along
-     *   * Remark: This is identical to the Arema spiral
-     * @param localToWorld axes with inflection at origin, tangent along x axis
+     * Create a Japanese spiral clothoid approximation.
+     *   * X is 1 terms of the clothoid series as a function of nominal distance along.
+     *   * Y is 1 terms of the clothoid series as a function of nominal distance along.
+     *   * Remark: This is identical to the ChineseCubic.
+     * @param localToWorld axes with inflection at origin, tangent along x axis.
      * @param nominalL1 nominal length as used in series LR terms.
-     * @param nominalR1 nominal final radius as used in series LR terms
+     * @param nominalR1 nominal final radius as used in series LR terms.
      * @param activeInterval fractional interval with (0, nominalL1) range for nominal distance along
      */
+    static createJapaneseCubic(localToWorld, nominalL1, nominalR1, activeInterval) {
+        return this.createTruncatedClothoid("JapaneseCubic", localToWorld, 1, 1, undefined, nominalL1, nominalR1, activeInterval);
+    }
+    /**
+     * Create a Chinese clothoid approximation
+     *   * X is 2 terms of the clothoid series as a function of nominal distance along.
+     *   * Y is 2 terms f the clothoid series as a function of nominal distance along.
+     *   * Remark: This is identical to the Arema spiral.
+     * @param localToWorld axes with inflection at origin, tangent along x axis.
+     * @param nominalL1 nominal length as used in series LR terms.
+     * @param nominalR1 nominal final radius as used in series LR terms.
+     * @param activeInterval fractional interval with (0, nominalL1) range for nominal distance along.
+     */
     static createChineseCubic(localToWorld, nominalL1, nominalR1, activeInterval) {
         return this.createTruncatedClothoid("ChineseCubic", localToWorld, 2, 2, undefined, nominalL1, nominalR1, activeInterval);
     }
     /**
      * Create a Western Australian direct spiral.
-     *   * X is 2 terms of the clothoid series as a function of distance along
-     *   * Y is 1 term (cubic in nominal distance along)
-     * @param localToWorld axes with inflection at origin, tangent along x axis
+     *   * X is 2 terms of the clothoid series as a function of distance along.
+     *   * Y is 1 term (cubic in nominal distance along).
+     * @param localToWorld axes with inflection at origin, tangent along x axis.
      * @param nominalL1 nominal length as used in series LR terms.
-     * @param nominalR1 nominal final radius as used in series LR terms
-     * @param activeInterval fractional interval with (0, nominalL1) range for nominal distance along
+     * @param nominalR1 nominal final radius as used in series LR terms.
+     * @param activeInterval fractional interval with (0, nominalL1) range for nominal distance along.
      */
     static createWesternAustralian(localToWorld, nominalL1, nominalR1, activeInterval) {
         return this.createTruncatedClothoid("WesternAustralian", localToWorld, 2, 1, undefined, nominalL1, nominalR1, activeInterval);
     }
     /**
      * Create (if possible) a DirectSpiral3d, applying various strict conditions appropriate to the spiral type.
-     * The parameter list includes extraneous values in order to directly match IntegratedSpiral3d.create, which has greater flexibility about
-     *    mixtures of values.
-     * * IMPORTANT RESTRICTIONS
+     * The parameter list includes extraneous values in order to directly match IntegratedSpiral3d.create, which has
+     * greater flexibility about mixtures of values.
+     * * IMPORTANT RESTRICTIONS:
      *   * Direct spirals must have the inflection at the origin of their coordinate system, aligned with the x axis.
-     *      * hence bearing0 = 0
-     *      * hence radius0 = 0
-     *   * bearing1 is ignored
+     *      * hence bearing0 = 0.
+     *      * hence radius0 = 0.
+     *   * bearing1 is ignored.
      *   * radius1 must be given.
      *   * arcLength must be given,
-     * @param spiralType one of the types in `DirectSpiralTypeNames`
-     * @param radius0 radius (or 0 for tangent to line) at start.   Must be ZERO or UNDEFINED
+     * @param spiralType one of the types in `DirectSpiralTypeName`
+     * @param radius0 radius (or 0 for tangent to line) at start. Must be ZERO or UNDEFINED
      * @param radius1 radius (or 0 for tangent to line) at end.
-     * @param bearing0 bearing, measured CCW from x axis at start.   Must be ZERO or UNDEFINED
-     * @param bearing1 bearing, measured CCW from x axis at end.    IGNORED.
-     * @param fractionInterval optional fractional interval for an "active" portion of the curve.   if omitted, the full [0,1] is used.
-     * @param localToWorld placement transform
+     * @param bearing0 bearing, measured CCW from x axis at start. Must be ZERO or UNDEFINED
+     * @param bearing1 bearing, measured CCW from x axis at end. IGNORED.
+     * @param fractionInterval (optional) fractional interval for an "active" portion of the curve. If omitted, the
+     * full [0,1] is used.
+     * @param localToWorld placement transform.
      */
     static createFromLengthAndRadius(spiralType, radius0, radius1, bearing0, _bearing1, arcLength, activeInterval, localToWorld) {
         if (bearing0 !== undefined && !bearing0.isAlmostZero)
@@ -327,11 +344,11 @@ export class DirectSpiral3d extends TransitionSpiral3d {
             return this.createPolishCubic(localToWorld, arcLength, radius1, activeInterval);
         return undefined;
     }
-    /** Deep clone of this spiral */
+    /** Deep clone of this spiral. */
     clone() {
         return new DirectSpiral3d(this.localToWorld.clone(), this._spiralType, this.designProperties?.clone(), this._nominalL1, this._nominalR1, this._activeFractionInterval?.clone(), this._evaluator.clone());
     }
-    /** apply `transform` to this spiral's local to world transform. */
+    /** Apply `transform` to this spiral's local to world transform. */
     tryTransformInPlace(transformA) {
         const rigidData = this.applyRigidPartOfTransform(transformA);
         if (rigidData !== undefined) {
@@ -346,17 +363,18 @@ export class DirectSpiral3d extends TransitionSpiral3d {
     startPoint(result) {
         return this.activeStrokes.startPoint(result);
     }
-    /** return the spiral end point. */
+    /** Return the spiral end point. */
     endPoint(result) {
         return this.activeStrokes.endPoint(result);
     }
-    /** test if the local to world transform places the spiral xy plane into `plane` */
+    /** Test if the local to world transform places the spiral xy plane into `plane`. */
     isInPlane(plane) {
         return plane.isPointInPlane(this.localToWorld.origin)
             && Geometry.isSameCoordinate(0.0, this.localToWorld.matrix.dotColumnX(plane.getNormalRef()))
             && Geometry.isSameCoordinate(0.0, this.localToWorld.matrix.dotColumnY(plane.getNormalRef()));
     }
-    /** Return quick length of the spiral.
+    /**
+     * Return quick length of the spiral.
      * The tangent vector of a true clothoid is length 1 everywhere, so simple proportion of nominalL1 is a good approximation.
      */
     quickLength() {
@@ -364,18 +382,24 @@ export class DirectSpiral3d extends TransitionSpiral3d {
         const n = distanceData.length;
         return distanceData.getYAtUncheckedPointIndex(n - 1);
     }
-    /** Return length of the spiral.
-     * * True length is stored at back of uvParams . . .
-     */
-    //   use the generic integrator ... public override curveLength() { return this.quickLength(); }
+    // We claim true length is stored at the back of `packedUVParams`.
+    // Nevertheless defer to the generic integrator in the default implementation.
+    // public override curveLength() {
+    //   return this.quickLength();
+    // }
     /** Test if `other` is an instance of `TransitionSpiral3d` */
-    isSameGeometryClass(other) { return other instanceof DirectSpiral3d; }
-    /** Add strokes from this spiral to `dest`.
-     * * Linestrings will usually stroke as just their points.
+    isSameGeometryClass(other) {
+        return other instanceof TransitionSpiral3d;
+    }
+    /**
+     * Add strokes from this spiral to `dest`.
+     * * Line strings will usually stroke as just their points.
      * * If maxEdgeLength is given, this will sub-stroke within the linestring -- not what we want.
      */
-    emitStrokes(dest, options) { this.activeStrokes.emitStrokes(dest, options); }
-    /** emit stroke fragments to `dest` handler. */
+    emitStrokes(dest, options) {
+        this.activeStrokes.emitStrokes(dest, options);
+    }
+    /** Emit stroke fragments to `dest` handler. */
     emitStrokableParts(dest, options) {
         const n = this.computeStrokeCountForOptions(options);
         const activeStrokes = this.activeStrokes;
@@ -396,8 +420,8 @@ export class DirectSpiral3d extends TransitionSpiral3d {
         dest.endParentCurvePrimitive(this);
     }
     /**
-     * return the stroke count required for given options.
-     * @param options StrokeOptions that determine count
+     * Return the stroke count required for given options.
+     * @param options StrokeOptions that determine count.
      */
     computeStrokeCountForOptions(options) {
         let numStroke;
@@ -414,8 +438,9 @@ export class DirectSpiral3d extends TransitionSpiral3d {
         numStroke = Math.ceil(this._activeFractionInterval.absoluteDelta() * numStroke);
         return numStroke;
     }
-    /** Reverse the active interval and active strokes.
-     * * Primary defining data remains unchanged !!!
+    /**
+     * Reverse the active interval and active strokes.
+     * * Primary defining data remains unchanged.
      */
     reverseInPlace() {
         this._activeFractionInterval.reverseInPlace();
@@ -438,10 +463,11 @@ export class DirectSpiral3d extends TransitionSpiral3d {
         result.transformInPlace(this.localToWorld);
         return result;
     }
-    /** Return a plane with
-     *
-     * * origin at fractional position along the curve
-     * * vectorU is the first derivative, i.e. tangent vector with length equal to the rate of change with respect to the fraction.
+    /**
+     * Return a plane with
+     * * origin at fractional position along the curve.
+     * * vectorU is the first derivative, i.e. tangent vector with length equal to the rate of change with respect to
+     * the fraction.
      * * vectorV is the second derivative, i.e.derivative of vectorU.
      */
     fractionToPointAnd2Derivatives(activeFraction, result) {
@@ -453,11 +479,11 @@ export class DirectSpiral3d extends TransitionSpiral3d {
         result.transformInPlace(this.localToWorld);
         return result;
     }
-    /** Second step of double dispatch:  call `handler.handleTransitionSpiral(this)` */
+    /** Second step of double dispatch: call `handler.handleTransitionSpiral(this)`. */
     dispatchToGeometryHandler(handler) {
         return handler.handleTransitionSpiral(this);
     }
-    /** compare various coordinate quantities */
+    /** Compare various coordinate quantities. */
     isAlmostEqual(other) {
         if (other instanceof DirectSpiral3d) {
             return Geometry.isSameCoordinate(this._nominalL1, other._nominalL1)