@itwin/core-geometry 5.0.0-dev.3 → 5.0.0-dev.32

package/lib/esm/geometry3d/PolygonOps.js

@@ -453,8 +453,8 @@ export class PolygonOps {
     }
     /**
      * Return a Ray3d with (assuming the polygon is planar and not self-intersecting):
-     * * `origin` at the centroid of the (3D) polygon
-     * * `direction` is the unit vector perpendicular to the plane
+     * * `origin` at the centroid of the (3D) polygon,
+     * * `direction` is the unit vector perpendicular to the plane,
      * * `a` is the area.
      * @param points
      */
@@ -839,7 +839,10 @@ export class PolygonOps {
      * * Compare to [[closestPoint]].
      * @param polygon points of the polygon, closure point optional
      * @param testPoint point p to project onto the polygon edges. Works best when p is in the plane of the polygon.
-     * @param tolerance optional distance tolerance to determine point-vertex and point-edge coincidence.
+     * @param tolerance optional tolerance(s) to determine point-vertex and point-edge coincidence. A single number
+     * is interpreted as distance tolerance. If an array is given, the first number is interpreted as distance tolerance;
+     * the second, as parametric tolerance. Default values are [[Geometry.smallMetricDistance]] for distance tolerance
+     * and 0.0 for parameter tolerance.
      * @param result optional pre-allocated object to fill and return
      * @returns details d of the closest point `d.point`:
      * * `d.isValid()` returns true if and only if the polygon is nontrivial.
@@ -851,7 +854,9 @@ export class PolygonOps {
     static closestPointOnBoundary(polygon, testPoint, tolerance = Geometry.smallMetricDistance, result) {
         if (!(polygon instanceof IndexedXYZCollection))
             return this.closestPointOnBoundary(new Point3dArrayCarrier(polygon), testPoint, tolerance, result);
-        const distTol2 = tolerance * tolerance;
+        const distTol = Array.isArray(tolerance) ? tolerance[0] : tolerance;
+        const paramTol = Array.isArray(tolerance) ? Math.abs(tolerance[1]) : 0.0;
+        const distTol2 = distTol * distTol;
         let numPoints = polygon.length;
         while (numPoints > 1) {
             if (polygon.distanceSquaredIndexIndex(0, numPoints - 1) > distTol2)
@@ -861,29 +866,59 @@ export class PolygonOps {
         result = PolygonLocationDetail.create(result);
         if (0 === numPoints)
             return result; // invalid
-        if (1 === numPoints) {
-            polygon.getPoint3dAtUncheckedPointIndex(0, result.point);
+        const constructSingletonPoint = (index) => {
+            polygon.getPoint3dAtUncheckedPointIndex(index, result.point);
             result.a = result.point.distance(testPoint);
             result.v.setZero();
             result.code = PolygonLocation.OnPolygonVertex;
-            result.closestEdgeIndex = 0;
+            result.closestEdgeIndex = index;
             result.closestEdgeParam = 0.0;
             return result;
-        }
+        };
+        if (1 === numPoints)
+            return constructSingletonPoint(0);
+        // lambda for computing edge parameter at which testPoint projects onto the edge starting at iEdgeStart
+        const projectToEdge = (iEdgeStart) => {
+            let isValid = false;
+            let edgeParam = 0.0;
+            let uDotU = 0.0;
+            let vDotV = 0.0;
+            if (iEdgeStart >= 0 && iEdgeStart < numPoints) {
+                let iEdgeEnd = iEdgeStart + 1;
+                if (iEdgeEnd === numPoints)
+                    iEdgeEnd = 0;
+                uDotU = polygon.distanceSquaredIndexIndex(iEdgeStart, iEdgeEnd);
+                if (uDotU > distTol2) { // nontrivial edge
+                    vDotV = polygon.distanceSquaredIndexXYAndZ(iEdgeStart, testPoint);
+                    const uDotV = polygon.dotProductIndexIndexXYAndZ(iEdgeStart, iEdgeEnd, testPoint);
+                    edgeParam = uDotV / uDotU; // param of projection of testPoint onto edge [iEdgeStart, iEdgeEnd]
+                    isValid = true;
+                }
+            }
+            return { isValid, edgeParam, uDotU, vDotV };
+        };
+        // find the previous nontrivial edge's projection status before processing the first edge
+        let projBeyondPrevEdge = false;
         let iPrev = numPoints - 1;
+        for (; iPrev > 0; --iPrev) {
+            const projData = projectToEdge(iPrev);
+            if (projData.isValid) {
+                projBeyondPrevEdge = projData.edgeParam > 1.0 + paramTol;
+                break;
+            }
+        }
+        if (iPrev <= 0) // all segments trivial, so treat like single point case
+            return constructSingletonPoint(0);
         let minDist2 = Geometry.largeCoordinateResult;
         for (let iBase = 0; iBase < numPoints; ++iBase) {
             let iNext = iBase + 1;
             if (iNext === numPoints)
                 iNext = 0;
-            const uDotU = polygon.distanceSquaredIndexIndex(iBase, iNext);
-            if (uDotU <= distTol2)
-                continue; // ignore trivial polygon edge (keep iPrev)
-            const vDotV = polygon.distanceSquaredIndexXYAndZ(iBase, testPoint);
-            const uDotV = polygon.dotProductIndexIndexXYAndZ(iBase, iNext, testPoint);
-            const edgeParam = uDotV / uDotU; // param of projection of testPoint onto this edge
-            if (edgeParam <= 0.0) { // testPoint projects to/before edge start
-                const distToStart2 = vDotV;
+            const projData = projectToEdge(iBase);
+            if (!projData.isValid)
+                continue; // ignore trivial polygon edge (keep iPrev, projBeyondPrevEdge)
+            if (projData.edgeParam <= paramTol) { // testPoint projects to/before edge start
+                const distToStart2 = projData.vDotV;
                 if (distToStart2 <= distTol2) {
                     // testPoint is at edge start; we are done
                     polygon.getPoint3dAtUncheckedPointIndex(iBase, result.point);
@@ -894,25 +929,25 @@ export class PolygonOps {
                     result.closestEdgeParam = 0.0;
                     return result;
                 }
-                if (distToStart2 < minDist2) {
-                    if (polygon.dotProductIndexIndexXYAndZ(iBase, iPrev, testPoint) <= 0.0) {
-                        // update candidate (to edge start) only if testPoint projected beyond previous edge end
-                        polygon.getPoint3dAtUncheckedPointIndex(iBase, result.point);
-                        result.a = Math.sqrt(distToStart2);
-                        polygon.crossProductIndexIndexIndex(iBase, iPrev, iNext, result.v);
-                        result.code = PolygonLocation.OnPolygonVertex;
-                        result.closestEdgeIndex = iBase;
-                        result.closestEdgeParam = 0.0;
-                        minDist2 = distToStart2;
-                    }
+                if (distToStart2 < minDist2 && projBeyondPrevEdge) {
+                    // update candidate (to edge start) only if testPoint projected beyond previous edge end
+                    polygon.getPoint3dAtUncheckedPointIndex(iBase, result.point);
+                    result.a = Math.sqrt(distToStart2);
+                    polygon.crossProductIndexIndexIndex(iBase, iPrev, iNext, result.v);
+                    result.code = PolygonLocation.OnPolygonVertex;
+                    result.closestEdgeIndex = iBase;
+                    result.closestEdgeParam = 0.0;
+                    minDist2 = distToStart2;
                 }
+                projBeyondPrevEdge = false;
             }
-            else if (edgeParam <= 1.0) { // testPoint projects inside edge, or to edge end
-                const projDist2 = vDotV - edgeParam * edgeParam * uDotU;
+            else if (projData.edgeParam <= 1.0 + paramTol) { // testPoint projects inside edge, or to edge end
+                projData.edgeParam = Geometry.clamp(projData.edgeParam, 0.0, 1.0);
+                const projDist2 = projData.vDotV - projData.edgeParam * projData.edgeParam * projData.uDotU;
                 if (projDist2 <= distTol2) {
                     // testPoint is on edge; we are done
-                    const distToStart2 = vDotV;
-                    if (edgeParam <= 0.5 && distToStart2 <= distTol2) {
+                    const distToStart2 = projData.vDotV;
+                    if (projData.edgeParam <= 0.5 && distToStart2 <= distTol2) {
                         // testPoint is at edge start
                         polygon.getPoint3dAtUncheckedPointIndex(iBase, result.point);
                         result.a = Math.sqrt(distToStart2);
@@ -922,8 +957,8 @@ export class PolygonOps {
                         result.closestEdgeParam = 0.0;
                         return result;
                     }
-                    const distToEnd2 = projDist2 + (1.0 - edgeParam) * (1.0 - edgeParam) * uDotU;
-                    if (edgeParam > 0.5 && distToEnd2 <= distTol2) {
+                    const distToEnd2 = projDist2 + (1.0 - projData.edgeParam) * (1.0 - projData.edgeParam) * projData.uDotU;
+                    if (projData.edgeParam > 0.5 && distToEnd2 <= distTol2) {
                         // testPoint is at edge end
                         polygon.getPoint3dAtUncheckedPointIndex(iNext, result.point);
                         result.a = Math.sqrt(distToEnd2);
@@ -934,27 +969,29 @@ export class PolygonOps {
                         return result;
                     }
                     // testPoint is on edge interior
-                    polygon.interpolateIndexIndex(iBase, edgeParam, iNext, result.point);
+                    polygon.interpolateIndexIndex(iBase, projData.edgeParam, iNext, result.point);
                     result.a = Math.sqrt(projDist2);
                     result.v.setZero();
                     result.code = PolygonLocation.OnPolygonEdgeInterior;
                     result.closestEdgeIndex = iBase;
-                    result.closestEdgeParam = edgeParam;
+                    result.closestEdgeParam = projData.edgeParam;
                     return result;
                 }
                 if (projDist2 < minDist2) {
-                    // update candidate (to edge interior)
-                    polygon.interpolateIndexIndex(iBase, edgeParam, iNext, result.point);
+                    // update candidate
+                    polygon.interpolateIndexIndex(iBase, projData.edgeParam, iNext, result.point);
                     result.a = Math.sqrt(projDist2);
                     polygon.crossProductIndexIndexXYAndZ(iBase, iNext, testPoint, result.v);
-                    result.code = PolygonLocation.OnPolygonEdgeInterior;
+                    result.code = projData.edgeParam < 1.0 ? PolygonLocation.OnPolygonEdgeInterior : PolygonLocation.OnPolygonVertex;
+                    ;
                     result.closestEdgeIndex = iBase;
-                    result.closestEdgeParam = edgeParam;
+                    result.closestEdgeParam = projData.edgeParam;
                     minDist2 = projDist2;
                 }
+                projBeyondPrevEdge = false;
             }
-            else { // edgeParam > 1.0
-                // NOOP: testPoint projects beyond edge end, handled by next edge
+            else {
+                projBeyondPrevEdge = true; // to be handled by next edge
             }
             iPrev = iBase;
         }
@@ -998,7 +1035,10 @@ export class PolygonOps {
     /** Compute the intersection of a line (parameterized as a ray) with the plane of this polygon.
      * @param polygon points of the polygon, closure point optional
      * @param ray infinite line to intersect, as a ray
-     * @param tolerance optional distance tolerance to determine point-vertex and point-edge coincidence.
+     * @param tolerance optional tolerance(s) to determine point-vertex and point-edge coincidence. A single number
+     * is interpreted as distance tolerance. If an array is given, the first number is interpreted as distance tolerance;
+     * the second, as parametric tolerance. Default values are [[Geometry.smallMetricDistance]] for distance tolerance
+     * and 0.0 for parameter tolerance.
      * @param result optional pre-allocated object to fill and return
      * @returns details d of the line-plane intersection `d.point`:
      * * `d.isValid()` returns true if and only if the line intersects the plane.
@@ -1025,11 +1065,18 @@ export class PolygonOps {
                 // NOOP: intersectionPoint is on the polygon, so result.code already classifies it
             }
             else {
-                // intersectionPoint is not on polygon, so result.code refers to the closest point. Update it to refer to intersectionPoint.
-                if (PolygonLocation.OnPolygonVertex === result.code)
-                    result.code = (dot > 0.0) ? PolygonLocation.InsidePolygonProjectsToVertex : PolygonLocation.OutsidePolygonProjectsToVertex;
-                else if (PolygonLocation.OnPolygonEdgeInterior === result.code)
-                    result.code = (dot > 0.0) ? PolygonLocation.InsidePolygonProjectsToEdgeInterior : PolygonLocation.OutsidePolygonProjectsToEdgeInterior;
+                // intersectionPoint is not on the polygon, so result.code refers to the closest point;
+                // update it to refer to intersectionPoint.
+                if (PolygonLocation.OnPolygonVertex === result.code) {
+                    result.code = (dot > 0.0)
+                        ? PolygonLocation.InsidePolygonProjectsToVertex
+                        : PolygonLocation.OutsidePolygonProjectsToVertex;
+                }
+                else if (PolygonLocation.OnPolygonEdgeInterior === result.code) {
+                    result.code = (dot > 0.0)
+                        ? PolygonLocation.InsidePolygonProjectsToEdgeInterior
+                        : PolygonLocation.OutsidePolygonProjectsToEdgeInterior;
+                }
             }
         }
         return result;