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 :

Commandes disponibles¶

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 \
    --merge-lines

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 \
    --merge-lines \
    --typ-file bdtopo.typ \
    --dem ./srtm_hgt/ \
    --keep-going \
    --packaging legacy

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 :

Fusion de polylignes (--merge-lines)¶

L'option --merge-lines fusionne automatiquement les polylignes adjacentes partageant le même type Garmin et le même label. Sur les gros scopes (quadrants, France entière), elle divise par 2 à 3 le nombre de polylignes et réduit significativement la taille du fichier IMG :

imgforge build tiles/ --merge-lines

Format d'emballage (--packaging)¶

Le mode gmp réduit le nombre d'entrées FAT de 6 à 1 par tuile, ce qui allège le parsing du répertoire au démarrage sur les firmware NT modernes. Sur un build France entière (~1 500 tuiles), cela représente ~9 000 entrées FAT en legacy contre ~1 500 en gmp. Voir GMP — Format Garmin NT consolidé pour les détails techniques.

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.

Parité chaîne de filtres mkgmap¶

imgforge implémente la chaîne de filtres géométriques de mkgmap r4924 (normalFilters), appliquée à chaque niveau de zoom n>0 :

Ces filtres sont actifs par défaut. Les flags --no-* permettent de les désactiver individuellement pour mesurer leur impact ou reproduire une baseline sans filtrage :

# Mesurer l'impact de RoundCoordsFilter seul
imgforge build tiles/ --no-round-coords

# Baseline sans les trois filtres (comportement pré-parité mkgmap)
imgforge build tiles/ --no-round-coords --no-size-filter --no-remove-obsolete-points

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.

Gestion des fichiers TYP¶

La commande imgforge typ permet de convertir les fichiers TYP entre leur forme texte (lisible et éditable) et leur forme binaire (chargée par le GPS).

Compiler un TYP texte → binaire¶

# Depuis un fichier texte UTF-8 ou CP1252 (auto-détection du BOM)
imgforge typ compile mon-style.txt

# Spécifier l'encodage explicitement (CP1252 — sortie TYPViewer)
imgforge typ compile mon-style.txt --encoding cp1252

# Choisir le fichier de sortie
imgforge typ compile mon-style.txt --output mon-style.typ

Décompiler un TYP binaire → texte¶

# Sortie UTF-8 par défaut (avec BOM)
imgforge typ decompile bdtopo.typ

# Sortie CP1252 pour réimport dans TYPViewer
imgforge typ decompile bdtopo.typ --encoding cp1252 --output bdtopo.txt

Options¶

Installation¶

Binaire pré-compilé¶

# Télécharger et extraire l'archive
wget https://github.com/allfab/garmin-img-forge/releases/download/imgforge-v0.9.0/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