RoadTripsGenerator/README.md

*RoadTripsGenerator* (RTG) est un logiciel qui génère un site web statique de road-trips : une carte interactive par voyage et par jour, avec les photos, les vidéos, les traces GPS et le récit du voyage.

C'est sans prétention et il faudrait probablement des développements bien plus sérieux pour obtenir un logiciel « presse-bouton », mais si cela peut donner des idées…

Je me suis rendu compte que je passais des heures à monter des films de mes road-trips que finalement je ne regardais pas moi-même : trop longs mais pas assez d'infos, pas interactifs, etc. Je me suis donc demandé sous quelle forme présenter mes voyages pour pouvoir me les remémorer en famille et les partager. C'est comme cela que ce petit projet a vu le jour.

## Le principe

Pour chaque voyage, je dispose de photos et de vidéos géolocalisées (photos iPhone, films GoPro), des traces GPS de chaque journée et d'un récit écrit en Markdown.

RTG lit les positions GPS des photos et des vidéos, les placent sur une carte avec la trace du parcours découpée par jour, et construit des pages web où l'on peut, en parallèle, lire le récit du voyage. Voir par exemple mon [road-trip de l'été 2025](https://roadtrips.ouaibe.fr/Ete-2025/).

Il prépare aussi les médias pour le web :

* **vidéos** : un 720p H.264 lisible partout, chargé par défaut, et un 1080p HEVC proposé à la demande (environ 40 % plus léger que du H.264 à qualité égale) ;
* **photos** : une version allégée (1600 px, quelques centaines de Ko) affichée dans les diaporamas, le clic ouvrant l'original ;
* **aperçus** : une image tirée de chaque vidéo, affichée avant la lecture.

Les originaux ne sont jamais modifiés. Le site produit est statique : une simple copie suffit pour le publier ou le transporter.

## Installation

RTG fonctionne sous macOS et Linux ; Windows devrait fonctionner mais n'a pas encore été testé. Il lui faut :

| Élément | Rôle | Version |
| --- | --- | --- |
| Python | le logiciel lui-même | 3.10 ou plus récent |
| pipx | installe RTG et ses modules Python dans un espace à part | — |
| exiftool | lit les dates et positions GPS des photos et des vidéos | toute version récente |
| ffmpeg (avec libx265 et libx264) | compresse les vidéos, tire les images d'aperçu | 5 ou plus récent |

Les modules Python (folium, pandas, gpxpy, Pillow, pillow-heif…) sont installés automatiquement avec RTG.

### macOS

1. Installer [Homebrew](https://brew.sh) s'il n'est pas déjà là :
   ```
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
2. Installer les outils, puis rendre pipx accessible :
   ```
   brew install python pipx exiftool ffmpeg
   pipx ensurepath
   ```
3. Ouvrir une nouvelle fenêtre de Terminal (ou taper `source ~/.zshrc`, zsh étant le shell par défaut de macOS) : `pipx ensurepath` ajoute `~/.local/bin` au chemin des commandes, mais une fenêtre déjà ouverte ne le voit pas. Si `rtg` reste introuvable, c'est ce point.

Le ffmpeg de Homebrew contient libx265, libx264 et l'encodeur matériel VideoToolbox du Mac.

### Linux (Debian, Ubuntu et dérivées)

```
sudo apt install python3 pipx ffmpeg libimage-exiftool-perl
pipx ensurepath
```

Puis fermer et rouvrir le terminal. Sur Fedora : `sudo dnf install pipx perl-Image-ExifTool` et ffmpeg depuis RPM Fusion.

### Windows (non testé)

Dans PowerShell :

```
winget install Python.Python.3.12 Gyan.FFmpeg OliverBetz.ExifTool
py -m pip install --user pipx
py -m pipx ensurepath
```

Puis fermer et rouvrir PowerShell.

### Installer RTG

Récupérer le dépôt (ou le copier, par exemple sur un disque externe) :

```
git clone https://git.ouaibe.fr/Korrigan/RoadTripsGenerator.git
pipx install --editable ./RoadTripsGenerator
```

Avec `--editable`, la commande `rtg` utilise directement le code du dossier : une mise à jour du dépôt (`git pull`) est prise en compte sans réinstaller. Le dossier doit alors rester accessible (disque branché).

### Vérifier

```
rtg verifier
```

La commande contrôle Python, les modules, exiftool, ffmpeg et ses encodeurs, et donne pour chaque élément manquant la commande à taper sur votre système.

## Premiers pas

```
cd /Volumes/CLEROADTRIPS/Road-Trips
rtg interface
```

L'interface s'ouvre dans le navigateur. Laisser la fenêtre de Terminal ouverte pendant l'utilisation ; Ctrl+C l'arrête.

- **Site existant**, organisé à l'ancienne (avant RTG) : `rtg migrer` écrit une fois `site.toml` et un `voyage.toml` par voyage.
- **Nouveau site** : lancer `rtg interface` dans un dossier vide ; l'interface propose de créer le site.

**L'aide d'utilisation est dans l'interface** : un bouton « ? » sur chaque écran et chaque onglet, et la page « Aide » du menu. Elle est aussi lisible ici, dans [`rtg/interface/aide/`](rtg/interface/aide/index.md).

## Organisation des dossiers

Le dépôt et le site sont deux dossiers voisins. Un voyage est un dossier qui contient un `voyage.toml` (ou, à l'ancienne, un des sous-dossiers `photos`, `rushs` ou `routes`). Les voyages rangés à la racine du site forment la rubrique « Voyages » de la page d'accueil ; ceux rangés un niveau plus bas, dans un dossier de regroupement (ici `Balades`), forment une rubrique du nom de ce dossier.

```
CLEROADTRIPS
|-RoadTripsGenerator          ce dépôt
| |-rtg                       le logiciel (interface, pages, encodage…)
| |-exemples                  docker-compose, nginx, admin.sh
| |-Scripts                   anciens scripts
|-Road-Trips                  le site
  |-site.toml                 réglages du site
  |-Ete-2025
  | |-voyage.toml             sources, infos et réglages du voyage
  | |-voyage.md               le récit
  | |-routes                  une trace GPX par jour (écrite par RTG)
  | |-photos, photos_web      photos et versions allégées
  | |-videos, apercus         vidéos encodées et images d'aperçu
  |-Balades
    |-Aisne-06-2026
      |-...
```

Les sources (rushs, photos, traces d'origine) peuvent rester sur d'autres disques ; leurs chemins sont notés dans `voyage.toml`.

## Administration depuis le site : mise en place

Le bouton « Connexion » de l'accueil mène à l'interface, servie sous `/admin/` par le serveur web du site. Exemple avec le site servi par un conteneur nginx derrière Traefik, et l'interface lancée directement sur le Mac :

```
Traefik (HTTPS) → nginx (le site, dans Docker) → /admin/ → RTG sur le Mac (host.docker.internal:8765)
```

L'interface ne tourne qu'à la demande (`./admin.sh`, `./admin.sh stop`). Fermée, `/admin/` affiche « Administration fermée » et le site reste en ligne. Sur le Mac, elle voit tous les disques et encode à pleine vitesse. Son utilisation est décrite dans l'aide de l'interface.

1. **Mot de passe**, une fois : `rtg mot-de-passe` (10 caractères au moins).
2. **`docker-compose.yml`** du site : le service nginx doit pouvoir joindre le Mac, avec `extra_hosts: ["host.docker.internal:host-gateway"]`. Voir [`exemples/docker-compose.yml`](exemples/docker-compose.yml).
3. **`nginx.conf`** : ajouter le bloc `/admin/` et la page « Administration fermée », voir [`exemples/nginx-admin.conf`](exemples/nginx-admin.conf). Le `^~` de `location ^~ /admin/` est nécessaire si `nginx.conf` contient déjà une règle pour les `.js`, `.css` ou images.
4. `docker compose up -d --remove-orphans`.
5. **`admin.sh`** : copier [`exemples/admin.sh`](exemples/admin.sh) à côté du `docker-compose.yml`, puis `chmod +x admin.sh` et `./admin.sh`. L'interface tourne en arrière-plan ; son journal est dans `rtg-admin.log`.
6. Dans l'interface, **Réglages → Administration depuis le site** : `/admin/`, puis « Refaire l'accueil » pour faire apparaître le bouton « Connexion ».

Après une mise à jour de RTG : `./admin.sh stop`, puis `./admin.sh`.

**Variantes**

- **Interface dans un conteneur** : [`exemples/docker-compose-conteneur.yml`](exemples/docker-compose-conteneur.yml) et [`exemples/admin-docker.sh`](exemples/admin-docker.sh), avec le `Dockerfile` à la racine du dépôt. L'encodage y est plus lent : il n'a que les processeurs que Docker Desktop attribue, et pas l'encodeur matériel du Mac. Chaque disque des sources doit aussi être déclaré dans Docker Desktop (Réglages → Resources → File sharing). **Ne jamais déclarer `/Volumes` en entier** : avec le partage de la clé du site, Docker Desktop échoue (« mkdir /host_mnt/Volumes/…: file exists ») et nginx ne démarre plus. Le mot de passe se copie à côté du compose : `mkdir -p rtg-acces && cp ~/.config/rtg/acces.toml rtg-acces/`.
- **Traefik seul**, sans nginx : [`exemples/traefik-rtg-admin.yml`](exemples/traefik-rtg-admin.yml).
- **Autre machine du réseau** : `rtg interface --distant` (mot de passe obligatoire), de préférence en HTTPS (`--certificat`, `--cle`) ou par un tunnel SSH (`ssh -L 8765:127.0.0.1:8765 serveur`, puis l'adresse avec la clé affichée sur le serveur).

Le dossier du site étant publié tel quel, les `.toml` (chemins de vos disques) sont lisibles en ligne si le serveur web ne les refuse pas : la règle `location ~ \.toml$ { deny all; }` de l'exemple nginx s'en charge (Apache : `<FilesMatch "\.toml$"> Require all denied </FilesMatch>`).

## Commandes

Tout ce que fait l'interface existe aussi dans le Terminal, depuis le dossier du site (`Road-Trips`) ou avec `--racine CHEMIN`.

| Commande | Rôle |
| --- | --- |
| `rtg interface` | ouvrir l'interface dans le navigateur |
| `rtg generer [VOYAGE…]` | générer un, plusieurs ou tous les voyages, puis l'accueil |
| `rtg etat` | avancement de chaque voyage |
| `rtg analyser VOYAGE` | ce que RTG trouve dans les sources d'un voyage |
| `rtg compresser VOYAGE` | encoder les vidéos d'un voyage |
| `rtg accueil` | refaire l'accueil et la carte globale |
| `rtg migrer` | une fois : écrire `site.toml` et un `voyage.toml` par voyage d'après l'existant |
| `rtg verifier` | Python, exiftool et ffmpeg sont-ils bien installés ? |
| `rtg mot-de-passe` | définir le mot de passe de l'interface (`--tester`, `--supprimer`) |

### Options utiles

- `rtg generer --sans-compression` : sans encoder les vidéos.
- `rtg generer --force` : tout refaire, même ce qui est à jour.
- `rtg generer --mymaps-maj` : récupérer à nouveau les cartes Google My Maps.
- `rtg compresser VOYAGE --reglages-changes` : réencoder aussi les vidéos faites avec d'autres réglages que les actuels.
- `rtg compresser VOYAGE --seulement 1080p` (ou `720p`) : ne traiter qu'une version.
- `rtg compresser VOYAGE --force` : tout réencoder.
- `rtg interface --port 8765 --sans-navigateur` : autre port, sans ouvrir le navigateur.
- `rtg interface --proxy --prefixe /admin` : derrière le serveur web du site (mot de passe obligatoire).
- `rtg interface --arret-inactif 120` : s'arrêter après 120 minutes sans activité.
- `rtg interface --distant [--certificat cert.pem --cle cle.pem]` : accepter les connexions du réseau, mot de passe obligatoire, HTTPS conseillé.

Exemple : `rtg compresser Balades/Aisne-06-2026 --reglages-changes --seulement 1080p`.

## Fichiers de réglages

Tout ce que fait l'interface est noté dans deux fichiers texte au format TOML. On peut aussi les modifier à la main ; une réécriture par l'interface garde les valeurs mais pas les commentaires.

### site.toml (racine du site)

```toml
titre = "Nos Road-Trips"
adresse_publique = "https://roadtrips.ouaibe.fr/"
accueil_nb_recents = 2

[video]
qualite = "equilibree"      # econome | equilibree | haute
encodeur = "processeur"     # processeur | materiel
preset = "medium"
jobs = 0                    # 0 = automatique

[photos]
grand_cote = 1600
qualite = 80
positions_deduites = true

[journees]
fuseau = "Europe/Paris"
coupure_heure = 4

[carte_globale]
mymaps = ["https://www.google.com/maps/d/…"]

[administration]
adresse = "/admin/"         # bouton Connexion sur l'accueil

[confidentialite]
zones = [[48.80, 2.10, 500]]   # zones privées : latitude, longitude, rayon en m
```

### voyage.toml (un par voyage)

```toml
titre = "Été 2026"
moto = "BMW R 1300 GS Adventure"

[sources]
traces = ["routes"]
videos = ["/Volumes/LaCie/Perso/Gopro/Gopro-2026/Ete-2026"]
photos = ["photos"]

[video]                     # réglages vidéo propres au voyage (facultatif)
qualite = "econome"
preset = "slow"
crf_hevc = 28
crf_h264 = 27

[dates_traces]              # jours imposés aux traces
"Etape 3.gpx" = "2026-08-03"

[positions]                 # médias placés à la main
"IMG_4831.jpeg" = [48.85, 2.35]

[corrections]
masques = [[48.85, 2.35, 300]]   # zones retirées des traces de ce voyage
```

Un chemin relatif (comme `routes`) part du dossier du voyage.

## Publier

Le site est statique. Servi directement depuis son dossier (comme ici par nginx), il est en ligne dès la génération terminée. Sinon, il suffit de le copier : les sous-dossiers `rushs` (originaux, très lourds) et les fichiers `export_*.csv` sont inutiles en ligne ; `photos` reste nécessaire pour l'ouverture des originaux.

## Anciens scripts

Les scripts de `Scripts/` (`genere_site.sh`, `compress.sh`, `prepare_web.py`…) produisent le même site que RTG ; ils restent disponibles pendant la transition. Ils demandent d'installer à la main les modules Python : `pip3 install pandas folium gpxpy markdown2 numpy pillow`. `bench_crf.sh` mesure la qualité (VMAF ou SSIM) d'un extrait de rush à plusieurs CRF, pour choisir les réglages sur ses propres images.

La mise en page de RTG est dans `rtg/templates/` (pages des voyages, accueil, carte globale) et `rtg/interface/` (interface).

## Contribuer

### Pour pouvoir faire des push :

```
git remote set-url origin https://<nom d'utilisateur>@git.ouaibe.fr/Korrigan/RoadTripsGenerator.git
```

Pour éviter de retaper le mot de passe pendant une heure pour les autres push :

```
git config --global credential.helper 'cache --timeout=3600'
```