From 466ada80add412901a435e458c92944ca2147feb Mon Sep 17 00:00:00 2001 From: Lucas MATHIEU Date: Wed, 26 Jun 2024 01:17:35 +0200 Subject: [PATCH] Add global project description to README + french version --- README.md | 95 ++++++++++++++++++++++++++++++++++++++- README_fr.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++ requirements.txt | 6 +++ 3 files changed, 212 insertions(+), 2 deletions(-) create mode 100644 README_fr.md create mode 100644 requirements.txt diff --git a/README.md b/README.md index c49d8f8..e4e09e9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,96 @@ # video2geoframes.py -Python script to generate a collection of geotagged images from a video and a GPS track. +![Gitea Release](https://img.shields.io/gitea/v/release/lumathieu/video2geoframes.py?gitea_url=https%3A%2F%2Fgit.luc-geo.fr&include_prereleases&sort=semver&display_name=tag) -Designed for contribution to street-level imagery projects like Mapillary or Panoramax. \ No newline at end of file +_🇬🇧 version_ / [_🇫🇷 version here_]() + +Python program to generate a collection of geotagged images from a video and a GPS track. + +Designed for ease contribution to street-level imagery projects like Mapillary or Panoramax. + +## Quick start + +Nothing simpler : collect your video, your GPS track, execute Python script and follow the guide ! + +In detail, the program is built around a TUI or _Textual User Interface_, permitting to launch video process easily with +step-by-step parameters input. + +Input is guided by textual help indicating attempted values. + +Before script starting, you need to have : +* a video file with exact timestamp (start) in local time or UTC +* a clean GPS tack file covering video duration +* a working directory. + +## Documentation + +_Coming soon._ + +## Features + +_Coming soon._ + +### Comparison v1 / v2 + +| Features | v1-beta | v2-alpha9 | +|-----------------------------|------------|------------| +| Timelapse video support | ✔️ | ✔️ | +| EXIF tags writing | ✔️ | ✔️ | +| Extended tags support | ✔️ | ❌ | +| Milliseconds support | ✔️ | ✔️ | +| Progress displaying | 🟡 raw | ✔️ | +| Multilingual TUI 🇺🇳 | 🟡 limited | ✔️ | +| Configuration customization | ❌ | 🟡 partial | +| JPEG qualtiy customization | ❌ | 🔄 planned | +| TOML setting | ❌ | 🔄 planned | + +## Languages + +TUI is multilingual thanks to "locales" base in the form of TOML files (`locales/*.toml`) easily extensible. + +| Languages | Locale | Support | Maintainer | +|--------------|---------|------------|--------------| +| 🇺🇸 English | `en_us` | ✔️ 100 % | @lumathieu | +| 🇫🇷 French | `fr_fr` | ✔️ 100 % | @lumathieu | +| 🇮🇹 Italian | `it_it` | 🔄 planned | @lumathieu ? | + +## Versions + +See [_Releases_](https://git.luc-geo.fr/lumathieu/video2geoframes.py/releases). + +## Setup + +To set up program, be enough to clone Git repository, set up software dependencies and build Python environnement. +Recommended to use a virtual environnement (venv). + +### Python + +Entire project is developed and tested on **Python 3.11** (Windows x86-64). + +### Dépendances + +Core script uses following Python libraries (see also `requirements.txt`) : +- `numpy` +- `opencv-python` +- `piexif` +- `tomlkit` +- `tqdm`. + +## Compatibility + +Code is designed to be platform-independent. + +Official supported platforms are Windows and Linux (partially tested under Debian / Ubuntu). + +## Contribution + +_Coming soon._ + +If you are interested to project contribution, you can send a mail to campanu@luc-geo.fr. + +## License + +This repository, except dependencies, is licensed under **GNU AGPL v3**. + +Dependencies are included in repository for development and keep their original license +(see `dependencies/EXTRA_LICENSES.md`). diff --git a/README_fr.md b/README_fr.md new file mode 100644 index 0000000..69f7bc5 --- /dev/null +++ b/README_fr.md @@ -0,0 +1,113 @@ +# video2geoframes.py + +![Gitea Release](https://img.shields.io/gitea/v/release/lumathieu/video2geoframes.py?gitea_url=https%3A%2F%2Fgit.luc-geo.fr&include_prereleases&sort=semver&display_name=tag) + +_version 🇫🇷_ + +Programme Python permettant de générer un ensemble d'images géotaguées depuis une vidéo et une trace GPS. + +Conçu pour faciliter la contribution à des projets de photo-cartographie de rue tels que Mapillary ou Panoramax. + +## Démarrage rapide + +Rien de plus simple : rassemblez votre vidéo, votre trace GPS, lancez le script Python et suivez le guide ! + +En détail, le programme est entièrement construit autour d'une TUI ou _Textual User Interface_, qui permet de lancer +facilement le traitement de la vidéo par la saisie pas-à-pas des paramètres. + +La saisie est guidée par une aide textuelle indiquant les valeurs attendues. + +Avant de lancer le script, vous avez besoin d'avoir : +* un fichier vidéo avec son horodatage exact (début) en temps local ou UTC +* un fichier de trace GPS propre couvrant la durée de la vidéo +* un dossier de travail. + +## Documentation + +_A venir._ + +## Fonctionnalités + +Le programme permet d'exécuter en un seul traitement les tâches suivantes : +* le séquençage de la vidéo selon un intervalle de temps +* l'horodatage incrémental de la séquence d'image +* l'export des images au format JPEG +* le géotaguage des images exportées à partir de la trace GPS. + +Il inclut également : +* le support des vidéos timelapse +* le redimensionnement des images à une résolution inférieure à la vidéo d'origine tout en conservant le ratio +* l'ajout de métadonnées avec les tags EXIF `artist`, `make`, `model` et `copyright` (cf. [documentation ExifTool](https://exiftool.org/TagNames/EXIF.html)) +* l'horodatage à la précision de la milliseconde +* le support du temps local décalé par rapport à UTC. +* l'ajout d'un décalage temporel pour mieux corréler la vidéo et la trace GPS. + +Lors de l'export, un sous-dossier nommé selon la vidéo est créé automatiquement dans le répertoire de sortie. + +### Comparaison v1 / v2 + +| Fonctionnalité | v1-beta | v2-alpha9 | +|--------------------------------------|------------|--------------| +| Support des vidéos timelapse | ✔️ | ✔️ | +| Écriture des tags EXIF | ✔️ | ✔️ | +| Support des tags étendus | ✔️ | ❌ | +| Support des millisecondes | ✔️ | ✔️ | +| Affichage de la progression | 🟡 brut | ✔️ | +| TUI multilingue 🇺🇳 | 🟡 limitée | ✔️ | +| Personnalisation de la configuration | ❌ | 🟡 partielle | +| Personnalisation qualité JPEG | ❌ | 🔄 planifié | +| Paramétrage via TOML | ❌ | 🔄 planifié | + +## Langues + +La TUI est multilingue grâce une base de "locales" sous forme de fichiers TOML (`locales/*.toml`) facilement extensible. + +| Langue | Locale | Support | Mainteneur | +|---------------|---------|-------------|--------------| +| 🇺🇸 Anglais | `en_us` | ✔️ 100 % | @lumathieu | +| 🇫🇷 Français | `fr_fr` | ✔️ 100 % | @lumathieu | +| 🇮🇹 Italien | `it_it` | 🔄 planifié | @lumathieu ? | + +## Versions + +Voir [_Releases_](https://git.luc-geo.fr/lumathieu/video2geoframes.py/releases). + +## Installation + +Pour installer le programme, il suffit de cloner le dépôt Git, d'installer les dépendances logicielles et de construire +l'environnement Python. Il est recommandé d'utiliser un environnement virtuel (venv). + +### Python + +L'ensemble du projet est développé et testé avec **Python 3.11** (Windows x86-64). + +### Dépendances + +Le script principal utilise les librairies Python suivantes (voir aussi `requirements.txt`) : +- `numpy` +- `opencv-python` +- `piexif` +- `tomlkit` +- `tqdm`. + +Il utilise également le programme [`ExifTool`](https://exiftool.org/) pour le géotaguage des images. +Appelée par une commande système, cette dépendance est prévue pour être supprimée dans les versions futures. + +## Compatibilité + +Le code est conçu pour être indépendant de la plateforme. + +Les plateformes officiellement supportées sont Windows et Linux (partiellement testé sous Debian / Ubuntu). + +## Contribution + +_A venir._ + +Si vous intéressé pour contribuer au projet, vous pouvez envoyer un mail à campanu@luc-geo.fr. + +## Licence + +Ce dépôt, à l'exception des dépendances, est sous licence **GNU AGPL v3**. + +Les dépendances sont incluses au dépôt pour le développement et restent sous leur licence d'origine +(voir `dependencies/EXTRA_LICENSES.md`). \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..5468665 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,6 @@ +colorama==0.4.6 +numpy==2.0.0 +opencv-python==4.10.0.84 +piexif==1.1.3 +tomlkit==0.12.5 +tqdm==4.66.4