Skip to content

edge-stitch

Inputs

  • edge-stitch MUST read the input and reproject it to EPSG:4326.
  • edge-stitch MUST NOT coverage-clean the input before stitching: whatever seams or defects the input has are exactly what the stitch pass exists to close.

Stitching

  • edge-stitch MUST run one whole-table ST_CoverageClean pass over the input, using a fixed snapping-distance-scale gap-closing width, not a shape-based heuristic.

Outputs

  • edge-stitch's final output MUST pass the coverage check (no overlap; unlike other tools, an unfilled gap does not block export, see docs/adr/0027).
  • edge-stitch MUST export the final cleaned layer, and MUST NOT carry a source_file column on it even if the input already had one (e.g. a re-stitched edge-mosaic/edge-match output), silently dropping it (see docs/adr/0087).
  • edge-stitch MUST also export an issues report alongside it, using the same columns as every other tool's issues report, listing every leftover gap wider than SNAP_TOLERANCE, so a human can audit what may need review. area_m2, max_width_m, and thinness_ratio MUST be populated for each row; every other column MUST be null.
  • edge-stitch MUST produce the issues report only when it has at least one row; when it would be empty, no file MUST be written (and a stale file from a previous run at that path MUST be removed).

Configuration (api.edge_stitch.stitch() / CLI)

  • edge-stitch's input role MAY span multiple already-tiled files, combined internally into one table before the clean pass. The CLI additionally accepts --input (repeatable and comma-separable) alongside the glob-capable INPUT_FILE positional, matching edge-mosaic's own --input idiom.
  • With a single input file, the output path MUST default to that input path with a _stitched suffix. With multiple input files, output_path MUST be given explicitly. The issues-report path MUST default to the output path with an _issues suffix.
  • edge-stitch MUST raise FileExistsError if either output path already exists and overwriting wasn't requested.
  • step, if given, MUST be one of inputs, topo-clean, outputs; any other value MUST raise ValueError.
  • edge-stitch MAY opt into cascading admin-hierarchy columns via fill_schema/--fill-schema, right after cleaning and before export. name_field/code_field/--name-field/--code-field (given together or both omitted; omitted falls back to structural auto-detection) and depth_column/--depth-column (default adm_lvl) narrow it; all MUST raise ValueError if given without fill_schema=True. edge-stitch MUST raise ValueError if depth_column already names an existing column when fill_schema is set (see docs/adr/0095).

Examples

Example 1: basic run, output name chosen automatically

topo-tools edge-stitch tiled.geojson

Example 2: explicit output

topo-tools edge-stitch tiled.gpkg stitched.gpkg

Example 3: custom issues report path

topo-tools edge-stitch tiled.parquet stitched.parquet --issues-file stitch_report.parquet

Example 4: combine every already-clipped file into one global output

topo-tools edge-stitch "tmp/clipped/*.parquet" stitched.parquet

Example 5: cascade admin-hierarchy columns and stamp each row's depth before export

topo-tools edge-stitch tiled.parquet stitched.parquet --fill-schema