geo-polygonize 0.34.0 → 0.35.0

package/README.md

@@ -88,11 +88,15 @@ use geo_polygonize_core::arrow_api::{polygonize_arrow, PolygonizerOptions};
 
 ### Python
 
-The library provides native Python bindings via PyO3, packaged as `geo-polygonize`.
+The Python package is published as `geo-polygonize-py` and imported as `geo_polygonize`.
+
+```bash
+pip install geo-polygonize-py
+```
 
 ```python
 import numpy as np
-from geo_polygonize import polygonize
+from geo_polygonize import polygonize, import_probe
 
 # 1. Using Shapely LineStrings or coordinate lists directly
 lines = [
@@ -116,8 +120,54 @@ coords = np.array([
 # The final closing offset is computed implicitly.
 offsets = np.array([0, 5], dtype=np.uint32)
 
-# Returns a dictionary with 'flat_coords', 'ring_offsets', 'polygon_offsets', etc.
+# Returns a stable dictionary with 'polygons', diagnostics, and provenance.
 result_dict = polygonize(coords=coords, offsets=offsets)
+
+# Native-extension probes are cheap and safe for optional integrations.
+ok, error = import_probe()
+```
+
+CFB/autograder integrations should use the versioned production profile rather
+than assembling caller-side knobs or using legacy `polygonize(..., node=True,
+snap=0.5)` calls:
+
+```python
+from geo_polygonize import cfb_robust_options, polygonize_with_options
+
+result = polygonize_with_options(
+    coords=coords,
+    offsets=offsets,
+    options=cfb_robust_options(),
+)
+```
+
+The default return shape is a stable dictionary with `polygons` as
+`SimplePolygon` values. Use `return_polygons=True` only when you want Shapely
+`Polygon` objects.
+
+For Shapely parity checks, compare report-mode outputs with the built-in
+mismatch helper:
+
+```python
+from geo_polygonize import explain_mismatch, polygonize_with_options
+
+options = cfb_robust_options()
+result_a = polygonize_with_options(coords=coords_a, offsets=offsets_a, options=options)
+result_b = polygonize_with_options(coords=coords_b, offsets=offsets_b, options=options)
+result_a["options"] = options
+result_b["options"] = options
+
+mismatch = explain_mismatch(result_a, result_b)
+```
+
+For a minimal Shapely smoke comparison, use area signatures:
+
+```python
+from shapely.ops import polygonize as shapely_polygonize
+
+rust_polys = polygonize_with_options(lines=lines, options=cfb_robust_options(), return_polygons=True)
+rust_areas = sorted(round(poly.area, 6) for poly in rust_polys)
+shapely_areas = sorted(round(poly.area, 6) for poly in shapely_polygonize(lines))
 ```
 
 ### WebAssembly (WASM)
@@ -129,8 +179,8 @@ This library supports WebAssembly with an ergonomic dual-build configuration tha
 npm install geo-polygonize
 ```
 
-**Standard Usage (Bundlers / Browser):**
-The default entry point automatically handles feature detection (SIMD) and lazy-loading of the Wasm binary. The Wasm is inlined as a Base64 Data URI, so no extra bundler configuration is needed.
+**Standard Usage (Quick Demos):**
+The default entry point automatically handles feature detection (SIMD) and lazy-loading of the Wasm binary. The Wasm is inlined as a Base64 Data URI, so no extra bundler configuration is needed. For app builds, prefer the slim entry point below so your bundler keeps the Wasm assets out of the JavaScript chunk.
 
 ```javascript
 import init, { polygonize, polygonize_geoarrow } from "geo-polygonize";
@@ -160,24 +210,24 @@ async function run() {
 }
 ```
 
-**Slim Usage (Manual Loading):**
-If you prefer to manage the Wasm binary yourself (e.g., to reduce bundle size or load from a CDN), import from `geo-polygonize/slim`.
+**Slim Usage (Apps / Manual Loading):**
+For Vite and other app bundlers, import from `geo-polygonize/slim` and pass explicit Wasm asset URLs.
 
 ```javascript
-import { initBest, polygonize } from "geo-polygonize/slim";
+import { cfbRobustOptions, initBest } from "geo-polygonize/slim";
+import scalarUrl from "geo-polygonize/geo_polygonize.wasm?url";
+import simdUrl from "geo-polygonize/geo_polygonize_simd.wasm?url";
 
 async function run() {
-    // You must provide the compiled WebAssembly.Module or URL
-    // You can choose to load the SIMD or Scalar version based on your own detection or availability
-    const response = await fetch("geo_polygonize.wasm");
-    const buffer = await response.arrayBuffer();
-    const module = await WebAssembly.compile(buffer);
-
-    // Helper to initialize the best available implementation
-    // Pass the module to both arguments if you only have one version
-    await initBest(module, module);
+    const wasm = await initBest(
+        { module_or_path: scalarUrl },
+        { module_or_path: simdUrl },
+    );
 
-    // ... use polygonize
+    const result = wasm.polygonizeWithOptions(
+        JSON.stringify(geojson),
+        cfbRobustOptions,
+    );
 }
 ```
 

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

@@ -17,4 +17,4 @@ 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>;
+export declare function initBest(scalarModule: any, simdModule?: any): Promise<typeof scalarExports>;