parking-land/GUIDE_UTILISATION.md

Guide d'Utilisation Détaillé - Analyse Urbaine

Ce guide détaille l'utilisation des différents scripts disponibles dans ce projet d'analyse urbaine.

Table des matières

1. Génération de rapports HTML
2. Génération de cartes
3. Conversion HTML vers JPG
4. Récupération et analyse des données
5. Workflow recommandé
6. Dépannage
7. Utilisation simplifiée avec Make

Génération de rapports HTML

Le script present.py permet de générer des rapports HTML à partir de données JSON.

Syntaxe

python present.py <fichier_json> [fichier_html_sortie] [fichier_template]

Arguments

• <fichier_json> : Chemin vers le fichier JSON contenant les données (obligatoire)
• [fichier_html_sortie] : Chemin où sauvegarder le fichier HTML (par défaut: resultat.html)
• [fichier_template] : Nom du fichier template à utiliser (par défaut: template.html)

Exemples

# Utilisation basique
python present.py summary_results.json

# Spécifier le fichier de sortie
python present.py summary_results.json rapport_ville.html

# Utiliser un template personnalisé
python present.py summary_results.json rapport_ville.html template_ameliore.html

Génération de cartes

Plusieurs scripts sont disponibles pour générer des cartes de villes à partir de leur ID OpenStreetMap.

Script principal : generate_city_map.py

Ce script est un wrapper qui utilise soit OSMnx, soit Folium selon les options.

Syntaxe

python generate_city_map.py <osm_id> [options]

Arguments

• <osm_id> : ID OpenStreetMap de la ville (obligatoire)
• -o, --output : Chemin où sauvegarder l'image (par défaut: city_map.jpg)
• --folium : Utiliser Folium au lieu d'OSMnx (plus léger mais moins détaillé)
• -v, --verbose : Afficher les messages de débogage

Exemples

# Générer une carte avec OSMnx (haute qualité)
python generate_city_map.py 1209165 -o carte_ville.jpg

# Générer une carte avec Folium (plus léger, recommandé)
python generate_city_map.py 1209165 -o carte_ville.html --folium

Script alternatif : map_simple.py

Ce script utilise Folium pour générer des cartes interactives en HTML.

Syntaxe

python map_simple.py <osm_id> [options]

Arguments

• <osm_id> : ID OpenStreetMap de la ville (obligatoire)
• -o, --output : Chemin où sauvegarder la carte HTML (par défaut: city_map.html)
• -v, --verbose : Afficher les messages de débogage

Exemples

python map_simple.py 1209165 -o carte_ville.html

Script simplifié : simple_map.py

Version simplifiée qui utilise directement l'API Overpass pour récupérer les données.

Syntaxe

python simple_map.py <osm_id> [options]

Arguments

• <osm_id> : ID OpenStreetMap de la ville (obligatoire)
• -o, --output : Chemin où sauvegarder la carte HTML (par défaut: city_map.html)

Exemples

python simple_map.py 1209165 -o carte_ville.html

Fonds de carte disponibles

Les cartes générées utilisent par défaut le fond de carte Stamen Terrain qui offre une meilleure lisibilité et un rendu plus esthétique que le fond OpenStreetMap standard. Les cartes interactives incluent également un sélecteur de fonds de carte permettant de basculer entre :

• Stamen Terrain : fond topographique détaillé avec relief (par défaut)
• Stamen Toner : fond noir et blanc minimaliste, idéal pour l'impression
• Stamen Watercolor : fond artistique style aquarelle
• OpenStreetMap : fond standard d'OpenStreetMap

Pour changer de fond de carte, utilisez le contrôle de couches situé en haut à droite de la carte interactive.

Filtrage précis des éléments

Les scripts de génération de cartes utilisent désormais une méthode avancée pour récupérer uniquement les éléments (routes, bâtiments, parkings) qui se trouvent à l'intérieur du polygone de la ville, et non plus simplement dans une boîte englobante rectangulaire. Cela permet d'obtenir des cartes plus précises qui ne contiennent que les éléments appartenant réellement à la ville.

Cette fonctionnalité utilise l'opérateur area de l'API Overpass pour filtrer les éléments par leur appartenance géographique au polygone de la ville, ce qui donne des résultats beaucoup plus précis qu'un simple filtrage par coordonnées.

Note : Pour les points d'intérêt (nodes), un filtrage par boîte englobante est toujours utilisé, mais avec un rayon réduit.

Conversion HTML vers JPG

Deux scripts sont disponibles pour convertir les cartes HTML en images JPG.

Script recommandé : html2jpg.py

Ce script utilise Playwright pour rendre la page web et la capturer en image.

Prérequis

pip install playwright
playwright install

Syntaxe

python html2jpg.py <fichier_html> [-o output.jpg]

Arguments

• <fichier_html> : Chemin vers le fichier HTML à convertir (obligatoire)
• -o, --output : Chemin où sauvegarder l'image JPG (par défaut: nom_du_fichier.jpg)

Exemples

python html2jpg.py carte_ville.html -o carte_ville.jpg

Script alternatif : html_to_jpg.py

Ce script propose plusieurs méthodes de conversion.

Syntaxe

python html_to_jpg.py <fichier_html> [-o output.jpg] [-m méthode]

Arguments

• <fichier_html> : Chemin vers le fichier HTML à convertir (obligatoire)
• -o, --output : Chemin où sauvegarder l'image JPG (par défaut: nom_du_fichier.jpg)
• -m, --method : Méthode de conversion à utiliser (wkhtmltoimage, imgkit, cutycapt, selenium)

Exemples

python html_to_jpg.py carte_ville.html -o carte_ville.jpg -m selenium

Récupération et analyse des données

Script fetch.py

Le script fetch.py permet de récupérer les données OpenStreetMap pour une ville et d'exécuter automatiquement l'analyse avec compute.py.

Syntaxe

python fetch.py <id_ou_nom_ville> [options]

Arguments

• <id_ou_nom_ville> : Identifiant OpenStreetMap de la ville ou nom de la ville (obligatoire)
• --no-compute : Ne pas exécuter compute.py après la récupération des données
• --output, -o : Fichier de sortie pour les résultats de compute.py (défaut: summary_results.json)
• --verbose, -v : Afficher plus d'informations pendant l'exécution

Exemples

# Utilisation avec un ID OpenStreetMap
python fetch.py 1209165

# Utilisation avec un nom de ville
python fetch.py "Briis-sous-Forges"

# Spécifier le fichier de sortie
python fetch.py "Paris" -o paris_results.json

# Récupérer les données sans exécuter l'analyse
python fetch.py "Lyon" --no-compute

Fonctionnement

Le script effectue les opérations suivantes :

1. Si un nom de ville est fourni, il utilise find_city_osm_id.py pour rechercher l'ID OpenStreetMap correspondant
2. Il récupère les données OpenStreetMap pour la ville et les sauvegarde dans overpass_data.json
3. Par défaut, il exécute automatiquement compute.py pour analyser les données
4. Les résultats de l'analyse sont sauvegardés dans le fichier spécifié (par défaut: summary_results.json)
5. Un résumé des résultats est affiché à l'écran

Script compute.py

Le script compute.py analyse les données OpenStreetMap récupérées par fetch.py et génère des statistiques.

Syntaxe

python compute.py [options]

Fonctionnement

Le script lit le fichier overpass_data.json généré par fetch.py et calcule diverses statistiques :

• Longueur totale des routes
• Surface des routes
• Nombre et surface des bâtiments
• Nombre et capacité des parkings
• Longueur des pistes cyclables
• Nombre de stations de recharge

Les résultats sont sauvegardés dans le fichier summary_results.json qui peut ensuite être utilisé par present.py pour générer un rapport HTML.

Workflow recommandé

Pour une analyse complète d'une ville, suivez ce workflow :

1. Récupérer les données et effectuer l'analyse :

   python fetch.py "Nom de la ville" -o resultats_ville.json
   

   Cette commande va :

   • Rechercher l'ID OpenStreetMap de la ville
   • Récupérer les données OpenStreetMap
   • Exécuter l'analyse avec compute.py
   • Sauvegarder les résultats dans resultats_ville.json

2. Générer un rapport HTML :

   python present.py resultats_ville.json rapport_ville.html
   

3. Générer une carte de la ville :

   python find_city_osm_id.py "Nom de la ville" -o carte_ville.html
   

4. Convertir la carte HTML en image JPG (si nécessaire) :

   python html2jpg.py carte_ville.html -o carte_ville.jpg
   

Cette approche en quatre étapes permet d'obtenir à la fois un rapport détaillé et une carte visuelle de la ville analysée.

Dépannage

Problèmes avec OSMnx

Si vous rencontrez des erreurs avec OSMnx, utilisez l'option --folium :

python generate_city_map.py <osm_id> -o carte_ville.html --folium

Problèmes avec la conversion HTML vers JPG

1. Vérifiez que Playwright est installé :

   pip install playwright
   playwright install
   

2. Utilisez le script html2jpg.py qui est plus robuste :

   python html2jpg.py carte_ville.html -o carte_ville.jpg
   

3. Alternative manuelle : Ouvrez le fichier HTML dans un navigateur et prenez une capture d'écran.

ID OpenStreetMap invalide

Si l'ID OpenStreetMap ne fonctionne pas, vérifiez qu'il s'agit bien d'une relation, d'un way ou d'un node valide sur OpenStreetMap.

Trouver l'ID OpenStreetMap d'une ville

1. Allez sur OpenStreetMap
2. Recherchez la ville souhaitée
3. Cliquez sur la ville dans les résultats
4. L'URL contiendra l'ID, par exemple : https://www.openstreetmap.org/relation/123456
5. L'ID est le nombre après "relation/" (ici, 123456)

Recherche automatique d'ID OpenStreetMap

Le script find_city_osm_id.py permet de rechercher automatiquement l'identifiant OpenStreetMap d'une ville à partir de son nom.

Syntaxe

python find_city_osm_id.py <nom_ville> [options]

Arguments

• <nom_ville> : Nom de la ville à rechercher (obligatoire)
• -c, --country : Code pays pour filtrer les résultats (ex: fr, be, ch)
• -l, --limit : Nombre maximum de résultats à afficher (défaut: 5)
• -r, --relation-only : Afficher uniquement les IDs de relation
• -j, --json : Afficher les résultats au format JSON
• -g, --generate-map : Générer automatiquement une carte pour le premier résultat (actif par défaut)
• -ng, --no-generate-map : Ne pas générer automatiquement de carte
• -o, --output : Chemin où sauvegarder la carte générée (défaut: carte_ville.html)
• --no-folium : Utiliser OSMnx au lieu de Folium pour la génération de carte
• -v, --verbose : Afficher les messages de débogage

Exemples

# Recherche simple avec génération automatique de carte
python find_city_osm_id.py "Briis-sous-Forges"

# Filtrer par pays (France) sans génération de carte
python find_city_osm_id.py "Paris" -c fr -ng

# Recherche avec génération de carte et spécification du fichier de sortie
python find_city_osm_id.py "Lyon" -c fr -o lyon_carte.html

# Recherche avec génération de carte en utilisant OSMnx au lieu de Folium
python find_city_osm_id.py "Marseille" -c fr --no-folium -o marseille_carte.jpg

Fonctionnement

Le script utilise l'API Nominatim d'OpenStreetMap pour rechercher les villes correspondant au nom fourni. Pour chaque résultat, il affiche :

1. Le nom de la ville et son type (city, town, village, etc.)
2. Sa localisation (département, région, pays)
3. Son identifiant OpenStreetMap et son type (node, way, relation)
4. L'URL pour accéder à la ville sur OpenStreetMap

Si le résultat n'est pas déjà une relation, le script recherche automatiquement l'identifiant de relation associé en utilisant l'API Overpass.

Génération automatique de carte

Par défaut, le script génère automatiquement une carte HTML avec Folium pour le premier résultat trouvé. Cette fonctionnalité peut être désactivée avec l'option -ng ou --no-generate-map.

Le processus de génération de carte est le suivant :

1. Le script trouve l'ID OpenStreetMap de la ville
2. Si l'élément n'est pas une relation, il recherche l'ID de relation associé
3. Il exécute automatiquement generate_city_map.py avec l'ID trouvé
4. La carte est générée au format HTML (par défaut) ou JPG (si --no-folium est spécifié)
5. Le chemin vers la carte générée est affiché

Si la carte est générée au format HTML, le script suggère également la commande pour la convertir en JPG avec html2jpg.py.

Workflow tout-en-un

Ce script simplifie considérablement le workflow en permettant de passer directement du nom d'une ville à une carte générée en une seule commande :

# Rechercher une ville, générer sa carte HTML et la convertir en JPG
python find_city_osm_id.py "Briis-sous-Forges" -c fr -o briis.html && python html2jpg.py briis.html -o briis.jpg

Cette approche est beaucoup plus simple que de rechercher manuellement l'ID OpenStreetMap de la ville, puis d'exécuter séparément les scripts de génération de carte.

Utilisation simplifiée avec Make

Un Makefile est disponible pour simplifier l'installation et l'utilisation du projet. Cette approche est recommandée pour les utilisateurs qui souhaitent une solution clé en main.

Installation avec Make

Pour installer l'environnement virtuel et toutes les dépendances nécessaires :

make setup

Cette commande va :

• Créer un environnement virtuel Python
• Installer toutes les dépendances requises depuis requirements.txt
• Installer et configurer Playwright pour la conversion HTML vers JPG

Après l'installation, activez l'environnement virtuel :

source venv/bin/activate

Commandes disponibles

Analyse d'une ville

Pour récupérer les données, effectuer l'analyse et générer une carte pour une ville :

make city CITY="Nom de la ville"

Exemple :

make city CITY="Paris"

Cette commande exécute automatiquement :

1. fetch.py pour récupérer les données OpenStreetMap
2. find_city_osm_id.py pour générer une carte HTML
3. html2jpg.py pour convertir la carte en image JPG

Les fichiers générés seront :

• Paris_results.json : Résultats de l'analyse
• Paris_carte.html : Carte HTML interactive
• Paris_carte.jpg : Image de la carte

Génération d'un rapport HTML

Pour générer un rapport HTML à partir des résultats d'analyse :

make report CITY="Paris"

Cette commande utilise present.py pour générer un rapport HTML à partir du fichier Paris_results.json.

Analyse complète

Pour effectuer l'analyse complète (données, carte et rapport) en une seule commande :

make all CITY="Paris"

Nettoyage

Pour supprimer tous les fichiers temporaires et l'environnement virtuel :

make clean

Avantages de l'utilisation de Make

• Simplicité : Une seule commande pour effectuer plusieurs opérations
• Cohérence : Nommage cohérent des fichiers de sortie
• Environnement isolé : Utilisation d'un environnement virtuel pour éviter les conflits de dépendances
• Automatisation : Enchaînement automatique des différentes étapes du workflow

Cette approche est particulièrement recommandée pour les utilisateurs qui souhaitent analyser plusieurs villes ou qui utilisent régulièrement le projet.