garmin-img-format-parsing/stage-1-read-garmin-img/readme.md

Done.

Updated extractor:
[garmin_img_to_osmand_v6.py](sandbox:/mnt/data/garmin_img_to_osmand_v6.py)

Validation sample for the blue unnamed marker:

* [near_blue_marker_02235051.csv](sandbox:/mnt/data/near_blue_marker_02235051.csv)
* [near_blue_marker_02235051.json](sandbox:/mnt/data/near_blue_marker_02235051.json)

What changed in v6

* Added **point-focused parametrization** so unnamed/raw symbols can be kept on purpose instead of disappearing behind semantic filters.
* Added **near-coordinate capture**:

  * `--near lon,lat[,radius_m]`
* Added **point discovery profiles**:

  * `--point-profile all`
  * `--point-profile named`
  * `--point-profile semantic`
  * `--point-profile symbols`
  * `--point-profile interesting`
  * `--point-profile named_or_symbol`
* Added **raw type inclusion/exclusion**:

  * `--include-raw-point-type 0x65:0x00`
  * `--exclude-raw-point-type ...`
* Added **grouping key output** for landmarks:

  * `--point-group-by auto|semantic|raw_type|image|mapset`
* Landmark CSV/GeoJSON now includes:

  * `point_group_key`
  * `point_interest_reasons_json`
  * `distance_m` when `--near` is used
  * `has_name`
  * `has_semantic`
* Kept the previous fixes:

  * better POI-indirected label decoding
  * image id / image blob best-effort extraction
  * all mapsets traversal
  * segment stats and error previews in metadata

Most important test result

The previously missing point is now capturable with parameters.

Using:

* mapsets `02235051` and `02235063`
* `--near 25.1401,42.3391,60`
* `--point-profile interesting`
* `--include-unnamed`
* `--include-raw-point-type 0x65:0x00`

the extractor returns:

* mapset: `02235051`
* lon: `25.14019489`
* lat: `42.33907700`
* type: `point / 0x65 / 0x00`
* name: empty
* group key: `raw:0x65:0x00`
* reasons: `["unnamed_raw_symbol", "raw_type_include"]`

So that class of point is no longer lost.

Useful commands

Targeted check for a suspicious map symbol:

```bash
python garmin_img_to_osmand_v6.py gmapsupp.img ^
  --mapset 02235051 ^
  --mapset 02235063 ^
  --near 25.1401,42.3391,60 ^
  --point-profile interesting ^
  --include-unnamed ^
  --include-raw-point-type 0x65:0x00 ^
  --landmarks-csv near_check.csv ^
  --meta-json near_check.json
```

Maximal “interesting spots” extraction from one IMG:

```bash
python garmin_img_to_osmand_v6.py gmapsupp.img ^
  --point-profile interesting ^
  --include-unnamed ^
  --point-group-by auto ^
  --landmarks-csv interesting_spots.csv ^
  --landmarks-geojson interesting_spots.geojson ^
  --meta-json interesting_spots.json
```

Same, but grouped by raw Garmin type:

```bash
python garmin_img_to_osmand_v6.py gmapsupp.img ^
  --point-profile interesting ^
  --include-unnamed ^
  --point-group-by raw_type ^
  --landmarks-csv interesting_raw_groups.csv
```

Same, but force-include raw symbol classes you discover:

```bash
python garmin_img_to_osmand_v6.py gmapsupp.img ^
  --point-profile interesting ^
  --include-unnamed ^
  --include-raw-point-type 0x65:0x00 ^
  --include-raw-point-type 0x64:0x14 ^
  --include-raw-point-type 0x66:0x16 ^
  --landmarks-csv interesting_plus_whitelist.csv
```

If you want every point, no heuristics:

```bash
python garmin_img_to_osmand_v6.py gmapsupp.img ^
  --point-profile all ^
  --include-unnamed ^
  --landmarks-csv all_points.csv
```

What I consider improved beyond your direct request

* The extractor now supports a **discovery workflow**, not just a clean export workflow.
* The output has enough metadata to build downstream grouping logic without reparsing:

  * semantic group
  * raw type group
  * image group
  * mapset group
  * interest reasons
* Near-coordinate debugging is now a first-class capability, which is crucial for validating “I see this on the map, why isn’t it in the export?”

What is still not fully solved

* Not every Garmin symbol is semantically understood yet.
* Image/icon extraction is still best-effort, because some symbol rendering in Garmin maps is style/TYP-driven rather than directly stored as easy blobs.
* Some “interesting” raw point types will still need iterative whitelisting as you discover them.

The next strong upgrade would be adding a **discovery summary mode** that automatically ranks raw point types/subtypes by:

* unnamed count
* image-backed count
* frequency
* clustering
* proximity to trails/water/peaks

That would make the whitelist-building process much faster.