Backend IArbre ¶

Aperçu¶

Le backend d'IArbre calcule l'occupation des sols et les différents indices (plantabilité, etc.). Le backend utilise Django et une base de données PostGIS.

Il existe trois applications Django :

• iarbre_data pour les calculs d’occupation des sols ;
• plantability pour le calcul de l'indice de plantabilité. Le développement correspond à une réplication de l'implémentation V1 réalisée par Exo-dev;
• api pour la génération de tuiles MVT qui vont pouvoir être servis par l'API REST.

Contenu¶

• Données requises
• Déploiement avec Ansible
• Installation manuelle
• Pipeline de plantabilité
• Génération de la base de données
• Gestion des sauvegardes de base de données
• Démarrage du backend
• Aide

Données requises¶

Un dossier nommé file_data contenant les données nécessaires qui ne sont pas sous license open-data (réseaux ENEDIS, GRDF, d'assainissement et d'eau potable, signalisation lumineuse et tricolore, etc) doit être présent à la racine du projet. Pour obtenir ces données pour la Métropole de Lyon, veuillez envoyer un e-mail à contact@telescoop.fr.

Déploiement avec Ansible¶

Consultez la documentation de déploiement pour plus de détails.

Installation manuelle¶

Ubuntu¶

Le backend nécessite GDAL et PostGIS.

Il s'installent via apt :

sudo apt install postgresql-14 postgresql-14-postgis-3 postgresql-server-dev-14 python3-psycopg2
sudo apt install binutils libproj-dev gdal-bin  # Pour les requêtes géographiques

macOS¶

Pour macOS, vous pouvez utiliser Homebrew pour installer les packages requis :

brew install postgresql postgis gdal

Initialisation de la base de données¶

Après l'installation, créez un utilisateur et une nouvelle base de données PostGIS :

1. Connectez-vous en tant que super-utilisateur postgres :

sudo -u postgres psql postgres

1. Créez un nouvel utilisateur et une base de données :

CREATE USER <nom_utilisateur> WITH PASSWORD 'votre_mot_de_passe_sécurisé';
ALTER USER <nom_utilisateur> WITH SUPERUSER CREATEDB;
CREATE DATABASE <nom_base_de_données> OWNER <nom_utilisateur>;
\q

1. Connectez-vous avec le nouvel utilisateur et activez PostGIS :

   psql -U <nom_utilisateur> <nom_base_de_données>
   CREATE EXTENSION postgis;
   \q
   

Installation des packages Python requis¶

Nous recommandons d'utiliser un environnement virtuel Python géré par pew :

pip install pew
cd <chemin>
pew mkproject <nom_projet>

Cela crée un nouvel environnement virtuel et un répertoire de projet associé dans <chemin>.

Ensuite, clonez le dépôt et installez les packages requis :

git clone https://github.com/TelesCoop/iarbre-back.git
pip install -r requirements.txt

Créez un fichier local_settings.ini, à la racine du dossier back, avec le contenu suivant :

[database]
engine=postgresql
user=<nom_utilisateur>
name=<nom_base_de_données>
password=votre_mot_de_passe_sécurisé

Pour travailler sur le projet à l'avenir, activez l'environnement :

pew workon <nom_projet>

Recover de la dernière version de DB¶

Dans le cas où tu fais parti de TelesCoop, tu peux récupérer directement la dernière version de la DB sur S3 avec :

python manage.py backup_db recover_db_and_media

Pipeline de plantabilité¶

Le pipeline orchestre l'ensemble des étapes de calcul du calque de plantabilité, de l'ingestion des données brutes jusqu'aux statistiques par ville et IRIS. Il est défini dans pipeline/plantability_pipeline.yaml et piloté par une commande Django dédiée.

Lancer le pipeline¶

Rappel — assurez-vous que les données nécessaires sont bien présentes dans file_data avant de lancer le pipeline. Si vous n'avez pas ces données, veuillez envoyer un e-mail à contact@telescoop.fr.

python manage.py migrate
python manage.py run_pipeline

Options¶

python manage.py run_pipeline --dry-run   # aperçu des étapes sans exécution
python manage.py run_pipeline --reset     # repart de zéro en ignorant l'état existant
python manage.py run_pipeline --config pipeline/plantability_pipeline.yaml  # config explicite
python manage.py run_pipeline --state /chemin/vers/state.json               # fichier d'état explicite

Reprise après échec¶

À chaque étape, le runner sauvegarde un fichier d'état JSON dans output/pipeline_calque_de_plantabilite_state.json. En cas d'échec, il suffit de relancer exactement la même commande : les étapes déjà terminées ("status": "completed") sont automatiquement ignorées et le pipeline reprend à partir de l'étape échouée.

python manage.py run_pipeline   # reprend depuis la dernière étape échouée

Étapes du pipeline¶

Le graphe de dépendances complet et les descriptions détaillées de chaque étape sont dans pipeline/plantability_pipeline.yaml.

Génération de la base de données¶

Les commandes ci-dessous correspondent aux étapes individuelles du pipeline. Pour une exécution complète, préférez utiliser python manage.py run_pipeline décrit dans la section précédente.

Pour plus de détails sur les données d'occupation des sols et leur traitement, consultez data_config.py.

Ajout des données de cadastre¶

La commande :

python manage.py import_cadastre

va permettre d'ajouter en base le cadastre, ce qui permettra plus tard de générer des MVT qui pourront être rajoutés en fond de carte.

Génération des calques de LCZ et vulnérabilité à la chaleur¶

Les données de zones climatiques locales et de vulnérabilité à la chaleur ont été généré par ailleurs. Les zones climatiques locales sont calculées par le CEREMA qui met les données à disposition sur data.gouv.fr.

python manage.py import_lcz

Permet de télécharger les données relatives au zones climatiques locales de la métropole de Lyon et les ajouter dans la DB.

python manage.py import_vulnerability

Permet d'ajouter en DB les résultats de l'étude menée par la Métropole de Lyon à partir du GeoPackage fourni. Les données, sans le détail des sous-facteurs, sont disponibles en open-data sur data.grandlyon.

Genération du calque de plantabilité raster¶

A partir des données géographiques d'occupation des sols de Data :

1. Conversion des données de Data pour tous les facteurs en raster haute résolution (1x1m)
2. Convolution des rasters, individuellement, avec un noyau carré 5x5. Le raster en résultat contiennent le pourcentage de chaque facteur sur des tuiles carrés 5x5m.
3. Somme pondérée des rasters, avec les poids relatifs aux facteurs, pour produire un raster de plantabilité.
4. Vectorisation : ronversion des pixels du raster de plantabilié en géométries pour insérer dans notre base PostGIS. Des carrés 5x5m vont être créés. On utilise les valeurs des pixels dans le raster de plantabilité pour remplir le champ correspondant à la plantabilité et à la plantabilité seuillée.

Le calcul est rapide, de l'ordre de 3h pour du 5x5m pour les 3 premières étapes. La dernière étape de vectorisation est la plus longue (~24h).

python manage.py data_to_raster
python manage.py compute_plantability_raster
python manage.py raster_plantability_to_geom

Génération des tuiles MVT¶

generate_mvt_files, génère des tuiles vectorielles Mapbox/MapLibre (MVT) pour différents niveaux de zoom. Ces tuiles sont accessibles via l'API et peuvent être affichées avec MapLibre.

python manage.py generate_mvt_files --geolevel tile --datatype plantability --number_of_threads 4

Gestion des sauvegardes de base de données¶

Sauvegarde de la base de données¶

Pour créer une sauvegarde de la base de données et des fichiers media sur S3 :

python manage.py backup_db backup_db_and_media --zipped

Cette commande utilise telescoop_backup pour créer une sauvegarde compressée avec un timestamp (format : YYYY-MM-DDTHH:MM_postgres_backup.dump).

Restauration de la base de données¶

Restaurer une version spécifique¶

Pour restaurer une version spécifique de la base de données, créez ou modifiez le fichier back/.db_recover_target avec le nom de la sauvegarde :

echo "2025-10-21T13:12_postgres_backup.dump" > back/.db_recover_target
cd back && python manage.py backup_db recover_db_and_media

Restaurer la dernière version¶

Si le fichier .db_recover_target n'existe pas, la commande restaurera automatiquement la dernière sauvegarde disponible :

make back_recover_db_and_media

Vous pouvez également ignorer le fichier .db_recover_target (s'il existe) et forcer l'utilisation de la dernière sauvegarde :

make back_recover_db_and_media USE_FILE=no

Liste des sauvegardes disponibles¶

Pour voir toutes les sauvegardes disponibles sur S3 :

make back_backup_list

Historique des sauvegardes¶

Consultez le fichier database_changelog.md pour voir l'historique détaillé de toutes les sauvegardes et leurs changements.

Déploiement¶

Lors du déploiement avec Ansible, le système :

• Vérifie si back/.db_recover_target existe
• Si oui : restaure la version spécifiée dans le fichier
• Si non : restaure la dernière sauvegarde disponible

Cela permet de contrôler précisément quelle version de la base de données est déployée en production.

Démarrage du service backend¶

python manage.py runserver --nostatic

Le backend est maintenant en cours d'exécution, et l'API est prête pour le frontend.

Générer le code coverage¶

coverage run manage.py test && coverage report

Cette commande va exécuter tous les tests et générer un report pour mesurer si toutes les lignes sont testées. Si il n'existe aucun test pour un script, ce script ne sera pas inclus dans le report.

Aide¶

🆘 Si vous rencontrez des problèmes ou avez des suggestions d'amélioration, veuillez ouvrir un nouvel issue sur notre page GitHub Issues.