import initial

2026-06-10 10:21:18 +02:00
commit 5a03f8a38d
59 changed files with 4777 additions and 0 deletions
@@ -0,0 +1,101 @@
+# Logimage Generator
+
+Génère des puzzles nonogrammes (logimages) au format PDF à partir d'images récupérées automatiquement via Pexels ou Unsplash.
+
+## Prérequis
+
+- Python 3.11+
+- Une clé API [Pexels](https://www.pexels.com/api/) (gratuite) ou [Unsplash](https://unsplash.com/developers) — facultatif si tu utilises une image locale (`--local-image`)
+
+## Installation
+
+Crée un environnement virtuel (obligatoire sur Debian/Ubuntu) :
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+> À chaque nouvelle session de terminal, réactive l'environnement avec `source .venv/bin/activate` avant de lancer `logimage`.
+
+## Configuration
+
+Copie le fichier d'exemple et renseigne ta clé API :
+
+```bash
+cp .env.example .env
+```
+
+Édite `.env` :
+
+```env
+# Pexels (prioritaire) — https://www.pexels.com/api/
+PEXELS_API_KEY=ta_clé_pexels
+
+# Unsplash (fallback) — https://unsplash.com/developers
+UNSPLASH_ACCESS_KEY=ta_clé_unsplash
+```
+
+Si les deux clés sont présentes, Pexels est utilisé en priorité. Une seule clé suffit.
+
+## Utilisation
+
+```bash
+# Un puzzle sur un thème aléatoire (difficulté moyenne, 15×15)
+logimage
+
+# Thème personnalisé
+logimage --theme "montagne"
+
+# Difficulté
+logimage --difficulty easy    # 10×10
+logimage --difficulty medium  # 15×15 (défaut)
+logimage --difficulty hard    # 20×20
+
+# Taille personnalisée
+logimage --size 20x25
+
+# Plusieurs puzzles dans un seul PDF
+logimage --count 5
+
+# Inclure les pages solution
+logimage --solution
+
+# Chemin de sortie
+logimage --output mon_carnet.pdf
+
+# Image locale (sans appel API)
+logimage --local-image photo.jpg
+
+# Combinaisons
+logimage --theme "architecture" --count 3 --difficulty hard --solution --output archi.pdf
+```
+
+Le PDF est généré dans le répertoire courant (`puzzles.pdf` par défaut).
+
+## Recommandations d'usage
+
+- **Thèmes en anglais** : les APIs Pexels et Unsplash renvoient de meilleurs résultats avec des mots-clés en anglais (`forest`, `city`, `animals`…).
+- **Difficulté** : commence par `easy` (10×10) pour vérifier le rendu avant de générer des grilles complexes.
+- **Lot de puzzles** : `--count 5 --solution` génère un carnet complet avec les solutions en fin de PDF.
+- **Résolution** : les images sont redimensionnées automatiquement selon la taille de grille choisie. Une grille plus grande donne un puzzle plus précis mais plus difficile à résoudre.
+
+## Développement
+
+```bash
+# Installer les dépendances de dev (dans le venv activé)
+pip install -e ".[dev]"
+
+# Lancer les tests
+pytest tests/ -v
+
+# Tests d'intégration (nécessitent une clé API valide)
+pytest tests/ -v -m integration
+
+# Linter
+ruff check src/ tests/
+
+# Vérification des types
+mypy src/
+```