kub-enrich-gis
1. Overview
kub-enrich-gis enriches building records from GIS data (geo/gis.json) using external national building databases.
It supports:
-
enrich: fetch matches and produce an enrichment dataset (json,jsonl, or partitionedparquet) -
inspect: inspect enrichment output and manifest statistics -
materialize: apply high-confidence enrichment fields back intogeo/gis.json
2. Installation
Install optional enrichment dependencies:
pip install feelpp-ktirio-urban-building[enrichment]
3. Synopsis
kub-enrich-gis [-h] [-v] {enrich,inspect,materialize} ...
Help text may display the internal program name ktirio-urban-building-enrich-gis; the installed CLI entry point is kub-enrich-gis.
|
4. Commands
4.1. enrich
Read input GIS buildings and generate enrichment output.
kub-enrich-gis enrich --input <gis.json> --output <path> [OPTIONS]
Options:
| Option | Description |
|---|---|
|
Path to input GIS JSON file (required) |
|
Output file or directory path (required) |
|
Output format (default: |
|
Country code (default: |
|
JSON selector for buildings (default: |
|
Output compression (default: |
|
Parquet partition columns, comma-separated (default: |
|
Spatial partitioning mode (default: |
|
Grid resolution in degrees (default: |
|
H3 resolution (default: |
|
Parquet row group size (default: |
|
Include raw API payloads in output |
|
SQLite cache database path |
|
Cache TTL (default: |
|
API rate limit in requests/second (default: |
|
API burst limit (default: |
|
RNB API base URL |
|
BDNB API base URL |
|
BDNB endpoint used for RNB lookup |
|
Force operation (overwrite / bypass limits) |
4.2. inspect
Inspect an enrichment file or dataset directory.
kub-enrich-gis inspect <path> [-v]
Options:
| Option | Description |
|---|---|
|
Dataset/file to inspect |
|
Print detailed metadata (including full manifest when available) |
4.3. materialize
Apply enrichment results into GIS data.
kub-enrich-gis materialize --gis <geo/gis.json> --enrichment <path> [OPTIONS]
Options:
| Option | Description |
|---|---|
|
GIS file to update (required) |
|
Enrichment file or directory ( |
|
Optional output GIS path (default: in-place update) |
|
Minimum confidence to apply (default: |
|
Allow overwriting existing GIS values |
|
Do not update location manifest enrichment metadata |
|
Disable automatic |
|
Compute updates without writing files |
5. Examples
# 1) Enrich GIS buildings to JSONL
kub-enrich-gis enrich \
--input cemdb/locations/arz/v0.1.0/geo/gis.json \
--output cemdb/locations/arz/v0.1.0/preprocessing/enrichment/buildings.jsonl
# 2) Enrich to partitioned Parquet dataset
kub-enrich-gis enrich \
--input cemdb/locations/arz/v0.1.0/geo/gis.json \
--output cemdb/locations/arz/v0.1.0/preprocessing/enrichment/ \
--format parquet \
--partition country,spatial_key \
--compression zstd
# 3) Inspect generated data
kub-enrich-gis inspect cemdb/locations/arz/v0.1.0/preprocessing/enrichment/
# 4) Preview materialization without writing
kub-enrich-gis materialize \
--gis cemdb/locations/arz/v0.1.0/geo/gis.json \
--enrichment cemdb/locations/arz/v0.1.0/preprocessing/enrichment/ \
--min-confidence 0.85 \
--dry-run
# 5) Apply high-confidence matches in place
kub-enrich-gis materialize \
--gis cemdb/locations/arz/v0.1.0/geo/gis.json \
--enrichment cemdb/locations/arz/v0.1.0/preprocessing/enrichment/ \
--min-confidence 0.85
6. Exit Codes
-
0: success -
1: error (missing dependencies, invalid input paths/options, pipeline/materialization failure)
7. Related Tools
-
kub-dataset for packaging and distribution of enriched datasets