GMP Container & Sub-Headers¶

This page describes the GMP container format, subfile organization, and all sub-headers (TRE, RGN, LBL, NET). For the outer file structure (header, FAT), see Header & FAT. For the tile data stored inside the GMP, see Tile Storage.

3. Subfile Organization¶

3.1 Subfile Types in Raster Maps¶

Raster IMG files can contain either 2 subfiles (single-map) or many subfiles (multi-map):

Single-map raster:

Multi-map raster (IOM format):

Subfile names in the FAT directory:

• GMP subfiles: map ID as 8-char uppercase hex (e.g., 00355951)
• MPS subfile: MAPSOURC

3.1.1 Multi-Map Organization¶

Multi-map IMG files (like IOM.img) split the coverage area into multiple GMP subfiles, each representing one geographic tile. The MPS subfile contains reference records for all maps.

IOM.img example:

FAT entries: 51 GMP subfiles + 1 MPS subfile
Each GMP subfile: ~660KB with 8 zoom levels, covering ~7×5 km area
MPS subfile: 3936 bytes with L-records for all 51 maps

MPS multi-map reference format:

• Contains L-records listing all maps with Product ID (PID) and Family ID (FID)
• IOM.img: PID=1, FID=2150 for all 51 maps

Multi-map vs single-map parameter differences:

3.2 GMP Container Format¶

The GMP subfile is a container that embeds standard Garmin sub-file headers (TRE, RGN, LBL, NET). This is the same format used by vector maps, but adapted for raster tiles.

GMP Container Layout:

[GMP Container Header: 53 bytes]
[Copyright strings: null-terminated]
[TRE Sub-Header: 273 bytes]
[Map Info Strings: "Raster Map\0" + copyright\0"]
[RGN Sub-Header: 125 bytes]
[LBL Sub-Header: 596 bytes]
[NET Sub-Header: 100 bytes]
[TRE Data Sections: copyright, subdivisions, map_levels]
[RGN Data Section: subdivision records]
[LBL Labels: tile filenames as null-terminated strings]
[Tile Index Table: N × uint32 offsets]
[JPEG Tile Data: concatenated JFIF JPEGs]

3.3 GMP Container Header (53 bytes)¶

3.4 Common Sub-Header Format (21 bytes)¶

All sub-section headers (TRE, RGN, LBL, NET) share a common 21-byte prefix:

3.5 TRE Sub-Header (273 bytes)¶

After the 21-byte common header, the TRE sub-header uses the following layout. All position values are GMP-relative offsets (see TRE Sections for complete field reference):

3-byte signed map units: degrees × 2^24 / 360. For example, latitude 47.65°:

int(47.65 * 2^24 / 360) = 2,225,653 = 0x21E825 → bytes 25 E8 21

Display priority: 20 (matching IOM reference, optimal for raster basemaps).

3.6 RGN Sub-Header (125 bytes)¶

After the 21-byte common header, the RGN sub-header uses the following layout. All position values are GMP-relative offsets. Field values are from the Oppmann PDF spec (2023-09-05) and verified against reference files.

Critical field: RGN+0x25. The value 2 at this offset indicates extended polygon encoding. Without this field set correctly, Garmin device firmware will not parse the RGN2 section as extended/raster data. A value of 0 means standard (non-extended) polygon format.

Local flag bitmasks: The flags fields at 0x2D, 0x31, 0x49, 0x4D, 0x65, 0x69 are bitmasks that tell the device firmware which extended object types (type values >= 0x100) have local fields in each section.

Section positions for empty sections: RGN3, RGN4, and RGN5 positions are set to rgn2_pos + rgn2_size (immediately after the RGN2 data) with size=0, indicating no polyline, POI, or dictionary data.

3.7 LBL Sub-Header (596 bytes)¶

After the 21-byte common header:

Labels content: Tile filenames as null-terminated strings (e.g., "0.jpg", "1.jpg", ...).

3.8 NET Sub-Header (100 bytes)¶

Minimal stub for raster maps. Contains the 21-byte common header, with all NET-specific fields set to zero (no network/routing data needed for raster maps).

10. Reference File Analysis¶

10.1 IOM.img (Isle of Man, Multi-Map Raster)¶

Primary analysis target: Subfile 00355951 — fully validated against QMapShack wiki analysis by Alex Whiter.

10.2 Single-Map Raster Reference¶

10.3 Single-Map Raster Reference (East)¶

10.4 Our Implementation Output¶

12. Format Variant Recommendation¶

12.1 Comparison: Single-Map vs Multi-Map Raster IMG¶

Based on analysis of both reference files, there are two distinct raster IMG format variants:

12.2 Recommendation: IOM-Compatible Format¶

Our implementation targets the IOM parameter set within a single-GMP container. Rationale:

1. Device compatibility: The IOM parameter set (priority 20, TRE7 rec_size=4, TRE8 with 2 entries, TRE parameters 10 01 08 24) is proven to work on Garmin devices for both multi-map and single-map configurations. The single-map parameter set uses a different TRE7 format (rec_size=5 with flag bytes) that is less well understood.

2. GPXSee compatibility: The TRE7 rec_size=4 format with _flags=0x01 is cleanly parsed by GPXSee: it reads exactly 4 bytes per entry (polygon offset only) and uses the sentinel entry for setExtEnds().

3. Simplicity: Single GMP container = no FAT chain traversal, no multi-map MPS coordination. The writer generates exactly 2 subfiles (1 GMP + 1 MPS).

4. Scalability: A single GMP container handles 32,000+ tiles with no subfile splitting logic. The FAT system handles multi-part GMP subfiles automatically.

5. Documentation coverage: All sections are fully understood — TRE1 through TRE10, RGN1-RGN5, LBL1/LBL28/LBL29. Validated against both IOM reference and GPXSee source code.

6. Implementation path: Our writer uses single-map container format with IOM-compatible TRE parameters, confirmed working on GPXSee and Garmin devices.

When to consider multi-map format: Only if targeting very small block sizes (2,048 bytes) or if Garmin device compatibility testing reveals that multi-map is required for specific use cases. For all typical raster map use cases, single-map is preferred.