Vincent Bourdon
102 lines
2.7 KiB
Markdown
102 lines
2.7 KiB
Markdown
# 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/
|
||
```
|