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

I reworked the extractor around the weak spots you pointed out and validated it against the uploaded `gmapsupp.img`, using GPXSee’s Garmin IMG support and source tree as the reference model for the label and local-field paths. GPXSee officially supports Garmin IMG/GMAP maps, and its public source is the right place to mirror parsing behavior from. ([gpxsee.org][1])

Updated script:
[garmin_img_to_osmand_v5.py](sandbox:/mnt/data/garmin_img_to_osmand_v5.py)

What changed:

* **better name extraction**

  * fixed the big one: standard point labels now respect the Garmin **POI indirection bit**, instead of always treating the label offset as a direct string pointer
  * codepage handling is kept for your map’s Cyrillic labels
  * uppercase labels are normalized more cleanly
  * control-character cleanup added
* **all mapsets / segments**

  * still traverses all mapsets
  * now records **segment stats** and **segment error previews** into metadata so you can see where parsing is still rough
* **image/icon grouping**

  * extended points can now expose `garmin_image_id` when present in local fields
  * landmark CSV/GeoJSON now includes:

    * `mapset`
    * `garmin_image_id`
    * `garmin_image_file`
  * best-effort embedded image dumping is supported with `--extract-images-dir`
  * image grouping can be listed/exported with:

    * `--list-image-groups`
    * `--image-groups-csv`
* **validation against your upload**

  * the broken/truncated names improved a lot on the tested mapset
  * examples that now decode sensibly include:

    * `Полски ясен`
    * `Андзова чешма`
    * `Дубрава (310)`
    * `Св. Димитър`
    * `Паметник на Мико Нинов`

A concrete test I ran on your uploaded mapset `02234010`:

* parsed `52686` features
* water-source landmark export produced `1404` point rows
* segment stats reported parsed points/polylines/polygons instead of only points

Use it like this.

Better landmark CSV with mapset + image fields:

```bash
python garmin_img_to_osmand_v5.py gmapsupp.img ^
  --mapset 02234010 ^
  --category water_sources ^
  --landmarks-csv water_sources.csv ^
  --meta-json water_sources.meta.json
```

List landmark types with better names:

```bash
python garmin_img_to_osmand_v5.py gmapsupp.img ^
  --mapset 02234010 ^
  --list-landmark-types
```

List image/icon groups:

```bash
python garmin_img_to_osmand_v5.py gmapsupp.img ^
  --mapset 02234010 ^
  --list-image-groups
```

Export image/icon group summary:

```bash
python garmin_img_to_osmand_v5.py gmapsupp.img ^
  --mapset 02234010 ^
  --image-groups-csv image_groups.csv
```

Best-effort dump embedded Garmin image blobs:

```bash
python garmin_img_to_osmand_v5.py gmapsupp.img ^
  --mapset 02234010 ^
  --extract-images-dir dumped_images ^
  --landmarks-csv landmarks.csv
```

The landmark CSV now has these extra columns:

* `mapset`
* `garmin_image_id`
* `garmin_image_file`

So even if a real image blob is not recoverable for a given point, you can still group by image id or by dumped image file when present.

One important note: on the tested mapset, I did **not** see a rich population of extracted image-backed point icons yet. The support is there now, but this particular IMG seems to benefit much more from the **fixed label path** than from embedded-image extraction. So the image grouping path is now available, but the biggest win on your sample was clearly the label repair.

What is still not fully okay:

* some segment errors remain, and the script now reports them in metadata instead of silently hiding them
* extended/local/class Garmin fields are still only partially decoded
* raw embedded icon extraction is best-effort, not guaranteed for every IMG flavor

The next best refinement is to push one more level into GPXSee-style local/class field parsing so more special POIs get richer metadata instead of only names and coordinates.

[1]: https://www.gpxsee.org/doc "https://www.gpxsee.org/doc"