Step 3: Tiling (mpforge)¶

This is the central step of the pipeline: mpforge reads geospatial data, slices it into spatial tiles and generates a Polish Map file (.mp) per tile.

Via the build script (recommended)¶

The build-garmin-map.sh script orchestrates mpforge and imgforge in a single command:

# A single department
./scripts/build-garmin-map.sh --zones D038

# Multiple departments
./scripts/build-garmin-map.sh --zones D038,D069 --jobs 4

# Dry-run to verify paths and commands
./scripts/build-garmin-map.sh --zones D038,D069 --dry-run

The script:

• Auto-detects the year and version of BDTOPO data
• Exports environment variables (DATA_ROOT, ZONES, OUTPUT_DIR...) for mpforge
• Chains mpforge (tiling) then imgforge (compilation) automatically
• Manages multi-zone DEM (one --dem per department)

build-garmin-map.sh options¶

Geography¶

Data paths¶

The --contours-dir, --dem-dir, --osm-dir and --hiking-trails-dir options allow pointing to existing directories without having to follow the default directory structure. If omitted, they are derived from --data-dir.

mpforge¶

imgforge¶

imgforge — geometry options (opt-in, recommended for large scopes)¶

These options propagate the corresponding imgforge flags; they change nothing if omitted. All values aligned with mkgmap defaults.

Build control¶

Complete example¶

export PROJ_DATA=/usr/share/proj
export OSM_CONFIG_FILE=./pipeline/configs/osm/osmconf.ini
export OGR_GEOMETRY_ACCEPT_UNCLOSED_RING=YES
export OSM_MAX_TMPFILE_SIZE=1024

./scripts/build-garmin-map.sh \
  --zones D038 \
  --year 2025 \
  --version v2025.12 \
  --data-dir ./pipeline/data \
  --contours-dir ./pipeline/data/courbes \
  --dem-dir ./pipeline/data/bdaltiv2 \
  --output-base ./pipeline/output \
  --jobs 4 \
  -v

Direct mpforge command¶

For fine control, mpforge can be called directly:

export DATA_ROOT=./pipeline/data/bdtopo/2025/v2025.12
export ZONES=D038
export OUTPUT_DIR=./pipeline/output/2025/v2025.12/D038
export BASE_ID=38

mpforge build --config pipeline/configs/ign-bdtopo/departement/sources.yaml --jobs 8

mpforge will:

1. Substitute variables ${DATA_ROOT}, ${ZONES}, etc. in the YAML
2. Expand brace patterns {D038,D069} to concrete paths
3. Resolve wildcards (*, **) via glob
4. Index features in a spatial R-tree
5. Compute the tiling grid according to cell_size and overlap
6. Distribute tiles across N parallel workers
7. For each tile: clip geometries, apply rules, export the .mp

Spatial filtering (optional)¶

If large sources (contour lines, OSM...) are configured with a spatial_filter, mpforge pre-filters features by a reference geometry before tiling. In multi-zone mode, geometries from all matched files are automatically unioned:

inputs:
  - path: "${CONTOURS_DATA_ROOT}/{${ZONES}}/**/COURBE_*.shp"
    spatial_filter:
      source: "${DATA_ROOT}/{${ZONES}}/ADMINISTRATIF/COMMUNE.shp"
      buffer: 500

cell_size strategy by scope¶

The grid.cell_size parameter in the YAML config controls the mpforge tile size in degrees. This is the most important lever to adapt when changing scale. Contrary to natural intuition, the right value is not "the smallest possible for precision": imgforge's RGN splitter automatically subdivides large tiles internally. The real cost of small tiles is the number of FAT entries in the gmapsupp.img — which some GPS devices like the Garmin Alpha 100 load into RAM at boot, with a strict ceiling.

In practice, quadrants share a common config file (pipeline/configs/ign-bdtopo/france-quadrant/sources.yaml) that overrides grid.cell_size and lowers the EndLevel of bulky features (BATIMENT, ZONE_DE_VEGETATION) to lighten zoomed-out views. DOM territories each have their own outre-mer/<slug>/sources.yaml (native projection per territory).

Output¶

output/tiles/
├── 000_000.mp
├── 000_001.mp
├── 001_000.mp
├── 001_001.mp
├── ...
└── 045_067.mp

Each .mp file is a complete Polish Map file, readable in a text editor:

[IMG ID]
Name=BDTOPO France
ID=0
Copyright=IGN 2026
Levels=4
Level0=24
Level1=21
Level2=18
Level3=15
[END]

[POLYLINE]
Type=0x0002
Label=National Road 7
Levels=0-2
Data0=(45.1234,5.6789),(45.1235,5.6790),(45.1240,5.6800)
[END]

[POLYGON]
Type=0x0050
Label=Chartreuse Forest
Data0=(45.35,5.78),(45.36,5.79),(45.35,5.80),(45.35,5.78)
[END]

Useful options in production¶

Preview without writing¶

# Dry-run: see how many tiles would be generated
mpforge build --config configs/france-bdtopo.yaml --dry-run

The pipeline runs normally (source reading, R-tree, clipping) but no file is created. Useful for validating the configuration before a long export.

Resume an interrupted export¶

# If the export was interrupted (crash, timeout, Ctrl+C)
mpforge build --config configs/france-bdtopo.yaml --jobs 8 --skip-existing

Only missing tiles are generated. Tiles already present on disk are skipped.

Estimate remaining tiles¶

# Combine dry-run and skip-existing
mpforge build --config configs/france-bdtopo.yaml --dry-run --skip-existing

Generate a JSON report¶

mpforge build --config configs/france-bdtopo.yaml --jobs 8 --report report.json

The report contains export statistics:

{
  "status": "success",
  "tiles_generated": 2047,
  "tiles_failed": 0,
  "tiles_skipped": 150,
  "features_processed": 1234567,
  "skipped_additional_geom": 0,
  "duration_seconds": 1845.3,
  "errors": []
}

Progressive verbosity¶

# Production — progress bar only
mpforge build --config configs/france-bdtopo.yaml

# INFO: main steps
mpforge build --config configs/france-bdtopo.yaml -v

# DEBUG: detailed GDAL logs (disables progress bar)
mpforge build --config configs/france-bdtopo.yaml -vv

# TRACE: maximum verbosity (development only)
mpforge build --config configs/france-bdtopo.yaml -vvv

# Silence GDAL, keep mpforge in DEBUG
RUST_LOG=mpforge=debug,gdal=warn mpforge build --config config.yaml -vv

Parallelization¶

# Check number of available CPUs
nproc

# Adapt thread count
mpforge build --config configs/france-bdtopo.yaml --jobs $(nproc)

Error handling¶

In continue mode (default), tiles with errors are logged but do not interrupt processing:

⚠️  Tile 012_045 failed: GDAL error: Invalid geometry
✅ Processing continues with remaining tiles...

In fail-fast mode, the first error stops everything:

mpforge build --config configs/france-bdtopo.yaml --fail-fast

Tile verification¶

After tiling, you can verify the content of a tile with standard GDAL tools:

# Read tile metadata
ogrinfo -al output/tiles/015_042.mp

# Count features by layer
ogrinfo -al -so output/tiles/015_042.mp

# Convert to GeoJSON for visualization in QGIS
ogr2ogr -f "GeoJSON" tile_preview.geojson output/tiles/015_042.mp