Configuration POI (poiConfig)

Version: 2.0.0 Dernière mise à jour : mars 2026

---

Note v2.0.0 : poiConfig est défini dans profile.json (racine), et reste consommé directement par les modules POI/GeoJSON.

Description

Le paramètre poiConfig dans le fichier profile.json configure le comportement des Points d'Intérêt (POI), notamment le clustering des marqueurs sur la carte.

Localisation dans le code

• Lecture : src/modules/built-in/poi/, src/modules/built-in/geojson/loader/
• Utilisation : src/modules/built-in/poi/, src/modules/built-in/geojson/loader/

Structure minimale

{
    "poiConfig": {
        "clusterStrategy": "unified"
    }
}

Paramètres disponibles

clusterStrategy (requis)

Définit la stratégie de regroupement des marqueurs POI.

Valeurs possibles:

"unified" (recommandé)

Un seul cluster partagé pour tous les POI (JSON + GeoJSON).

Comportement:

• Tous les POI sont regroupés dans une seule source GeoJSON clusterisée
• Performance optimale
• Vue d'ensemble claire de la densité des POI

Quand utiliser: Pour la plupart des cas d'usage standard.

{
    "poiConfig": {
        "clusterStrategy": "unified"
    }
}

"by-source"

Un cluster séparé par type de source (JSON vs GeoJSON).

Comportement:

• Les POI JSON sont groupés ensemble
• Les POI GeoJSON sont groupés séparément
• Permet de distinguer visuellement les sources de données

Configuration complète:

{
    "poiConfig": {
        "clusterStrategy": "by-source",
        "sources": {
            "json": true,
            "geojson": true
        }
    }
}

Quand utiliser: Quand vous avez des sources de données distinctes à différencier visuellement.

"json-only"

Cluster uniquement pour les POI provenant de fichiers JSON.

Comportement:

• Les POI JSON sont groupés en clusters
• Les POI GeoJSON restent individuels (pas de clustering)
• Utile quand les données GeoJSON sont déjà agrégées

Configuration complète:

{
    "poiConfig": {
        "clusterStrategy": "json-only",
        "jsonClustering": true,
        "geojsonClustering": false
    }
}

Quand utiliser: Quand vos POI GeoJSON ne doivent pas être regroupés (déjà agrégés, faible densité, etc.).

Autres paramètres poiConfig

Ces paramètres sont également supportés par le module POI:

{
    "poiConfig": {
        "clusterStrategy": "unified",

        // Clustering
        "clustering": true, // Activer/désactiver le clustering (défaut: true)
        "clusterRadius": 80, // Rayon de regroupement en pixels (défaut: 80)
        "disableClusteringAtZoom": 18, // Niveau de zoom où le clustering s'arrête (défaut: 18)

        // Affichage
        "showIconsOnMap": true, // Afficher les icônes sur la carte (défaut: true)
        "showPopup": true, // Afficher les popups au clic (défaut: true)

        // Données
        "dataUrl": "path/to/poi.json", // URL des données POI (optionnel)
        "enabled": true, // Activer/désactiver le module POI (défaut: true)
    },
}

Exemples d'utilisation

Configuration minimaliste (recommandée)

{
    "poiConfig": {
        "clusterStrategy": "unified"
    }
}

Configuration avancée

{
    "poiConfig": {
        "clusterStrategy": "unified",
        "clustering": true,
        "clusterRadius": 100,
        "disableClusteringAtZoom": 16,
        "showIconsOnMap": true,
        "showPopup": true
    }
}

Désactiver le clustering complètement

{
    "poiConfig": {
        "clustering": false,
        "showIconsOnMap": true,
        "showPopup": true
    }
}

⚠️ Avertissement performance — Désactiver le clustering (clustering: false) avec un grand nombre de marqueurs peut entraîner une dégradation importante des performances de rendu.

Marqueurs	Clustering activé	Clustering désactivé
1 000	~56 FPS	~30 FPS
5 000	~56 FPS	~17 FPS
10 000	~56 FPS	~4 FPS

Au-delà de 1 000 marqueurs sans clustering, GeoLeaf émet un avertissement console [GeoLeaf PERF] pour signaler la dégradation potentielle. Le clustering est activé par défaut (clustering: true) et gère efficacement jusqu'à plusieurs dizaines de milliers de points via Supercluster (MapLibre natif).

Recommandation : n'utiliser clustering: false que pour des jeux de données de moins de 500 marqueurs, ou lorsque la densité géographique des POI garantit qu'ils ne se chevauchent pas.

Notes techniques

• Le code lit poiConfig.clusterStrategy avec fallback sur "unified" si non spécifié
• Les clusters sont gérés nativement par MapLibre GL JS (Supercluster) via cluster: true sur la source GeoJSON
• La stratégie peut être surchargée au niveau de chaque couche via les paramètres de layer.json
• L'objet clusterStrategies avec descriptions était uniquement documentaire et peut être supprimé du profile.json

Fichiers concernés

• src/modules/built-in/geojson/clustering.ts - Logique de stratégie de clustering
• src/modules/built-in/geojson/loader/clustering-setup.ts - Chargement et application du clustering
• src/modules/built-in/poi/core.ts - Initialisation du module POI
• src/modules/built-in/poi/markers.ts - Création des marqueurs
• src/modules/built-in/poi/shared.ts - État partagé incluant poiConfig

Historique

• 1.0.0: Ajout du support des stratégies de clustering multiples
• pre-1.0: Clustering unifié par défaut uniquement