GeoLeaf.Route — Documentation du module Route (Itinéraires / GPX)

Product Version: GeoLeaf Platform V2 — Version doc: 2.0.0

Fichier source : packages/core/src/modules/geoleaf.route.tsImplémentation : packages/core/src/modules/optional/route/route-api.tsDernière mise à jour : mars 2026

---

Module optionnel / lazy-loaded — Le module Route est chargé à la demande. Il ne fait pas partie du bundle core lite (bundle-core-lite-entry.ts). Une façade lite geoleaf.route-lite.ts est disponible pour les cas minimalistes.

---

Le module GeoLeaf.Route gère l'affichage des itinéraires dans GeoLeaf sur une carte MapLibre GL JS.

Les itinéraires sont rendus comme des sources/layers GeoJSON de type LineString dans MapLibre GL JS. Le module prend en charge :

• itinéraires depuis des fichiers GPX (URL)
• itinéraires depuis des coordonnées ou un objet GeoJSON
• itinéraires depuis la configuration JSON du profil (routes[])
• gestion de plusieurs segments
• waypoints (points de départ/arrivée)
• fitBounds automatique
• styles personnalisés par itinéraire
• visibilité filtrée par ID

---

1. Rôle fonctionnel de GeoLeaf.Route

1. Charger et afficher des itinéraires linéaires sur une carte MapLibre GL JS via des layers LineString.
2. Permettre plusieurs modes de chargement : GPX, GeoJSON, coordonnées, configuration de profil.
3. Convertir automatiquement les données en layers MapLibre GL JS (addSource + addLayer).
4. Proposer un style par défaut personnalisable.
5. Centrer automatiquement la carte (fitBounds) si demandé.
6. Gérer les endpoints (marqueurs de départ/arrivée) configurable par profil.

---

2. API publique de GeoLeaf.Route

Méthode	Rôle
init(options)	Initialise le module Route (mode MapLibre)
loadGPX(url)	Charge un itinéraire depuis un fichier GPX
loadGeoJSON(geojson)	Charge un itinéraire depuis un objet GeoJSON
loadFromConfig(routes)	Charge plusieurs itinéraires depuis un profil
clear()	Supprime tous les layers d'itinéraires
show()	Affiche tous les layers d'itinéraires
hide()	Masque tous les layers d'itinéraires
toggleVisibility()	Bascule la visibilité
filterVisibility(filteredRoutes)	Filtre la visibilité par IDs de routes
getLayer()	Retourne la référence du groupe de couches
isInitialized()	Indique si le module est initialisé
isVisible()	Indique si les itinéraires sont visibles

---

3. GeoLeaf.Route.init(options)

Initialise le module et prépare le moteur de rendu MapLibre GL JS.

GeoLeaf.Route.init({
    fitBoundsOnLoad: true,
    lineStyle: {
        color: "#1E88E5",
        weight: 4,
        opacity: 0.9,
    },
});

3.1 Paramètres

Paramètre	Type	Défaut	Description
map	object	auto	Instance de carte (facultatif si GeoLeaf.Core est actif)
lineStyle	object	voir ci-dessous	Style par défaut appliqué aux itinéraires
waypointStyle	object	voir ci-dessous	Style des points de passage
fitBoundsOnLoad	boolean	true	Recentre automatiquement la carte après chargement
maxZoomOnFit	number	14	Zoom maximum lors du fitBounds (entre 1 et 20)
showStart	boolean	true	Affiche le marker de départ
showEnd	boolean	true	Affiche le marker d'arrivée

Style de ligne par défaut :

{
    color: "#1E88E5",
    weight: 4,
    opacity: 0.9,
    interactive: false
}

Style des waypoints par défaut :

{
    radius: 5,
    color: "#0D47A1",
    fillColor: "#42A5F5",
    fillOpacity: 0.9,
    weight: 2
}

3.2 Comportement

• Détecte automatiquement le moteur MapLibre via GeoLeaf.Core.getAdapter().
• Initialise le mode MapLibre (sources + layers GeoJSON LineString).
• Log une erreur si l'adapter MapLibre n'est pas disponible.

---

4. GeoLeaf.Route.loadGPX(url)

Charge un itinéraire depuis un fichier GPX externe.

GeoLeaf.Route.loadGPX("./data/circuit1.gpx");

4.1 Paramètres

Paramètre	Type	Obligatoire	Description
url	string	oui	Chemin du fichier GPX

Retour : Promise<void>

4.2 Comportement

1. Télécharge le GPX via fetch (avec FetchHelper si disponible : timeout 15s, retry 2 fois).
2. Parse le XML → extraction des <trkpt> (lat/lon).
3. Construit un GeoJSON LineString avec les coordonnées [lng, lat] (convention MapLibre).
4. Ajoute un layer MapLibre via adapter.addGeoJSONLayer().
5. Si fitBoundsOnLoad = true : appelle map.fitBounds().

4.3 Gestion des erreurs

• GPX invalide → log [GeoLeaf.Route] Erreur GPX
• URL inaccessible → fallback silencieux
• Aucun plantage de l'application

---

5. GeoLeaf.Route.loadGeoJSON(geojson)

Charge un itinéraire à partir d'un objet GeoJSON.

GeoLeaf.Route.loadGeoJSON({
    type: "Feature",
    geometry: {
        type: "LineString",
        coordinates: [
            [-60.65, -32.95],
            [-60.6, -32.96],
            [-60.58, -32.97],
        ],
    },
    properties: { name: "Circuit Nord" },
});

Note : les coordonnées GeoJSON sont en format [longitude, latitude] (convention GeoJSON/MapLibre).

5.1 Paramètres

Paramètre	Type	Obligatoire	Description
geojson	object	oui	Feature ou FeatureCollection GeoJSON

---

6. GeoLeaf.Route.loadFromConfig(routes)

Charge plusieurs itinéraires depuis un tableau de configuration (typiquement issu du profil JSON).

GeoLeaf.Route.loadFromConfig([
    {
        id: "circuit-nord",
        label: "Circuit Nord",
        coordinates: [
            [-32.95, -60.65],
            [-32.96, -60.6],
        ],
        style: { color: "#E53935" },
    },
    {
        id: "circuit-sud",
        gpx: "./data/circuit-sud.gpx",
        style: { color: "#43A047" },
    },
]);

6.1 Paramètres — objet RouteItem

Propriété	Type	Description
id	string	Identifiant unique de la route
label/name	string	Nom affiché dans le tooltip/popup
geometry	[lat, lng][] | GeoJSONLineString | GeoJSONMultiLineString	Géométrie de l'itinéraire
gpx	string	URL du fichier GPX
geojson	object	GeoJSON LineString ou Feature
style	object	Surcharge du style de la ligne

6.2 Comportement

• Appelle clear() avant de charger les nouveaux itinéraires.
• Pour chaque route, crée un layer MapLibre LineString (route-{id}).
• Crée un layer endpoints (route-{id}-endpoints) si showStart/showEnd sont actifs.
• Résout le style via le profil actif et defaultSettings.routeConfig.default.

---

7. GeoLeaf.Route.clear()

Supprime tous les layers d'itinéraires de la carte MapLibre.

GeoLeaf.Route.clear();

• Retire chaque layer (ligne + endpoints) via adapter.removeLayer().
• Réinitialise _routeLayerIds.
• Utile pour recharger de nouveaux itinéraires.

---

8. GeoLeaf.Route.show() / hide() / toggleVisibility()

Contrôle la visibilité de tous les layers d'itinéraires.

GeoLeaf.Route.show();
GeoLeaf.Route.hide();
GeoLeaf.Route.toggleVisibility();

---

9. GeoLeaf.Route.filterVisibility(filteredRoutes)

Affiche uniquement les routes dont les IDs sont dans le tableau fourni.

GeoLeaf.Route.filterVisibility([{ id: "circuit-nord" }, { id: "circuit-est" }]);

Paramètres :

Paramètre	Type	Description
filteredRoutes	Array<{ id: string }>	Tableau des routes à afficher

Toutes les routes non présentes dans le tableau sont masquées via adapter.hideLayer().

---

10. GeoLeaf.Route.getLayer()

Retourne la référence au groupe de couches (ou null en mode MapLibre pur).

const routeLayer = GeoLeaf.Route.getLayer();

---

11. Style des itinéraires

Le style d'une ligne MapLibre accepte les attributs suivants :

{
    color: "#ff5500",     // Couleur de la ligne
    weight: 4,            // Épaisseur (pixels)
    opacity: 0.9,         // Opacité (0-1)
    dashArray: "4, 8"     // Pointillés (optionnel)
}

Exemple avec style personnalisé

GeoLeaf.Route.init({
    lineStyle: {
        color: "#00cc88",
        weight: 3,
        dashArray: "6, 6",
        opacity: 0.8,
    },
    fitBoundsOnLoad: true,
});

---

12. FitBounds automatique

Lorsque fitBoundsOnLoad: true (défaut), la carte se recentre automatiquement sur les bounds de l'itinéraire après chargement.

GeoLeaf.Route.init({ fitBoundsOnLoad: true, maxZoomOnFit: 14 });
GeoLeaf.Route.loadGPX("./data/route.gpx");
// → La carte se recentre sur l'itinéraire, zoom max = 14

---

13. Intégration avec la configuration JSON

Exemple de profil geoleaf.config.json :

{
    "route": {
        "enabled": true,
        "fitBoundsOnLoad": true,
        "routes": [
            {
                "id": "circuit1",
                "label": "Circuit principal",
                "gpx": "./data/circuit1.gpx",
                "style": { "color": "#1E88E5", "weight": 4 }
            }
        ]
    }
}

Exemple d'intégration en boot :

const config = GeoLeaf.Config.get("route");

if (config?.enabled) {
    GeoLeaf.Route.init({ fitBoundsOnLoad: config.fitBoundsOnLoad });
    if (config.routes?.length) {
        GeoLeaf.Route.loadFromConfig(config.routes);
    }
}

---

14. Séquence typique d'utilisation

1. GeoLeaf.Config charge le JSON de profil
2. GeoLeaf.Core.init() crée la carte MapLibre GL JS
3. GeoLeaf.Baselayers.init() installe la basemap
4. GeoLeaf.POI.init() charge les POI
5. GeoLeaf.Route.init() prépare le module route (détecte l'adapter MapLibre)
6. GeoLeaf.Route.loadFromConfig() ou .loadGPX() ou .loadGeoJSON()
7. GeoLeaf.LayerManager.init() complète l'interface

---

15. Bonnes pratiques

• Toujours appeler init() avant tout chargement de route.
• Éviter les GPX très lourds → simplifier la trace si > 10 000 points.
• Activer fitBoundsOnLoad pour une UX optimale.
• Utiliser filterVisibility() plutôt que clear() + rechargement si les routes sont déjà chargées.
• Préparer une structure de données claire :
  • properties.name — nom de l'itinéraire
  • properties.difficulty — niveau de difficulté
  • properties.duration — durée estimée