@itwin/core-geometry 4.0.0-dev.4 → 4.0.0-dev.41

package/lib/esm/geometry3d/PolygonOps.js

@@ -5,18 +5,75 @@
 /** @packageDocumentation
  * @module CartesianGeometry
  */
-import { Geometry } from "../Geometry";
+import { assert } from "@itwin/core-bentley";
+import { AxisOrder, Geometry, PolygonLocation } from "../Geometry";
 import { Matrix4d } from "../geometry4d/Matrix4d";
 import { Point4d } from "../geometry4d/Point4d";
 import { XYParitySearchContext } from "../topology/XYParitySearchContext";
 import { FrameBuilder } from "./FrameBuilder";
 import { GrowableXYZArray } from "./GrowableXYZArray";
 import { IndexedXYZCollection } from "./IndexedXYZCollection";
+import { Matrix3d } from "./Matrix3d";
+import { Plane3dByOriginAndUnitNormal } from "./Plane3dByOriginAndUnitNormal";
 import { Point2d, Vector2d } from "./Point2dVector2d";
 import { Point3dArrayCarrier } from "./Point3dArrayCarrier";
 import { Point3d, Vector3d } from "./Point3dVector3d";
 import { Ray3d } from "./Ray3d";
 import { SortablePolygon } from "./SortablePolygon";
+/**
+ * Carries data about a point in the plane of a polygon.
+ * @public
+ */
+export class PolygonLocationDetail {
+    constructor() {
+        this.point = new Point3d();
+        this.a = 0.0;
+        this.v = new Vector3d();
+        this.code = PolygonLocation.Unknown;
+        this.closestEdgeIndex = 0;
+        this.closestEdgeParam = 0.0;
+    }
+    /** Invalidate this detail. */
+    invalidate() {
+        this.point.setZero();
+        this.a = 0.0;
+        this.v.setZero();
+        this.code = PolygonLocation.Unknown;
+        this.closestEdgeIndex = 0;
+        this.closestEdgeParam = 0.0;
+    }
+    /** Create an invalid detail.
+     * @param result optional pre-allocated object to fill and return
+     */
+    static create(result) {
+        if (undefined === result)
+            result = new PolygonLocationDetail();
+        else
+            result.invalidate();
+        return result;
+    }
+    /** Set the instance contents from the other detail.
+     * @param other detail to clone
+     */
+    copyContentsFrom(other) {
+        this.point.setFrom(other.point);
+        this.a = other.a;
+        this.v.setFrom(other.v);
+        this.code = other.code;
+        this.closestEdgeIndex = other.closestEdgeIndex;
+        this.closestEdgeParam = other.closestEdgeParam;
+    }
+    /** Whether this detail is valid. */
+    get isValid() {
+        return this.code !== PolygonLocation.Unknown;
+    }
+    /** Whether this instance specifies a location inside or on the polygon. */
+    get isInsideOrOn() {
+        return this.code === PolygonLocation.InsidePolygon ||
+            this.code === PolygonLocation.OnPolygonVertex || this.code === PolygonLocation.OnPolygonEdgeInterior ||
+            this.code === PolygonLocation.InsidePolygonProjectsToVertex || this.code === PolygonLocation.InsidePolygonProjectsToEdgeInterior;
+    }
+}
 /**
  * Carrier for a loop extracted from clip operation, annotated for sorting
  * @internal
@@ -533,29 +590,27 @@ export class PolygonOps {
         }
     }
     /** Test the direction of turn at the vertices of the polygon, ignoring z-coordinates.
-     *
-     * *  For a polygon without self intersections, this is a convexity and orientation test: all positive is convex and counterclockwise,
-     * all negative is convex and clockwise
-     * *  Beware that a polygon which turns through more than a full turn can cross itself and close, but is not convex
-     * *  Returns 1 if all turns are to the left, -1 if all to the right, and 0 if there are any zero or reverse turns
+     * * For a polygon without self-intersections and successive colinear edges, this is a convexity and orientation test: all positive is convex and counterclockwise, all negative is convex and clockwise.
+     * * Beware that a polygon which turns through more than a full turn can cross itself and close, but is not convex.
+     * @returns 1 if all turns are to the left, -1 if all to the right, and 0 if there are any zero or reverse turns
      */
-    static testXYPolygonTurningDirections(pPointArray) {
+    static testXYPolygonTurningDirections(points) {
         // Reduce count by trailing duplicates; leaves iLast at final index
-        let numPoint = pPointArray.length;
+        let numPoint = points.length;
         let iLast = numPoint - 1;
-        while (iLast > 1 && pPointArray[iLast].x === pPointArray[0].x && pPointArray[iLast].y === pPointArray[0].y) {
+        while (iLast > 1 && points[iLast].x === points[0].x && points[iLast].y === points[0].y) {
             numPoint = iLast--;
         }
         if (numPoint > 2) {
-            let vector0 = Point2d.create(pPointArray[iLast].x - pPointArray[iLast - 1].x, pPointArray[iLast].y - pPointArray[iLast - 1].y);
-            const vector1 = Point2d.create(pPointArray[0].x - pPointArray[iLast].x, pPointArray[0].y - pPointArray[iLast].y);
+            let vector0 = Point2d.create(points[iLast].x - points[iLast - 1].x, points[iLast].y - points[iLast - 1].y);
+            const vector1 = Point2d.create(points[0].x - points[iLast].x, points[0].y - points[iLast].y);
             const baseArea = vector0.x * vector1.y - vector0.y * vector1.x;
             // In a convex polygon, all successive-vector cross products will
             // have the same sign as the base area, hence all products will be
             // positive.
             for (let i1 = 1; i1 < numPoint; i1++) {
                 vector0 = vector1.clone();
-                Point2d.create(pPointArray[i1].x - pPointArray[i1 - 1].x, pPointArray[i1].y - pPointArray[i1 - 1].y, vector1);
+                Point2d.create(points[i1].x - points[i1 - 1].x, points[i1].y - points[i1 - 1].y, vector1);
                 const currArea = vector0.x * vector1.y - vector0.y * vector1.x;
                 if (currArea * baseArea <= 0.0)
                     return 0;
@@ -565,6 +620,36 @@ export class PolygonOps {
         }
         return 0;
     }
+    /**
+     * Determine whether the polygon is convex.
+     * @param polygon vertices, closure point optional
+     * @returns whether the polygon is convex.
+     */
+    static isConvex(polygon) {
+        if (!(polygon instanceof IndexedXYZCollection))
+            return this.isConvex(new Point3dArrayCarrier(polygon));
+        let n = polygon.length;
+        if (n > 1 && polygon.getPoint3dAtUncheckedPointIndex(0).isExactEqual(polygon.getPoint3dAtUncheckedPointIndex(n - 1)))
+            --n; // ignore closure point
+        const normal = Vector3d.create();
+        if (!this.unitNormal(polygon, normal))
+            return false;
+        let positiveArea = 0.0;
+        let negativeArea = 0.0;
+        const vecA = this._vector0;
+        let vecB = Vector3d.createStartEnd(polygon.getPoint3dAtUncheckedPointIndex(n - 1), polygon.getPoint3dAtUncheckedPointIndex(0), this._vector1);
+        for (let i = 1; i <= n; i++) {
+            // check turn through vertices i-1,i,i+1
+            vecA.setFromVector3d(vecB);
+            vecB = Vector3d.createStartEnd(polygon.getPoint3dAtUncheckedPointIndex(i - 1), polygon.getPoint3dAtUncheckedPointIndex(i % n), vecB);
+            const signedArea = normal.tripleProduct(vecA, vecB);
+            if (signedArea >= 0.0)
+                positiveArea += signedArea;
+            else
+                negativeArea += signedArea;
+        }
+        return Math.abs(negativeArea) < Geometry.smallMetricDistanceSquared * positiveArea;
+    }
     /**
      * Test if point (x,y) is IN, OUT or ON a polygon.
      * @return (1) for in, (-1) for OUT, (0) for ON
@@ -661,15 +746,12 @@ export class PolygonOps {
         return numReverse;
     }
     /**
-     * Reverse loops as necessary to make them all have CCW orientation for given outward normal.
-     * * Return an array of arrays which capture the input pointers.
-     * * In each first level array:
-     *    * The first loop is an outer loop.
-     *    * all subsequent loops are holes
-     *    * The outer loop is CCW
-     *    * The holes are CW.
-     * * Call RegionOps.sortOuterAndHoleLoopsXY to have the result returned as a UnionRegion
-     * @param loops multiple loops to sort and reverse.
+     * Reverse and reorder loops in the xy-plane for consistency and containment.
+     * @param loops multiple polygons in any order and orientation, z-coordinates ignored
+     * @returns array of arrays of polygons that capture the input pointers. In each first level array:
+     * * The first polygon is an outer loop, oriented counterclockwise.
+     * * Any subsequent polygons are holes of the outer loop, oriented clockwise.
+     * @see RegionOps.sortOuterAndHoleLoopsXY
      */
     static sortOuterAndHoleLoopsXY(loops) {
         const loopAndArea = [];
@@ -682,10 +764,11 @@ export class PolygonOps {
      * Exactly like `sortOuterAndHoleLoopsXY` but allows loops in any plane.
      * @param loops multiple loops to sort and reverse.
      * @param defaultNormal optional normal for the loops, if known
+     * @see sortOuterAndHoleLoopsXY
      */
     static sortOuterAndHoleLoops(loops, defaultNormal) {
         const localToWorld = FrameBuilder.createRightHandedFrame(defaultNormal, loops);
-        const worldToLocal = localToWorld === null || localToWorld === void 0 ? void 0 : localToWorld.inverse();
+        const worldToLocal = localToWorld?.inverse();
         const xyLoops = [];
         if (worldToLocal !== undefined) {
             // transform into plane so we can ignore z in the sort
@@ -712,6 +795,320 @@ export class PolygonOps {
         }
         return sortedLoopsArray;
     }
+    /** Compute the closest point on the polygon boundary to the given point.
+     * @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 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.
+     * * `d.edgeIndex` and `d.edgeParam` specify the location of the closest point, within `distTol`.
+     * * `d.code` classifies the closest point as a vertex (`PolygonLocation.OnPolygonVertex`) or as a point on an edge (`PolygonLocation.OnPolygonEdgeInterior`).
+     * * `d.a` is the distance from testPoint to the closest point.
+     * * `d.v` can be used to classify p (if p and polygon are coplanar): if n is the polygon normal then `d.v.dotProduct(n)` is +/-/0 if and only if p is inside/outside/on the polygon.
+    */
+    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;
+        let numPoints = polygon.length;
+        while (numPoints > 1) {
+            if (polygon.distanceSquaredIndexIndex(0, numPoints - 1) > distTol2)
+                break;
+            --numPoints; // ignore closure point
+        }
+        result = PolygonLocationDetail.create(result);
+        if (0 === numPoints)
+            return result; // invalid
+        if (1 === numPoints) {
+            polygon.getPoint3dAtUncheckedPointIndex(0, result.point);
+            result.a = result.point.distance(testPoint);
+            result.v.setZero();
+            result.code = PolygonLocation.OnPolygonVertex;
+            result.closestEdgeIndex = 0;
+            result.closestEdgeParam = 0.0;
+            return result;
+        }
+        let iPrev = numPoints - 1;
+        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;
+                if (distToStart2 <= distTol2) {
+                    // testPoint is at edge start; we are done
+                    polygon.getPoint3dAtUncheckedPointIndex(iBase, result.point);
+                    result.a = Math.sqrt(distToStart2);
+                    result.v.setZero();
+                    result.code = PolygonLocation.OnPolygonVertex;
+                    result.closestEdgeIndex = iBase;
+                    result.closestEdgeParam = 0.0;
+                    return result;
+                }
+                if (distToStart2 < minDist2) {
+                    if (polygon.dotProductIndexIndexXYAndZ(iBase, iPrev, testPoint) <= 0.0) {
+                        // update candidate (to edge start) only if previous edge was NOOP
+                        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;
+                    }
+                }
+            }
+            else if (edgeParam <= 1.0) { // testPoint projects inside edge, or to edge end
+                const projDist2 = vDotV - edgeParam * edgeParam * uDotU;
+                if (projDist2 <= distTol2) {
+                    // testPoint is on edge; we are done
+                    const distToStart2 = vDotV;
+                    if (edgeParam <= 0.5 && distToStart2 <= distTol2) {
+                        // testPoint is at edge start
+                        polygon.getPoint3dAtUncheckedPointIndex(iBase, result.point);
+                        result.a = Math.sqrt(distToStart2);
+                        result.v.setZero();
+                        result.code = PolygonLocation.OnPolygonVertex;
+                        result.closestEdgeIndex = iBase;
+                        result.closestEdgeParam = 0.0;
+                        return result;
+                    }
+                    const distToEnd2 = projDist2 + (1.0 - edgeParam) * (1.0 - edgeParam) * uDotU;
+                    if (edgeParam > 0.5 && distToEnd2 <= distTol2) {
+                        // testPoint is at edge end
+                        polygon.getPoint3dAtUncheckedPointIndex(iNext, result.point);
+                        result.a = Math.sqrt(distToEnd2);
+                        result.v.setZero();
+                        result.code = PolygonLocation.OnPolygonVertex;
+                        result.closestEdgeIndex = iNext;
+                        result.closestEdgeParam = 0.0;
+                        return result;
+                    }
+                    // testPoint is on edge interior
+                    polygon.interpolateIndexIndex(iBase, edgeParam, iNext, result.point);
+                    result.a = Math.sqrt(projDist2);
+                    result.v.setZero();
+                    result.code = PolygonLocation.OnPolygonEdgeInterior;
+                    result.closestEdgeIndex = iBase;
+                    result.closestEdgeParam = edgeParam;
+                    return result;
+                }
+                if (projDist2 < minDist2) {
+                    // update candidate (to edge interior)
+                    polygon.interpolateIndexIndex(iBase, edgeParam, iNext, result.point);
+                    result.a = Math.sqrt(projDist2);
+                    polygon.crossProductIndexIndexXYAndZ(iBase, iNext, testPoint, result.v);
+                    result.code = PolygonLocation.OnPolygonEdgeInterior;
+                    result.closestEdgeIndex = iBase;
+                    result.closestEdgeParam = edgeParam;
+                    minDist2 = projDist2;
+                }
+            }
+            else { // edgeParam > 1.0
+                // NOOP: testPoint projects beyond edge end, handled by next edge
+            }
+            iPrev = iBase;
+        }
+        return result;
+    }
+    /** 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 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.
+     * * `d.code` indicates where the intersection lies with respect to the polygon.
+     * * `d.a` is the ray intersection parameter. If `d.a` >= 0, the ray intersects the plane of the polygon.
+     * * `d.edgeIndex` and `d.edgeParam` specify the location of the closest point on the polygon to the intersection, within `distTol`.
+     */
+    static intersectRay3d(polygon, ray, tolerance = Geometry.smallMetricDistance, result) {
+        if (!(polygon instanceof IndexedXYZCollection))
+            return this.intersectRay3d(new Point3dArrayCarrier(polygon), ray, tolerance, result);
+        if (!this.unitNormal(polygon, this._normal))
+            return PolygonLocationDetail.create(result); // invalid
+        this._workPlane = Plane3dByOriginAndUnitNormal.createXYZUVW(polygon.getXAtUncheckedPointIndex(0), polygon.getYAtUncheckedPointIndex(0), polygon.getZAtUncheckedPointIndex(0), this._normal.x, this._normal.y, this._normal.z, this._workPlane);
+        const intersectionPoint = Point3d.createZero(this._workXYZ);
+        const rayParam = ray.intersectionWithPlane(this._workPlane, intersectionPoint);
+        if (undefined === rayParam)
+            return PolygonLocationDetail.create(result);
+        result = this.closestPointOnBoundary(polygon, intersectionPoint, tolerance, result);
+        if (result.isValid) {
+            result.point.setFrom(intersectionPoint);
+            result.a = rayParam;
+            const dot = result.v.dotProduct(this._normal);
+            if (dot === 0.0) {
+                // 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;
+            }
+        }
+        return result;
+    }
+    /** Compute the intersection of a line (parameterized as a line segment) with the plane of this polygon.
+     * @param polygon points of the polygon, closure point optional
+     * @param point0 start point of segment on line to intersect
+     * @param point1 end point of segment on line to intersect
+     * @param tolerance optional distance tolerance to determine point-vertex and point-edge coincidence.
+     * @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.
+     * * `d.code` indicates where the intersection lies with respect to the polygon.
+     * * `d.a` is the segment intersection parameter. If `d.a` is in [0,1], the segment intersects the plane of the polygon.
+     * * `d.edgeIndex` and `d.edgeParam` specify the location of the closest point on the polygon to the intersection, within `distTol`.
+     * @see intersectRay3d
+     */
+    static intersectSegment(polygon, point0, point1, tolerance = Geometry.smallMetricDistance, result) {
+        this._workRay = Ray3d.createStartEnd(point0, point1, this._workRay);
+        return this.intersectRay3d(polygon, this._workRay, tolerance, result);
+    }
+    /** Compute edge data for the barycentric coordinate computation, ignoring all z-coordinates.
+     * @param polygon points of the polygon (without closure point)
+     * @param edgeStartVertexIndex index of start vertex of the edge (unchecked)
+     * @param point point to project to the edge
+     * @param edgeOutwardUnitNormal pre-allocated vector to be populated on return with the unit perpendicular to the edge, facing outward, in xy-plane
+     * @param tolerance used to clamp outputs
+     * @param result optional pre-allocated result
+     * @returns x: signed projection distance of `point` to the edge, y: edge parameter of the projection
+     */
+    static computeEdgeDataXY(polygon, edgeStartVertexIndex, point, edgeOutwardUnitNormal, tolerance = Geometry.smallMetricDistance, result) {
+        const i0 = edgeStartVertexIndex % polygon.length;
+        const i1 = (i0 + 1) % polygon.length;
+        polygon.vectorIndexIndex(i0, i1, edgeOutwardUnitNormal).unitPerpendicularXY(edgeOutwardUnitNormal).negate(edgeOutwardUnitNormal); // z is zero
+        const hypDeltaX = polygon.getXAtUncheckedPointIndex(i0) - point.x;
+        const hypDeltaY = polygon.getYAtUncheckedPointIndex(i0) - point.y;
+        let projDist = Geometry.dotProductXYXY(hypDeltaX, hypDeltaY, edgeOutwardUnitNormal.x, edgeOutwardUnitNormal.y);
+        const edgeDist = Geometry.crossProductXYXY(hypDeltaX, hypDeltaY, edgeOutwardUnitNormal.x, edgeOutwardUnitNormal.y);
+        const edgeLength = Geometry.distanceXYXY(polygon.getXAtUncheckedPointIndex(i0), polygon.getYAtUncheckedPointIndex(i0), polygon.getXAtUncheckedPointIndex(i1), polygon.getYAtUncheckedPointIndex(i1));
+        let edgeParam = Geometry.safeDivideFraction(edgeDist, edgeLength, 0.0);
+        if (Geometry.isSameCoordinate(0.0, projDist, tolerance))
+            projDist = 0.0;
+        if (Geometry.isSameCoordinate(0.0, edgeParam, tolerance))
+            edgeParam = 0.0;
+        else if (Geometry.isSameCoordinate(1.0, edgeParam, tolerance))
+            edgeParam = 1.0;
+        return Point2d.create(projDist, edgeParam, result);
+    }
+    /** Compute the barycentric coordinates for a point on either of a pair of adjacent edges of a convex polygon.
+     * @param polygon points of the polygon, assumed to be convex. Assumed to have no closure point.
+     * @param iPrev start index of previous edge
+     * @param prevNormal outward unit normal of previous edge
+     * @param prevProj x = signed distance from point to previous edge; y = edge parameter of this projection in [0,1]
+     * @param i start index of current edge
+     * @param normal outward unit normal of current edge
+     * @param proj x = signed distance from point to current edge; y = edge parameter of this projection in [0,1]
+     * @param coords pre-allocated barycentric coordinate array to return, assumed to have length at least `polygon.length`
+     * @returns barycentric coordinates, or undefined if not on either edge
+     */
+    static convexBarycentricCoordinatesOnEdge(polygon, iPrev, prevNormal, prevProj, i, normal, proj, coords) {
+        // ignore degenerate edges
+        const pointIsOnPrevEdge = !prevNormal.isZero && (0.0 === prevProj.x) && Geometry.isIn01(prevProj.y);
+        const pointIsOnEdge = !normal.isZero && (0.0 === proj.x) && Geometry.isIn01(proj.y);
+        if (pointIsOnPrevEdge && pointIsOnEdge) { // the point is at vertex i
+            coords.fill(0);
+            coords[i] = 1.0;
+            return coords;
+        }
+        const n = polygon.length;
+        if (pointIsOnPrevEdge) { // the point is on the previous edge
+            coords.fill(0);
+            const i0 = iPrev;
+            const i1 = i;
+            const edgeParam = prevProj.y;
+            coords[i0] = 1.0 - edgeParam;
+            coords[i1] = edgeParam;
+            return coords;
+        }
+        if (pointIsOnEdge) { // the point is on the edge starting at the i_th vertex
+            coords.fill(0);
+            const i0 = i;
+            const i1 = (i + 1) % n;
+            const edgeParam = proj.y;
+            coords[i0] = 1.0 - edgeParam;
+            coords[i1] = edgeParam;
+            return coords;
+        }
+        return undefined; // not on edge
+    }
+    // cspell:word CAGD
+    /** Compute the barycentric coordinates for a point inside a convex polygon.
+     * @param polygon points of the polygon, assumed to be convex. Closure point optional.
+     * @param point point assumed to be inside or on polygon
+     * @param tolerance distance tolerance for point to be considered on a polygon edge
+     * @return barycentric coordinates of the interior point, or undefined if invalid polygon or exterior point. Length is same as `polygon.length`.
+     * @see BarycentricTriangle.pointToFraction
+     */
+    static convexBarycentricCoordinates(polygon, point, tolerance = Geometry.smallMetricDistance) {
+        // cf. "Barycentric Coordinates for Convex Sets", by Warren et al., CAGD (2003)
+        if (Array.isArray(polygon))
+            return this.convexBarycentricCoordinates(new Point3dArrayCarrier(polygon), point);
+        let n = polygon.length;
+        while (n > 1 && polygon.getPoint3dAtUncheckedPointIndex(0).isExactEqual(polygon.getPoint3dAtUncheckedPointIndex(n - 1)))
+            --n; // ignore closure point(s)
+        if (n < 3 || !PolygonOps.unitNormal(polygon, this._normal))
+            return undefined;
+        const localToWorld = this._workMatrix3d = Matrix3d.createRigidHeadsUp(this._normal, AxisOrder.ZXY, this._workMatrix3d);
+        const polygonXY = new GrowableXYZArray(n);
+        for (let i = 0; i < n; ++i)
+            polygonXY.push(localToWorld.multiplyInverseXYZAsPoint3d(polygon.getXAtUncheckedPointIndex(i), polygon.getYAtUncheckedPointIndex(i), polygon.getZAtUncheckedPointIndex(i), this._workXYZ));
+        const pointXY = this._workXYZ = localToWorld.multiplyInverseXYZAsPoint3d(point.x, point.y, point.z, this._workXYZ);
+        // now we know polygon orientation is ccw, its last edge has positive length, and we can ignore z-coords
+        let iPrev = n - 1;
+        const outwardUnitNormalOfLastEdge = this._vector0;
+        const projToLastEdge = this._workXY0 = this.computeEdgeDataXY(polygonXY, iPrev, pointXY, outwardUnitNormalOfLastEdge, tolerance, this._workXY0);
+        // we can compare to exact zero because computeEdgeDataXY has chopped small distances to zero
+        if (projToLastEdge.x < 0.0)
+            return undefined; // point is outside polygon, or polygon is nonconvex
+        const outwardUnitNormalOfPrevEdge = Vector3d.createFrom(outwardUnitNormalOfLastEdge, this._vector1);
+        const projToPrevEdge = this._workXY1 = Point2d.createFrom(projToLastEdge, this._workXY1);
+        const coords = Array(polygon.length).fill(0); // use original length
+        const largestResult = (tolerance > 0.0) ? 1.0 / (tolerance * tolerance) : Geometry.largeCoordinateResult;
+        let coordSum = 0.0;
+        for (let i = 0; i < n; ++i) {
+            const outwardUnitNormalOfEdge = Vector3d.createFrom(outwardUnitNormalOfLastEdge, this._vector2);
+            const projToEdge = this._workXY2 = (i < n - 1) ? this.computeEdgeDataXY(polygonXY, i, pointXY, outwardUnitNormalOfEdge, tolerance, this._workXY2) : Point2d.createFrom(projToLastEdge, this._workXY2);
+            if (projToEdge.x < 0.0)
+                return undefined; // point is outside polygon, or polygon is nonconvex
+            if (undefined !== this.convexBarycentricCoordinatesOnEdge(polygonXY, iPrev, outwardUnitNormalOfPrevEdge, projToPrevEdge, i, outwardUnitNormalOfEdge, projToEdge, coords))
+                return coords; // point is on vertex or edge; we are done
+            if (outwardUnitNormalOfEdge.x === 0.0 && outwardUnitNormalOfEdge.y === 0.0)
+                continue; // edge is degenerate; coords[i] = 0; keep previous edge data
+            if (0.0 === projToPrevEdge.x || 0.0 === projToEdge.x)
+                continue; // point is on subsequent colinear edge (ASSUMING interior point, convex polygon!); coords[i] = 0; keep previous edge data
+            const areaOfNormalParallelogram = Math.abs(outwardUnitNormalOfPrevEdge.crossProductXY(outwardUnitNormalOfEdge));
+            const coord = Geometry.conditionalDivideCoordinate(areaOfNormalParallelogram, projToPrevEdge.x * projToEdge.x, largestResult);
+            if (undefined === coord) {
+                assert(!"unexpectedly small projection distance to an edge");
+                return undefined; // shouldn't happen due to chopping in computeEdgeDataXY: area/(dist*dist) <= 1/tol^2 = largestResult
+            }
+            coords[i] = coord;
+            coordSum += coord;
+            outwardUnitNormalOfPrevEdge.setFrom(outwardUnitNormalOfEdge);
+            projToPrevEdge.setFrom(projToEdge);
+            iPrev = i;
+        }
+        const scale = Geometry.conditionalDivideCoordinate(1.0, coordSum);
+        if (undefined === scale) {
+            assert(!"unexpected zero barycentric coordinate sum");
+            return undefined;
+        }
+        for (let i = 0; i < n; ++i)
+            coords[i] *= scale; // normalized
+        return coords;
+    }
 }
 /** These values are the integrated area moment products [xx,xy,xz, x]
  * for a right triangle in the first quadrant at the origin -- (0,0),(1,0),(0,1)