@itwin/core-geometry 4.4.0-dev.8 → 4.5.0-dev.0

package/lib/esm/topology/HalfEdgeGraphSearch.d.ts

@@ -1,125 +1,162 @@
-/** @packageDocumentation
- * @module Topology
- */
 import { HalfEdge, HalfEdgeGraph, HalfEdgeMask, HalfEdgeToBooleanFunction, NodeToNumberFunction } from "./Graph";
 import { SignedDataSummary } from "./SignedDataSummary";
 /**
  * Interface for an object that executes boolean tests on edges.
+ * @internal
  */
 export interface HalfEdgeTestObject {
     testEdge(h: HalfEdge): boolean;
 }
 /**
+ * Class to test match of half edge mask.
+ * @internal
  */
 export declare class HalfEdgeMaskTester {
     private _targetMask;
     private _targetValue;
     /**
-     *
+     * Constructor
      * @param mask mask to test in `testEdge` function
      * @param targetValue value to match for true return
      */
     constructor(mask: HalfEdgeMask, targetValue?: boolean);
-    /** Return true if the value of the targetMask matches the targetValue */
+    /** Return true if the value of the targetMask matches the targetValue. */
     testEdge(edge: HalfEdge): boolean;
 }
+/**
+ * Class for different types of searches for HalfEdgeGraph.
+ *  @internal
+ */
 export declare class HalfEdgeGraphSearch {
     /**
-     * * for each node of face, set the mask push to allNodesStack
-     * * push the faceSeed on onePerFaceStack[]
-     */
-    private static pushAndMaskAllNodesInFace;
-    /**
-     * Search an array of faceSeed nodes for the face with the most negative area.
-     * @param oneCandidateNodePerFace array containing one node from each face to be considered.
-     * @returns node on the minimum area face, or undefined if no such face (e.g., all faces have zero area).
-     */
-    static findMinimumAreaFace(oneCandidateNodePerFace: HalfEdgeGraph | HalfEdge[], faceAreaFunction?: NodeToNumberFunction): HalfEdge | undefined;
-    /**
-     * static method for face area computation -- useful as function parameter in collect FaceAreaSummary.
-     * * This simply calls `node.signedFaceArea ()`
+     * Static method for face area computation -- useful as function parameter in `collectFaceAreaSummary`.
+     * * This simply calls `node.signedFaceArea()`
      * @param node instance for signedFaceArea call.
      */
     static signedFaceArea(node: HalfEdge): number;
     /**
-     *
-     * Return a summary structure data about face (or other numeric quantity if the caller's areaFunction returns other value)
-     * * The default areaFunction computes area of polygonal face.
+     * Return a summary of face data (e.g., area) as computed by the callback on the faces of the graph.
      * * Callers with curved edge graphs must supply their own area function.
-     * @param source graph or array of nodes to examine
-     * @param collectAllNodes flag to pass to the SignedDataSummary constructor to control collection of nodes.
-     * @param areaFunction function to all to obtain area (or other numeric value)
+     * @param source graph or array of nodes to examine.
+     * @param collectAllNodes flag to pass to the `SignedDataSummary` constructor to control collection of nodes.
+     * @param areaFunction function to obtain area (or other numeric value). Default computes polygonal face area.
      */
     static collectFaceAreaSummary(source: HalfEdgeGraph | HalfEdge[], collectAllNodes?: boolean, areaFunction?: NodeToNumberFunction): SignedDataSummary<HalfEdge>;
     /**
-     * * Test if the graph is triangulated.
-     * * Return false if:
-     *   * Positive area face with more than 3 edges
-     *   * more than 1 negative area face with `allowMultipleNegativeAreaFaces` false
+     * Search the graph for the face with the most negative area.
+     * @param oneCandidateNodePerFace graph or an array containing one node from each face to be considered.
+     * @returns node on the negative area face with largest absolute area, or `undefined` if no negative area face.
+     */
+    static findMinimumAreaFace(oneCandidateNodePerFace: HalfEdgeGraph | HalfEdge[], faceAreaFunction?: NodeToNumberFunction): HalfEdge | undefined;
+    /**
+     * Test if the graph is triangulated.
+     * * Return `false` if:
+     *   * number of positive area faces with more than 3 edges is larger than `numPositiveExceptionsAllowed`.
+     *   * graph has more than 1 negative area face when `allowMultipleNegativeAreaFaces` is `false`.
      * * 2-edge faces are ignored.
      */
     static isTriangulatedCCW(source: HalfEdgeGraph | HalfEdge[], allowMultipleNegativeAreaFaces?: boolean, numPositiveExceptionsAllowed?: number): boolean;
     /**
-     * Search to all accessible faces from given seed.
-     * * The returned array contains one representative node in each face of the connected component.
-     * * If (nonnull) parity mask is given, on return:
-     *    * It is entirely set or entirely clear around each face
-     *    * It is entirely set on all faces that are an even number of face-to-face steps away from the seed.
-     *    * It is entirely clear on all faces that are an odd number of face-to-face steps away from the seed.
-     * @param seedEdge first edge to search.
+     * Process a face during graph traversal.
+     * @param faceSeed a node in the face.
+     * @param mask mask to set on each node of the face.
+     * @param allNodeStack array appended with each node of the face.
+     * @param onePerFaceStack array appended with `faceSeed`.
+     */
+    private static pushAndMaskAllNodesInFace;
+    /**
+     * Traverse (via Depth First Search) to all accessible faces from the given seed.
+     * @param faceSeed first node to start the traverse.
      * @param visitMask mask applied to all faces as visited.
-     * @param parityMask mask to apply (a) to first face, (b) to faces with alternating parity during the search.
+     * @param parityEdgeTester function to test if an edge is adjacent to two faces of opposite parity, e.g., a boundary
+     * edge that separates an "interior" face and an "exterior" face. If `parityEdgeTester` is not supplied and `parityMask`
+     * is supplied, the default parity rule is to alternate parity state in a "bullseye" pattern starting at the seed face,
+     * with each successive concentric ring of faces at constant topological distance from the seed face receiving the
+     * opposite parity state of the previous ring.
+     * @param parityMask mask to apply to the first face and faces that share the same parity as the first face, as
+     * determined by the parity rule. If this is `NULL_MASK`, there is no record of parity. If (non-null) parity mask
+     * is given, on return it is entirely set or entirely clear around each face.
+     * @returns an array that contains one representative node in each face of the connected component.
      */
     private static parityFloodFromSeed;
     /**
-     * * Search the given faces for the one with the minimum area.
-     * * If the mask in that face is OFF, toggle it on (all half edges of) all the faces.
+     * * Correct the parity mask in the faces of a component.
+     * * It is assumed that the parity mask is applied _consistently_ throughout the supplied faces, but maybe
+     * not _correctly_.
+     * * A consistently applied parity mask is "correct" if it is set on the negative area ("exterior") face of
+     * a connected component.
+     * * This method finds a face with negative area and toggles the mask throughout the input faces if this face
+     * lacks the parity mask.
      * * In a properly merged planar subdivision there should be only one true negative area face per component.
-     * @param graph parent graph
-     * @param parityMask mask which was previously set with alternating parity, but with an arbitrary start face.
-     * @param faces array of faces to search.
      */
     private static correctParityInSingleComponent;
-    /** Apply correctParityInSingleComponent to each array in components. (Quick exit if mask in NULL_MASK) */
+    /** Apply `correctParityInSingleComponent` to each array in components (quick exit if `parityMask` is `NULL_MASK`). */
     private static correctParityInComponentArrays;
     /**
-     * Collect arrays gathering faces by connected component.
-     * @param graph graph to inspect
-     * @param parityEdgeTester (optional) function to test if an edge is a parity change (e.g., a boundary edge).
-     * @param parityMask (optional, along with parityEdgeTester) mask to apply indicating parity.  If this is Mask.NULL_MASK, there is no record of parity.
+     * Collect connected components of the graph (via Depth First Search).
+     * @param graph graph to inspect.
+     * @param parityEdgeTester (optional) function to test if an edge is adjacent to two faces of opposite parity,
+     * e.g., a boundary edge that separates an "interior" face and an "exterior" face. If `parityEdgeTester` is not
+     * supplied and `parityMask` is supplied, the default parity rule is to alternate parity state in a "bullseye"
+     * pattern starting at the seed face, with each successive concentric ring of faces at constant topological
+     * distance from the seed face receiving the opposite parity state of the previous ring.
+     * @param parityMask (optional) mask to apply to the first face and faces that share the same parity as the
+     * first face, as determined by the parity rule. If this is `NULL_MASK`, there is no record of parity. If
+     * (non-null) parity mask is given, on return it is entirely set or entirely clear around each face.
+     * @returns the components of the graph, each component represented by an array of nodes, one node per face
+     * of the component. In other words, entry [i][j] is a HalfEdge in the j_th face loop of the i_th component.
      */
     static collectConnectedComponentsWithExteriorParityMasks(graph: HalfEdgeGraph, parityEdgeTester: HalfEdgeTestObject | undefined, parityMask?: HalfEdgeMask): HalfEdge[][];
     /**
-     * Test if (x,y) is inside (1), on an edge (0) or outside (-1) a face.
-     * @param seedNode any node on the face loop
-     * @param x x coordinate of test point.
-     * @param y y coordinate of test point.
+     * Breadth First Search through connected component of a graph.
+     * @param component vector of nodes, one per face.
+     * @param seed seed node in component.
+     * @param visitMask mask to apply to visited nodes. Assumed cleared throughout component.
+     * @param ignoreMask (optional) mask preset on faces to ignore. Default value is `HalfEdgeMask.EXTERIOR` to
+     * ignore exterior faces. Pass `HalfEdgeMask.NULL_MASK` to process all faces.
+     * @param maxFaceCount (optional) maximum number of faces in the component. Should be positive; otherwise
+     * `Infinity` is used.
+     * @returns node at which to start next component if maximum face count exceeded, or undefined.
      */
-    static pointInOrOnFaceXY(seedNode: HalfEdge, x: number, y: number): number | undefined;
+    private static exploreComponent;
     /**
-     * Announce nodes that are "extended face boundary" by conditions (usually mask of node and mate) in test functions.
-     * * After each node, the next candidate in reached by looking "around the head vertex loop" for the next boundary.
-     *   * "Around the vertex" from nodeA means
-     *      * First look at nodeA.faceSuccessor;
-     *      * Then look at vertexPredecessor around that vertex loop.
-     * * Each accepted node is passed to announceNode, and marked with the visit mask.
-     * * The counter of the announceEdge function is zero for the first edge, then increases with each edge.
-     * @param seed start node.
-     * @param isBoundaryEdge
-     * @param announceEdge
+     * Collect connected components of the graph (via Breadth First Search).
+     * @param graph graph to inspect.
+     * @param maxFaceCount (optional) maximum number of faces in each component. Should be positive; otherwise
+     * `Infinity` is used.
+     * @param ignoreMask (optional) mask preset on faces to ignore. Default value is `HalfEdgeMask.EXTERIOR` to ignore
+     * exterior faces. Pass `HalfEdgeMask.NULL_MASK` to process all faces.
+     * @returns the components of the graph, each component represented by an array of nodes, one node per face
+     * of the component. In other words, entry [i][j] is a HalfEdge in the j_th face loop of the i_th component.
+     */
+    static collectConnectedComponents(graph: HalfEdgeGraph, maxFaceCount?: number, ignoreMask?: HalfEdgeMask): HalfEdge[][];
+    /**
+     * Test if test point (xTest,yTest) is inside/outside a face or on an edge.
+     * @param seedNode any node on the face loop.
+     * @param xTest x coordinate of the test point.
+     * @param yTest y coordinate of the test point.
+     * @returns 0 if ON, 1 if IN, -1 if OUT.
      */
-    static collectExtendedBoundaryLoopFromSeed(seed: HalfEdge, visitMask: HalfEdgeMask, isBoundaryEdge: HalfEdgeToBooleanFunction, announceEdge: (edge: HalfEdge, counter: number) => void): void;
+    static pointInOrOnFaceXY(seedNode: HalfEdge, xTest: number, yTest: number): number | undefined;
     /**
-     * Collect arrays of nodes "around the boundary" of a graph with extraneous (non-boundary) edges.
-     * * The "boundary" is nodes that do NOT have the exterior mask, but whose mates DO have the exterior mask.
-     * * After each node, the next candidate in reached by looking "around the head vertex loop" for the next boundary.
-     *   * "Around the vertex" from nodeA means
-     *      * First look at nodeA.faceSuccessor;
-     *      * Then look at vertexPredecessor around that vertex loop.
-     * * Each accepted node is passed to announceNode, and marked with the visit mask.
+     * Collect boundary edges starting from `seed`.
+     * * If `seed` is not a boundary node or is already visited, the function exists early.
      * @param seed start node.
-     * @param isBoundaryNode
-     * @param announceNode
+     * @param visitMask mask to set on processed nodes.
+     * @param isBoundaryEdge function to test if an edge in a boundary edge.
+     * @param announceEdgeInBoundary callback invoked on each edge in the boundary loop in order. The counter is zero
+     * for the first edge, and incremented with each successive edge.
+     */
+    static collectExtendedBoundaryLoopFromSeed(seed: HalfEdge, visitMask: HalfEdgeMask, isBoundaryEdge: HalfEdgeToBooleanFunction, announceEdgeInBoundary: (edge: HalfEdge, counter: number) => void): void;
+    /**
+     * Collect boundary edges in the graph.
+     * * A boundary edge is defined by `exteriorMask` being set on only its "exterior" edge mate.
+     * * Each boundary edge is identified in the output by its edge mate that lacks `exteriorMask`.
+     * * Each inner array is ordered in the output so that its boundary edges form a connected path. If `exteriorMask`
+     * is preset consistently around each "exterior" face, these paths are loops.
+     * @param graph the graph to query
+     * @param exteriorMask mask preset on exactly one side of boundary edges
+     * @returns array of boundary loops, each loop an array of the unmasked mates of boundary edges
      */
     static collectExtendedBoundaryLoopsInGraph(graph: HalfEdgeGraph, exteriorMask: HalfEdgeMask): HalfEdge[][];
 }

package/lib/esm/topology/HalfEdgeGraphSearch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HalfEdgeGraphSearch.d.ts","sourceRoot":"","sources":["../../../src/topology/HalfEdgeGraphSearch.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACjH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAChC;AACD;GACG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,YAAY,CAAU;IAC9B;;;;OAIG;gBACgB,IAAI,EAAE,YAAY,EAAE,WAAW,GAAE,OAAc;IAIlE,yEAAyE;IAClE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;CAIzC;AAED,qBAAa,mBAAmB;IAE9B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAQxC;;;;OAIG;WACW,mBAAmB,CAAC,uBAAuB,EAAE,aAAa,GAAG,QAAQ,EAAE,EAAE,gBAAgB,CAAC,EAAE,oBAAoB,GAAG,QAAQ,GAAG,SAAS;IAKrJ;;;;OAIG;WACW,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM;IACpD;;;;;;;;OAQG;WACW,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAAE,eAAe,GAAE,OAAe,EACvG,YAAY,GAAE,oBAAyE,GAAG,iBAAiB,CAAC,QAAQ,CAAC;IAgBvH;;;;;;OAMG;WACW,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAAE,8BAA8B,GAAE,OAAc,EAAE,4BAA4B,SAAI,GAAG,OAAO;IA+B9J;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAsBlC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAgB7C,0GAA0G;IAC1G,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAM7C;;;;;OAKG;WACW,iDAAiD,CAAC,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,GAAG,SAAS,EAAE,UAAU,GAAE,YAAqC,GAAG,QAAQ,EAAE,EAAE;IAcxM;;;;;OAKG;WACW,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IA4B7F;;;;;;;;;;;OAWG;WACW,mCAAmC,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,yBAAyB,EAClI,YAAY,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI;IAoBzD;;;;;;;;;;;OAWG;WACW,mCAAmC,CAAC,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,GAAG,QAAQ,EAAE,EAAE;CAiBlH"}
+{"version":3,"file":"HalfEdgeGraphSearch.d.ts","sourceRoot":"","sources":["../../../src/topology/HalfEdgeGraphSearch.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,yBAAyB,EAAgB,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAC/H,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAKxD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAChC;AACD;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,YAAY,CAAU;IAC9B;;;;OAIG;gBACgB,IAAI,EAAE,YAAY,EAAE,WAAW,GAAE,OAAc;IAIlE,0EAA0E;IACnE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;CAGzC;AACD;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B;;;;OAIG;WACW,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM;IAGpD;;;;;;OAMG;WACW,sBAAsB,CAClC,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAClC,eAAe,GAAE,OAAe,EAChC,YAAY,GAAE,oBAAyE,GACtF,iBAAiB,CAAC,QAAQ,CAAC;IAa9B;;;;OAIG;WACW,mBAAmB,CAC/B,uBAAuB,EAAE,aAAa,GAAG,QAAQ,EAAE,EAAE,gBAAgB,CAAC,EAAE,oBAAoB,GAC3F,QAAQ,GAAG,SAAS;IAIvB;;;;;;OAMG;WACW,iBAAiB,CAC7B,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAClC,8BAA8B,GAAE,OAAc,EAC9C,4BAA4B,GAAE,MAAU,GACvC,OAAO;IA6BV;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IASxC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA2BlC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAgB7C,sHAAsH;IACtH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAM7C;;;;;;;;;;;;;OAaG;WACW,iDAAiD,CAC7D,KAAK,EAAE,aAAa,EACpB,gBAAgB,EAAE,kBAAkB,GAAG,SAAS,EAChD,UAAU,GAAE,YAAqC,GAChD,QAAQ,EAAE,EAAE;IAgBf;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IA4C/B;;;;;;;;;OASG;WACW,0BAA0B,CACtC,KAAK,EAAE,aAAa,EACpB,YAAY,GAAE,MAAiB,EAC/B,UAAU,GAAE,YAAoC,GAC/C,QAAQ,EAAE,EAAE;IAkCf;;;;;;OAMG;WACW,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IA2BrG;;;;;;;;OAQG;WACW,mCAAmC,CAC/C,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,YAAY,EACvB,cAAc,EAAE,yBAAyB,EACzC,sBAAsB,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAChE,IAAI;IAoBP;;;;;;;;;OASG;WACW,mCAAmC,CAAC,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,GAAG,QAAQ,EAAE,EAAE;CAkBlH"}