mpforge — The Tile Forger¶

The problem: massive data to slice¶

The IGN BD TOPO represents approximately 40 GB of data for the southern half of France (Nouvelle-Aquitaine, Auvergne-Rhône-Alpes, Provence-Alpes-Côte d'Azur, Corse and Occitanie regions), with dozens of geographic layers (roads, buildings, hydrography, vegetation...). A Garmin GPS cannot digest a monolithic Polish Map file of this size. The data must be sliced into spatial tiles — manageable geographic chunks — then recombined during compilation.

This spatial tiling is a complex operation:

• Geometries must be clipped at tile boundaries
• Overlap must be managed to avoid visual artifacts
• Categorization rules must be applied (which Garmin type for which object?)
• Millions of features must be processed in a reasonable time

The solution: mpforge¶

mpforge is a Rust CLI that orchestrates this entire process in a single command:

mpforge build --config france-bdtopo.yaml --jobs 8

Output: hundreds (or even thousands) of .mp files, each covering a portion of the territory, ready to be compiled by imgforge.

Architecture¶

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#4caf50', 'lineColor': '#90a4ae'}}}%%
flowchart TD
    A["GDAL Sources<br/>(.shp, .gpkg)"] --> B["OGR Read<br/>+ spatial filtering"]
    B --> C["Spatial R-tree<br/>indexing"]
    C --> D["Tiling grid<br/>cell_size + overlap"]
    D --> E["Parallel workers<br/>(rayon)"]
    E --> F["Geometric clipping<br/>per tile"]
    F --> G["Polish Map export<br/>via ogr-polishmap"]
    G --> H["tiles/*.mp"]

    style A fill:#4caf50,stroke:#2e7d32,color:#fff
    style B fill:#78909c,stroke:#546e7a,color:#fff
    style C fill:#78909c,stroke:#546e7a,color:#fff
    style D fill:#78909c,stroke:#546e7a,color:#fff
    style E fill:#78909c,stroke:#546e7a,color:#fff
    style F fill:#78909c,stroke:#546e7a,color:#fff
    style G fill:#78909c,stroke:#546e7a,color:#fff
    style H fill:#ff9800,stroke:#e65100,color:#fff

What happens internally¶

1. Reading — mpforge opens all GDAL sources declared in the configuration
2. Spatial filtering — If configured, features are pre-filtered by a reference geometry (e.g.: communes)
3. Indexing — Features are indexed in a spatial R-tree for fast queries
4. Grid — A regular grid (configurable in degrees) is computed over the data extent
5. Parallelization — Each tile is processed by an independent worker (rayon)
6. Clipping — Geometries are clipped at the tile boundaries (with overlap)
7. Generalization — Optional smoothing (Chaikin) and simplification (Douglas-Peucker)
8. Export — The ogr-polishmap driver generates the .mp file with the configured field mapping

mpforge CLI¶

Commands¶

mpforge build options¶

mpforge build --config <file.yaml> [options]

Examples:

# Sequential mode (debug)
mpforge build --config config.yaml

# Production mode — 8 parallel threads
mpforge build --config config.yaml --jobs 8

# Resume an interrupted export
mpforge build --config config.yaml --jobs 8 --skip-existing

# Preview without writing (dry-run)
mpforge build --config config.yaml --dry-run

# With JSON report for CI/CD
mpforge build --config config.yaml --jobs 8 --report report.json

mpforge validate options¶

mpforge validate --config <file.yaml> [options]

Nine checks are performed:

Example output:

✓ yaml_syntax          — Parsed successfully
✓ semantic_validation  — All validations passed
✓ input_files          — 104 files found
✓ rules_file           — 28 rulesets, 351 rules total
- field_mapping        — Not configured (optional — renames raw GDAL attribute keys before applying garmin-rules.yaml)
✓ header_template      — Header configured (direct values, no template file)
✓ spatial_filter       — inputs #21-#103 (83): data/COMMUNE.shp (pattern)
✓ generalize           — catalog: ../generalize-profiles.yaml (8 profil(s), 84 niveau(x))
✓ label_case           — 20 ruleset(s): Voies ferrees: Title, Communes: Title, ...

Config valid. (7/10 checks passed)

Exit code: 0 if valid, 1 if invalid. The JSON report can be used in CI/CD.

Parallelization¶

mpforge uses the rayon library (Rust) to distribute processing across N independent workers via the --jobs option. Each worker opens its own GDAL datasets — no shared state between threads.

# Sequential (debug, no parallelization)
mpforge build --config config.yaml --jobs 1

# 8 threads (production)
mpforge build --config config.yaml --jobs 8

Error handling¶

Two configurable modes in the YAML (error_handling) or via CLI (--fail-fast):

• continue (default) — Tiles in error are logged but processing continues. Ideal for production where a few problematic tiles should not block 2000 others.
• fail-fast — Immediate stop on first error. Ideal for development and debugging.

JSON report¶

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

The skipped_additional_geom field counts features that were dropped because at least one additional Data<n>= bucket failed to write (FFI error OGR_F_SetGeomField ≠ NONE, or invalid WKT). It does not appear when the value is 0 (mono-Data mode). See Multi-level profiles.

Multi-level profiles¶

mpforge can produce multi-Data .mp files: each feature carries multiple geometries (Data0= detailed, Data2= simplified for mid-zoom, etc.), selected by imgforge according to the zoom level. Two mechanisms coexist:

1. Inline in sources.yaml via generalize: — produces a single-level geometry (n=0).
2. External catalog generalize_profiles_path: "./generalize-profiles.yaml" — multi-level profiles by BD TOPO type, with attribute-based dispatch (e.g. CL_ADMIN for TRONCON_DE_ROUTE) and fail-fast bounds at load time (iterations ∈ [0, 5], simplify ∈ [0, 0.001]).

Semantics of n: index in MpHeader.levels (0 = most detailed, emitted as Data0=). The ogr-polishmap driver serializes each bucket on a separate Data<n>= line.

See Step 2 — Configuration for the complete catalog schema and examples. The detailed catalog reference is available in Generalization Profiles.

Fail-fast constraints at load_config:

• Any routable layer (TRONCON_DE_ROUTE) must declare n: 0 in each visible branch (default + each when) — routing requires a Data0= to build the NET/NOD graph.
• Inline/external conflict on the same source_layer is rejected.
• max(n) across all profiles must be < header.levels.len() — otherwise imgforge silently drops out-of-range DataN.

Opt-out: mpforge build --disable-profiles bypasses only the external catalog (inline remains active).

YAML Configuration¶

mpforge uses a declarative YAML file to define the entire pipeline. This file consists of two distinct parts:

1. The sources configuration file — Defines inputs, the grid, output, header and processing options
2. The Garmin rules file — Defines attribute transformations (types, labels, zoom levels)

The rules file is referenced by the configuration file via the rules: directive.

Sources configuration file¶

Here is the complete structure, based on the production sources.yaml file:

version: 1

# Routable layer declaration (optional — see "Declarative routing" section)
routing:
  source_layer: TRONCON_DE_ROUTE
  rules: pipeline/configs/ign-bdtopo/routing-rules.yaml

grid:
  cell_size: 0.15       # ~16.5 km per tile (recommended for mkgmap/Garmin)
  overlap: 0.005        # Slight overlap to avoid edge artifacts

inputs:
  # Simple source with reprojection
  - path: "${DATA_ROOT}/TRANSPORT/TRONCON_DE_ROUTE.shp"
    source_srs: "EPSG:2154"
    target_srs: "EPSG:4326"

  # Source with geometry generalization
  - path: "${DATA_ROOT}/LIEUX_NOMMES/ZONE_D_HABITATION.shp"
    source_srs: "EPSG:2154"
    target_srs: "EPSG:4326"
    generalize:
      smooth: "chaikin"
      iterations: 1
      simplify: 0.00003

  # Wildcards + spatial filtering + attribute filter
  - path: "${CONTOURS_DATA_ROOT}/**/COURBE_*.shp"
    source_srs: "EPSG:2154"
    target_srs: "EPSG:4326"
    attribute_filter: "CAST(ALTITUDE AS INTEGER) = (CAST(ALTITUDE AS INTEGER) / 10) * 10"
    layer_alias: "COURBE"
    spatial_filter:
      source: "${DATA_ROOT}/ADMINISTRATIF/COMMUNE.shp"
      buffer: 500  # metres, in source SRS (EPSG:2154)

output:
  directory: "${OUTPUT_DIR}/mp/"
  filename_pattern: "BDTOPO-{col:03}-{row:03}.mp"
  overwrite: true
  base_id: ${BASE_ID}

header:
  name: "BDTOPO-{col:03}-{row:03}"
  copyright: "2026 Allfab Studio - IGN BDTOPO 2025"
  levels: "5"
  level0: "24"
  level1: "22"
  level2: "20"
  level3: "18"
  level4: "16"
  simplify_level: "0"
  tree_size: "1000"
  rgn_limit: "1024"
  lbl_coding: "9"
  routing: "Y"

# Reference to the Garmin rules file
rules: pipeline/configs/ign-bdtopo/departement/garmin-rules.yaml

error_handling: "continue"

# Bbox filter (WGS84) — optional
# filters:
#   bbox: [5.0, 44.6, 6.4, 45.9]

Per-source directives (inputs)¶

Each inputs entry can contain:

* path or connection, one of the two is required (not both).

Spatial filtering (spatial_filter)¶

For large sources (contour lines, DEM...), mpforge allows spatially filtering features by a reference geometry before tiling. This drastically reduces the volume of data processed.

inputs:
  - path: "${CONTOURS_DATA_ROOT}/**/COURBE_*.shp"
    source_srs: "EPSG:2154"
    target_srs: "EPSG:4326"
    spatial_filter:
      source: "${DATA_ROOT}/ADMINISTRATIF/COMMUNE.shp"  # Reference geometry
      buffer: 500                                         # Buffer in metres (source SRS)

The filter works by binary union (O(n log n)) of reference geometries, with envelope pre-rejection to optimize performance. Only features intersecting the resulting geometry (with buffer) are retained.

Geometry generalization (generalize)¶

mpforge integrates a generalization pipeline applied after clipping and before export. The generalize directive is a nested block within each source:

inputs:
  - path: "${DATA_ROOT}/LIEUX_NOMMES/ZONE_D_HABITATION.shp"
    source_srs: "EPSG:2154"
    target_srs: "EPSG:4326"
    generalize:
      smooth: "chaikin"       # Chaikin smoothing (corner-cutting)
      iterations: 1           # Number of smoothing passes
      simplify: 0.00003       # Douglas-Peucker tolerance (in degrees)

Environment variables¶

Configuration files support environment variables with the ${VAR} syntax. They are substituted before YAML parsing:

inputs:
  - path: "${DATA_ROOT}/TRANSPORT/TRONCON_DE_ROUTE.shp"

output:
  directory: "${OUTPUT_DIR}/tiles/"
  base_id: ${BASE_ID}   # Also works for numeric fields

# Variables are resolved at startup
DATA_ROOT=/data/bdtopo OUTPUT_DIR=/output BASE_ID=38 \
  mpforge build --config config.yaml --jobs 8

Only valid POSIX variable names are recognized ([A-Za-z_][A-Za-z0-9_]*). Undefined variables are left as-is — mpforge validate reports them as warnings.

Field mapping¶

BD TOPO data uses field names like MP_TYPE, NAME, MPBITLEVEL. The Polish Map format expects Type, Label, Levels. Field mapping bridges the gap:

# bdtopo-mapping.yaml
field_mapping:
  MP_TYPE: Type          # Garmin type code
  NAME: Label            # Object name
  Country: CountryName   # Country
  CityName: CityName     # Commune
  MPBITLEVEL: Levels     # Zoom levels

This separation into two files (config + mapping) allows reusing the same mapping for multiple configurations.

Header template¶

Each .mp tile needs a header with metadata (name, copyright, zoom levels). The header can be defined directly in the YAML or via an external template:

# Directly in the YAML
header:
  name: "BDTOPO-{col:03}-{row:03}"
  copyright: "2026 Allfab Studio"
  levels: "5"
  level0: "24"
  level1: "22"
  level2: "20"

# OR via an external template
header:
  template: "header_template.mp"

Garmin rules file¶

The rules file (garmin-rules.yaml) is a separate YAML file, referenced in the configuration via rules:. It defines how attributes from source features are transformed into Polish Map attributes (Garmin types, labels, zoom levels).

Structure¶

version: 1

rulesets:
  - name: "Roads"
    source_layer: "TRONCON_DE_ROUTE"
    rules:
      - match:
          CL_ADMIN: "Autoroute"
        set:
          Type: "0x01"
          EndLevel: "2"
          Label: "~[0x04]${NUMERO}"

      - match:
          CL_ADMIN: "Nationale"
          NATURE: "!Rond-point"
        set:
          Type: "0x04"
          EndLevel: "2"
          Label: "~[0x05]${NUMERO}"

Each ruleset targets a source layer (source_layer) and contains a list of rules evaluated in first-match-wins order: the first rule whose all match conditions are satisfied is applied.

Matching operators¶

Field substitution¶

In set values, the ${FIELD} syntax substitutes the source attribute value:

set:
  Label: "~[0x04]${NUMERO}"   # → "~[0x04]A7"
  Label: "${TOPONYME}"          # → "Mont Blanc"

Label case formatting (label_case)¶

The label_case option controls the case of labels written in MP files. It can be defined at the ruleset level (default for all rules) or at an individual rule level (ruleset override).

Garmin prefixes (~[0xNN]) are preserved: only the text part is transformed.

- name: "Toponymy"
  source_layer: "TOPONYMIE"
  label_case: "title"        # Default for the whole ruleset
  rules:
    - match:
        CLASSE: "Montagne"
      set:
        Type: "0x6616"
        Label: "${GRAPHIE}"
      label_case: "upper"    # Override: summits in uppercase

Declarative routing (routing-rules.yaml)¶

BDTOPO routing is fully declarative: a top-level routing: block in sources.yaml points to a dedicated routing-rules.yaml file, separate from the cartographic garmin-rules.yaml.

routing: block in sources.yaml¶

version: 1

routing:
  source_layer: TRONCON_DE_ROUTE
  rules: ../routing-rules.yaml

inputs:
  - path: "${DATA_ROOT}/{${ZONES}}/TRANSPORT/TRONCON_DE_ROUTE.shp"
    ...

routing-rules.yaml structure¶

The routing rules file uses the same format as garmin-rules.yaml (rulesets, first-match-wins), but targets Polish Map attributes specific to routing:

version: 1

rulesets:
  - name: speed_from_vit
    source_layer: TRONCON_DE_ROUTE
    rules:
      - match: { VIT_MOY_VL: "<10" }
        set: { Speed: "0" }
      - match: { VIT_MOY_VL: "range:45..60" }
        set: { Speed: "4" }
      - match: { VIT_MOY_VL: ">=95" }
        set: { Speed: "7" }
      - match: { VIT_MOY_VL: "*" }
        set: { Speed: "0" }

  - name: oneway_from_sens
    source_layer: TRONCON_DE_ROUTE
    rules:
      - match: { SENS: "Sens direct" }
        set: { Oneway: "1", DirIndicator: "1" }
      - match: { SENS: "Sens inverse" }
        set: { Oneway: "1", DirIndicator: "1", __reverse_geometry: "1" }
      - match: { SENS: "*" }
        set: { Oneway: "0", DirIndicator: "0" }

Available routing attributes in set:¶

__reverse_geometry pseudo-attribute¶

The special attribute __reverse_geometry: "1" in a set: block tells mpforge to reverse the polyligne coordinates before Polish Map encoding. It is used for SENS=Sens inverse BDTOPO segments, whose IGN geometry is oriented opposite to the allowed direction of travel.

- match: { SENS: "Sens inverse" }
  set: { Oneway: "1", DirIndicator: "1", __reverse_geometry: "1" }

This pseudo-attribute produces no entry in the .mp file — it only drives geometry reversal inside mpforge.

Production BDTOPO rulesets¶

The file pipeline/configs/ign-bdtopo/routing-rules.yaml contains 10 rulesets shared across all scopes (departement/, france-quadrant/, outre-mer/*/):

Supported sources¶

mpforge reads all GDAL/OGR file formats:

Installation¶

Pre-compiled binary (recommended)¶

The static binary includes PROJ 9.3.1, GEOS 3.13.0, GDAL 3.10.1 and the ogr-polishmap driver built-in. Zero configuration required:

# Download and extract the archive
wget https://github.com/allfab/garmin-img-forge/releases/download/mpforge-v0.9.0/mpforge-linux-amd64.tar.gz
tar xzf mpforge-linux-amd64.tar.gz

chmod +x mpforge
sudo mv mpforge /usr/local/bin/
mpforge --version

Compilation from sources¶

# Prerequisites: Rust 1.70+ and GDAL 3.0+
cd tools/mpforge
cargo build --release