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](#génération-de-rapports-html)
2. [Génération de cartes](#génération-de-cartes)
3. [Conversion HTML vers JPG](#conversion-html-vers-jpg)
4. [Récupération et analyse des données](#récupération-et-analyse-des-données)
5. [Workflow recommandé](#workflow-recommandé)
6. [Dépannage](#dépannage)
7. [Utilisation simplifiée avec Make](#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

```bash
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

```bash
# 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

```bash
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

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
pip install playwright
playwright install
```

#### Syntaxe

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
# 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

```bash
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** :
   ```bash
   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** :
   ```bash
   python present.py resultats_ville.json rapport_ville.html
   ```

3. **Générer une carte de la ville** :
   ```bash
   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) :
   ```bash
   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` :

```bash
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é** :
   ```bash
   pip install playwright
   playwright install
   ```

2. **Utilisez le script html2jpg.py** qui est plus robuste :
   ```bash
   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](https://www.openstreetmap.org/).

### Trouver l'ID OpenStreetMap d'une ville

1. Allez sur [OpenStreetMap](https://www.openstreetmap.org/)
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

```bash
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

```bash
# 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 :

```bash
# 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 :

```bash
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 :

```bash
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 :

```bash
make city CITY="Nom de la ville"
```

Exemple :
```bash
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 :

```bash
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 :

```bash
make all CITY="Paris"
```

#### Nettoyage

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

```bash
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.