geo-polygonize 0.43.0 → 0.45.0

package/README.md

@@ -24,27 +24,37 @@ For an ambitious, prioritized plan covering performance, security, API consisten
 ### Library
 
 ```rust
-use geo_polygonize_core::{polygonize, Coord3D, Line3D};
-use geo_polygonize_core::options::PolygonizerOptions;
+use geo_polygonize_core::{polygonize_line_strings, PolygonizerOptions};
+use geo_types::LineString;
 
 fn main() {
-    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())
+    let ring = LineString::from(vec![
+        (0.0, 0.0),
+        (10.0, 0.0),
+        (10.0, 10.0),
+        (0.0, 10.0),
+        (0.0, 0.0),
+    ]);
+
+    let result = polygonize_line_strings([&ring], &PolygonizerOptions::default())
         .expect("Polygonization failed");
+    let polygons = result.into_multi_polygon();
 
-    for polygon in result.polygons {
-        println!("Found polygon with area: {}", polygon.unsigned_area_2d());
+    for polygon in polygons {
+        println!("Found polygon: {polygon:?}");
     }
 }
 ```
 
+`polygonize_line_strings` accepts owned or borrowed `geo_traits::LineStringTrait`
+values. Use `polygonize` when source IDs or Z values must be supplied explicitly,
+and keep its full result when dangles, cut edges, invalid rings, or diagnostics are
+needed.
+
+Rust consumers should import the supported facade from the crate root. Graph,
+noding, containment, utility, mutable-builder, and tiled APIs are internal or
+experimental and may change without compatibility guarantees before `1.0`.
+
 ### Choosing noding and precision
 
 Polygonization quality is heavily influenced by input noding strategy.
@@ -70,6 +80,19 @@ Use `NodingGuarantee::CertifiedFixedPrecision` with `node_input`, `FixedGrid`,
 the `Snap` backend, and `SnapStrategy::Grid` for hot-pixel snap rounding plus
 that validation. Certified coordinates must fit exact integer grid indices.
 
+### Z semantics
+
+Topology is always computed in XY. `ZPolicy::InterpolateAlongEdge` is the
+default and reconstructs split-vertex Z on each source edge;
+`PreferNearestEndpoint` uses the nearer endpoint, and `Ignore` emits zero Z.
+When several source edges meet at the same XY node, the graph chooses the Z
+from the lowest line ID (then the lowest Z) and reports conflicts through
+diagnostics. `ErrorOnConflict` instead returns a typed error when the difference
+exceeds `z.conflict_tolerance`.
+
+Use `Line3D` or the Python/Wasm typed-buffer APIs with `stride=3` for Z-aware
+processing. The GeoRust, GeoJSON, and current GeoArrow adapters are XY-only.
+
 ### Output semantics
 
 The polygonizer intentionally returns only valid polygonal areas that can be formed from closed cycles:
@@ -155,7 +178,7 @@ are dissolved into one topology edge while every contributing nonzero
 
 `SnapStrategy::Grid` keeps topology and output coordinates on a configured
 fixed precision grid. The CFB profile uses `GeosCompat`: the grid establishes robust
-topology, then output nodes regain deterministic source coordinates to better
+topology, then output nodes regain deterministic source XY coordinates to better
 match Shapely `snap` plus full-precision noding. It is not `set_precision`
 emulation, and exact parity is not guaranteed for many-to-one snaps.
 

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

@@ -6,6 +6,7 @@ import type { OutputFilterOptions } from "./OutputFilterOptions";
 import type { PrecisionModel } from "./PrecisionModel";
 import type { ProvenanceOptions } from "./ProvenanceOptions";
 import type { SnapStrategy } from "./SnapStrategy";
+import type { ZOptions } from "./ZOptions";
 /**
  * The canonical configuration object for the `geo-polygonize` engine.
  *
@@ -77,6 +78,10 @@ export type PolygonizerOptions = {
      * Options for mapping final faces back to original input geometry IDs.
      */
     provenance: ProvenanceOptions;
+    /**
+     * Controls Z reconstruction and same-XY conflict handling.
+     */
+    z: ZOptions;
     /**
      * Optional application-level filtering applied after topology is established.
      */

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

@@ -2,7 +2,7 @@
  * Strategy for robust snap noding and output coordinates.
  *
  * `Grid` uses the precision grid for both topology and output coordinates.
- * `GeosCompat` uses the grid for topology, then restores one deterministic nearest source
+ * `GeosCompat` uses the grid for topology, then restores one deterministic nearest source XY
  * coordinate per snapped node. This targets Shapely-style `snap` followed by full-precision
  * noding and polygonization; it does not emulate `set_precision` output.
  *

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

@@ -0,0 +1,8 @@
+import type { ZPolicy } from "./ZPolicy";
+export type ZOptions = {
+    policy: ZPolicy;
+    /**
+     * Z values at one XY node conflict when their difference exceeds this value.
+     */
+    conflict_tolerance: number;
+};

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

@@ -0,0 +1 @@
+export type ZPolicy = "Ignore" | "InterpolateAlongEdge" | "PreferNearestEndpoint" | "ErrorOnConflict";

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

@@ -13,5 +13,7 @@ export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";
 export * from "./bindings/TouchPolicy";
+export * from "./bindings/ZOptions";
+export * from "./bindings/ZPolicy";
 export * from "./cfb";
 export default function init(_input?: any): Promise<typeof exports>;

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

@@ -13,5 +13,7 @@ export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";
 export * from "./bindings/TouchPolicy";
+export * from "./bindings/ZOptions";
+export * from "./bindings/ZPolicy";
 export * from "./cfb";
 export declare function initBest(scalarModule: any, simdModule?: any): Promise<typeof scalarExports>;

package/dist/slim/cjs/index_slim.js

@@ -975,6 +975,10 @@ const cfbRobustOptions = {
         enabled: true,
         include_boundary_line_ids: true,
     },
+    z: {
+        policy: "InterpolateAlongEdge",
+        conflict_tolerance: 0,
+    },
     output_filter: {
         minimum_face_area: undefined,
     },

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

@@ -13,5 +13,7 @@ export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";
 export * from "./bindings/TouchPolicy";
+export * from "./bindings/ZOptions";
+export * from "./bindings/ZPolicy";
 export * from "./cfb";
 export default init;

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

@@ -6,6 +6,7 @@ import type { OutputFilterOptions } from "./OutputFilterOptions";
 import type { PrecisionModel } from "./PrecisionModel";
 import type { ProvenanceOptions } from "./ProvenanceOptions";
 import type { SnapStrategy } from "./SnapStrategy";
+import type { ZOptions } from "./ZOptions";
 /**
  * The canonical configuration object for the `geo-polygonize` engine.
  *
@@ -77,6 +78,10 @@ export type PolygonizerOptions = {
      * Options for mapping final faces back to original input geometry IDs.
      */
     provenance: ProvenanceOptions;
+    /**
+     * Controls Z reconstruction and same-XY conflict handling.
+     */
+    z: ZOptions;
     /**
      * Optional application-level filtering applied after topology is established.
      */

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

@@ -2,7 +2,7 @@
  * Strategy for robust snap noding and output coordinates.
  *
  * `Grid` uses the precision grid for both topology and output coordinates.
- * `GeosCompat` uses the grid for topology, then restores one deterministic nearest source
+ * `GeosCompat` uses the grid for topology, then restores one deterministic nearest source XY
  * coordinate per snapped node. This targets Shapely-style `snap` followed by full-precision
  * noding and polygonization; it does not emulate `set_precision` output.
  *

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

@@ -0,0 +1,8 @@
+import type { ZPolicy } from "./ZPolicy";
+export type ZOptions = {
+    policy: ZPolicy;
+    /**
+     * Z values at one XY node conflict when their difference exceeds this value.
+     */
+    conflict_tolerance: number;
+};

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

@@ -0,0 +1 @@
+export type ZPolicy = "Ignore" | "InterpolateAlongEdge" | "PreferNearestEndpoint" | "ErrorOnConflict";

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

@@ -13,5 +13,7 @@ export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";
 export * from "./bindings/TouchPolicy";
+export * from "./bindings/ZOptions";
+export * from "./bindings/ZPolicy";
 export * from "./cfb";
 export default function init(_input?: any): Promise<typeof exports>;

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

@@ -13,5 +13,7 @@ export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";
 export * from "./bindings/TouchPolicy";
+export * from "./bindings/ZOptions";
+export * from "./bindings/ZPolicy";
 export * from "./cfb";
 export declare function initBest(scalarModule: any, simdModule?: any): Promise<typeof scalarExports>;

package/dist/slim/es/index_slim.js

@@ -972,6 +972,10 @@ const cfbRobustOptions = {
         enabled: true,
         include_boundary_line_ids: true,
     },
+    z: {
+        policy: "InterpolateAlongEdge",
+        conflict_tolerance: 0,
+    },
     output_filter: {
         minimum_face_area: undefined,
     },

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

@@ -13,5 +13,7 @@ export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";
 export * from "./bindings/TouchPolicy";
+export * from "./bindings/ZOptions";
+export * from "./bindings/ZPolicy";
 export * from "./cfb";
 export default init;

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

@@ -6,6 +6,7 @@ import type { OutputFilterOptions } from "./OutputFilterOptions";
 import type { PrecisionModel } from "./PrecisionModel";
 import type { ProvenanceOptions } from "./ProvenanceOptions";
 import type { SnapStrategy } from "./SnapStrategy";
+import type { ZOptions } from "./ZOptions";
 /**
  * The canonical configuration object for the `geo-polygonize` engine.
  *
@@ -77,6 +78,10 @@ export type PolygonizerOptions = {
      * Options for mapping final faces back to original input geometry IDs.
      */
     provenance: ProvenanceOptions;
+    /**
+     * Controls Z reconstruction and same-XY conflict handling.
+     */
+    z: ZOptions;
     /**
      * Optional application-level filtering applied after topology is established.
      */

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

@@ -2,7 +2,7 @@
  * Strategy for robust snap noding and output coordinates.
  *
  * `Grid` uses the precision grid for both topology and output coordinates.
- * `GeosCompat` uses the grid for topology, then restores one deterministic nearest source
+ * `GeosCompat` uses the grid for topology, then restores one deterministic nearest source XY
  * coordinate per snapped node. This targets Shapely-style `snap` followed by full-precision
  * noding and polygonization; it does not emulate `set_precision` output.
  *

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

@@ -0,0 +1,8 @@
+import type { ZPolicy } from "./ZPolicy";
+export type ZOptions = {
+    policy: ZPolicy;
+    /**
+     * Z values at one XY node conflict when their difference exceeds this value.
+     */
+    conflict_tolerance: number;
+};

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

@@ -0,0 +1 @@
+export type ZPolicy = "Ignore" | "InterpolateAlongEdge" | "PreferNearestEndpoint" | "ErrorOnConflict";

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

@@ -6,6 +6,7 @@ import type { OutputFilterOptions } from "./OutputFilterOptions";
 import type { PrecisionModel } from "./PrecisionModel";
 import type { ProvenanceOptions } from "./ProvenanceOptions";
 import type { SnapStrategy } from "./SnapStrategy";
+import type { ZOptions } from "./ZOptions";
 /**
  * The canonical configuration object for the `geo-polygonize` engine.
  *
@@ -77,6 +78,10 @@ export type PolygonizerOptions = {
      * Options for mapping final faces back to original input geometry IDs.
      */
     provenance: ProvenanceOptions;
+    /**
+     * Controls Z reconstruction and same-XY conflict handling.
+     */
+    z: ZOptions;
     /**
      * Optional application-level filtering applied after topology is established.
      */

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

@@ -2,7 +2,7 @@
  * Strategy for robust snap noding and output coordinates.
  *
  * `Grid` uses the precision grid for both topology and output coordinates.
- * `GeosCompat` uses the grid for topology, then restores one deterministic nearest source
+ * `GeosCompat` uses the grid for topology, then restores one deterministic nearest source XY
  * coordinate per snapped node. This targets Shapely-style `snap` followed by full-precision
  * noding and polygonization; it does not emulate `set_precision` output.
  *

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

@@ -0,0 +1,8 @@
+import type { ZPolicy } from "./ZPolicy";
+export type ZOptions = {
+    policy: ZPolicy;
+    /**
+     * Z values at one XY node conflict when their difference exceeds this value.
+     */
+    conflict_tolerance: number;
+};

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

@@ -0,0 +1 @@
+export type ZPolicy = "Ignore" | "InterpolateAlongEdge" | "PreferNearestEndpoint" | "ErrorOnConflict";

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

@@ -13,5 +13,7 @@ export * from "./bindings/ProvenanceOptions";
 export * from "./bindings/SnapStrategy";
 export * from "./bindings/TileOwnershipPolicy";
 export * from "./bindings/TouchPolicy";
+export * from "./bindings/ZOptions";
+export * from "./bindings/ZPolicy";
 export * from "./cfb";
 export default function init(_input?: any): Promise<typeof exports>;