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
• roads_stage2_configurable_v3.py

Tested artifacts:

• sample road CSV
• road extraction summary
• road stage-2 config
• road stage-2 config summary
• resolved road CSV
• resolved road OSM
• resolved road summary
• unmatched road 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:

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:

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

Verifier with external viewer:

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:

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:

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.