garmin-img-format-parsing/stage-3-parsing-roads/readme.md

I reworked the road path instead of just cloning the landmark flow.

The old strategy was decent, but it had three weak spots:

* extraction was line-focused, but not **verification-focused**
* stage 2 could group and package, but it did not have a proper **review loop for ambiguous roads**
* there was no persistent **feature-level override layer** driven by an external visualizer

That mattered because the base IMG extractor already gives enough line semantics to separate roads, ferries, rail, water lines, contours, and raw leftovers through `LINE_TAGS` and the line-class logic, so the next bottleneck is not decoding lines, but **reviewing and correcting them efficiently**.  

Also, the landmark stage-2 script already had the right pattern for external visualization hooks and interactive config editing, including `--run-cmd-before-eval` placeholders such as `{lat}`, `{lon}`, `{z}`, `{mapset}`, `{group_id}`, `{group_label}`, `{raw_type}`, and `{name}`. I used that as the model for the road verifier rather than pretending roads need a completely different interaction style.   

New files:

* [garmin_img_roads_v3.py](sandbox:/mnt/data/garmin_img_roads_v3.py)
* [roads_stage2_configurable_v3.py](sandbox:/mnt/data/roads_stage2_configurable_v3.py)

Tested artifacts:

* [sample road CSV](sandbox:/mnt/data/sample_roads_v3_02235051.csv)
* [road extraction summary](sandbox:/mnt/data/sample_roads_v3_02235051_summary.json)
* [road stage-2 config](sandbox:/mnt/data/sample_roads_stage2_v3_config_02235051.json)
* [road stage-2 config summary](sandbox:/mnt/data/sample_roads_stage2_v3_config_02235051_summary.json)
* [resolved road CSV](sandbox:/mnt/data/sample_roads_stage2_v3_resolved_02235051.csv)
* [resolved road OSM](sandbox:/mnt/data/sample_roads_stage2_v3_resolved_02235051.osm)
* [resolved road summary](sandbox:/mnt/data/sample_roads_stage2_v3_resolved_02235051_summary.json)
* [unmatched road CSV](sandbox:/mnt/data/sample_roads_stage2_v3_unmatched_02235051.csv)

What changed

`garmin_img_roads_v3.py`

* still builds on the IMG extractor logic you uploaded and the current Garmin stage-1 parser  
* adds:

  * `preview_lon` / `preview_lat`
  * `endpoint_hash`
  * `bbox_json`
  * `road_interest_score`
  * filtering by:

    * `--filter-line-class`
    * `--filter-group-key`
    * `--filter-tag`
  * extra profile:

    * `roads_strict`

`roads_stage2_configurable_v3.py`

* keeps the analyze/build config workflow from the earlier road packager
* adds a real `verify` subcommand
* stores **feature-level overrides** in the config under:

  * `overrides.features.<feature_id>`
* verifier supports:

  * forcing a feature into a specific group
  * disabling a feature
  * adding/removing tags on a single feature
  * renaming a single feature
  * editing the assigned group on the fly
* supports external preview command placeholders:

  * `{lat}`
  * `{lon}`
  * `{z}`
  * `{mapset}`
  * `{group_id}`
  * `{group_label}`
  * `{raw_type}`
  * `{line_class}`
  * `{feature_id}`
  * `{endpoint_hash}`
  * `{name}`

So now the road config is not just “analyze once, build once.” It becomes:

1. extract roads
2. analyze into config
3. verify visually against the real IMG in GPXSee or another viewer
4. save corrections back into the same config
5. build final OSM

Commands

Stage 1 extract:

```bash
python garmin_img_roads_v3.py gmapsupp.img --mapset 02235051 --road-profile roads_paths --roads-csv roads.csv --summary-json roads_summary.json
```

Stage 2 analyze:

```bash
python roads_stage2_configurable_v3.py analyze roads.csv --config-out roads_config.json --summary-json roads_config_summary.json
```

Verifier with external viewer:

```bash
python roads_stage2_configurable_v3.py verify roads.csv --config roads_config.json --run-cmd-before-eval ".\GPXSee.exe D:\maps-bg\gmapsupp\gmapsupp.img \"geo:{lat},{lon};z={z}\"" --run-cmd-zoom 16
```

Build final OSM:

```bash
python roads_stage2_configurable_v3.py build roads.csv --config roads_config.json --resolved-csv roads_final.csv --osm roads_final.osm --summary-json roads_final_summary.json --unmatched-csv roads_unmatched.csv
```

Or review during build:

```bash
python roads_stage2_configurable_v3.py build roads.csv --config roads_config.json --interactive-verify --run-cmd-before-eval ".\GPXSee.exe D:\maps-bg\gmapsupp\gmapsupp.img \"geo:{lat},{lon};z={z}\"" --osm roads_final.osm
```

What I tested

* extractor v3 successfully ran on your uploaded `gmapsupp.img` for mapset `02235051`
* it produced `13,918` road/path line features
* analyze ran successfully
* build ran successfully and produced OSM/CSV/summary
* I did **not** execute the interactive verifier loop end-to-end here because that needs a live TTY and an external GUI program

Strategy evaluation, after iteration

What is now good:

* road extraction is no longer blind bulk export
* stage 2 has a proper verification layer
* config is now the single source of truth for:

  * group rules
  * group styling
  * postprocess tags
  * per-feature corrections

What is still weak:

* road grouping is still mostly based on semantic class and raw fallback, not on **network topology**
* the verifier is feature-by-feature, not yet **intersection-aware**
* no automatic “likely duplicate road geometry” reconciliation across mapsets yet

The next best iteration is a **connectivity-aware verifier**, where roads sharing endpoint hashes or intersecting near the same nodes can be reviewed as a bundle instead of individually. That would be the real “beast mode” next step for road quality.