mkgmap / imgforge Comparison — IMG Size and Geometric Smoothing¶

This page analyzes why mkgmap r4924 and imgforge produce IMGs of different sizes and visually distinct geometries, from the same .mp tile. It is based on direct measurements of the BDTOPO-001-004 tile (Vienne, D038) and the Java source code of mkgmap r4924 (build/MapBuilder.java L929-1354).

Introduction — the question asked¶

For the same MP tile (BDTOPO-001-004.mp, 43 MB), mkgmap r4924 and imgforge produce IMGs of different sizes. The size ratio mentioned upstream ("6×") resulted from a non-rigorous comparison (different scopes: number of tiles, included sections). The instrumented measurement on the same tile BDTOPO-001-004 gives a very different result, detailed below.

§1 — Reference measurements (current state)¶

Measurement conditions¶

Method¶

For each IMG, the script extracts the TRE from the main sub-map, reads the map levels section and the subdivisions section, then aggregates the deltas rgn_offset(i+1) − rgn_offset(i) by level. This is the measurement used by the Garmin firmware to select data to render. It excludes extended sections (extended types, NET, NOD, RGN2-RGN5).

Reproduction commands¶

# mkgmap measurement (IMG already available)
python3 scripts/debug/bytes-per-level.py tmp/mkgmap-vienne-build.img

# Single-tile imgforge build (sub-map 00380042)
mkdir -p /tmp/vienne-mp
cp pipeline/output/2026/v2026.03/D038/mp/BDTOPO-001-004.mp /tmp/vienne-mp/
imgforge build /tmp/vienne-mp --output /tmp/vienne-local.img

# imgforge measurement (analyze sub-map 00380042, not 00011855 which is the GMP container)
python3 scripts/debug/bytes-per-level.py /tmp/vienne-local.img  # reads the first sub-map
# Note: bytes-per-level.py reads the first alphabetical sub-map; for imgforge GMP,
# the tile sub-map (00380042) comes after the container (00011855). See §A.

Comparison table¶

Convention — column mk÷if: value > 1 means mkgmap has more bytes than imgforge at that level.

(1) "inh." for inherited: level 6 inherits its subdivision from level 5; no feature is emitted directly.

Key observations¶

1. imgforge is now 1.73× more compact than mkgmap in geometric RGN data: 1 053 284 bytes vs 1 817 996 bytes. The EndLevel filtering fix (commit 6478c47) eliminated erroneous emission at wide levels.

2. The gap is greatest at wide levels: at n=5, mkgmap stores 15.8× more data. But at n=0 the trend reverses: imgforge has 30% more data at maximum detail level.

3. mkgmap includes more features at wide levels: 95 subdivisions at n=5 vs 4 for imgforge. This is not poor quality — it is a design choice: mkgmap keeps more features visible when zooming out but simplifies them aggressively via its filter chain. imgforge applies EndLevel filtering (features absent from levels above their EndLevel) but does not simplify the geometry of present features.

4. The total single-tile IMG remains larger for imgforge (4.9 MB vs 3.8 MB for mkgmap), despite smaller ordinal geometry. The difference comes from the GMP container overhead and extended sections: the declared imgforge RGN is 3.37 MB of which 2.32 MB are extended types/NET/NOD, vs 3.79 MB declared mkgmap of which 1.97 MB are extended. It is not the geometric section that explains the difference in total IMG size — it is the format overhead.

Historical baseline (before EndLevel fix)¶

Level 0 is almost identical before and after the fix: features with EndLevel=0 were not affected by the bug. The improvement is entirely concentrated on levels n=1..5.

§2 — The mkgmap filter chain¶

Overview¶

mkgmap applies a filter chain per resolution, in two passes depending on the feature type. The reference source code is MapBuilder.java L929-1354.

Preliminary gate (L929-930):

lines = lines.stream().filter(l -> l.getMinResolution() <= res).collect(Collectors.toList());
shapes = shapes.stream().filter(s -> s.getMinResolution() <= res).collect(Collectors.toList());

This gate is the equivalent of imgforge's EndLevel filtering (fix TD-1). A feature whose MinResolution > res is not simplified — it is not emitted at all.

Polyline chain (L1248-1283)¶

For normal polylines (res < 24, all levels except n=0):

RoundCoordsFilter
→ SizeFilter(MIN_SIZE_LINE=1)
→ RemoveObsoletePointsFilter
→ DouglasPeuckerFilter(2.6 × (1 << shift))
→ RemoveEmpty → LineSplitterFilter → LinePreparerFilter → LineAddFilter

Polygon chain (L1313-1335)¶

PolygonSplitterFilter
→ RoundCoordsFilter
→ RemoveObsoletePointsFilter
→ SizeFilter(min-size-polygon=8)
→ DouglasPeuckerFilter(2.6 × (1 << shift))
→ RemoveEmpty → LinePreparerFilter → ShapeAddFilter

Default parameters¶

§3 — Filter by filter¶

RoundCoordsFilter¶

Quantizes each coordinate to the resolution grid (1 << shift) Garmin units. One Garmin unit ≈ 2.14 m (latitude, at French latitudes). Disabled at res=24 (enableLineCleanFilters requires res < 24).

Special contour line mode: for each intermediate point, mkgmap tests the 4 corners of the cell and chooses the one that minimizes the sum of distances to the segment before and after (calcDistortion). This "best-fit" mode produces a trace naturally aligned on the grid, visually smoother than naive rounding.

SizeFilter¶

Removes features whose bounding box is too small to be visible at the current resolution. Disabled at res=24.

maxDimension < minSize × (1 << shift)

Example: a section of CONSTRUCTION_LINEAIRE (wall, hedge) 20 m long disappears from n=3 (shift=3, threshold = 8 units ≈ 17 m for lines). This reduces the RGN at wide levels without affecting maximum zoom.

DouglasPeuckerFilter¶

The maximum error is scaled exponentially by level:

// DouglasPeuckerFilter.java L43
maxErrorDistance = filterDistance * (1 << config.getShift());
// with filterDistance = 2.6 (default) and shift = 24 - res
// Disabled at res=24 (enableLineCleanFilters requires res < 24)

mkgmap is 10 to 40× more aggressive than our profile at wide zoom levels (n=4..6). At n=6, mkgmap tolerates an error of ~1.4 km — only the large inflections of the road network survive.

RemoveObsoletePointsFilter¶

Eliminates after each filter:

• Duplicate points (identical coordinates after rounding)
• Strictly colinear points (STRICTLY_STRAIGHT)
• Spikes (abrupt direction reversals)

Applied after RoundCoordsFilter for polylines and polygons. Post-quantization cleanup is crucial: RoundCoordsFilter may project two distinct coordinates to the same rounded value, producing duplicates that RemoveObsolete immediately eliminates.

SmoothingFilter — dead code¶

// SmoothingFilter.java — never instantiated in MapBuilder r4924
// stepsize = 5 << shift — sliding average of adjacent point groups

SmoothingFilter is present in the mkgmap r4924 sources but never instantiated in MapBuilder.java. It is a historical artifact. The visual smoothing effect of mkgmap comes from RoundCoordsFilter (grid quantization, best-fit contour line mode) and DouglasPeuckerFilter (elimination of micro-deviations), not from this filter.

The smooth: chaikin smoothing of imgforge/mpforge (curve subdivision iterations) has no equivalent in mkgmap r4924 — both tools smooth via orthogonal mechanisms.

LineMergeFilter — advanced option¶

LineMergeFilter is instantiated in MapBuilder.java L933 only if the --merge-lines option is passed to mkgmap. Not enabled by default. This filter merges segments of the same type that are adjacent to reduce the number of distinct features. It is not included in the standard chain documented here.

§4 — Comparison with our pipeline¶

What mpforge/imgforge implements¶

Layer coverage by generalize-profiles-local.yaml¶

Out of 124 863 features in BDTOPO-001-004.mp (Vienne), the local profile covers 8 layers representing 34% of features. The remaining 66% traverse the pipeline without per-level geometric simplification.

Covered layers (profile with simplification):

Main uncovered layers:

§5 — Behavior according to profiles configuration¶

§6 — Prioritized recommendations¶

Implementation candidates ranked by gain/complexity ratio, based on §1 measurements.

Levels n=1..5 represent 389 342 bytes (37% of total RGN) — this is the range where mkgmap filters have the most effect. Level n=0 (663 942 bytes, 63%) is unaffected by mkgmap filters (res < 24).

Summary¶

All 5 candidates are now implemented. The estimated total combined gain remains on the order of 12-21% of total RGN (1 053 284 → ~830-925 KB), assuming approximate independence of effects. The main effect of mkgmap visually (geometric smoothing at wide zooms) comes mostly from RoundCoordsFilter + scaled DP.

The three imgforge filters (RoundCoordsFilter, SizeFilter, RemoveObsoletePointsFilter) are active by default at all levels n>0. They can be disabled individually to measure their isolated impact or reproduce a baseline behavior without filters:

# Disable only RoundCoordsFilter (measure sub-pixel impact)
imgforge build tiles/ --no-round-coords

# Disable all three filters (baseline without post-parsing filtering)
imgforge build tiles/ --no-round-coords --no-size-filter --no-remove-obsolete-points

§7 — Feature selection by level: is imgforge correct?¶

Initial hypothesis¶

The difference of 95 subdivisions (mkgmap) vs 4 (imgforge) at n=5, with a byte gap of 15.8×, had raised the question: does mkgmap include features at n=5 that imgforge would wrongly exclude? The hypothesis was that mkgmap reads DataN sections cumulatively (minResolution = min(resolution of all DataN read)) and thus promotes features beyond their EndLevel.

Verification — mpforge never emits DataN beyond EndLevel¶

The distribution of the production MP (BDTOPO-001-004.mp, 124 863 features) is perfectly clean:

mpforge never emits DataN beyond EndLevel. The hypothesis of promotion by cumulative reading cannot therefore occur: mkgmap does not see Data5= for a feature with EndLevel=4.

Verification — same features at n=5¶

According to imgforge's feature_visible_at_level logic (writer.rs):

• Feature visible at n=5 if EndLevel ≥ 5 AND there exists DataN(k ≤ 5)
• Result on the MP: 4 795 features (exactly those with EndLevel=6)

mkgmap applies the same rule via its gate l.getMinResolution() <= res (MapBuilder.java L929), where minResolution is derived from EndLevel. Both tools include the same features at n=5.

Explanation of the byte gap¶

The difference of 129 713 bytes (mkgmap) vs 8 200 bytes (imgforge) at n=5 for the same 4 795 features comes from two combined factors:

1. Splitter granularity: mkgmap creates 95 small subdivisions (~50 features/subdiv) where imgforge creates 4 large subdivisions (~1 200 features/subdiv). Each subdivision carries a fixed structural overhead in the RGN — 95 × overhead >> 4 × overhead.

2. Filter chain: the 4 795 features pass through RoundCoordsFilter + DouglasPeuckerFilter (error 166 units ≈ 356 m at n=5) in mkgmap, reducing each polyline to a few points. In imgforge, simplification at n=5 depends on the YAML profile (14 m for municipal roads, absent for features outside the profile).

Conclusion¶

The imgforge implementation is correct and semantically faithful to mkgmap on feature selection. The size difference at n=5 is entirely explained by the splitter granularity (more structural overhead on the mkgmap side) and the absence of RoundCoords + SizeFilter filters on the imgforge side.

mkgmap's fine granularity (small subdivisions) may offer an advantage on the Garmin firmware side (less data to load per query), but this is a splitter optimization distinct from the subject of this page.

Appendix A — Manual extraction of the imgforge sub-map¶

The bytes-per-level.py script reads the first alphabetical sub-map finding a TRE. For an imgforge IMG in GMP format, two sub-maps have a TRE:

The script chooses 00011855 (alphabetical order) — the result displayed by default is the empty container. To analyze the actual tile, modify the script to target 00380042 explicitly, or add a --submap <name> argument.

Appendix B — Reference sources¶