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 (gratuite) ou Unsplash — facultatif si tu utilises une image locale (--local-image)

Installation

Crée un environnement virtuel (obligatoire sur Debian/Ubuntu) :

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 :

cp .env.example .env

Édite .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

# 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

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