smoothify 0.2.3__tar.gz → 0.3.1__tar.gz

{smoothify-0.2.3 → smoothify-0.3.1}/.gitignore

@@ -184,3 +184,6 @@ smoothify/_version.py
 
 # uv lockfile (not tracked — library, resolve fresh)
 uv.lock
+
+# Benchmarks
+benchmarks/baseline_output.gpkg

{smoothify-0.2.3 → smoothify-0.3.1}/.vscode/settings.json

@@ -12,6 +12,7 @@
         "geodataframe",
         "geopandas",
         "gpkg",
+        "hausdorffs",
         "ipykernel",
         "joblib",
         "lightgreen",

smoothify-0.3.1/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.3.1] - 2026-06-15
+
+### Fixed
+- Fixed an `AssertionError` crash (`Resulting geometry must be Polygon or LineString. Got <GeometryCollection>`) when smoothing certain valid thin/staircase polygons only a few `segment_length`s across. A rotated start-point variant could self-intersect after simplify + Chaikin where it rounds a neck about one `segment_length` wide; `make_valid()` then repaired that variant into a polygon *plus* a zero-area line filament at the pinch, and `unary_union` kept the 1-D debris, so the variant union became a `GeometryCollection` the rest of the pipeline could not handle. Zero-area debris is now stripped from each repaired variant before the union, so the result stays a clean, valid `Polygon`.
+- Improved the sharp-concave-fold repair (introduced in 0.3.0) for thin features that shed significant area during smoothing. The closing (dilate-erode) seal now operates on the area-preserved result and restores area again afterwards, instead of sealing the area-deficient pre-buffer variant union — which the area-preservation buffer could then re-expand into the same cusp. This reduces residual folds on narrow arms.
+
+## [0.3.0] - 2026-06-12
+
+### Changed
+- Single-core smoothing is ~3.5x faster on typical raster-derived data (benchmarked on `examples/Water.gpkg`: 6.8s → 1.9s, including the cost of the new fold-repair check below). Output differences are sub-pixel (bounded by the algorithm's own start-point noise floor); area preservation accuracy is unchanged or slightly better. The main changes:
+  - Removed the reversed-direction smoothing variants for polygons: Chaikin corner cutting is direction-invariant on closed rings, so they duplicated the forward variants bit-for-bit and only inflated the variant union (output unchanged).
+  - Holes are now subtracted in a single `difference` call against their union instead of one `intersection` + `difference` pair per hole (output unchanged).
+  - The tiny merge/dissolve buffer now uses mitre joins, which keep corners as single vertices instead of adding ~8 arc vertices per corner (boundary differences at the millimetre scale of the buffer itself).
+  - Pre-union Chaikin smoothing of the start-point variants is capped at 2 iterations; detail beyond that was erased by the post-union simplify anyway, while doubling the vertex count entering the expensive union. The final smoothing pass still runs the full `smooth_iterations`.
+  - The area-preservation root finder brackets the root from one side using its linear estimate, caches evaluations, and uses a step tolerance derived from the area tolerance via the perimeter, roughly halving the number of buffer operations.
+  - Congruent geometries (translated copies of the same shape, common in raster-derived data) are now smoothed once and the result translated to each occurrence; this also reduces work dispatched to parallel workers.
+
+### Added
+- New `merge_holes` option (default `True`): holes that touch or nearly touch (e.g. diagonally adjacent raster cells) are joined before smoothing, so they smooth into one coherent opening instead of separate overlapping shapes leaving a fake land bridge. Pass `merge_holes=False` for the previous per-hole behaviour. Mirrors what `merge_multipolygons` does for shells.
+- `examples/merge_holes_examples.ipynb`: worked examples of `merge_holes` and its interplay with `merge_collection` (touching holes, overlapping donuts, holes split across features).
+- `benchmarks/bench_water.py`: single-core timing/profiling benchmark with baseline output comparison.
+
+### Fixed
+- Fixed sharp concave folds in smoothed output on shapes with features about one `segment_length` wide (e.g. a hole with a one-pixel-wide arm, as produced by `merge_holes` joining a small hole to a larger one). The start-point smoothing variants can disagree about such features, leaving a forked slit in their union that the area-preservation shrink sharpens into a cusp. The final result is now checked for sharp concave turns and, when one is found, recomputed from the variant union sealed with a small closing (dilate-erode at `segment_length / 4`).
+- Fixed sharp cusps where a smoothed hole crosses the independently smoothed exterior and gets clipped by the hole subtraction (previously up to a 180-degree fold at the tangential crossing points). When detected, the result is repaired with a small opening + closing (at `segment_length / 4`), which removes hair-thin material needles and seals thin slits without visibly moving the boundary.
+- Fixed shapes with long straight edges being massively over-rounded (e.g. a large square with a small `segment_length` collapsed into a circle). The simplify steps strip all collinear vertices from straight edges, and Chaikin's corner cuts scale with segment length, so corner rounding grew with edge length instead of `segment_length`. Geometries are now re-segmentized after each simplify step, capping corner rounding at roughly `segment_length` while still smoothing raster staircase artifacts into curves. Applies to all geometry types. Note: outputs are somewhat denser (more vertices) and smoothing is ~20% slower on typical raster-derived data.
+
+## [0.2.3] - 2026-06-02
+
+### Added
+- The package now ships inline type hints and a `py.typed` marker, so type checkers (mypy, Pyright/Pylance) pick up `smoothify()`'s signatures and overloads in downstream code.
+
+### Changed
+- Invalid geometries (e.g. self-intersecting polygons) are now returned unchanged with a warning instead of crashing with a cryptic error or silently collapsing to an empty geometry. Behaviour is consistent across single geometries, lists/collections, and GeoDataFrames (and regardless of `merge_collection`). Repair them with shapely's `make_valid()` first if you want them smoothed.
+
+## [0.2.2] - 2026-03-24
+
+### Fixed
+- Fixed LineString smoothing: self-intersecting lines are no longer run through the polygon-only `make_valid`/`unary_union` step, which could split them into a MultiLineString at crossing points
+- Preserve coordinate dimensionality during Chaikin corner cutting instead of forcing 2D output, so smoothed geometries keep their original dimensions
+
+## [0.2.1] - 2026-02-25
+
+### Fixed
+- Fixed `TopologyException` crash on thin/elongated polygons by validating smoothed variants before union
+- Fixed crash when hole subtraction splits a polygon into a MultiPolygon (e.g. tiny holes relative to segment length)
+
+## [0.2.0] - 2026-02-25
+
+### Fixed
+- `smooth_iterations=0` now returns the original input unchanged instead of running the geometry through segmentize/simplify pipeline without smoothing
+
+## [0.1.0] - 2025-11-25
+
+### Added
+- Initial public release
+- Core smoothing functionality using Chaikin's corner-cutting algorithm
+- Support for all Shapely geometry types (Polygon, LineString, MultiPolygon, etc.)
+- Automatic segment length detection
+- Parallel processing support
+- Area preservation for polygons

{smoothify-0.2.3 → smoothify-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smoothify
-Version: 0.2.3
+Version: 0.3.1
 Summary: Transform pixelated geometries from raster data into smooth natural looking features
 Author-email: Nick Wright <nicholas.wright@dpird.wa.gov.au>
 License-Expression: MIT
@@ -61,7 +61,7 @@ Polygons and lines derived from classified raster data (e.g., ML model predictio
 Smoothify applies an optimized implementation of Chaikin's corner-cutting algorithm along with other geometric processing to create smooth, natural-looking features while:
 
 - Preserving the general shape and area of polygons
-- Supporting all shapley geometry types
+- Supporting all shapely geometry types
 - Handling shapes with interior holes
 - Efficiently processing large datasets with multiprocessing
 
@@ -118,6 +118,7 @@ Example notebooks:
 - [Usage examples](https://github.com/DPIRD-DMA/Smoothify/blob/main/examples/usage_examples.ipynb)
 - [Smoothify vs. Shapely comparison](https://github.com/DPIRD-DMA/Smoothify/blob/main/examples/smoothify_vs_shapely_comparison.ipynb)
 - [Real-world water example](https://github.com/DPIRD-DMA/Smoothify/blob/main/examples/real_world_water_example.ipynb)
+- [Merging holes](https://github.com/DPIRD-DMA/Smoothify/blob/main/examples/merge_holes_examples.ipynb)
 
 
 ### Basic Polygon Smoothing
@@ -222,6 +223,7 @@ smoothed = smoothify(
 | `merge_collection` | bool | True | Whether to merge/dissolve adjacent geometries in collections before smoothing |
 | `merge_field` | str | None | **GeoDataFrame only**: Column name to use for dissolving geometries. Only valid when `merge_collection=True`. If None, dissolves all geometries together. If specified, dissolves geometries grouped by the column values |
 | `merge_multipolygons` | bool | True | Whether to merge adjacent polygons within MultiPolygons before smoothing |
+| `merge_holes` | bool | True | Whether to join holes that touch or nearly touch (e.g. diagonally adjacent raster cells) before smoothing, so they smooth into one coherent opening instead of separate overlapping shapes |
 | `preserve_area` | bool | True | Whether to restore original area after smoothing via buffering (applies to Polygons only) |
 | `area_tolerance` | float | 0.01 | Percentage of original area allowed as error (e.g., 0.01 = 0.01% error = 99.99% preservation). Only affects Polygons when preserve_area=True |
 
@@ -229,14 +231,20 @@ smoothed = smoothify(
 
 Smoothify uses an advanced multi-step smoothing pipeline:
 
+<p align="left">
+  <img src="https://raw.githubusercontent.com/DPIRD-DMA/Smoothify/main/images/pipeline_steps.png" alt="Smoothify pipeline steps" width="800">
+</p>
+
 
-1. Adds intermediate vertices along line segments (segmentize)
-2. Generates multiple rotated variants (for Polygons) to avoid artifacts
-3. Simplifies each variant to remove noise
-4. Applies Chaikin corner cutting to smooth
-5. Merges all variants via union to eliminate start-point artifacts
-6. Applies final smoothing pass
-7. Optionally restores original area via buffering (for Polygons)
+1. Joins touching holes (for Polygons, when `merge_holes=True`) so they smooth as one opening
+2. Adds intermediate vertices along line segments (segmentize)
+3. Generates multiple rotated variants (for Polygons) to avoid artifacts
+4. Simplifies each variant to remove noise
+5. Applies Chaikin corner cutting to smooth
+6. Merges all variants via union to eliminate start-point artifacts
+7. Applies final smoothing pass
+8. Optionally restores original area via buffering (for Polygons)
+9. Detects and repairs any sharp folds left by features near the smoothing scale (e.g. one-pixel-wide arms), using a small morphological opening/closing bounded at `segment_length / 4`
 
 ## Invalid Geometries
 
@@ -257,9 +265,10 @@ smoothed = smoothify(make_valid(polygon), segment_length=1.0)
 ## Performance Considerations
 
 - **Parallel Processing**: For large GeoDataFrames or collections, use `num_cores` = 0 to enable parallel processing
+- **Duplicate Shapes**: Geometries that are translated copies of the same shape (common in raster-derived data, e.g. single-pixel polygons) are automatically smoothed once and the result reused
 - **Smoothing Iterations**: Values of 3-5 typically provide good results. Higher values create smoother output but increase processing time and vertex count
 - **Memory Usage**: Scales with geometry complexity. The algorithm creates multiple variants during smoothing
-- **Optimal segment_length**: Should match the original raster cell size (pixel size) or be slightly larger for best results
+- **Optimal segment_length**: Anything from about half the original raster pixel size and up should produce reasonable output — larger values produce more rounded output, smaller values stay more faithful to the original geometry
 
 ## Running the Tests
 

{smoothify-0.2.3 → smoothify-0.3.1}/README.md

@@ -28,7 +28,7 @@ Polygons and lines derived from classified raster data (e.g., ML model predictio
 Smoothify applies an optimized implementation of Chaikin's corner-cutting algorithm along with other geometric processing to create smooth, natural-looking features while:
 
 - Preserving the general shape and area of polygons
-- Supporting all shapley geometry types
+- Supporting all shapely geometry types
 - Handling shapes with interior holes
 - Efficiently processing large datasets with multiprocessing
 
@@ -85,6 +85,7 @@ Example notebooks:
 - [Usage examples](https://github.com/DPIRD-DMA/Smoothify/blob/main/examples/usage_examples.ipynb)
 - [Smoothify vs. Shapely comparison](https://github.com/DPIRD-DMA/Smoothify/blob/main/examples/smoothify_vs_shapely_comparison.ipynb)
 - [Real-world water example](https://github.com/DPIRD-DMA/Smoothify/blob/main/examples/real_world_water_example.ipynb)
+- [Merging holes](https://github.com/DPIRD-DMA/Smoothify/blob/main/examples/merge_holes_examples.ipynb)
 
 
 ### Basic Polygon Smoothing
@@ -189,6 +190,7 @@ smoothed = smoothify(
 | `merge_collection` | bool | True | Whether to merge/dissolve adjacent geometries in collections before smoothing |
 | `merge_field` | str | None | **GeoDataFrame only**: Column name to use for dissolving geometries. Only valid when `merge_collection=True`. If None, dissolves all geometries together. If specified, dissolves geometries grouped by the column values |
 | `merge_multipolygons` | bool | True | Whether to merge adjacent polygons within MultiPolygons before smoothing |
+| `merge_holes` | bool | True | Whether to join holes that touch or nearly touch (e.g. diagonally adjacent raster cells) before smoothing, so they smooth into one coherent opening instead of separate overlapping shapes |
 | `preserve_area` | bool | True | Whether to restore original area after smoothing via buffering (applies to Polygons only) |
 | `area_tolerance` | float | 0.01 | Percentage of original area allowed as error (e.g., 0.01 = 0.01% error = 99.99% preservation). Only affects Polygons when preserve_area=True |
 
@@ -196,14 +198,20 @@ smoothed = smoothify(
 
 Smoothify uses an advanced multi-step smoothing pipeline:
 
+<p align="left">
+  <img src="https://raw.githubusercontent.com/DPIRD-DMA/Smoothify/main/images/pipeline_steps.png" alt="Smoothify pipeline steps" width="800">
+</p>
+
 
-1. Adds intermediate vertices along line segments (segmentize)
-2. Generates multiple rotated variants (for Polygons) to avoid artifacts
-3. Simplifies each variant to remove noise
-4. Applies Chaikin corner cutting to smooth
-5. Merges all variants via union to eliminate start-point artifacts
-6. Applies final smoothing pass
-7. Optionally restores original area via buffering (for Polygons)
+1. Joins touching holes (for Polygons, when `merge_holes=True`) so they smooth as one opening
+2. Adds intermediate vertices along line segments (segmentize)
+3. Generates multiple rotated variants (for Polygons) to avoid artifacts
+4. Simplifies each variant to remove noise
+5. Applies Chaikin corner cutting to smooth
+6. Merges all variants via union to eliminate start-point artifacts
+7. Applies final smoothing pass
+8. Optionally restores original area via buffering (for Polygons)
+9. Detects and repairs any sharp folds left by features near the smoothing scale (e.g. one-pixel-wide arms), using a small morphological opening/closing bounded at `segment_length / 4`
 
 ## Invalid Geometries
 
@@ -224,9 +232,10 @@ smoothed = smoothify(make_valid(polygon), segment_length=1.0)
 ## Performance Considerations
 
 - **Parallel Processing**: For large GeoDataFrames or collections, use `num_cores` = 0 to enable parallel processing
+- **Duplicate Shapes**: Geometries that are translated copies of the same shape (common in raster-derived data, e.g. single-pixel polygons) are automatically smoothed once and the result reused
 - **Smoothing Iterations**: Values of 3-5 typically provide good results. Higher values create smoother output but increase processing time and vertex count
 - **Memory Usage**: Scales with geometry complexity. The algorithm creates multiple variants during smoothing
-- **Optimal segment_length**: Should match the original raster cell size (pixel size) or be slightly larger for best results
+- **Optimal segment_length**: Anything from about half the original raster pixel size and up should produce reasonable output — larger values produce more rounded output, smaller values stay more faithful to the original geometry
 
 ## Running the Tests
 

smoothify-0.3.1/benchmarks/bench_water.py

@@ -0,0 +1,93 @@
+"""Benchmark smoothify on examples/Water.gpkg (single core).
+
+Usage:
+    python benchmarks/bench_water.py                  # time it
+    python benchmarks/bench_water.py --profile        # cProfile, print top hotspots
+    python benchmarks/bench_water.py --save-baseline  # save output for comparison
+    python benchmarks/bench_water.py --compare        # compare output to baseline
+"""
+
+import argparse
+import cProfile
+import pstats
+import time
+from pathlib import Path
+
+import geopandas as gpd
+import numpy as np
+import shapely
+
+from smoothify import smoothify
+
+ROOT = Path(__file__).resolve().parent.parent
+DATA = ROOT / "examples" / "Water.gpkg"
+BASELINE = ROOT / "benchmarks" / "baseline_output.gpkg"
+
+
+def run(gdf: gpd.GeoDataFrame) -> gpd.GeoDataFrame:
+    return smoothify(gdf, num_cores=1)
+
+
+def quality_report(result: gpd.GeoDataFrame, baseline: gpd.GeoDataFrame) -> None:
+    """Compare result to baseline: per-feature symmetric difference / hausdorff."""
+    if len(result) != len(baseline):
+        print(f"FEATURE COUNT DIFFERS: {len(result)} vs baseline {len(baseline)}")
+        return
+    sym_ratios = []
+    hausdorffs = []
+    for g_new, g_old in zip(result.geometry, baseline.geometry, strict=True):
+        if g_old.is_empty and g_new.is_empty:
+            continue
+        denom = g_old.area if g_old.area > 0 else 1.0
+        sym_ratios.append(g_new.symmetric_difference(g_old).area / denom)
+        hausdorffs.append(g_new.hausdorff_distance(g_old))
+    sym = np.array(sym_ratios)
+    hd = np.array(hausdorffs)
+    print(f"identical features:        {(sym == 0).sum()}/{len(sym)}")
+    print(f"sym-diff area ratio  mean: {sym.mean():.2e}  max: {sym.max():.2e}")
+    print(f"hausdorff dist (m)   mean: {hd.mean():.3f}  max: {hd.max():.3f}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--profile", action="store_true")
+    parser.add_argument("--save-baseline", action="store_true")
+    parser.add_argument("--compare", action="store_true")
+    parser.add_argument("--repeat", type=int, default=1)
+    parser.add_argument("--limit", type=int, default=0, help="only first N features")
+    args = parser.parse_args()
+
+    gdf = gpd.read_file(DATA)
+    if args.limit:
+        gdf = gdf.head(args.limit).copy()
+    nverts = shapely.get_num_coordinates(gdf.geometry.values).sum()
+    print(f"{len(gdf)} features, {nverts} vertices")
+
+    if args.profile:
+        profiler = cProfile.Profile()
+        profiler.enable()
+        result = run(gdf)
+        profiler.disable()
+        stats = pstats.Stats(profiler)
+        stats.sort_stats("cumulative").print_stats(30)
+        stats.sort_stats("tottime").print_stats(30)
+    else:
+        times = []
+        result = None
+        for _ in range(args.repeat):
+            t0 = time.perf_counter()
+            result = run(gdf)
+            times.append(time.perf_counter() - t0)
+        print(f"time: best {min(times):.2f}s  " + " ".join(f"{t:.2f}" for t in times))
+
+    assert result is not None
+    if args.save_baseline:
+        result.to_file(BASELINE, driver="GPKG")
+        print(f"baseline saved to {BASELINE}")
+    elif args.compare:
+        baseline = gpd.read_file(BASELINE)
+        quality_report(result, baseline)
+
+
+if __name__ == "__main__":
+    main()