@itwin/core-geometry 5.2.0-dev.8 → 5.2.1

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

@@ -0,0 +1,195 @@
+/** @packageDocumentation
+ * @module Bspline
+ */
+import { UnionOfConvexClipPlaneSets } from "../clipping/UnionOfConvexClipPlaneSets";
+import { CurveChain } from "../curve/CurveCollection";
+import { CurvePrimitive } from "../curve/CurvePrimitive";
+import { StrokeOptions } from "../curve/StrokeOptions";
+import { Point3d } from "../geometry3d/Point3dVector3d";
+import { Range2d } from "../geometry3d/Range";
+import { LowAndHighXY, XAndY } from "../geometry3d/XYZProps";
+import { HalfEdge, HalfEdgeGraph, HalfEdgeMask } from "./Graph";
+/**
+ * A class to represent a Voronoi diagram in the xy-plane.
+ * * A Voronoi diagram is a partitioning of the plane into regions of points closest to a given generating point or curve.
+ * * It is constructed from the circumcenters of its dual Delaunay triangulation.
+ * * Static construction methods take Delaunay, points, and CurveChain input.
+ * * More info can be found here: https://en.wikipedia.org/wiki/Voronoi_diagram and
+ * https://en.wikipedia.org/wiki/Delaunay_triangulation
+ * @internal
+ */
+export declare class Voronoi {
+    private _voronoiGraph;
+    private _inputGraph;
+    private _inputGraphIsTriangulation;
+    private _inputGraphRange;
+    private _idToIndexMap;
+    private _circumcenterMap;
+    private _circumcenterRange;
+    private _isCurveBased;
+    private _superFaceMask;
+    private static _workXY0;
+    private static _workXY1;
+    private static _workRay;
+    private static _workArc;
+    /** Construct an empty Voronoi graph and minimally validate input (use [[isValid]] to check). */
+    private constructor();
+    /**
+     * Accessor for the graph passed into the private constructor.
+     * * It is either a triangulation (assumed Delaunay) or a graph with no interior faces (assumed colinear path).
+     */
+    get getInputGraph(): HalfEdgeGraph;
+    /** Accessor for the input graph's range */
+    get getInputGraphRange(): Range2d;
+    /**
+     * Accessor for the Voronoi graph constructed from the input graph.
+     * * The Voronoi graph is typically constructed by static createFromXXX methods.
+     */
+    get getVoronoiGraph(): HalfEdgeGraph;
+    /** Whether or not this instance represents a curve-based Voronoi diagram. */
+    get isCurveBased(): boolean;
+    /** Accessor for the super face mask used for constructing a curve-based Voronoi diagram. */
+    get getSuperFaceMask(): HalfEdgeMask;
+    /** Whether the constructor has created a minimally valid instance. */
+    protected get isValid(): boolean;
+    /** Add an edge to the graph and set its edgeTags. */
+    private static addEdgeWithEdgeTags;
+    /** Add an edge to the graph and set its faceTags. */
+    private static addEdgeWithFaceTags;
+    /** Return the smallest HalfEdge id in the face, or -1 if not a triangle. */
+    private getTriangleId;
+    /**
+     * Populate a mapping from a triangle's id to its circumcircle.
+     * @returns whether the input graph is a triangulation.
+     */
+    private populateCircumcenters;
+    /**
+     * Return a segment along the bisector of the given triangle edge with the following properties:
+     * * start point is the triangle's circumcenter
+     * * end point is on the Voronoi boundary
+     * * direction vector has positive dot product with the vector from triangle centroid to edge midpoint
+     * @returns bisector segment, or undefined if the triangle circumcenter lies outside the Voronoi boundary
+     */
+    private getTriangleEdgeBisector;
+    /** Add the edge of an unbounded Voronoi region that corresponds to a Delaunay boundary edge; clip it at the boundary. */
+    private addVoronoiEdgeForDelaunayBoundaryEdge;
+    /** Add the edge of a bounded Voronoi region that corresponds to a Delaunay interior edge. */
+    private addVoronoiEdgeForDelaunayInteriorEdge;
+    /** Mask the exterior face, and set missing interior face tags */
+    private populateMasksAndFaceTags;
+    /**
+     * Construct a Voronoi instance from a Delaunay triangulation.
+     * * The Delaunay generating vertex `v` for a returned Voronoi region `R` is encoded thusly:
+     *   * For each [[HalfEdge]] `e` in the face loop of `R`, `delaunayGraph.allHalfEdges[e.faceTag]` is a HalfEdge in the
+     * vertex loop of `v`.
+     *   * The same `faceTag` is assigned to all HalfEdges in the face loop of `R`.
+     * * For best results:
+     *   * The input triangulation should be Delaunay and have convex boundary.
+     *   * Each HalfEdge in the exterior face loop of the input graph should have `HalfEdgeMask.BOUNDARY_EDGE` set on both edge mates.
+     *   * Each HalfEdge in the exterior face loop of the input graph should have `HalfEdgeMask.EXTERIOR` set.
+     *   * The input graph should not contain any pair of vertices closer than `distanceTol`.
+     *   * The input graph should not contain any triangle altitude smaller than `distanceTol` (this is a degenerate triangle).
+     * @param delaunayGraph A HalfEdgeGraph representing a Delaunay triangulation. Z-coordinates are ignored.
+     * @param distanceTol Optional distance tolerance to use when comparing points; default is `Geometry.smallMetricDistance`.
+     * @param boundingBox Optional nominal xy-bounding box for the Voronoi diagram. Default uses the Delaunay circumcenter range so
+     * that interior Voronoi regions are maximal.
+     * @returns a new instance containing the Voronoi diagram derived from the input graph, or `undefined` if invalid input.
+     */
+    static createFromDelaunayGraph(delaunayGraph: HalfEdgeGraph, distanceTol?: number, boundingBox?: LowAndHighXY): Voronoi | undefined;
+    /** Create a graph from ordered colinear points; optional Dictionary supplies edgeTag for the HalfEdges at each vertex. */
+    private static createColinearXYGraph;
+    /** Return a segment along the bisector of the given edge. Clip the bisector to the Voronoi boundary. */
+    private static getEdgeBisector;
+    /** Construct a Voronoi instance from a graph representing a colinear linestring. */
+    private static createFromColinearGraph;
+    /**
+     * Construct a Voronoi instance from a set of points.
+     * @param points An array of points. Z-coordinates are ignored. Points can be colinear.
+     * @param distanceTol Optional distance tolerance to use when comparing points; default is [[Geometry.smallMetricDistance]].
+     * @param boundingBox Optional nominal xy-bounding box for the Voronoi diagram. If unspecified, interior Voronoi cells are maximal.
+     * @returns a new instance containing the Voronoi diagram derived from the input points, or `undefined` if invalid input.
+     */
+    static createFromPoints(points: Point3d[], distanceTol?: number, boundingBox?: LowAndHighXY): Voronoi | undefined;
+    /** Stroke the curve interior, and associate the stroke points to the given index. Return first and last point. */
+    private static pushInteriorStrokePoints;
+    /** Intersect the circle with the curve and return the intersection closest to the desired curve endpoint. */
+    private static computeCircleIntersection;
+    /** Intersect two consecutive curves with a tiny circle centered at their joint, and associate the intersection on each curve with its respective index. */
+    private static pushSymmetricPointPairAtJoint;
+    /** Stroke each curve in the chain and associate each point with the index of its generating curve in the chain. */
+    private static createStrokePointsWithIndices;
+    /** Construct a graph from unique xy points. */
+    private static createGraphFromPointsWithIndices;
+    /**
+     * Create a Voronoi instance from a curve chain.
+     * * This is the curve-based analog for point-based Voronoi cells.
+     * * Each curve in the chain is sampled and a Voronoi diagram is generated from the Delaunay triangulation of all samples.
+     * * The union of Voronoi cells generated by a single curve's samples is:
+     *   * an approximation to the xy-region of points closest to the curve
+     *   * represented in the Voronoi graph by a _super face_, a loop of edges from multiple adjacent faces
+     *   * not necessarily convex
+     * * The generating curve with chain index `i` for the returned Voronoi super face `R` is encoded thusly:
+     *   * Each Voronoi edge has `faceTag` set as per [[createFromDelaunayGraph]], referring to its generating Delaunay vertex.
+     *   * Each Delaunay edge has `edgeTag` set to the index in `curveChain` of its generating curve.
+     *   * For each [[HalfEdge]] `e` in the super face loop of `R`, `delaunayGraph.allHalfEdges[e.faceTag].edgeTag === i`.
+     * @param curveChain A curve chain consisting of at least two [[CurvePrimitive]]s. Z-coordinates are ignored.
+     * The length of each child should exceed `distanceTol`.
+     * @param strokeOptions Optional stroke options to control the sampling of the curve chain.
+     * @param distanceTol Optional distance tolerance to use when comparing points; default is [[Geometry.smallMetricDistance]].
+     * @param boundingBox Optional nominal xy-bounding box for the Voronoi diagram. If unspecified, interior Voronoi cells are maximal.
+     * @returns a new instance, or `undefined` for invalid input.
+     */
+    static createFromCurveChain(curveChain: CurveChain, strokeOptions?: StrokeOptions, distanceTol?: number, boundingBox?: LowAndHighXY): Voronoi | undefined;
+    /**
+     * Test whether the edge is part of a curve-based Voronoi graph super face.
+     * @param curveIndex optional test for a _specific_ super face associated with the curve with the given index.
+     */
+    private isEdgeInVoronoiSuperFace;
+    /** Examine all edges in the curve-based Voronoi graph and return the first edge in an unvisited Voronoi super face. */
+    private findNextVoronoiSuperFaceStart;
+    /**
+     * Traverse the curve-based Voronoi graph and collect the edges comprising the Voronoi super face that starts with
+     * the given seed edge.
+     */
+    private collectVoronoiSuperFace;
+    /**
+     * Compute super faces of a curve-based Voronoi diagram.
+     * * The instance must have been constructed with [[createFromCurveChain]].
+     * * Each super face corresponds to the planar region of points closer to one curve in the generating chain than to any other.
+     * * Each returned edge is masked for querying by subsequent methods.
+     * @param numSuperFaces maximum number of super faces to return.
+     * @returns up to `numSuperFaces` Voronoi super faces, sorted by curve index, or `undefined` if invalid input.
+     * Each super face is an array of HalfEdges that form a loop.
+     */
+    computeVoronoiSuperFaces(numSuperFaces: number): HalfEdge[][] | undefined;
+    /**
+     * Construct a clipper for each curve-based Voronoi super face in the input array.
+     * @param superFaces array returned by [[collectVoronoiSuperFaces]].
+     * @returns array of clippers; the i_th clipper corresponds to the i_th input super face.
+     * Returns `undefined` if input is invalid, or if a clipper construction failed.
+     */
+    generateClippersFromVoronoiSuperFaces(superFaces: HalfEdge[][]): UnionOfConvexClipPlaneSets[] | undefined;
+}
+/**
+ * Interfaces used by the Voronoi class.
+ * @internal
+ */
+export declare namespace Voronoi {
+    /** An interface to represent a 2D line segment */
+    interface Segment2d {
+        start: XAndY;
+        end: XAndY;
+    }
+    /** An interface to represent a single stroke point with an associated index. */
+    interface StrokeData {
+        pt: Point3d;
+        cp: CurvePrimitive;
+        i: number;
+    }
+    /** An interface to represent two stroke points, e.g., first and last. */
+    interface Stroke01 {
+        p0: Point3d;
+        p1: Point3d;
+    }
+}
+//# sourceMappingURL=Voronoi.d.ts.map

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

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