🧱 LegoLab

LegoLab est un ensemble d'outils Python permettant de créer des œuvres artistiques à partir de briques LEGO. Le projet s'appuie sur l'API Rebrickable pour récupérer en temps réel les pièces et couleurs disponibles dans le catalogue LEGO officiel.

---

📋 Table des matières

• Sous-projets
• Roadmap
• Prérequis
• Installation
• Configuration
• Package data
• API Rebrickable
• Licence

---

🎯 Sous-projets

1. Lego Mosaic

Transformez n'importe quelle photo en tableau LEGO en approximant les couleurs de chaque pixel vers les couleurs de briques réellement disponibles.

Fonctionnalités prévues :

• Import d'une image (JPG, PNG)
• Choix de la taille de grille parmi les formats officiels LEGO
• Approximation colorimétrique configurable
• Faire un fichier LDraw
• Export de la liste des pièces nécessaires

2. My Own BrickHead

Créez une BrickHead personnalisée à partir de photos d'une personne. Le programme analyse les proportions du visage, des cheveux, des vêtements, etc.

Fonctionnalités prévues :

• Analyse de photos (visage, cheveux, habits)
• Génération du visuel 3D de la BrickHead
• Export de la liste de pièces complète
• Génération de la notice de montage

---

Roadmap

Le développement suit 4 phases. Chaque phase produit un livrable fonctionnel.

Phase 0 — Fondations (package data/) ✅

Objectif : centraliser l'accès aux données LEGO pour tous les sous-projets.

Tâche	Statut
Client HTTP Rebrickable (auth, throttle, pagination)	✅
Moteur de cache JSON local avec expiration	✅
Catalogue des couleurs LEGO (fetch, cache 7j, modèle Color)	✅
Recherche de pièces, détails, couleurs par pièce	✅
Estimation de prix + liens marchands (BrickLink, BrickOwl)	✅
Fonction find_closest_color(r, g, b) (distance RGB)	✅

---

Phase 1 — Lego Mosaic 🎨

Objectif : transformer une image en mosaïque LEGO avec notice de montage.

Étape 1.1 — Traitement d'image

Tâche	Dépendance	Statut
Charger une image (JPG, PNG)	Pillow	✅
Redimensionner selon la grille choisie (ex: 48×48, 32×32)	Pillow	✅
Quantification des couleurs → palette LEGO	data.colors + K-means (scikit-learn)	✅
Aperçu de la mosaïque (rendu pixel-art)	Pillow ou matplotlib	✅

Étape 1.2 — Mapping vers les pièces LEGO

Tâche	Dépendance	Statut
Mapper chaque pixel → couleur LEGO la plus proche	data.find_closest_color	✅
Choisir le type de pièce (plate 1×1, tile 1×1, ou d'autre taille pour l'optimisation des pieces)	data.parts	✅
Générer la BOM (Bill of Materials / liste de pièces)	data.prices	✅
Estimer le coût total du projet	data.estimate_cost	✅

Étape 1.3 — Export LDraw & notice

Tâche	Dépendance	Statut
Générer un fichier .ldr (format LDraw)	pyldraw	⬜
Visualisation 3D (optionnel, via LDView ou Studio 2.0)	externe	⬜
Notice de montage : rendu couche par couche en images	Pillow / matplotlib	⬜
Export PDF via LPub3D (optionnel)	LPub3D (externe)	⬜
Export PDF de la notice (alternatif)	reportlab ou matplotlib	⬜

---

Phase 2 — My Own BrickHead 🧑‍🎨

Objectif : générer une BrickHead personnalisée à partir de photos.

Étape 2.1 — Analyse du visage

Tâche	Dépendance	Statut
Détection de visage dans la photo	OpenCV + Haar Cascade ou MediaPipe	⬜
Extraction des zones : peau, cheveux, yeux, bouche	MediaPipe Face Mesh	⬜
Extraction des couleurs dominantes par zone	K-means (scikit-learn)	⬜
Mapping couleurs dominantes → couleurs LEGO	data.find_closest_color	⬜

Étape 2.2 — Génération du modèle BrickHead

Tâche	Dépendance	Statut
Template BrickHead paramétrique (grille 3D voxels)	NumPy	⬜
Placement des couleurs sur le template (peau, cheveux, habits)	—	⬜
Choix automatique des briques selon la géométrie	data.parts	⬜
Rendu visuel 3D en voxels	matplotlib (3D) ou export LDraw	⬜

Étape 2.3 — Export et notice

Tâche	Dépendance	Statut
Export fichier .ldr (LDraw) de la BrickHead	pyldraw	⬜
Génération BOM + estimation de prix	data.prices	⬜
Notice de montage étape par étape (couche par couche)	Pillow / reportlab	⬜
Export PDF via LPub3D (optionnel)	LPub3D (externe)	⬜
Export PDF de la notice (alternatif)	reportlab ou matplotlib	⬜

---

Phase 3 — Améliorations ✨

Tâche	Projet	Priorité
Amélioration colorimétrique (distance CIE-Lab au lieu de RGB)	Commun	Moyenne
Support des plates 1×2, 1×3, 1×4 pour optimiser la mosaïque	Mosaic	Moyenne
Détection du style vestimentaire (T-shirt, costume, etc.)	BrickHead	Basse
Interface web locale simple (upload photo → résultat)	Commun	Basse
Compatibilité directe BrickLink Studio (.io)	Commun	Basse

---

Technologies retenues

Catégorie	Outil	Rôle
Données LEGO	API Rebrickable + cache local	Couleurs, pièces, prix
Traitement image	Pillow, OpenCV	Chargement, redim, détection visage
Analyse couleurs	scikit-learn (K-means)	Quantification, couleurs dominantes
Analyse visage	MediaPipe Face Mesh	Segmentation zones du visage
Modélisation 3D	NumPy (voxels)	Template BrickHead paramétrique
Export LEGO	pyldraw (format LDraw .ldr)	Génération programmatique de modèles LDraw
Instructions	LPub3D (externe)	Génération de notices PDF depuis un fichier .ldr
Notice/PDF	Pillow, matplotlib, reportlab	Rendu couche par couche

Écarté volontairement : Flask/FastAPI (pas de serveur nécessaire), Flutter/React Native (pas d'appli mobile), U-Net/Mask R-CNN (surdimensionné), Three.js (on reste en Python), bricknil (pilotage moteurs LEGO Powered Up, hors sujet).

---

🀽 Prérequis

Outil	Version	Description
Python	≥ 3.10	Langage principal
pip	≥ 22.0	Gestionnaire de paquets Python
Git	≥ 2.30	Versionnement du code
Compte Rebrickable	—	Gratuit — nécessaire pour obtenir une clé API

Dépendances Python

Paquet	Rôle	Phase
requests	Requêtes HTTP vers l'API Rebrickable	0 ✅
python-dotenv	Chargement des variables d'environnement	0 ✅
pyldraw	Génération de fichiers LDraw (.ldr) en Python	1–2
Pillow	Chargement, redimensionnement et rendu d'images	1
numpy	Manipulation de tableaux / grilles de voxels	1
scikit-learn	K-means pour quantification des couleurs	1
matplotlib	Aperçu mosaïque, rendu 3D voxels	1–2
opencv-python	Détection de visage, traitement image avancé	2
mediapipe	Face Mesh – segmentation zones du visage	2
reportlab	Génération de notices PDF	1–2

---

🚀 Installation

# 1. Cloner le dépôt
git clone https://github.com/<votre-utilisateur>/LegoLab.git
cd LegoLab
# 2. Créer un environnement virtuel (recommandé)
python -m venv venv
source venv/bin/activate # Linux / macOS
venv\Scripts\activate # Windows# 3. Installer les dépendances
pip install -r requirements.txt²

---

⚙️ Configuration

1. Créer un compte gratuit sur rebrickable.com
2. Accéder à la page API : rebrickable.com/api/
3. Générer une clé API
4. Copier le template et renseigner la clé :

cp .env.example .env

Puis éditer .env :

REBRICKABLE_API_KEY=votre_clé_ici

---

📦 Package data – Utilisation

Le package data/ centralise tous les accès à l'API Rebrickable. Les sous-projets n'appellent jamais l'API directement.

Import rapide

fromdataimportget_colors, find_closest_color, search_parts, estimate_cost

Couleurs

fromdataimportget_colors, find_closest_color, get_color_by_name# Toutes les couleurs (cache auto 7 jours)colors=get_colors()
# Trouver la couleur LEGO la plus proche d'un pixelclosest=find_closest_color(200, 50, 30) # RGBprint(closest[0]) # → Dark Red #720E0F [id=320]# Recherche par nomred=get_color_by_name("Red")
print(red.hex, red.rgb_tuple) # → #C91A09 (201, 26, 9)

Pièces

fromdataimportsearch_parts, get_part_colors, get_parts_by_nums# Rechercheresults=search_parts("brick 2x4")
# Couleurs dispo pour une pièce (cache 30 jours)colors=get_part_colors("3001")
forcincolors:
print(f"{c.color_name} #{c.color_rgb} – {c.num_sets} sets")
# Batch : plusieurs pièces en un seul appelparts=get_parts_by_nums(["3001", "3002", "3003"])

Estimation de prix

fromdataimportestimate_cost, get_price_links# Liens marchands pour une piècelinks=get_price_links("3001", color_id=5)
print(links.bricklink_url)
# Estimation du coût d'un projetcost=estimate_cost([("3001", 100), ("3003", 50)])
print(f"Coût estimé : {cost['total_eur']} €")

Cache

Les données sont stockées automatiquement dans data/cache/ :

Donnée	Fichier cache	Durée
Couleurs LEGO	colors.json	30 jours
Couleurs par pièce	part_colors_<num>.json	30 jours
Catégories	part_categories.json	30 jours

Pour forcer un rafraîchissement :

fromdataimportrefresh_colorsrefresh_colors() # re-télécharge depuis l'API

---

🔧 Pipeline LDraw → Instructions

Le projet utilise le format LDraw (.ldr) comme format pivot pour l'export des modèles LEGO. Deux chemins sont possibles pour générer des instructions de montage :

Python (pyldraw) LPub3D (externe)
┌────────────┐ ┌──────────────────────────┐
│ Modèle │ │ 1. Ouvrir le .ldr │
│ → Piece() │ │ 2. Configurer les steps │
│ → Vector() │ ──▶ │ 3. Générer les images │
│ → .ldr │ │ 4. Export PDF │
└────────────┘ └──────────────────────────┘

Outil	Type	Rôle
pyldraw	Lib Python	Génération programmatique de fichiers .ldr (pièces, couleurs, positions)
LPub3D	App externe	Génération de notices de montage PDF à partir d'un .ldr
LDView	App externe	Visualisation 3D d'un modèle .ldr (optionnel)
BrickLink Studio 2.0	App externe	Édition / rendu 3D avancé (optionnel)

Exemple de génération LDraw avec pyldraw

fromldraw.piecesimportPiecefromldraw.geometryimportVector, Identityfromldraw.library.coloursimportRed, Blue# Placer une brique 2×4 rouge à l'origineprint(Piece(Red, Vector(0, 0, 0), Identity(), "3001"))
# Placer une brique 2×4 bleue au-dessusprint(Piece(Blue, Vector(0, -24, 0), Identity(), "3001"))

Note :pyldraw nécessite la bibliothèque de pièces LDraw, téléchargée automatiquement au premier import.

---

🌐 API Rebrickable

Ce projet utilise l'API REST v3 de Rebrickable.

Endpoints utilisés :

Endpoint	Description
GET /lego/colors/	Liste de toutes les couleurs
GET /lego/parts/	Recherche de pièces
GET /lego/parts/{part_num}/	Détails d'une pièce
GET /lego/parts/{part_num}/colors/	Couleurs disponibles pour une pièce
GET /lego/part_categories/	Catégories de pièces

Limites : 1 requête/seconde (gestion automatique du rate-limiting intégrée).

---

📄 Licence

Ce projet est distribué sous licence MIT. Voir le fichier LICENSE pour plus de détails.

---

_{LEGO® est une marque déposée du groupe LEGO. Ce projet n'est ni affilié ni approuvé par LEGO.}