concavewrap-geo

Build auditable concave hulls that cover complete polygon areas.

Many concave-hull implementations guarantee that the output contains the input vertices. For areal data that is not enough: a hull edge can cut through a source polygon. concavewrap repairs or rejects invalid input, constructs the hull, and then enforces and verifies coverage of every source polygon.

Quick start

python -m pip install concavewrap-geo
concavewrap build areas.gpkg \
  --layer areas \
  --ratio 0.25 \
  --output hulls.gpkg \
  --diagnostics hulls.json

The output is a GeoPackage layer named hulls. The JSON report records input and output areas, added fill area, the convex-hull area, coverage checks, repaired features, and any convex fallback.

Reproducible example

Generate and process four synthetic polygon arrangements, including the failure modes that commonly make a single concave-hull setting misleading:

python examples/run_examples.py

Generated inputs, outputs, and JSON reports are placed under examples/generated/. To run the standard case through the CLI:

concavewrap build examples/generated/forest-patches.gpkg \
  --layer areas \
  --ratio 0.25 \
  --output examples/generated/forest-hull-cli.gpkg \
  --diagnostics examples/generated/forest-hull-cli.json

Expected audit values are printed and asserted by the script, then saved in summary.json. No external or real-world data is used.

Ratio and policies

--ratio follows GEOS/Shapely semantics:

The ratio is dimensionless. It is not an alpha radius or a distance threshold, so values from alpha-shape tools cannot be copied directly.

Guarantees

For every output record, concavewrap verifies that:

• the result is valid polygonal geometry;
• the result covers the complete input polygon area, not only its vertices;
• the result does not extend beyond the convex hull, within floating-point tolerance;
• the chosen hole, grouping, component, repair, and fallback policies are recorded;
• input ordering determines stable group and component ordering.

Output fields

Python API

import geopandas as gpd
from concavewrap import HullOptions, HullResult, build_hulls

areas = gpd.read_file("areas.gpkg", layer="areas")
result: HullResult = build_hulls(
    areas,
    HullOptions(ratio=0.25, scope="global", allow_holes=False),
)
result.hulls.to_file("hulls.gpkg", layer="hulls", driver="GPKG")
print(result.report())

The stable public interface is build_hulls(...), HullOptions, HullResult, and HullDiagnostic.

Limits

• Input geometries must be Polygon or MultiPolygon.
• A projected CRS with horizontal units in metres is required so that area audit values are meaningful and comparable.
• component scope dissolves touching and overlapping polygons before identifying disconnected components.
• Concave hulls are not unique across algorithms. This package uses the GEOS algorithm exposed by Shapely and records its ratio explicitly.
• A hull is a generalization. Always inspect results for sparse samples, narrow necks, very large gaps, and geometries whose holes have semantic meaning.

Run concavewrap --help for all options. Exit code 0 means success and 2 means invalid input or a processing failure.

The pre-release and launch checks are listed in docs/release-checklist.md.

Development

python -m pip install -e ".[test]"
python -m ruff check .
python -m ruff format --check .
python -m pytest

Copyright 2026 Alena Nikitina. Licensed under the Apache License 2.0.