imgforge — Le Compilateur Garmin¶

Le problème : un format binaire opaque¶

Le format Garmin IMG est un système de fichiers propriétaire contenant plusieurs sous-fichiers (TRE, RGN, LBL, NET, NOD, DEM...) encodés dans un format binaire non documenté publiquement. Jusqu'ici, deux outils savaient le produire :

• cGPSmapper — propriétaire, abandonné, Windows uniquement
• mkgmap — open-source mais écrit en Java, volumineux, lent sur les gros datasets

Mon objectif : un compilateur Garmin IMG natif en Rust, sans dépendance, capable de remplacer mkgmap tout en ajoutant des fonctionnalités modernes.

La solution : imgforge¶

imgforge est un binaire Rust autonome qui compile des fichiers Polish Map (.mp) en fichiers Garmin IMG. Il génère l'intégralité des sous-fichiers nécessaires :

Deux modes d'utilisation¶

compile : une tuile¶

# Compilation basique
imgforge compile tile_0_0.mp

# Avec options
imgforge compile tile_0_0.mp \
    --output ma_carte.img \
    --description "BDTOPO Réunion" \
    --latin1 \
    --reduce-point-density 5.0

build : carte complète (gmapsupp)¶

# Assembler toutes les tuiles en un gmapsupp.img
imgforge build tiles/ \
    --output gmapsupp.img \
    --jobs 8 \
    --family-id 4136 \
    --product-id 1 \
    --family-name "BDTOPO France" \
    --series-name "IGN BDTOPO 2026" \
    --area-name "France métropolitaine" \
    --country-name "France" \
    --country-abbr "FRA" \
    --product-version 100 \
    --copyright-message "IGN BDTOPO 2026" \
    --latin1 \
    --levels "24,20,16" \
    --reduce-point-density 3.0 \
    --min-size-polygon 8 \
    --typ-file bdtopo.typ \
    --dem ./srtm_hgt/ \
    --keep-going

La commande build est le coeur du pipeline de production. Elle :

1. Scanne le répertoire pour trouver tous les fichiers .mp
2. Compile chaque tuile en parallèle (rayon, N workers)
3. Assemble les tuiles compilées en un seul gmapsupp.img
4. Génère le fichier TDB compagnon
5. Intègre optionnellement le fichier TYP et les données DEM

Identité et métadonnées Garmin¶

La commande build accepte des options pour identifier la carte dans les logiciels Garmin (BaseCamp, MapInstall) :

Niveaux de zoom¶

L'option --levels définit la résolution en bits de chaque niveau de zoom :

# Format simple (bits par niveau, du plus détaillé au plus large)
imgforge build tiles/ --levels "24,20,16"

# Format explicite (niveau:bits)
imgforge build tiles/ --levels "0:24,1:20,2:16"

Voir la référence complète sur les niveaux de zoom pour le détail des correspondances EndLevel, l'impact sur la taille des fichiers et les recommandations.

Options de rendu supplémentaires :

Encodage des labels¶

Le format Garmin supporte trois encodages de labels, contrôlés par les options --latin1, --unicode ou --code-page :

Optimisation géométrique¶

imgforge propose des options pour réduire la taille des fichiers et améliorer les performances d'affichage sur GPS :

Simplification Douglas-Peucker¶

# Simplifier les lignes et polygones (seuil en map units)
imgforge build tiles/ --reduce-point-density 3.0

Réduit le nombre de points des géométries en éliminant les points qui ne contribuent pas significativement à la forme. Plus la valeur est élevée, plus la simplification est agressive.

Filtrage des petits polygones¶

# Supprimer les polygones dont l'aire < 8 map units²
imgforge build tiles/ --min-size-polygon 8

Élimine les micro-polygones invisibles à l'échelle du GPS (petits bâtiments, fragments de végétation...).

Simplification par résolution¶

En complément de --reduce-point-density (seuil global), --simplify-polygons permet un seuil Douglas-Peucker différent par résolution :

# Seuil DP adapté à chaque niveau de zoom (résolution:seuil)
imgforge build tiles/ --simplify-polygons "24:12,18:10,16:8"

Plus la résolution est basse (vue large), plus la simplification est agressive.

Découpage automatique des features volumineuses¶

imgforge découpe automatiquement les features de plus de 250 points pour éviter les débordements dans l'encodage RGN Garmin (delta variable-width) :

• Polylignes : découpées en segments de ≤250 points avec 1 point de recouvrement aux jointures
• Polygones : découpés par clipping Sutherland-Hodgman récursif le long de l'axe le plus long de la bounding box

Ce traitement est transparent — aucune option à configurer.

Contrôle du routing¶

imgforge gère trois modes de routing :

Par défaut, imgforge auto-détecte : si des routes avec RouteParam sont présentes dans les données, le routing complet est activé.

DEM / Hill Shading¶

imgforge génère le sous-fichier DEM Garmin pour l'ombrage du relief et les profils d'altitude directement sur le GPS :

# Depuis des fichiers HGT (SRTM)
imgforge build tiles/ --dem ./srtm_hgt/

# Depuis des fichiers ASC (BDAltiv2 IGN, Lambert 93)
imgforge build tiles/ --dem ./bdaltiv2/ --dem-source-srs EPSG:2154

# Avec contrôle de la résolution DEM et interpolation bicubique
imgforge build tiles/ --dem ./bdaltiv2/ \
    --dem-source-srs EPSG:2154 \
    --dem-dists 3,3,4,6,8,12,16,24,32 \
    --dem-interpolation bicubic

Formats d'élévation supportés¶

La reprojection est intégrée via proj4rs (zéro dépendance système) : Lambert 93, UTM, LAEA, Web Mercator et toute chaîne proj4 sont supportés.

Options DEM¶

Contrôler la taille du fichier avec --dem-dists¶

Le paramètre --dem-dists est le levier principal pour maîtriser la taille du fichier généré. Il contrôle la densité des points d'élévation encodés pour chaque niveau de zoom. Plus la valeur est grande, moins il y a de points d'élévation dans le fichier final.

Chaque valeur correspond à un niveau de zoom (dans l'ordre de --levels). Si vous fournissez moins de valeurs que de niveaux de zoom, les niveaux restants sont calculés automatiquement en doublant la dernière valeur.

Interpolation¶

• bilinear — Utilise 4 points voisins. Rapide, adapté aux données basse résolution (SRTM 3 arc-sec).
• bicubic — Utilise 16 points (Catmull-Rom). Produit un relief plus lisse, idéal pour les données haute résolution (BDAltiv2 25m). Retombe automatiquement sur bilinear en bord de grille.
• auto — Bilinéaire par défaut (recommandé).

Symbologie TYP¶

Un fichier .typ personnalise le rendu visuel de la carte sur le GPS (couleurs, motifs de remplissage, icônes) :

imgforge build tiles/ --typ-file bdtopo.typ

Le fichier TYP est intégré directement dans le gmapsupp.img final.

Résilience¶

En production, certaines tuiles peuvent contenir des données problématiques. L'option --keep-going permet de continuer la compilation malgré les erreurs :

imgforge build tiles/ --jobs 8 --keep-going

Les tuiles en erreur sont journalisées (warning) mais n'empêchent pas la génération des autres tuiles.

Installation¶

Binaire pré-compilé¶

# Télécharger et extraire l'archive
wget https://github.com/allfab/garmin-img-forge/releases/download/imgforge-v0.5.1/imgforge-linux-amd64.tar.gz
tar xzf imgforge-linux-amd64.tar.gz

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

Compilation depuis les sources¶

# Prérequis : Rust 1.70+ (pas besoin de GDAL !)
cd tools/imgforge
cargo build --release