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. [Workflow recommandé](#workflow-recommandé)
5. [Dépannage](#dépannage)

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

## Workflow recommandé

Pour obtenir les meilleurs résultats, suivez ce workflow en deux étapes :

1. **Générer une carte HTML avec Folium** :
   ```bash
   python generate_city_map.py 1209165 -o carte_ville.html --folium
   ```

2. **Convertir la carte HTML en image JPG** :
   ```bash
   python html2jpg.py carte_ville.html -o carte_ville.jpg
   ```

Cette approche en deux étapes est plus robuste que la génération directe en JPG.

## 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.