geo-polygonize 0.39.13 → 0.40.0

package/README.md

@@ -7,45 +7,39 @@ A native Rust port of the JTS/GEOS polygonization algorithm. This crate allows y
 ## Features
 
 - **Robust Polygonization**: Extracts polygons from unstructured linework.
-- **Robust Noding**: Implements **Iterated Snap Rounding (ISR)** to guarantee topological correctness on dirty inputs (self-intersections, overlaps).
+- **Iterative Grid Noding (Unchecked)**: Splits and snaps dirty linework, without claiming certified snap-rounding guarantees.
 - **Hardware Acceleration**: Uses **SIMD** instructions (via `wide` crate) for critical geometric predicates like Point-in-Polygon checks.
 - **Wasm Optimized**: Tailored for WebAssembly with `talc` allocator and binary GeoArrow support.
-- **Performance**: Competitive with GEOS/Shapely (C++), outperforming it on random sparse inputs and scaling well on dense grids.
+- **Performance**: SIMD, spatial indexing, and optional parallel execution, with checked-in benchmark tooling.
 - **Geo Ecosystem**: Fully integrated with `geo-types` and `geo` crates.
 - **GeoArrow Support**: Arrow C Data Interface and Arrow IPC integration with GeoArrow metadata.
 
 ## Engineering Roadmap
 
-For an ambitious, prioritized plan covering performance, security, API consistency, and maintainability, see [docs/roadmap.md](docs/roadmap.md).
+For an ambitious, prioritized plan covering performance, security, API consistency, and maintainability, see [ROADMAP.md](ROADMAP.md).
 
 ## Usage
 
 ### Library
 
 ```rust
-use geo_polygonize_core::Polygonizer;
-use geo_types::LineString;
+use geo_polygonize_core::{polygonize, Coord3D, Line3D};
+use geo_polygonize_core::options::PolygonizerOptions;
 
 fn main() {
-    let mut poly = Polygonizer::new();
-
-    // Enable robust noding if lines might intersect
-    poly.node_input = true;
-    // Optional: Configure snap grid (default 1e-10)
-    poly.snap_grid_size = 1e-6;
-
-    // Add lines (e.g., a square with diagonals)
-    poly.add_geometry(LineString::from(vec![
-        (0.0, 0.0), (10.0, 0.0), (10.0, 10.0), (0.0, 10.0), (0.0, 0.0)
-    ]).into());
-    poly.add_geometry(LineString::from(vec![
-        (0.0, 0.0), (10.0, 10.0)
-    ]).into());
-
-    let polygons = poly.polygonize().expect("Polygonization failed");
-
-    for p in polygons {
-        println!("Found polygon with area: {}", p.unsigned_area());
+    let points = [
+        Coord3D::new(0.0, 0.0, 0.0),
+        Coord3D::new(10.0, 0.0, 0.0),
+        Coord3D::new(10.0, 10.0, 0.0),
+        Coord3D::new(0.0, 10.0, 0.0),
+    ];
+    let lines = (0..4).map(|i| Line3D::new(points[i], points[(i + 1) % 4], i as u32));
+
+    let result = polygonize(lines, &PolygonizerOptions::default())
+        .expect("Polygonization failed");
+
+    for polygon in result.polygons {
+        println!("Found polygon with area: {}", polygon.unsigned_area_2d());
     }
 }
 ```
@@ -55,7 +49,7 @@ fn main() {
 Polygonization quality is heavily influenced by input noding strategy.
 
 - **`node_input = false`** (default): Fastest path. Use this when your input linework is already noded (all intersections are explicit vertices).
-- **`node_input = true`**: Enables Iterated Snap Rounding (ISR). Use this for real-world datasets that may contain slight misalignments, overlaps, or self-intersections.
+- **`node_input = true`**: Enables unchecked iterative grid noding. Use this for real-world datasets that may contain slight misalignments, overlaps, or self-intersections, and validate outputs when correctness must be certified.
 - **`snap_grid_size`** controls how aggressively coordinates are snapped during robust noding:
   - Start with `1e-10` for high-precision projected data.
   - Increase to `1e-8` or `1e-6` when near-duplicate vertices prevent clean topology.
@@ -254,7 +248,7 @@ async function run() {
 ```
 
 **Important:** Multithreaded WebAssembly requires `SharedArrayBuffer`, which is only available in secure contexts. You **must** serve your page with the following headers:
-```
+```text
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
@@ -332,7 +326,7 @@ This implementation moves away from the pointer-based graph structures of JTS/GE
 See [ARCHITECTURE.md](ARCHITECTURE.md) for a deep dive into the optimization strategies.
 
 Key optimizations include:
-1.  **Robust Noding**: Iterated Snap Rounding (ISR) using `rstar` for intersection detection and grid snapping.
+1.  **Noding**: Unchecked iterative grid noding with spatially dispatched intersection detection.
 2.  **Vectorization**: SIMD-accelerated Ray Casting for efficient Hole Assignment.
 3.  **Memory Layout**: Structure of Arrays (SoA) for graph nodes and `talc` allocator for Wasm.
 

package/dist/slim/cjs/bindings/OutputFilterOptions.d.ts

@@ -0,0 +1,6 @@
+export type OutputFilterOptions = {
+    /**
+     * Keep faces whose area is greater than or equal to this value.
+     */
+    minimum_face_area?: number;
+};

package/dist/slim/cjs/bindings/PolygonizerOptions.d.ts

@@ -2,6 +2,7 @@ import type { ContainmentOptions } from "./ContainmentOptions";
 import type { DeterminismOptions } from "./DeterminismOptions";
 import type { DiagnosticsOptions } from "./DiagnosticsOptions";
 import type { NodingOptions } from "./NodingOptions";
+import type { OutputFilterOptions } from "./OutputFilterOptions";
 import type { ProvenanceOptions } from "./ProvenanceOptions";
 import type { SnapStrategy } from "./SnapStrategy";
 /**
@@ -78,6 +79,10 @@ export type PolygonizerOptions = {
      * Options for mapping final faces back to original input geometry IDs.
      */
     provenance: ProvenanceOptions;
+    /**
+     * Optional application-level filtering applied after topology is established.
+     */
+    output_filter: OutputFilterOptions;
     /**
      * An optional identifier for the input dataset.
      */

package/dist/slim/cjs/index.d.ts

@@ -6,6 +6,7 @@ export * from "./bindings/DeterminismOptions";
 export * from "./bindings/DiagnosticsOptions";
 export * from "./bindings/NodingBackend";
 export * from "./bindings/NodingOptions";
+export * from "./bindings/OutputFilterOptions";
 export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";

package/dist/slim/cjs/index_slim.d.ts

@@ -6,6 +6,7 @@ export * from "./bindings/DeterminismOptions";
 export * from "./bindings/DiagnosticsOptions";
 export * from "./bindings/NodingBackend";
 export * from "./bindings/NodingOptions";
+export * from "./bindings/OutputFilterOptions";
 export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";

package/dist/slim/cjs/index_slim.js

@@ -892,6 +892,9 @@ const cfbRobustOptions = {
         enabled: true,
         include_boundary_line_ids: true,
     },
+    output_filter: {
+        minimum_face_area: undefined,
+    },
     input_profile_id: "cfb_robust_v1",
 };
 

package/dist/slim/cjs/index_threads.d.ts

@@ -6,6 +6,7 @@ export * from "./bindings/DeterminismOptions";
 export * from "./bindings/DiagnosticsOptions";
 export * from "./bindings/NodingBackend";
 export * from "./bindings/NodingOptions";
+export * from "./bindings/OutputFilterOptions";
 export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";

package/dist/slim/es/bindings/OutputFilterOptions.d.ts

@@ -0,0 +1,6 @@
+export type OutputFilterOptions = {
+    /**
+     * Keep faces whose area is greater than or equal to this value.
+     */
+    minimum_face_area?: number;
+};

package/dist/slim/es/bindings/PolygonizerOptions.d.ts

@@ -2,6 +2,7 @@ import type { ContainmentOptions } from "./ContainmentOptions";
 import type { DeterminismOptions } from "./DeterminismOptions";
 import type { DiagnosticsOptions } from "./DiagnosticsOptions";
 import type { NodingOptions } from "./NodingOptions";
+import type { OutputFilterOptions } from "./OutputFilterOptions";
 import type { ProvenanceOptions } from "./ProvenanceOptions";
 import type { SnapStrategy } from "./SnapStrategy";
 /**
@@ -78,6 +79,10 @@ export type PolygonizerOptions = {
      * Options for mapping final faces back to original input geometry IDs.
      */
     provenance: ProvenanceOptions;
+    /**
+     * Optional application-level filtering applied after topology is established.
+     */
+    output_filter: OutputFilterOptions;
     /**
      * An optional identifier for the input dataset.
      */

package/dist/slim/es/index.d.ts

@@ -6,6 +6,7 @@ export * from "./bindings/DeterminismOptions";
 export * from "./bindings/DiagnosticsOptions";
 export * from "./bindings/NodingBackend";
 export * from "./bindings/NodingOptions";
+export * from "./bindings/OutputFilterOptions";
 export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";

package/dist/slim/es/index_slim.d.ts

@@ -6,6 +6,7 @@ export * from "./bindings/DeterminismOptions";
 export * from "./bindings/DiagnosticsOptions";
 export * from "./bindings/NodingBackend";
 export * from "./bindings/NodingOptions";
+export * from "./bindings/OutputFilterOptions";
 export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";

package/dist/slim/es/index_slim.js

@@ -889,6 +889,9 @@ const cfbRobustOptions = {
         enabled: true,
         include_boundary_line_ids: true,
     },
+    output_filter: {
+        minimum_face_area: undefined,
+    },
     input_profile_id: "cfb_robust_v1",
 };
 

package/dist/slim/es/index_threads.d.ts

@@ -6,6 +6,7 @@ export * from "./bindings/DeterminismOptions";
 export * from "./bindings/DiagnosticsOptions";
 export * from "./bindings/NodingBackend";
 export * from "./bindings/NodingOptions";
+export * from "./bindings/OutputFilterOptions";
 export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";

package/dist/slim/pkg-wrapper/bindings/OutputFilterOptions.d.ts

@@ -0,0 +1,6 @@
+export type OutputFilterOptions = {
+    /**
+     * Keep faces whose area is greater than or equal to this value.
+     */
+    minimum_face_area?: number;
+};

package/dist/slim/pkg-wrapper/bindings/PolygonizerOptions.d.ts

@@ -2,6 +2,7 @@ import type { ContainmentOptions } from "./ContainmentOptions";
 import type { DeterminismOptions } from "./DeterminismOptions";
 import type { DiagnosticsOptions } from "./DiagnosticsOptions";
 import type { NodingOptions } from "./NodingOptions";
+import type { OutputFilterOptions } from "./OutputFilterOptions";
 import type { ProvenanceOptions } from "./ProvenanceOptions";
 import type { SnapStrategy } from "./SnapStrategy";
 /**
@@ -78,6 +79,10 @@ export type PolygonizerOptions = {
      * Options for mapping final faces back to original input geometry IDs.
      */
     provenance: ProvenanceOptions;
+    /**
+     * Optional application-level filtering applied after topology is established.
+     */
+    output_filter: OutputFilterOptions;
     /**
      * An optional identifier for the input dataset.
      */

package/dist/standard/cjs/bindings/OutputFilterOptions.d.ts

@@ -0,0 +1,6 @@
+export type OutputFilterOptions = {
+    /**
+     * Keep faces whose area is greater than or equal to this value.
+     */
+    minimum_face_area?: number;
+};

package/dist/standard/cjs/bindings/PolygonizerOptions.d.ts

@@ -2,6 +2,7 @@ import type { ContainmentOptions } from "./ContainmentOptions";
 import type { DeterminismOptions } from "./DeterminismOptions";
 import type { DiagnosticsOptions } from "./DiagnosticsOptions";
 import type { NodingOptions } from "./NodingOptions";
+import type { OutputFilterOptions } from "./OutputFilterOptions";
 import type { ProvenanceOptions } from "./ProvenanceOptions";
 import type { SnapStrategy } from "./SnapStrategy";
 /**
@@ -78,6 +79,10 @@ export type PolygonizerOptions = {
      * Options for mapping final faces back to original input geometry IDs.
      */
     provenance: ProvenanceOptions;
+    /**
+     * Optional application-level filtering applied after topology is established.
+     */
+    output_filter: OutputFilterOptions;
     /**
      * An optional identifier for the input dataset.
      */

package/dist/standard/cjs/index.d.ts

@@ -6,6 +6,7 @@ export * from "./bindings/DeterminismOptions";
 export * from "./bindings/DiagnosticsOptions";
 export * from "./bindings/NodingBackend";
 export * from "./bindings/NodingOptions";
+export * from "./bindings/OutputFilterOptions";
 export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";