Generalization Profiles Catalog¶

The generalize-profiles.yaml file is the central catalog for multi-level geometric generalization in mpforge. It declares, for each BD TOPO layer, how to simplify and smooth geometries at each Garmin map zoom level.

This file is referenced in sources.yaml via the directive:

generalize_profiles_path: "../generalize-profiles.yaml"

Why a profiles catalog?¶

The inline generalize: directive in sources.yaml produces a single simplified geometry (Data0=). The profiles catalog goes further: each feature carries multiple geometries according to zoom (Data0= detailed, Data2= simplified, etc.), which imgforge automatically selects for display.

Feature TRONCON_DE_ROUTE (motorway)
  └── Data0=  conservative VW geometry (max zoom)
  └── Data1=  medium VW
  └── Data2=  strong VW
  └── Data3=  ...
  └── Data4=
  └── Data5=
  └── Data6=  very aggressive VW (minimum zoom)

File structure¶

profiles:
  <SOURCE_LAYER>:          # GDAL layer name (e.g. TRONCON_DE_ROUTE)
    topology: true         # Optional — global topological simplification (absent = false)
    levels:                # Simple levels (without dispatch)
      - { n: 0, simplify: 0.00005 }
      - { n: 1, simplify: 0.00008 }
      ...
    when:                  # Conditional dispatch by attribute (optional)
      - field: CL_ADMIN
        values: [Autoroute, Nationale]
        levels:
          - { n: 0, simplify_vw: 0.000001 }
          ...

Level keys (levels[])¶

Tolerance reference¶

Level contiguity — critical rule¶

The n values declared in a profile must form a contiguous sequence from 0 to max(EndLevel) of the rules using that profile. Skipping an index (e.g. n=0 then n=2 without n=1) creates a gap in the Data0..DataN sections of the .mp that desynchronizes the RGN index on sensitive Garmin firmware.

mpforge automatically fills gaps after apply_profile (via fill_level_gaps in geometry_smoother.rs): the writer always emits contiguous DataN=, even if the YAML omitted some.

Topological simplification (topology: true)¶

Layers whose features share vertices at boundaries (adjacent municipalities, road intersections) use topology: true together with simplify_vw. The VW algorithm is preferred over DP (simplify) for these layers because its constraint on shared vertices is more compatible with topology, but simplify_vw can be used on any layer — it is not a technical constraint.

COMMUNE:
  topology: true
  levels:
    - { n: 0, simplify_vw: 0.00003 }
    - { n: 1, simplify_vw: 0.00007 }
    ...

Why? A tile-by-tile simplification would produce visual gaps at 4-tile crossings (yellow background between grey municipalities). mpforge runs a global pre-simplification (Phase 1.5) on all features before tiling, guaranteeing bit-exact boundaries in all adjacent tiles.

The Visvalingam-Whyatt algorithm (simplify_vw) is topologically constrained: it preserves vertices shared between neighboring features.

Conditional dispatch (when)¶

For layers with heterogeneous characteristics (e.g. TRONCON_DE_ROUTE mixing motorways and footpaths), attribute-based dispatch allows different tolerances depending on a field value:

TRONCON_DE_ROUTE:
  topology: true
  when:
    - field: CL_ADMIN
      values: [Autoroute, Nationale]
      levels:
        - { n: 0, simplify_vw: 0.000001 }
        - { n: 1, simplify_vw: 0.000002 }
        - { n: 2, simplify_vw: 0.000004 }
        - { n: 3, simplify_vw: 0.000008 }
        - { n: 4, simplify_vw: 0.000015 }
        - { n: 5, simplify_vw: 0.000030 }
        - { n: 6, simplify_vw: 0.000080 }
    - field: CL_ADMIN
      values: [Départementale]
      levels:
        - { n: 0, simplify_vw: 0.000003 }
        - { n: 1, simplify_vw: 0.000006 }
        - { n: 2, simplify_vw: 0.000010 }
        - { n: 3, simplify_vw: 0.000020 }
        - { n: 4, simplify_vw: 0.000040 }
        - { n: 5, simplify_vw: 0.000080 }
        - { n: 6, simplify_vw: 0.000200 }
    - field: CL_ADMIN
      values: [Communale, "Sans objet"]
      levels:
        - { n: 0, simplify_vw: 0.000005 }
        - { n: 1, simplify_vw: 0.000010 }
        - { n: 2, simplify_vw: 0.000018 }
        - { n: 3, simplify_vw: 0.000035 }
        - { n: 4, simplify_vw: 0.000070 }
        - { n: 5, simplify_vw: 0.000130 }
        - { n: 6, simplify_vw: 0.000300 }
    - field: CL_ADMIN
      values: [Chemin, Sentier]
      levels:
        - { n: 0, simplify_vw: 0.000010 }
        - { n: 1, simplify_vw: 0.000020 }
        - { n: 2, simplify_vw: 0.000035 }
        - { n: 3, simplify_vw: 0.000070 }
        - { n: 4, simplify_vw: 0.000130 }
        - { n: 5, simplify_vw: 0.000250 }
        - { n: 6, simplify_vw: 0.000550 }
  levels:
    # Default branch (features not matching any when branch above)
    - { n: 0, simplify_vw: 0.000005 }
    - { n: 1, simplify_vw: 0.000010 }
    - { n: 2, simplify_vw: 0.000018 }
    - { n: 3, simplify_vw: 0.000035 }
    - { n: 4, simplify_vw: 0.000070 }
    - { n: 5, simplify_vw: 0.000130 }
    - { n: 6, simplify_vw: 0.000300 }

Resolution follows first-match-wins: the first when branch whose field value is in the values list is applied. Any feature whose attribute matches no when branch falls into the root levels branch (default branch). Each branch must declare all levels n=0..6 — gaps are filled by fill_level_gaps but produce a discontinuous stepped simplification.

The production profiles table below indicates 5 branches for TRONCON_DE_ROUTE (4 when + 1 default branch).

Bifurcated catalogs by scope¶

The project maintains two distinct catalogs depending on the geographic scope of the build:

The simplification values (n=0..6) are identical between the two catalogs. Only topology differs. The france-quadrant catalog is referenced by its local sources.yaml via a direct relative path:

# pipeline/configs/ign-bdtopo/france-quadrant/sources.yaml
generalize_profiles_path: "generalize-profiles.yaml"   # local catalog

# pipeline/configs/ign-bdtopo/departement/sources.yaml
generalize_profiles_path: "../generalize-profiles.yaml" # shared catalog

Production BDTOPO profiles¶

Both catalogs cover 9 layers for the 7-level header 24/23/22/21/20/18/16:

Opting out of the catalog¶

To disable the external catalog without modifying the YAML (useful for debugging or comparing with a baseline):

# Via CLI
mpforge build --config config.yaml --disable-profiles

# Via environment variable
MPFORGE_PROFILES=off mpforge build --config config.yaml

Only the generalize_profiles_path catalog is disabled. Inline generalize: directives in sources.yaml remain active.

Going further¶

The mkgmap/imgforge comparison page analyzes the mkgmap r4924 filter chain (RoundCoordsFilter, SizeFilter, DouglasPeuckerFilter) by resolution, measures RGN bytes per level (mkgmap vs imgforge) on the reference BDTOPO-001-004 tile, and lists prioritized recommendations for reducing IMG size and aligning geometric smoothing.