geo-polygonize 0.2.1 → 0.6.2

package/README.md

@@ -14,6 +14,10 @@ A native Rust port of the JTS/GEOS polygonization algorithm. This crate allows y
 - **Geo Ecosystem**: Fully integrated with `geo-types` and `geo` crates.
 - **GeoArrow Support**: Zero-copy data transfer via Arrow C Data Interface and Arrow IPC (Wasm).
 
+## Engineering Roadmap
+
+For an ambitious, prioritized plan covering performance, security, API consistency, and maintainability, see [docs/roadmap.md](docs/roadmap.md).
+
 ## Usage
 
 ### Library
@@ -46,6 +50,32 @@ fn main() {
 }
 ```
 
+### Choosing `node_input` and `snap_grid_size`
+
+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.
+- **`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.
+  - Avoid very large values unless your coordinate units are coarse; oversnapping can collapse narrow features.
+
+Practical workflow:
+1. Run with `node_input = false` first on trusted data.
+2. If you observe missing polygons, sliver artifacts, or unresolved intersections, enable `node_input`.
+3. Tune `snap_grid_size` upward incrementally until topology stabilizes.
+
+### Output semantics
+
+The polygonizer intentionally returns only valid polygonal areas that can be formed from closed cycles:
+
+- **Dangles are removed**: dead-end edges do not appear in output polygons.
+- **Cut edges are excluded**: edges that are connected but cannot bound a face are ignored.
+- **Holes and nested shells are preserved** when enough boundary information is present.
+
+This behavior matches classical JTS/GEOS polygonization semantics and is useful for cleaning linework before area analysis.
+
 ### GeoArrow Integration
 
 The library supports ingesting data directly from Arrow arrays via the `arrow_api` module and `ffi`.
@@ -116,7 +146,12 @@ async function run() {
     };
 
     // Returns a GeoJSON FeatureCollection string
-    const result = polygonize(JSON.stringify(geojson));
+    // Pass explicitly matching backend configuration if desired
+    const result = polygonize(
+        JSON.stringify(geojson),
+        true, // node_input
+        0.5   // snap_grid_size
+    );
     console.log(JSON.parse(result));
 
     // Or use Arrow IPC bytes

package/dist/slim/cjs/index_slim.js

@@ -45,6 +45,10 @@ function getUint8ArrayMemory0$1() {
     return cachedUint8ArrayMemory0$1;
 }
 
+function isLikeNone$1(x) {
+    return x === undefined || x === null;
+}
+
 function passArray32ToWasm0$1(arg, malloc) {
     const ptr = malloc(arg.length * 4, 4) >>> 0;
     getUint32ArrayMemory0$1().set(arg, ptr / 4);
@@ -214,15 +218,18 @@ if (Symbol.dispose) WasmPolygonResult$1.prototype[Symbol.dispose] = WasmPolygonR
 
 /**
  * @param {string} geojson_str
+ * @param {boolean | null} [node_input]
+ * @param {number | null} [snap_grid_size]
+ * @param {boolean | null} [extract_only_polygonal]
  * @returns {string}
  */
-function polygonize$1(geojson_str) {
+function polygonize$1(geojson_str, node_input, snap_grid_size, extract_only_polygonal) {
     let deferred3_0;
     let deferred3_1;
     try {
         const ptr0 = passStringToWasm0$1(geojson_str, wasm$1.__wbindgen_malloc, wasm$1.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN$1;
-        const ret = wasm$1.polygonize(ptr0, len0);
+        const ret = wasm$1.polygonize(ptr0, len0, isLikeNone$1(node_input) ? 0xFFFFFF : node_input ? 1 : 0, !isLikeNone$1(snap_grid_size), isLikeNone$1(snap_grid_size) ? 0 : snap_grid_size, isLikeNone$1(extract_only_polygonal) ? 0xFFFFFF : extract_only_polygonal ? 1 : 0);
         var ptr2 = ret[0];
         var len2 = ret[1];
         if (ret[3]) {
@@ -467,6 +474,10 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 function passArray32ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 4, 4) >>> 0;
     getUint32ArrayMemory0().set(arg, ptr / 4);
@@ -636,15 +647,18 @@ if (Symbol.dispose) WasmPolygonResult.prototype[Symbol.dispose] = WasmPolygonRes
 
 /**
  * @param {string} geojson_str
+ * @param {boolean | null} [node_input]
+ * @param {number | null} [snap_grid_size]
+ * @param {boolean | null} [extract_only_polygonal]
  * @returns {string}
  */
-function polygonize(geojson_str) {
+function polygonize(geojson_str, node_input, snap_grid_size, extract_only_polygonal) {
     let deferred3_0;
     let deferred3_1;
     try {
         const ptr0 = passStringToWasm0(geojson_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.polygonize(ptr0, len0);
+        const ret = wasm.polygonize(ptr0, len0, isLikeNone(node_input) ? 0xFFFFFF : node_input ? 1 : 0, !isLikeNone(snap_grid_size), isLikeNone(snap_grid_size) ? 0 : snap_grid_size, isLikeNone(extract_only_polygonal) ? 0xFFFFFF : extract_only_polygonal ? 1 : 0);
         var ptr2 = ret[0];
         var len2 = ret[1];
         if (ret[3]) {

package/dist/slim/es/index_slim.js

@@ -42,6 +42,10 @@ function getUint8ArrayMemory0$1() {
     return cachedUint8ArrayMemory0$1;
 }
 
+function isLikeNone$1(x) {
+    return x === undefined || x === null;
+}
+
 function passArray32ToWasm0$1(arg, malloc) {
     const ptr = malloc(arg.length * 4, 4) >>> 0;
     getUint32ArrayMemory0$1().set(arg, ptr / 4);
@@ -211,15 +215,18 @@ if (Symbol.dispose) WasmPolygonResult$1.prototype[Symbol.dispose] = WasmPolygonR
 
 /**
  * @param {string} geojson_str
+ * @param {boolean | null} [node_input]
+ * @param {number | null} [snap_grid_size]
+ * @param {boolean | null} [extract_only_polygonal]
  * @returns {string}
  */
-function polygonize$1(geojson_str) {
+function polygonize$1(geojson_str, node_input, snap_grid_size, extract_only_polygonal) {
     let deferred3_0;
     let deferred3_1;
     try {
         const ptr0 = passStringToWasm0$1(geojson_str, wasm$1.__wbindgen_malloc, wasm$1.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN$1;
-        const ret = wasm$1.polygonize(ptr0, len0);
+        const ret = wasm$1.polygonize(ptr0, len0, isLikeNone$1(node_input) ? 0xFFFFFF : node_input ? 1 : 0, !isLikeNone$1(snap_grid_size), isLikeNone$1(snap_grid_size) ? 0 : snap_grid_size, isLikeNone$1(extract_only_polygonal) ? 0xFFFFFF : extract_only_polygonal ? 1 : 0);
         var ptr2 = ret[0];
         var len2 = ret[1];
         if (ret[3]) {
@@ -464,6 +471,10 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 function passArray32ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 4, 4) >>> 0;
     getUint32ArrayMemory0().set(arg, ptr / 4);
@@ -633,15 +644,18 @@ if (Symbol.dispose) WasmPolygonResult.prototype[Symbol.dispose] = WasmPolygonRes
 
 /**
  * @param {string} geojson_str
+ * @param {boolean | null} [node_input]
+ * @param {number | null} [snap_grid_size]
+ * @param {boolean | null} [extract_only_polygonal]
  * @returns {string}
  */
-function polygonize(geojson_str) {
+function polygonize(geojson_str, node_input, snap_grid_size, extract_only_polygonal) {
     let deferred3_0;
     let deferred3_1;
     try {
         const ptr0 = passStringToWasm0(geojson_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.polygonize(ptr0, len0);
+        const ret = wasm.polygonize(ptr0, len0, isLikeNone(node_input) ? 0xFFFFFF : node_input ? 1 : 0, !isLikeNone(snap_grid_size), isLikeNone(snap_grid_size) ? 0 : snap_grid_size, isLikeNone(extract_only_polygonal) ? 0xFFFFFF : extract_only_polygonal ? 1 : 0);
         var ptr2 = ret[0];
         var len2 = ret[1];
         if (ret[3]) {