topo-tools

topo-tools is a collection of DuckDB-powered geospatial topology utilities for cleaning and reconciling administrative boundary polygons. It ships sixteen tools, usable from the CLI or as a Python package. Composite tools are nested under the primitives they chain internally; every primitive is also usable standalone:

• schema-crosswalk: infers a source-column to target-schema crosswalk and immediately applies it, in one call.
  • schema-map: infers a polygon layer's admin hierarchy structurally and proposes a source to target-schema crosswalk for review.
  • schema-refactor: applies a crosswalk CSV, from schema-map or hand-edited, to rename or drop columns. Geometry passes through unchanged.
• schema-fill: cascades each admin-hierarchy column down from its nearest non-NULL shallower level and stamps a depth column.
• topo-clean: detects and fixes gap/overlap defects in a single polygon layer, reporting issues for manual review.
  • topo-detect: scans a single polygon layer for gap/overlap coverage defects and reports them, without fixing anything.
• edge-match: fits a finer child polygon layer into a coarser parent layer, grouping and extending each child to fill gaps within its own parent.
  • edge-extend: fills gaps around a polygon layer (missing coastline, disputed areas, water bodies) with a Voronoi extension, producing full coverage.
  • edge-mosaic: re-clips an already-extended child layer into a new/different parent layer, skipping Voronoi extension entirely.
    • edge-clip: assigns each child to its parent, then clips it to that parent's geometry.
    • edge-stitch: closes seams in an already-tiled polygon layer with one whole-table coverage-clean pass.
• change: compares two versions of a polygon layer and classifies every unit as unchanged, renamed, modified, split, merged, created, or removed.
• package: runs package-polygons, package-points, and package-lines against one input in a single call.
  • package-polygons: dissolves a polygon layer into every detected coarser admin level in a single call.
  • package-points: one label point per admin unit per detected level, using the pole of inaccessibility.
  • package-lines: one deduplicated line network of admin boundaries, tagged by the coarsest level each segment belongs to.

Installation

Install with uv (recommended):

uv tool install topo-tools   # CLI
uv add topo-tools            # Python library

Or with pip/pipx:

pip install topo-tools       # CLI or library
pipx install topo-tools      # CLI

On macOS/Linux, topo-tools is also available via Homebrew, no Python tooling required:

brew install OCHA-DAP/topo-tools/topo-tools

Each linked doc above covers that tool's CLI/Python usage, options, and examples.

Supported Formats

Polygon inputs/outputs: GeoParquet (.parquet), GeoPackage (.gpkg), Shapefile (.shp), GeoJSON (.geojson). Output format matches input format. change's tabular changelog is CSV or GeoParquet only; its spatial overlay layer supports the same four formats as the other tools.

See CONTRIBUTING.md for development setup.