@itwin/core-geometry 5.0.0-dev.113 → 5.0.0-dev.115

package/lib/cjs/curve/RegionOps.js

@@ -9,6 +9,7 @@ exports.ConsolidateAdjacentCurvePrimitivesOptions = exports.RegionOps = exports.
  * @module Curve
  */
 const Geometry_1 = require("../Geometry");
+const FrameBuilder_1 = require("../geometry3d/FrameBuilder");
 const GrowableXYZArray_1 = require("../geometry3d/GrowableXYZArray");
 const IndexedXYZCollection_1 = require("../geometry3d/IndexedXYZCollection");
 const Point3dArrayCarrier_1 = require("../geometry3d/Point3dArrayCarrier");
@@ -16,6 +17,7 @@ const Point3dVector3d_1 = require("../geometry3d/Point3dVector3d");
 const PolygonOps_1 = require("../geometry3d/PolygonOps");
 const PolylineCompressionByEdgeOffset_1 = require("../geometry3d/PolylineCompressionByEdgeOffset");
 const Range_1 = require("../geometry3d/Range");
+const Ray3d_1 = require("../geometry3d/Ray3d");
 const SortablePolygon_1 = require("../geometry3d/SortablePolygon");
 const Transform_1 = require("../geometry3d/Transform");
 const MomentData_1 = require("../geometry4d/MomentData");
@@ -32,6 +34,7 @@ const CurveWireMomentsXYZ_1 = require("./CurveWireMomentsXYZ");
 const GeometryQuery_1 = require("./GeometryQuery");
 const ChainCollectorContext_1 = require("./internalContexts/ChainCollectorContext");
 const PolygonOffsetContext_1 = require("./internalContexts/PolygonOffsetContext");
+const TransferWithSplitArcs_1 = require("./internalContexts/TransferWithSplitArcs");
 const LineString3d_1 = require("./LineString3d");
 const Loop_1 = require("./Loop");
 const OffsetOptions_1 = require("./OffsetOptions");
@@ -58,25 +61,29 @@ var RegionBinaryOpType;
 })(RegionBinaryOpType || (exports.RegionBinaryOpType = RegionBinaryOpType = {}));
 /**
  * Class `RegionOps` has static members for calculations on regions (areas).
- * * Regions are represented by these `CurveCollection` subclasses:
- *   * `Loop` -- a single loop
- *   * `ParityRegion` -- a collection of loops, interpreted by parity rules.
- * The common "One outer loop and many Inner loops" is a parity region.
- *   * `UnionRegion` -- a collection of `Loop` and `ParityRegion` objects understood as a (probably disjoint) union.
- * * **NOTE:** Most of the methods in this class ignore z-coordinates, so callers should ensure that input geometry has
- * been rotated parallel to the xy-plane.
+ * * Regions are represented by these [[CurveCollection]] subclasses:
+ *   * [[Loop]] -- a single loop
+ *   * [[ParityRegion]] -- a collection of loops, interpreted by parity rules.
+ * The common "One outer loop and many inner loops" is a parity region.
+ *   * [[UnionRegion]] -- a collection of `Loop` and `ParityRegion` objects understood as a (probably disjoint) union.
+ * * Most of the methods in this class:
+ *   * Ignore z-coordinates, so callers should ensure that input geometry has been rotated parallel to the xy-plane.
+ *   * Assume consistent Loop orientation: "solid" Loops are counterclockwise; "hole" Loops are clockwise.
  * @public
  */
 class RegionOps {
     /**
      * Return moment sums for a loop, parity region, or union region.
+     * * The input region should lie in a plane parallel to the xy-plane, as z-coords will be ignored.
      * * If `rawMomentData` is the MomentData returned by computeXYAreaMoments, convert to principal axes and moments with
-     *    call `principalMomentData = MomentData.inertiaProductsToPrincipalAxes (rawMomentData.origin, rawMomentData.sums);`
-     * @param root any Loop, ParityRegion, or UnionRegion.
+     * call `principalMomentData = MomentData.inertiaProductsToPrincipalAxes(rawMomentData.origin, rawMomentData.sums);`
+     * * `rawMomentData.origin` is the centroid of `region`.
+     * * `rawMomentData.sums.weight()` is the signed area of `region`.
+     * @param region any [[Loop]], [[ParityRegion]], or [[UnionRegion]].
      */
-    static computeXYAreaMoments(root) {
+    static computeXYAreaMoments(region) {
         const handler = new RegionMomentsXY_1.RegionMomentsXY();
-        const result = root.dispatchToGeometryHandler(handler);
+        const result = region.dispatchToGeometryHandler(handler);
         if (result instanceof MomentData_1.MomentData) {
             result.shiftOriginAndSumsToCentroidOfSums();
             return result;
@@ -85,8 +92,8 @@ class RegionOps {
     }
     /**
      * Return an area tolerance for a given xy-range and optional distance tolerance.
-     * @param range range of planar region to tolerance
-     * @param distanceTolerance optional absolute distance tolerance
+     * @param range range of planar region to tolerance.
+     * @param distanceTolerance optional absolute distance tolerance.
     */
     static computeXYAreaTolerance(range, distanceTolerance = Geometry_1.Geometry.smallMetricDistance) {
         // if A = bh and e is distance tolerance, then A' := (b+e/2)(h+e/2) = A + e/2(b+h+e/2), so A'-A = e/2(b+h+e/2).
@@ -95,12 +102,13 @@ class RegionOps {
     }
     /**
      * Return a (signed) xy area for a region.
+     * * The input region should lie in a plane parallel to the xy-plane, as z-coords will be ignored.
      * * The area is negative if and only if the region is oriented clockwise with respect to the positive z-axis.
-     * @param root any Loop, ParityRegion, or UnionRegion.
+     * @param region any [[Loop]], [[ParityRegion]], or [[UnionRegion]].
      */
-    static computeXYArea(root) {
+    static computeXYArea(region) {
         const handler = new RegionMomentsXY_1.RegionMomentsXY();
-        const result = root.dispatchToGeometryHandler(handler);
+        const result = region.dispatchToGeometryHandler(handler);
         if (result instanceof MomentData_1.MomentData) {
             return result.quantitySum;
         }
@@ -108,17 +116,56 @@ class RegionOps {
     }
     /**
      * Return MomentData with the sums of wire moments.
+     * * The input curve should lie in a plane parallel to the xy-plane, as z-coords will be ignored.
      * * If `rawMomentData` is the MomentData returned by computeXYAreaMoments, convert to principal axes and moments with
-     *    call `principalMomentData = MomentData.inertiaProductsToPrincipalAxes (rawMomentData.origin, rawMomentData.sums);`
-     * @param root any CurveCollection or CurvePrimitive.
+     * call `principalMomentData = MomentData.inertiaProductsToPrincipalAxes (rawMomentData.origin, rawMomentData.sums);`
+     * * `rawMomentData.origin` is the wire centroid of `curve`.
+     * * `rawMomentData.sums.weight()` is the signed length of `curve`.
+     * @param curve any [[CurveCollection]] or [[CurvePrimitive]].
      */
-    static computeXYZWireMomentSums(root) {
+    static computeXYZWireMomentSums(curve) {
         const handler = new CurveWireMomentsXYZ_1.CurveWireMomentsXYZ();
-        handler.visitLeaves(root);
+        handler.visitLeaves(curve);
         const result = handler.momentData;
         result.shiftOriginAndSumsToCentroidOfSums();
         return result;
     }
+    /**
+     * Return a [[Ray3d]] with:
+     * * `origin` is the centroid of the region,
+     * * `direction` is a unit vector perpendicular to the region plane,
+     * * `a` is the region area.
+     * @param region the region to process. Can lie in any plane.
+     * @param result optional pre-allocated result to populate and return.
+     */
+    static centroidAreaNormal(region, result) {
+        const localToWorld = FrameBuilder_1.FrameBuilder.createRightHandedFrame(undefined, region);
+        if (!localToWorld)
+            return undefined;
+        const normal = localToWorld.matrix.columnZ(result?.direction);
+        const regionIsXY = normal.isParallelTo(Point3dVector3d_1.Vector3d.unitZ(), true);
+        let regionXY = region;
+        if (!regionIsXY) { // rotate the region to be parallel to the xy-plane
+            regionXY = region.cloneTransformed(localToWorld.inverse());
+            if (!regionXY)
+                return undefined;
+        }
+        const momentData = RegionOps.computeXYAreaMoments(regionXY);
+        if (!momentData)
+            return undefined;
+        const centroid = momentData.origin.clone(result?.origin);
+        if (!regionIsXY) // rotate centroid back (area is unchanged)
+            localToWorld.multiplyPoint3d(centroid, centroid);
+        let area = momentData.sums.weight();
+        if (area < 0.0) {
+            area = -area;
+            normal.scale(-1.0, normal);
+        }
+        if (!result)
+            result = Ray3d_1.Ray3d.createCapture(centroid, normal);
+        result.a = area;
+        return result;
+    }
     /**
      * Create loops in the graph.
      * @internal
@@ -236,20 +283,41 @@ class RegionOps {
         const graph = RegionOpsClassificationSweeps_1.RegionOpsFaceToFaceSearch.doPolygonBoolean(loopsA, loopsB, (inA, inB) => (inA && !inB), this._graphCheckPointFunction);
         return this.finishGraphToPolyface(graph, triangulate);
     }
+    /**
+     * Simplify the type of the region by stripping redundant parent(s).
+     * * No Boolean operations are performed.
+     * * Invalid inputs (such as childless regions) are not corrected.
+     * @param region region to simplify
+     * @returns
+     * * For a [[UnionRegion]] with exactly one child, return it if it is a [[Loop]],
+     * or if it is a [[ParityRegion]] with multiple children, otherwise return the `ParityRegion`'s `Loop`.
+     * * For a `ParityRegion` with exactly one `Loop`, return it.
+     * * All other inputs returned unchanged.
+     */
+    static simplifyRegionType(region) {
+        if (region instanceof UnionRegion_1.UnionRegion) {
+            if (region.children.length === 1)
+                return this.simplifyRegionType(region.children[0]);
+        }
+        else if (region instanceof ParityRegion_1.ParityRegion) {
+            if (region.children.length === 1)
+                return region.children[0];
+        }
+        return region;
+    }
     /**
      * Return areas defined by a boolean operation.
-     * * If there are multiple regions in loopsA, they are treated as a union.
-     * * If there are multiple regions in loopsB, they are treated as a union.
-     * @param loopsA first set of loops
-     * @param loopsB second set of loops
+     * @note For best results, input regions should have correctly oriented loops. See [[sortOuterAndHoleLoopsXY]].
+     * @note A common use case of this method is to convert a region with overlapping children into one with
+     * non-overlapping children: `regionOut = RegionOps.regionBooleanXY(regionIn, undefined, RegionBinaryOpType.Union)`.
+     * @param loopsA first set of loops (treated as a union)
+     * @param loopsB second set of loops (treated as a union)
      * @param operation indicates Union, Intersection, Parity, AMinusB, or BMinusA
      * @param mergeTolerance absolute distance tolerance for merging loops
      * @returns a region resulting from merging input loops and the boolean operation. May contain bridge edges added
      * to connect interior loops to exterior loops.
      */
     static regionBooleanXY(loopsA, loopsB, operation, mergeTolerance = Geometry_1.Geometry.smallMetricDistance) {
-        // Always return UnionRegion for now. But keep return type as AnyRegion:
-        // in the future, we might return the *simplest* region type.
         const result = UnionRegion_1.UnionRegion.create();
         const context = RegionOpsClassificationSweeps_1.RegionBooleanContext.create(RegionOpsClassificationSweeps_1.RegionGroupOpType.Union, RegionOpsClassificationSweeps_1.RegionGroupOpType.Union);
         context.addMembers(loopsA, loopsB);
@@ -268,7 +336,7 @@ class RegionOps {
                     result.tryAddChild(loop);
             }
         });
-        return result;
+        return result ? this.simplifyRegionType(result) : undefined;
     }
     /**
      * Return a polyface whose facets are a boolean operation between the input regions.
@@ -559,14 +627,15 @@ class RegionOps {
         curves.dispatchToGeometryHandler(context);
     }
     /**
-     * Reverse and reorder loops in the xy-plane for consistency and containment.
-     * @param loops multiple loops in any order and orientation, z-coordinates ignored
+     * Reverse and reorder loops in the xy-plane for consistent orientation and containment.
+     * @param loops multiple loops in any order and orientation, z-coordinates ignored.
+     * * For best results, all overlaps should be containments, i.e., loop boundaries can touch, but should not cross.
      * @returns a region that captures the input pointers. This region is a:
-     * * `Loop` if there is exactly one input loop. It is oriented counterclockwise.
-     * * `ParityRegion` if input consists of exactly one outer loop with at least one hole loop.
+     * * [[Loop]] if there is exactly one input loop. It is oriented counterclockwise.
+     * * [[ParityRegion]] if input consists of exactly one outer loop with at least one hole loop.
      * Its first child is an outer loop oriented counterclockwise; all subsequent children are holes oriented
      * clockwise.
-     * * `UnionRegion` if any other input configuration. Its children are individually ordered/oriented as in
+     * * [[UnionRegion]] if any other input configuration. Its children are individually ordered/oriented as in
      * the above cases.
      * @see [[PolygonOps.sortOuterAndHoleLoopsXY]]
      */
@@ -586,14 +655,14 @@ class RegionOps {
      * Find all xy-areas bounded by the unstructured, possibly intersecting curves.
      * * For best results, input curves should be parallel to the xy-plane, as z-coordinates are ignored.
      * * A common use case of this method is to assemble the bounding "exterior" loop (or loops) containing the
-     * input curves.
+     * input curves. Note that "holes" implied by inputs are _not_ preserved in output.
      * * This method does not add bridge edges to connect outer loops to inner loops. Each disconnected loop,
      * regardless of its containment, is returned as its own SignedLoops object. Pre-process with [[regionBooleanXY]]
      * to add bridge edges so that [[constructAllXYRegionLoops]] will return outer and inner loops in the same
      * SignedLoops object.
      * @param curvesAndRegions Any collection of curves. Each Loop/ParityRegion/UnionRegion contributes its curve
-     * primitives.
-     * @param tolerance optional distance tolerance for coincidence
+     * primitives, stripped of parity context. This means holes are _not_ preserved in output.
+     * @param tolerance optional distance tolerance for coincidence.
      * @returns array of [[SignedLoops]], each entry of which describes the faces in a single connected component:
      *    * `positiveAreaLoops` contains "interior" loops, _including holes in ParityRegion input_. These loops have
      * positive area and counterclockwise orientation.
@@ -603,7 +672,8 @@ class RegionOps {
      * to the edge and a constituent curve in each.
      */
     static constructAllXYRegionLoops(curvesAndRegions, tolerance = Geometry_1.Geometry.smallMetricDistance) {
-        const primitives = RegionOps.collectCurvePrimitives(curvesAndRegions, undefined, true, true);
+        let primitives = RegionOps.collectCurvePrimitives(curvesAndRegions, undefined, true, true);
+        primitives = TransferWithSplitArcs_1.TransferWithSplitArcs.clone(CurveCollection_1.BagOfCurves.create(...primitives)).children;
         const range = this.curveArrayRange(primitives);
         const areaTol = this.computeXYAreaTolerance(range, tolerance);
         const intersections = CurveCurve_1.CurveCurve.allIntersectionsAmongPrimitivesXY(primitives, tolerance);
@@ -756,12 +826,10 @@ class RegionOps {
     }
     /**
      * Facet the region according to stroke options.
+     * @note For best results, [[UnionRegion]] input should consist of non-overlapping children. See [[regionBooleanXY]].
+     * @note For best results, [[ParityRegion]] input should be correctly oriented. See [[sortOuterAndHoleLoopsXY]].
      * @param region a closed xy-planar region, possibly with holes.
      * * The z-coordinates of the region are ignored. Caller is responsible for rotating the region into plane local coordinates beforehand, and reversing the rotation afterwards.
-     * * For best results, `UnionRegion` input should consist of non-overlapping children.
-     * Caller can ensure this by passing in `region = RegionOps.regionBooleanXY(unionRegion, undefined, RegionBinaryOpType.Union)`.
-     * * For best results, `ParityRegion` input should be correctly oriented (holes have opposite orientation to their containing loop).
-     * Caller can ensure this for non-intersecting loops by passing in `region = RegionOps.sortOuterAndHoleLoopsXY(loops)`.
      * @param options primarily how to stroke the region boundary, but also how to facet the region interior.
      * * By default, a triangulation is returned, but if `options.maximizeConvexFacets === true`, edges between coplanar triangles are removed to return maximally convex facets.
      * @returns facets for the region, or undefined if facetting failed
@@ -825,17 +893,19 @@ function pushToInOnOutArrays(curve, select, arrayNegative, array0, arrayPositive
         array0.push(curve);
 }
 /**
- * * Options to control method `RegionOps.consolidateAdjacentPrimitives`
+ * * Options to control method `RegionOps.consolidateAdjacentPrimitives`.
  * @public
  */
 class ConsolidateAdjacentCurvePrimitivesOptions {
-    /** True to consolidate adjacent linear geometry into a single LineString3d */
+    /** True to consolidate adjacent linear geometry into a single LineString3d. */
     consolidateLinearGeometry = true;
-    /** True to consolidate contiguous compatible arcs into a single Arc3d */
+    /** True to consolidate contiguous compatible arcs into a single Arc3d. */
     consolidateCompatibleArcs = true;
-    /** Tolerance for collapsing identical points */
+    /** Disable LineSegment3d and LineString3d point compression. */
+    disableLinearCompression = false;
+    /** Tolerance for collapsing identical points (if `!disableLinearCompression`). */
     duplicatePointTolerance = Geometry_1.Geometry.smallMetricDistance;
-    /** Tolerance for removing interior colinear points. */
+    /** Tolerance for removing interior colinear points (if `!disableLinearCompression`). */
     colinearPointTolerance = Geometry_1.Geometry.smallMetricDistance;
 }
 exports.ConsolidateAdjacentCurvePrimitivesOptions = ConsolidateAdjacentCurvePrimitivesOptions;