@itwin/core-geometry 3.5.0-dev.8 → 3.6.0-dev.1

package/lib/esm/curve/CurvePrimitive.js

@@ -1,16 +1,23 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Curve
+ */
+import { assert } from "@itwin/core-bentley";
 import { StrokeCountMap } from "../curve/Query/StrokeCountMap";
 import { AxisOrder, Geometry } from "../Geometry";
 import { Matrix3d } from "../geometry3d/Matrix3d";
 import { Point3d } from "../geometry3d/Point3dVector3d";
+import { Range3d } from "../geometry3d/Range";
 import { Ray3d } from "../geometry3d/Ray3d";
 import { Transform } from "../geometry3d/Transform";
-import { Order2Bezier } from "../numerics/BezierPolynomials";
-import { Newton1dUnboundedApproximateDerivative, NewtonEvaluatorRtoR } from "../numerics/Newton";
-import { GaussMapper } from "../numerics/Quadrature";
-import { CurveExtendOptions } from "./CurveExtendMode";
 import { CurveIntervalRole, CurveLocationDetail, CurveSearchStatus } from "./CurveLocationDetail";
 import { GeometryQuery } from "./GeometryQuery";
-import { Range3d } from "../geometry3d/Range";
+import { AppendPlaneIntersectionStrokeHandler } from "./internalContexts/AppendPlaneIntersectionStrokeHandler";
+import { ClosestPointStrokeHandler } from "./internalContexts/ClosestPointStrokeHandler";
+import { CurveLengthContext } from "./internalContexts/CurveLengthContext";
 /**
  * A curve primitive is bounded
  * A curve primitive maps fractions in 0..1 to points in space.
@@ -220,9 +227,8 @@ export class CurvePrimitive extends GeometryQuery {
      * * (Attempt to) find a position on the curve at a signed distance from start fraction.
      * * Return the position as a CurveLocationDetail.
      * * In the `CurveLocationDetail`, record:
-     *   * `fractional` position
-     *   * `fraction` = coordinates of the point
-     *   * `search
+     *   * `fraction` = fractional position
+     *   * `point` = coordinates of the point
      *   * `a` = (signed!) distance moved.   If `allowExtension` is false and the move reached the start or end of the curve, this distance is smaller than the requested signedDistance.
      *   * `curveSearchStatus` indicates one of:
      *     * `error` (unusual) computation failed not supported for this curve.
@@ -277,13 +283,39 @@ export class CurvePrimitive extends GeometryQuery {
      * @param result
      */
     moveSignedDistanceFromFractionGeneric(startFraction, signedDistance, allowExtension, result) {
-        const limitFraction = signedDistance > 0.0 ? 1.0 : 0.0;
+        let limitFraction;
+        const slackFraction = 0.1; // slack to use when integration would otherwise have no room to work
+        if (signedDistance === 0.0)
+            return CurveLocationDetail.createCurveEvaluatedFraction(this, startFraction, result); // no movement, just evaluate at startFraction
+        if (signedDistance > 0.0) {
+            limitFraction = 1.0;
+            if (startFraction >= 1.0) {
+                const newStartFraction = 1.0 - slackFraction;
+                signedDistance += this.curveLengthBetweenFractions(newStartFraction, startFraction);
+                startFraction = newStartFraction;
+            }
+        }
+        else { // signedDistance < 0.0
+            limitFraction = 0.0;
+            if (startFraction <= 0.0) {
+                const newStartFraction = 0.0 + slackFraction;
+                signedDistance -= this.curveLengthBetweenFractions(startFraction, newStartFraction);
+                startFraction = newStartFraction;
+            }
+        }
+        const availableLength = this.curveLengthBetweenFractions(startFraction, limitFraction);
+        assert(availableLength > 0.0);
         const absDistance = Math.abs(signedDistance);
-        const directionFactor = signedDistance < 0.0 ? -1.0 : 1.0;
-        const availableLength = this.curveLengthBetweenFractions(startFraction, limitFraction); // that is always positive
         if (availableLength < absDistance && !allowExtension)
             return CurveLocationDetail.createConditionalMoveSignedDistance(allowExtension, this, startFraction, limitFraction, signedDistance, result);
-        const fractionStep = absDistance / availableLength;
+        const fractionStep = Geometry.conditionalDivideCoordinate(absDistance, availableLength);
+        if (undefined === fractionStep) {
+            // no available length!
+            result = CurveLocationDetail.createCurveEvaluatedFraction(this, startFraction, result);
+            result.curveSearchStatus = CurveSearchStatus.error;
+            return result;
+        }
+        const directionFactor = signedDistance < 0.0 ? -1.0 : 1.0;
         let fractionB = Geometry.interpolate(startFraction, fractionStep, limitFraction);
         let fractionA = startFraction;
         let distanceA = 0.0;
@@ -318,9 +350,8 @@ export class CurvePrimitive extends GeometryQuery {
             distanceA = distance0B;
         }
         if (numConverged > 1)
-            return CurveLocationDetail.createConditionalMoveSignedDistance(false, this, startFraction, fractionB, signedDistance, result);
+            return CurveLocationDetail.createConditionalMoveSignedDistance(allowExtension, this, startFraction, fractionB, signedDistance, result);
         result = CurveLocationDetail.createCurveEvaluatedFraction(this, startFraction, result);
-        result.a = 0.0;
         result.curveSearchStatus = CurveSearchStatus.error;
         return result;
     }
@@ -364,7 +395,7 @@ export class CurvePrimitive extends GeometryQuery {
         return undefined;
     }
     /**
-     * * If the curve primitive has distance-along-curve strictly proportional to curve fraction, return true
+     * * If the curve primitive has distance-along-curve strictly proportional to curve fraction, return the scale factor.
      * * If distance-along-the-curve is not proportional, return undefined.
      * * When defined, the scale factor is always the length of the curve.
      * * This scale factor is typically available for these curve types:
@@ -536,325 +567,13 @@ export class CurvePrimitive extends GeometryQuery {
         this.collectCurvePrimitivesGo(results, smallestPossiblePrimitives, explodeLinestrings);
         return results;
     }
-}
-/** Intermediate class for managing the parentCurve announcements from an IStrokeHandler */
-class NewtonRotRStrokeHandler extends NewtonEvaluatorRtoR {
-    constructor() {
-        super();
-        this._parentCurvePrimitive = undefined;
-    }
-    /** retain the parentCurvePrimitive.
-     * * Calling this method tells the handler that the parent curve is to be used for detail searches.
-     * * Example: Transition spiral search is based on linestring first, then the exact spiral.
-     * * Example: CurveChainWithDistanceIndex does NOT do this announcement -- the constituents act independently.
-     */
-    startParentCurvePrimitive(curve) { this._parentCurvePrimitive = curve; }
-    /** Forget the parentCurvePrimitive */
-    endParentCurvePrimitive(_curve) { this._parentCurvePrimitive = undefined; }
-}
-class AppendPlaneIntersectionStrokeHandler extends NewtonRotRStrokeHandler {
-    constructor(plane, intersections) {
-        super();
-        this._fractionA = 0;
-        this._functionA = 0;
-        // private derivativeA: number;   <---- Not currently used
-        this._functionB = 0;
-        this._fractionB = 0;
-        this._derivativeB = 0;
-        this._numThisCurve = 0;
-        this._plane = plane;
-        this._intersections = intersections;
-        this.startCurvePrimitive(undefined);
-        this._ray = Ray3d.createZero();
-        this._newtonSolver = new Newton1dUnboundedApproximateDerivative(this);
-    }
-    // Return the first defined curve among: this.parentCurvePrimitive, this.curve;
-    effectiveCurve() {
-        if (this._parentCurvePrimitive)
-            return this._parentCurvePrimitive;
-        return this._curve;
-    }
-    get getDerivativeB() { return this._derivativeB; } // <--- DerivativeB is not currently used anywhere. Provided getter to suppress lint error
-    startCurvePrimitive(curve) {
-        this._curve = curve;
-        this._fractionA = 0.0;
-        this._numThisCurve = 0;
-        this._functionA = 0.0;
-        // this.derivativeA = 0.0;
-    }
-    endCurvePrimitive() { }
-    announceIntervalForUniformStepStrokes(cp, numStrokes, fraction0, fraction1) {
-        this.startCurvePrimitive(cp);
-        if (numStrokes < 1)
-            numStrokes = 1;
-        const df = 1.0 / numStrokes;
-        for (let i = 0; i <= numStrokes; i++) {
-            const fraction = Geometry.interpolate(fraction0, i * df, fraction1);
-            cp.fractionToPointAndDerivative(fraction, this._ray);
-            this.announcePointTangent(this._ray.origin, fraction, this._ray.direction);
-        }
-    }
-    announceSegmentInterval(_cp, point0, point1, _numStrokes, fraction0, fraction1) {
-        const h0 = this._plane.altitude(point0);
-        const h1 = this._plane.altitude(point1);
-        if (h0 * h1 > 0.0)
-            return;
-        const fraction01 = Order2Bezier.solveCoffs(h0, h1);
-        // let numIntersection = 0;
-        if (fraction01 !== undefined) {
-            // numIntersection++;
-            const fraction = Geometry.interpolate(fraction0, fraction01, fraction1);
-            this._newtonSolver.setX(fraction);
-            if (this._newtonSolver.runIterations()) {
-                this.announceSolutionFraction(this._newtonSolver.getX());
-            }
-            // this.intersections.push(CurveLocationDetail.createCurveFractionPoint(cp, fraction, cp.fractionToPoint(fraction)));
-        }
-    }
-    announceSolutionFraction(fraction) {
-        const curve = this.effectiveCurve();
-        if (curve) {
-            this._ray = curve.fractionToPointAndDerivative(fraction, this._ray);
-            this._intersections.push(CurveLocationDetail.createCurveFractionPoint(curve, fraction, this._ray.origin));
-        }
-    }
-    evaluate(fraction) {
-        const curve = this.effectiveCurve();
-        if (!curve)
-            return false;
-        this.currentF = this._plane.altitude(curve.fractionToPoint(fraction));
-        return true;
-    }
-    /**
-     * * ASSUME both the "A" and "B"  evaluations (fraction, function, and derivative) are known.
-     * * If function value changed sign between, interpolate an approximate root and improve it with
-     *     the newton solver.
+    /** 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.
      */
-    searchInterval() {
-        if (this._functionA * this._functionB > 0)
-            return;
-        if (this._functionA === 0)
-            this.announceSolutionFraction(this._fractionA);
-        if (this._functionB === 0)
-            this.announceSolutionFraction(this._fractionB);
-        if (this._functionA * this._functionB < 0) {
-            const fraction = Geometry.inverseInterpolate(this._fractionA, this._functionA, this._fractionB, this._functionB);
-            if (fraction) {
-                this._newtonSolver.setX(fraction);
-                if (this._newtonSolver.runIterations())
-                    this.announceSolutionFraction(this._newtonSolver.getX());
-            }
-        }
-    }
-    /** Evaluate and save _functionB, _derivativeB, and _fractionB. */
-    evaluateB(xyz, fraction, tangent) {
-        this._functionB = this._plane.altitude(xyz);
-        this._derivativeB = this._plane.velocity(tangent);
-        this._fractionB = fraction;
-    }
-    /**
-     * Announce point and tangent for evaluations.
-     * * The function evaluation is saved as the "B" function point.
-     * * The function point count is incremented
-     * * If function point count is greater than 1, the current interval is searched.
-     * * The just-evaluated point ("B") is saved as the "old" ("A") evaluation point.
-     * @param xyz
-     * @param fraction
-     * @param tangent
-     */
-    announcePointTangent(xyz, fraction, tangent) {
-        this.evaluateB(xyz, fraction, tangent);
-        if (this._numThisCurve++ > 0)
-            this.searchInterval();
-        this._functionA = this._functionB;
-        this._fractionA = this._fractionB;
-    }
-}
-class CurveLengthContext {
-    constructor(fraction0 = 0.0, fraction1 = 1.0, numGaussPoints = 5) {
-        this.startCurvePrimitive(undefined);
-        this._summedLength = 0.0;
-        this._ray = Ray3d.createZero();
-        if (fraction0 < fraction1) {
-            this._fraction0 = fraction0;
-            this._fraction1 = fraction1;
-        }
-        else {
-            this._fraction0 = fraction1;
-            this._fraction1 = fraction0;
-        }
-        this._gaussMapper = new GaussMapper(numGaussPoints);
-    }
-    tangentMagnitude(fraction) {
-        this._ray = this._curve.fractionToPointAndDerivative(fraction, this._ray);
-        return this._ray.direction.magnitude();
-    }
-    getSum() { return this._summedLength; }
-    startCurvePrimitive(curve) {
-        this._curve = curve;
-    }
-    startParentCurvePrimitive(_curve) { }
-    endParentCurvePrimitive(_curve) { }
-    endCurvePrimitive() { }
-    announceIntervalForUniformStepStrokes(cp, numStrokes, fraction0, fraction1) {
-        if (fraction0 < this._fraction0)
-            fraction0 = this._fraction0;
-        if (fraction1 > this._fraction1)
-            fraction1 = this._fraction1;
-        if (fraction1 > fraction0) {
-            this.startCurvePrimitive(cp);
-            if (numStrokes < 1)
-                numStrokes = 1;
-            const df = 1.0 / numStrokes;
-            for (let i = 1; i <= numStrokes; i++) {
-                const fractionA = Geometry.interpolate(fraction0, (i - 1) * df, fraction1);
-                const fractionB = i === numStrokes ? fraction1 : Geometry.interpolate(fraction0, (i) * df, fraction1);
-                const numGauss = this._gaussMapper.mapXAndW(fractionA, fractionB);
-                for (let k = 0; k < numGauss; k++) {
-                    this._summedLength += this._gaussMapper.gaussW[k] * this.tangentMagnitude(this._gaussMapper.gaussX[k]);
-                }
-            }
-        }
-    }
-    announceSegmentInterval(_cp, point0, point1, _numStrokes, fraction0, fraction1) {
-        const segmentLength = point0.distance(point1);
-        if (this._fraction0 <= fraction0 && fraction1 <= this._fraction1)
-            this._summedLength += segmentLength;
-        else {
-            let g0 = fraction0;
-            let g1 = fraction1;
-            if (g0 < this._fraction0)
-                g0 = this._fraction0;
-            if (g1 > this._fraction1)
-                g1 = this._fraction1;
-            if (g1 > g0) {
-                this._summedLength += segmentLength * (g1 - g0) / (fraction1 - fraction0);
-            }
-        }
-    }
-    announcePointTangent(_xyz, _fraction, _tangent) {
-        // uh oh -- need to retain point for next interval
-    }
-}
-// context for searching for closest point .. .
-class ClosestPointStrokeHandler extends NewtonRotRStrokeHandler {
-    constructor(spacePoint, extend) {
-        super();
-        this._fractionA = 0;
-        this._functionA = 0;
-        this._functionB = 0;
-        this._fractionB = 0;
-        this._numThisCurve = 0;
-        this._spacePoint = spacePoint;
-        this._workPoint = Point3d.create();
-        this._workRay = Ray3d.createZero();
-        this._closestPoint = undefined;
-        this._extend = extend;
-        this.startCurvePrimitive(undefined);
-        this._newtonSolver = new Newton1dUnboundedApproximateDerivative(this);
-    }
-    claimResult() {
-        if (this._closestPoint) {
-            this._newtonSolver.setX(this._closestPoint.fraction);
-            this._curve = this._closestPoint.curve;
-            if (this._newtonSolver.runIterations()) {
-                let fraction = this._newtonSolver.getX();
-                fraction = CurveExtendOptions.correctFraction(this._extend, fraction);
-                this.announceSolutionFraction(fraction);
-            }
-        }
-        return this._closestPoint;
-    }
-    needPrimaryGeometryForStrokes() { return true; }
-    startCurvePrimitive(curve) {
-        this._curve = curve;
-        this._fractionA = 0.0;
-        this._numThisCurve = 0;
-        this._functionA = 0.0;
-    }
-    endCurvePrimitive() { }
-    announceIntervalForUniformStepStrokes(cp, numStrokes, fraction0, fraction1) {
-        this.startCurvePrimitive(cp);
-        this.announceSolutionFraction(0.0); // test start point as closest
-        this.announceSolutionFraction(1.0); // test end point as closest
-        if (numStrokes < 1)
-            numStrokes = 1;
-        const df = 1.0 / numStrokes;
-        for (let i = 0; i <= numStrokes; i++) {
-            const fraction = Geometry.interpolate(fraction0, i * df, fraction1);
-            cp.fractionToPointAndDerivative(fraction, this._workRay);
-            this.announceRay(fraction, this._workRay);
-        }
-    }
-    announceCandidate(cp, fraction, point) {
-        const distance = this._spacePoint.distance(point);
-        if (this._closestPoint && distance > this._closestPoint.a)
-            return;
-        this._closestPoint = CurveLocationDetail.createCurveFractionPoint(cp, fraction, point, this._closestPoint);
-        this._closestPoint.a = distance;
-        if (this._parentCurvePrimitive !== undefined)
-            this._closestPoint.curve = this._parentCurvePrimitive;
-    }
-    announceSegmentInterval(cp, point0, point1, _numStrokes, fraction0, fraction1) {
-        let localFraction = this._spacePoint.fractionOfProjectionToLine(point0, point1, 0.0);
-        // only consider extending the segment if the immediate caller says we are at endpoints ...
-        if (!this._extend)
-            localFraction = Geometry.clampToStartEnd(localFraction, 0.0, 1.0);
-        else {
-            if (fraction0 !== 0.0)
-                localFraction = Math.max(localFraction, 0.0);
-            if (fraction1 !== 1.0)
-                localFraction = Math.min(localFraction, 1.0);
-        }
-        this._workPoint = point0.interpolate(localFraction, point1);
-        const globalFraction = Geometry.interpolate(fraction0, localFraction, fraction1);
-        this.announceCandidate(cp, globalFraction, this._workPoint);
-    }
-    searchInterval() {
-        if (this._functionA * this._functionB > 0)
-            return;
-        if (this._functionA === 0)
-            this.announceSolutionFraction(this._fractionA);
-        if (this._functionB === 0)
-            this.announceSolutionFraction(this._fractionB);
-        if (this._functionA * this._functionB < 0) {
-            const fraction = Geometry.inverseInterpolate(this._fractionA, this._functionA, this._fractionB, this._functionB);
-            if (fraction) {
-                this._newtonSolver.setX(fraction);
-                if (this._newtonSolver.runIterations())
-                    this.announceSolutionFraction(this._newtonSolver.getX());
-            }
-        }
-    }
-    evaluateB(fractionB, dataB) {
-        this._functionB = dataB.dotProductToPoint(this._spacePoint);
-        this._fractionB = fractionB;
-    }
-    announceSolutionFraction(fraction) {
-        if (this._curve)
-            this.announceCandidate(this._curve, fraction, this._curve.fractionToPoint(fraction));
-    }
-    evaluate(fraction) {
-        let curve = this._curve;
-        if (this._parentCurvePrimitive)
-            curve = this._parentCurvePrimitive;
-        if (curve) {
-            this._workRay = curve.fractionToPointAndDerivative(fraction, this._workRay);
-            this.currentF = this._workRay.dotProductToPoint(this._spacePoint);
-            return true;
-        }
-        return false;
-    }
-    announceRay(fraction, data) {
-        this.evaluateB(fraction, data);
-        if (this._numThisCurve++ > 0)
-            this.searchInterval();
-        this._functionA = this._functionB;
-        this._fractionA = this._fractionB;
-    }
-    announcePointTangent(point, fraction, tangent) {
-        this._workRay.set(point, tangent);
-        this.announceRay(fraction, this._workRay);
+    projectedParameterRange(_ray, _lowHigh) {
+        return undefined; // common implementation delegated to subclasses to avoid circular dependency
     }
 }
 //# sourceMappingURL=CurvePrimitive.js.map