@itwin/core-geometry 5.7.2 → 5.8.0-dev.10

package/lib/esm/curve/Arc3d.js

@@ -767,48 +767,61 @@ export 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 (default), consider only endpoints
+     * and projections within the arc sweep. Note that for an open arc, extending one end is the same as extending both ends.
      * @param result optional preallocated result.
      */
-    closestPoint(spacePoint, extend, result) {
+    closestPoint(spacePoint, extend = false, result) {
         result = CurveLocationDetail.create(this, result);
-        const allRadians = this.allPerpendicularAngles(spacePoint, true, true);
-        let extend0 = CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 0);
-        let extend1 = CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 1);
-        // distinct extends for cyclic space are awkward ....
-        if (this._sweep.isFullCircle) {
-            extend0 = CurveExtendMode.None;
-            extend1 = CurveExtendMode.None;
-        }
-        if (extend0 !== CurveExtendMode.None && extend1 !== CurveExtendMode.None) {
-            allRadians.push(this._sweep.startRadians);
-            allRadians.push(this._sweep.endRadians);
+        const allRadians = this.allPerpendicularAngles(spacePoint, true, false);
+        // test endpoints if and only if arc is open and unextended
+        if (!this._sweep.isFullCircle) {
+            const extend0 = CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 0);
+            const extend1 = CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 1);
+            if (extend0 === CurveExtendMode.None && extend1 === CurveExtendMode.None) {
+                allRadians.push(this._sweep.startRadians);
+                allRadians.push(this._sweep.endRadians);
+            }
         }
-        // hm... logically there must at least two angles there ...  but if it happens return the start point ...
         const workRay = Ray3d.createZero();
-        if (allRadians.length === 0) {
-            result.setFR(0.0, this.radiansToPointAndDerivative(this._sweep.startRadians, workRay));
-            result.a = spacePoint.distance(result.point);
+        if (allRadians.length === 0) { // shouldn't happen; there should always be at least 2 angles
+            result.setFR(0.0, this.radiansToPointAndDerivative(this._sweep.startRadians, workRay), spacePoint.distance(result.point));
         }
         else {
             let dMin = Number.MAX_VALUE;
             let d = 0;
             for (const radians of allRadians) {
-                const fraction = CurveExtendOptions.resolveRadiansToSweepFraction(extend, radians, this.sweep);
-                if (fraction !== undefined) {
-                    this.fractionToPointAndDerivative(fraction, workRay);
+                const validatedFraction = CurveExtendOptions.resolveRadiansToValidSweepFraction(extend, radians, this.sweep);
+                if (validatedFraction.isValid) {
+                    this.fractionToPointAndDerivative(validatedFraction.fraction, workRay);
                     d = spacePoint.distance(workRay.origin);
                     if (d < dMin) {
                         dMin = d;
-                        result.setFR(fraction, workRay);
-                        result.a = d;
+                        result.setFR(validatedFraction.fraction, workRay, d);
                     }
                 }
             }
         }
         return result;
     }
+    /**
+     * Search for a point on the Arc3d that is closest to the spacePoint as viewed in the xy-plane (ignoring z).
+     * * If the space point is exactly on the curve, this is the reverse of fractionToPoint.
+     * * Since CurvePrimitive should always have start and end available as candidate points, this method should always
+     * succeed.
+     * @param spacePoint point in space.
+     * @param extend if true, consider projections to the complete ellipse. If false (default), consider only endpoints
+     * and projections within the arc sweep. Note that for an open arc, extending one end is the same as extending both ends.
+     * @param result (optional) pre-allocated detail to populate and return.
+     * @returns details of the closest point.
+     */
+    closestPointXY(spacePoint, extend = false, result) {
+        // prevent `ClosestPointStroker.claimResult` from clamping an exterior fraction when arc is half-extended
+        const extend0 = CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 0);
+        const extend1 = CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 1);
+        extend = extend0 !== CurveExtendMode.None || extend1 !== CurveExtendMode.None;
+        return super.closestPointXY(spacePoint, extend, result); // TODO: implement exact solution instead of deferring to superclass
+    }
     /** Override of [[CurvePrimitive.emitTangents]] for Arc3d. */
     emitTangents(spacePoint, announceTangent, options) {
         const centerToPoint = Vector3d.createStartEnd(this.centerRef, spacePoint);
@@ -876,6 +889,20 @@ export class Arc3d extends CurvePrimitive {
         const axy = this._matrix.columnXDotColumnY();
         return Angle.isPerpendicularDotSet(axx, ayy, axy) && Geometry.isSameCoordinateSquared(axx, ayy);
     }
+    /** Return true if the vector0 and vector90 xy parts are of equal length and perpendicular. */
+    get isCircularXY() {
+        const columnX = this._matrix.columnX();
+        const columnY = this._matrix.columnY();
+        const axx = columnX.magnitudeSquaredXY();
+        const ayy = columnY.magnitudeSquaredXY();
+        const axy = columnX.dotProductXY(columnY);
+        return Angle.isPerpendicularDotSet(axx, ayy, axy) && Geometry.isSameCoordinateSquared(axx, ayy);
+    }
+    /** Return true if the arc has zero radius (is a point). */
+    get isDegenerateCircle() {
+        return Geometry.isSmallMetricDistanceSquared(this._matrix.columnXMagnitudeSquared()) &&
+            Geometry.isSmallMetricDistanceSquared(this._matrix.columnYMagnitudeSquared());
+    }
     /** Return radius if the vector0 and vector90 are of equal length and perpendicular. Ignores z. */
     circularRadiusXY() {
         const ux = this._matrix.at(0, 0);