@itwin/core-geometry 5.1.0-dev.9 → 5.2.0-dev.1

package/lib/cjs/curve/RegionOps.d.ts

@@ -36,13 +36,14 @@ export declare enum 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
  */
 export declare class RegionOps {
@@ -65,7 +66,8 @@ export declare 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.
+     * * For a non-self-intersecting Loop, the returned area is negative if and only if the Loop is oriented clockwise
+     * with respect to the positive z-axis.
      * @param region any [[Loop]], [[ParityRegion]], or [[UnionRegion]].
      */
     static computeXYArea(region: AnyRegion): number | undefined;
@@ -136,16 +138,38 @@ export declare class RegionOps {
      * @param triangulate whether to triangulate the result
      */
     static polygonXYAreaDifferenceLoopsToPolyface(loopsA: MultiLineStringDataVariant, loopsB: MultiLineStringDataVariant, triangulate?: boolean): Polyface | undefined;
+    /**
+     * Return the region's simplest representation by stripping redundant parent(s).
+     * * No Boolean operations are performed.
+     * @param region input region (unchanged). Assumed to have at least one child.
+     * @returns
+     * * For a [[UnionRegion]] with exactly one child, return the child 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 child, return the `Loop`.
+     * * All other inputs returned unchanged.
+     * @see [[simplifyRegion]]
+     */
+    static simplifyRegionType(region: AnyRegion): AnyRegion;
+    /**
+     * Simplify the region's parent/child hierarchy in place:
+     * * Regions with exactly one child are simplified as per [[simplifyRegionType]].
+     * * Regions without children are removed.
+     * * No Boolean operations are performed.
+     * @param region region to simplify in place
+     * @returns reference to the updated input region
+     * @see [[simplifyRegionType]]
+     */
+    static simplifyRegion(region: AnyRegion): AnyRegion | undefined;
     /**
      * 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.
+     * @returns a region resulting from merging input loops and the boolean operation.
      */
     static regionBooleanXY(loopsA: AnyRegion | AnyRegion[] | undefined, loopsB: AnyRegion | AnyRegion[] | undefined, operation: RegionBinaryOpType, mergeTolerance?: number): AnyRegion | undefined;
     /**
@@ -299,31 +323,40 @@ export declare class RegionOps {
      */
     static consolidateAdjacentPrimitives(curves: CurveCollection, options?: ConsolidateAdjacentCurvePrimitivesOptions): void;
     /**
-     * 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]]
      */
     static sortOuterAndHoleLoopsXY(loops: Array<Loop | IndexedXYZCollection>): AnyRegion;
+    /**
+     * Collect inputs that are nominally closed: regions, and physically closed curves.
+     * * Physically closed input curves are each returned wrapped in a Loop to facilitate xy-algorithms,
+     * but outside this limited context, these Loops only makes sense if they are planar.
+    */
+    private static collectRegionsAndClosedPrimitives;
     /**
      * 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.
-     * * 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
-     * @returns array of [[SignedLoops]], each entry of which describes the faces in a single connected component:
+     * * "Holes" implied/bounded by inputs are _not_ preserved/discovered in output; in particular [[ParityRegion]]
+     * hole loops are treated like any other positive area loops.
+     * * A common use case of this method is to assemble the bounding negative-area "exterior" loop for each connected
+     * component of input curves. Passing `addBridges = true` decreases the number of connected components for nested
+     * input [[Loop]]s, and thus increases the likelihood of returning exactly one exterior loop. (This is why the
+     * default value for `addBridges` is `true`.)
+     * @param curvesAndRegions Any collection of curves. Each [[AnyRegion]] contributes its children _stripped of
+     * parity context_.
+     * @param tolerance optional distance tolerance for coincidence.
+     * @param addBridges whether to add line segments to connect nested input [[Loop]]s (default is `true`). When `false`,
+     * no line segments are added to the input curves, but the number of output components may be greater than expected.
+     * @returns array of [[SignedLoops]], each entry of which describes the areas bounded by a single connected component:
      *    * `positiveAreaLoops` contains "interior" loops, _including holes in ParityRegion input_. These loops have
      * positive area and counterclockwise orientation.
      *    * `negativeAreaLoops` contains (probably just one) "exterior" loop which is ordered clockwise.
@@ -331,7 +364,7 @@ export declare class RegionOps {
      *    * `edges` contains a [[LoopCurveLoopCurve]] object for each component edge, collecting both loops adjacent
      * to the edge and a constituent curve in each.
      */
-    static constructAllXYRegionLoops(curvesAndRegions: AnyCurve | AnyCurve[], tolerance?: number): SignedLoops[];
+    static constructAllXYRegionLoops(curvesAndRegions: AnyCurve | AnyCurve[], tolerance?: number, addBridges?: boolean): SignedLoops[];
     /**
      * Collect all `CurvePrimitives` in loosely typed input.
      * * Always recurses into primitives within explicit collections (Path, Loop, ParityRegion, UnionRegion).
@@ -374,12 +407,10 @@ export declare class RegionOps {
     private static triangulateRegionComponent;
     /**
      * 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
@@ -394,17 +425,21 @@ export declare class RegionOps {
     static convexDecomposePolygonXY(polygon: MultiLineStringDataVariant, maximize?: boolean): GrowableXYZArray[] | undefined;
 }
 /**
- * * Options to control method `RegionOps.consolidateAdjacentPrimitives`
+ * * Options to control method `RegionOps.consolidateAdjacentPrimitives`.
  * @public
  */
 export declare class ConsolidateAdjacentCurvePrimitivesOptions {
-    /** True to consolidate adjacent linear geometry into a single LineString3d */
+    /** True to consolidate adjacent linear geometry into a single LineString3d. */
     consolidateLinearGeometry: boolean;
-    /** True to consolidate contiguous compatible arcs into a single Arc3d */
+    /** True to consolidate contiguous compatible arcs into a single Arc3d. */
     consolidateCompatibleArcs: boolean;
-    /** Tolerance for collapsing identical points */
+    /** True to consolidate the first and last primitives of a [[Loop]], allowing the start/end point to change. */
+    consolidateLoopSeam?: boolean;
+    /** Disable LineSegment3d and LineString3d point compression. */
+    disableLinearCompression?: boolean;
+    /** Tolerance for detecting identical points. */
     duplicatePointTolerance: number;
-    /** Tolerance for removing interior colinear points. */
+    /** Tolerance for removing interior colinear points (if `!disableLinearCompression`). */
     colinearPointTolerance: number;
 }
 //# sourceMappingURL=RegionOps.d.ts.map

package/lib/cjs/curve/RegionOps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RegionOps.d.ts","sourceRoot":"","sources":["../../../src/curve/RegionOps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RegionOps.d.ts","sourceRoot":"","sources":["../../../src/curve/RegionOps.ts"],"names":[],"mappings":"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"}

package/lib/cjs/curve/RegionOps.js

@@ -8,6 +8,7 @@ exports.ConsolidateAdjacentCurvePrimitivesOptions = exports.RegionOps = exports.
 /** @packageDocumentation
  * @module Curve
  */
+const core_bentley_1 = require("@itwin/core-bentley");
 const Geometry_1 = require("../Geometry");
 const FrameBuilder_1 = require("../geometry3d/FrameBuilder");
 const GrowableXYZArray_1 = require("../geometry3d/GrowableXYZArray");
@@ -34,6 +35,8 @@ 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 LineSegment3d_1 = require("./LineSegment3d");
 const LineString3d_1 = require("./LineString3d");
 const Loop_1 = require("./Loop");
 const OffsetOptions_1 = require("./OffsetOptions");
@@ -60,13 +63,14 @@ 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 {
@@ -101,7 +105,8 @@ 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.
+     * * For a non-self-intersecting Loop, the returned area is negative if and only if the Loop is oriented clockwise
+     * with respect to the positive z-axis.
      * @param region any [[Loop]], [[ParityRegion]], or [[UnionRegion]].
      */
     static computeXYArea(region) {
@@ -281,26 +286,79 @@ class RegionOps {
         const graph = RegionOpsClassificationSweeps_1.RegionOpsFaceToFaceSearch.doPolygonBoolean(loopsA, loopsB, (inA, inB) => (inA && !inB), this._graphCheckPointFunction);
         return this.finishGraphToPolyface(graph, triangulate);
     }
+    /**
+     * Return the region's simplest representation by stripping redundant parent(s).
+     * * No Boolean operations are performed.
+     * @param region input region (unchanged). Assumed to have at least one child.
+     * @returns
+     * * For a [[UnionRegion]] with exactly one child, return the child 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 child, return the `Loop`.
+     * * All other inputs returned unchanged.
+     * @see [[simplifyRegion]]
+     */
+    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;
+    }
+    /**
+     * Simplify the region's parent/child hierarchy in place:
+     * * Regions with exactly one child are simplified as per [[simplifyRegionType]].
+     * * Regions without children are removed.
+     * * No Boolean operations are performed.
+     * @param region region to simplify in place
+     * @returns reference to the updated input region
+     * @see [[simplifyRegionType]]
+     */
+    static simplifyRegion(region) {
+        if (region instanceof Loop_1.Loop)
+            return region.children.length > 0 ? region : undefined;
+        // remove childless Parity/UnionRegion
+        for (let i = 0; i < region.children.length; ++i) {
+            const child = region.children[i];
+            const newChild = this.simplifyRegion(child);
+            if (!newChild) {
+                region.children.splice(i--, 1);
+            }
+            else if (newChild !== child) {
+                (0, core_bentley_1.assert)(!(newChild instanceof UnionRegion_1.UnionRegion));
+                region.children.splice(i--, 1, newChild);
+            }
+        }
+        if (region.children.length === 0)
+            return undefined;
+        // remove redundant Parity/UnionRegion parent
+        if (region.children.length === 1)
+            return region.children.splice(0, 1)[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.
+     * @returns a region resulting from merging input loops and the boolean operation.
      */
     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);
         context.annotateAndMergeCurvesInGraph(mergeTolerance);
+        const visitMask = context.graph.grabMask(false);
         const range = context.groupA.range().union(context.groupB.range());
         const areaTol = this.computeXYAreaTolerance(range, mergeTolerance);
+        const bridgeMask = Graph_1.HalfEdgeMask.BRIDGE_EDGE;
         context.runClassificationSweep(operation, (_graph, face, faceType, area) => {
             // ignore danglers and null faces, but not 2-edge "banana" faces with nonzero area
             if (face.countEdgesAroundFace() < 2)
@@ -308,12 +366,13 @@ class RegionOps {
             if (Math.abs(area) < areaTol)
                 return;
             if (faceType === 1) {
-                const loop = PlanarSubdivision_1.PlanarSubdivision.createLoopInFace(face);
-                if (loop)
-                    result.tryAddChild(loop);
+                const loopOrParityRegion = PlanarSubdivision_1.PlanarSubdivision.createLoopOrParityRegionInFace(face, bridgeMask, visitMask);
+                if (loopOrParityRegion)
+                    result.tryAddChild(loopOrParityRegion);
             }
         });
-        return result;
+        context.graph.dropMask(visitMask);
+        return this.simplifyRegion(result);
     }
     /**
      * Return a polyface whose facets are a boolean operation between the input regions.
@@ -604,14 +663,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]]
      */
@@ -627,19 +687,45 @@ class RegionOps {
         }
         return SortablePolygon_1.SortablePolygon.sortAsAnyRegion(loopAndArea);
     }
+    /**
+     * Collect inputs that are nominally closed: regions, and physically closed curves.
+     * * Physically closed input curves are each returned wrapped in a Loop to facilitate xy-algorithms,
+     * but outside this limited context, these Loops only makes sense if they are planar.
+    */
+    static collectRegionsAndClosedPrimitives(curves, tolerance = Geometry_1.Geometry.smallMetricDistance) {
+        const regions = [];
+        if (!Array.isArray(curves))
+            curves = [curves];
+        for (const curve of curves) {
+            if (curve instanceof Loop_1.Loop || curve instanceof ParityRegion_1.ParityRegion || curve instanceof UnionRegion_1.UnionRegion) {
+                regions.push(curve);
+            }
+            else if (curve instanceof Path_1.Path) {
+                if (curve.isPhysicallyClosedCurve(tolerance))
+                    regions.push(Loop_1.Loop.create(...curve.children));
+            }
+            else if (curve instanceof CurvePrimitive_1.CurvePrimitive) {
+                if (curve.isPhysicallyClosedCurve(tolerance))
+                    regions.push(Loop_1.Loop.create(curve));
+            }
+        }
+        return regions;
+    }
     /**
      * 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.
-     * * 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
-     * @returns array of [[SignedLoops]], each entry of which describes the faces in a single connected component:
+     * * "Holes" implied/bounded by inputs are _not_ preserved/discovered in output; in particular [[ParityRegion]]
+     * hole loops are treated like any other positive area loops.
+     * * A common use case of this method is to assemble the bounding negative-area "exterior" loop for each connected
+     * component of input curves. Passing `addBridges = true` decreases the number of connected components for nested
+     * input [[Loop]]s, and thus increases the likelihood of returning exactly one exterior loop. (This is why the
+     * default value for `addBridges` is `true`.)
+     * @param curvesAndRegions Any collection of curves. Each [[AnyRegion]] contributes its children _stripped of
+     * parity context_.
+     * @param tolerance optional distance tolerance for coincidence.
+     * @param addBridges whether to add line segments to connect nested input [[Loop]]s (default is `true`). When `false`,
+     * no line segments are added to the input curves, but the number of output components may be greater than expected.
+     * @returns array of [[SignedLoops]], each entry of which describes the areas bounded by a single connected component:
      *    * `positiveAreaLoops` contains "interior" loops, _including holes in ParityRegion input_. These loops have
      * positive area and counterclockwise orientation.
      *    * `negativeAreaLoops` contains (probably just one) "exterior" loop which is ordered clockwise.
@@ -647,10 +733,22 @@ class RegionOps {
      *    * `edges` contains a [[LoopCurveLoopCurve]] object for each component edge, collecting both loops adjacent
      * 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);
+    static constructAllXYRegionLoops(curvesAndRegions, tolerance = Geometry_1.Geometry.smallMetricDistance, addBridges = 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);
+        if (addBridges) { // generate a temp graph to extract its bridge edges
+            const context = RegionOpsClassificationSweeps_1.RegionBooleanContext.create(RegionOpsClassificationSweeps_1.RegionGroupOpType.Union, RegionOpsClassificationSweeps_1.RegionGroupOpType.Union);
+            const regions = this.collectRegionsAndClosedPrimitives(curvesAndRegions, tolerance);
+            context.addMembers(regions, undefined);
+            context.annotateAndMergeCurvesInGraph(tolerance);
+            context.graph.announceEdges((_graph, edge) => {
+                if (edge.isMaskSet(Graph_1.HalfEdgeMask.BRIDGE_EDGE))
+                    primitives.push(LineSegment3d_1.LineSegment3d.create(edge.getPoint3d(), edge.faceSuccessor.getPoint3d()));
+                return true;
+            });
+        }
         const intersections = CurveCurve_1.CurveCurve.allIntersectionsAmongPrimitivesXY(primitives, tolerance);
         const graph = PlanarSubdivision_1.PlanarSubdivision.assembleHalfEdgeGraph(primitives, intersections, tolerance);
         return PlanarSubdivision_1.PlanarSubdivision.collectSignedLoopSetsInHalfEdgeGraph(graph, areaTol);
@@ -801,12 +899,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
@@ -870,17 +966,21 @@ 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 */
+    /** True to consolidate the first and last primitives of a [[Loop]], allowing the start/end point to change. */
+    consolidateLoopSeam = false;
+    /** Disable LineSegment3d and LineString3d point compression. */
+    disableLinearCompression = false;
+    /** Tolerance for detecting identical points. */
     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;