donataskasp/lego-set-finder

Chercheur d'ensembles LEGO

L'utilisateur photographie les pièces distinctives d'un tas : figurines, animaux, briques imprimées, véhicules, formes étranges. Chaque pièce est extraite des photos, identifiée par Brickognize (un service gratuit de reconnaissance d'image), et recherchée hors ligne dans le catalogue public de Rebrickable. Les ensembles sont classés en fonction du nombre de pièces distinctives indépendantes qui pointent vers eux. Les briques et plaques unies ne permettent pas de bien distinguer les ensembles, elles restent donc hors des photos et des preuves.

Toutes les commandes sont dans un seul script. Chaque étape lit et écrit des fichiers dans un dossier d'exécution (RUN ci-dessous, par exemple ./lego-run) :

python3 ${CLAUDE_SKILL_DIR}/scripts/lsf.py <étape> RUN ...

Ci-dessous, lsf.py représente cette commande complète. lsf.py <étape> -h liste toutes les options. Là où python3 n'est pas trouvé (souvent sur Windows, non testé), utilisez py à la place. Les formats de fichiers, le score et les correctifs pour les problèmes courants se trouvent dans reference.md ; lisez-le lorsqu'une étape échoue ou avant de modifier un fichier manuellement.

1. Convenez du travail avec l'utilisateur

Demandez, en un seul message :

1. Duplo ou LEGO standard ? (Ce skill n'a été testé que sur Duplo. Dites-le s'ils répondent LEGO.)
2. Où sont les photos ? S'il n'y en a pas encore, donnez-leur les conseils photo ci-dessous.
3. Le skill peut-il envoyer une image découpée de chaque pièce individuelle à Brickognize, un service de reconnaissance tiers gratuit ? Seules ces découpes quittent l'ordinateur, jamais les photos complètes, et elles ne portent aucune métadonnée (pas de données d'appareil photo, d'heure ou de localisation). Les conditions de Brickognize lui accordent une licence permanente et libre de droits pour utiliser les images téléchargées, y compris pour entraîner des modèles d'apprentissage automatique ; l'utilisateur peut demander à Brickognize de les supprimer. Sans un oui, arrêtez ici.
4. Des ensembles qu'ils soupçonnent déjà (boîtes, manuels, historique de commandes) ? Cela vous aide à vérifier le résultat, mais ne remplace jamais les preuves.

Conseils photo (donnez-les tels quels) :

• Ne sortez que les pièces distinctives : figurines, animaux, briques imprimées, véhicules, formes étranges. Les briques et plaques unies sont inutiles pour distinguer les ensembles.
• Étalez-en autant que possible sur une grande feuille blanche unie avec environ 2 cm d'espace autour de chaque pièce, face imprimée vers le haut. L'espace compte plus que le nombre : les pièces qui se touchent sont découpées comme une seule. Prenez autant de photos que nécessaire ; le skill demande avant de dépasser environ 300 pièces en une seule exécution. Les pièces blanches, grises et transparentes ressortent mieux sur une feuille foncée.
• Photographiez directement d'en haut avec une bonne lumière, la feuille entière dans le cadre.
• Pour le LEGO standard (pièces plus petites), mettez-en moins dans chaque photo et photographiez plus près.
• Les minifigurines et les pièces imprimées portent la plupart des preuves.
• Les photos JPEG ou PNG fonctionnent telles quelles. Les photos HEIC (iPhone) nécessitent le package pillow-heif, ou exportez-les en JPEG.

Terminé lorsque vous connaissez le type de pièces, les fichiers photo, et que vous avez le oui pour Brickognize.

2. Vérification de l'installation et catalogue

lsf.py selftest          # hors ligne, quelques secondes ; doit se terminer par "0 failed"
lsf.py data --info       # exit 0 : un catalogue est installé, passez à l'étape 3

Si Pillow est manquant, le script indique comment l'installer.

L'utilisateur télécharge le catalogue Rebrickable manuellement, une fois : les conditions de Rebrickable interdisent les téléchargements automatiques, donc ne récupérez jamais ces fichiers vous-même, avec aucun outil. Exécutez lsf.py data : cela imprime la page de téléchargement et les fichiers exacts (il se termine par exit 1 exprès). Donnez cette liste à l'utilisateur, dites-lui d'enregistrer les fichiers dans un dossier (Téléchargements convient), et attendez qu'il vous dise que c'est fait. Ensuite :

lsf.py data --from ~/Téléchargements     # ou le dossier utilisé ; nomme tout fichier toujours manquant

Terminé lorsque lsf.py data --info se termine par exit 0. Les téléchargements font environ 17 Mo ; l'index prend environ 115 Mo dans ~/.cache/lego-set-finder (ou $LEGO_SET_FINDER_DATA). Pour le rafraîchir plus tard, l'utilisateur télécharge à nouveau les fichiers et vous exécutez à nouveau data --from.

3. Trouver les pièces

lsf.py detect RUN <photos ou dossier>

Cela écrit RUN/overview/<photo>.jpg : la photo avec des boîtes numérotées et une grille étiquetée tous les 100 pixels. Ouvrez chaque aperçu et jugez chaque boîte :

• gardez une boîte qui contient exactement une pièce distinctive ;
• supprimez les boîtes sur les briques et plaques unies, l'arrière-plan, les ombres, le bord de la feuille et les fragments d'une pièce ;
• remplacez une boîte qui contient deux pièces qui se touchent par une boîte par pièce ;
• ajoutez une boîte pour chaque pièce distinctive qui n'en a pas (les pièces pâles sur un sol pâle sont souvent manquées).

lsf.py boxes RUN <photo> --only 3,7,12                  # gardez ces boîtes automatiques, supprimez le reste
lsf.py boxes RUN <photo> --drop 9 --add 405,225,515,385:figure --add 395,380,500,500

Les coordonnées sont en pixels de l'aperçu (x0,y0,x1,y1), lues sur la grille. Chaque appel redessine l'aperçu avec les seules boîtes conservées : les automatiques en magenta, les vôtres en cyan. Regardez à nouveau après chaque correction. Là où les pièces sont petites ou serrées, lsf.py zoom RUN <photo> x0,y0,x1,y1 montre cette région à deux fois la taille avec les mêmes coordonnées et une grille tous les 50 pixels ; lisez les coins des boîtes sur le zoom.

Terminé lorsque, sur chaque aperçu, chaque pièce distinctive se trouve dans exactement une boîte conservée et que chaque boîte conservée ne contient que cette pièce.

4. Découper et vérifier les extractions

lsf.py crop RUN

Ouvrez chaque RUN/sheets/crops_<photo>.jpg. Chaque extraction doit montrer une pièce entière. Corrigez les boîtes avec lsf.py boxes et recadrez jusqu'à ce que cela soit valable pour toutes.

5. Identifier

lsf.py identify RUN

Envoie chaque extraction à Brickognize, 3 à la fois par défaut (--workers, au maximum 4). Les réponses sont mises en cache par image et point d'accès, donc une réexécution ne coûte rien pour les extractions déjà envoyées à ce point d'accès. Il s'arrête à 300 nouveaux appels (code de sortie 2) : demandez à l'utilisateur avant de réexécuter avec un --max-calls plus élevé.

Les extractions sans réponse sont listées. Brickognize ne trouve souvent rien sur les grandes pièces ou les pièces molles (carrosseries de véhicules, chariots, tissu). Essayez une fois avec --endpoint predict/parts/ --only <crops>. Pour ce qui échoue encore, vous nommez vous-même la pièce à l'étape 6.

6. Cartographier et examiner chaque pièce

lsf.py match RUN --kind duplo        # ou --kind lego

Cela écrit RUN/pieces.tsv, une ligne par extraction : la réponse de Brickognize, la pièce ou figurine Rebrickable à laquelle elle correspond (rb, plusieurs en cas d'incertitude), la couleur et une confiance. Il imprime d'abord les lignes à vérifier, dont toutes les figurines : les correspondances de figurines gardent les concurrents proches qui peuvent être clairement erronés (une fille pour un garçon). Ouvrez chaque RUN/sheets/review_<photo>.jpg (extraction, confiance, nom Brickognize, numéro Rebrickable et couleur) et comparez chaque extraction avec sa légende.

Corrigez ce qui ne va pas à l'aide des assistants de catalogue :

lsf.py lookup yellow truck flatbed grille --duplo --colour Yellow   # rechercher par nom ou numéro de pièce
lsf.py fix RUN p10-m1 --rb 15454pr0006 --colour Yellow
lsf.py fix RUN p08-27 --colour "Neon Yellow"     # votre œil bat Brickognize sur la couleur
lsf.py fix RUN p08-m3 --use n                     # ne peut pas être identifié : laissez-le de côté
lsf.py set 10931                                  # les pièces d'un ensemble, pour vérifier une intuition
lsf.py sets-of 14094 --colour "Medium Azure"      # quels ensembles contiennent une pièce dans une couleur

Nommez une pièce que Brickognize a manquée à partir de ce que vous voyez, puis lookup la ; choisissez le candidat dont le nom et les couleurs correspondent. Lorsque deux ou trois candidats correspondent également, donnez-les tous (--rb a;b;c) : le classement gère cela mieux qu'une supposition erronée. Un tas Duplo répondant avec une pièce non Duplo est généralement faux.

Terminé lorsque chaque ligne avec use = y a un rb et une couleur que vous croyez d'après l'extraction, et que chaque ligne dont vous ne pouvez pas garantir a use = n.

7. Classer les ensembles

lsf.py rank RUN

Lisez RUN/sets.md. Pour chaque ensemble, il montre le niveau (probable, possible, faible), le score de classement, le nombre de pièces qui pointent vers lui, combien de celles-ci aucun autre ensemble n'a, la part des éléments distinctifs de l'ensemble vus sur les photos, et la preuve pièce par pièce.

Présentez les ensembles probables à l'utilisateur sous forme de tableau (numéro d'ensemble, nom, année, pièces, pièces uniques, part vue), puis les possibles sur une ligne chacun. Soulignez :

• les ensembles listés sous "Partage des preuves avec" : ils sont en concurrence pour les mêmes pièces, demandez donc à l'utilisateur lequel il a ;
• les grands ensembles qui marquent des points sur de nombreuses pièces partagées mais montrent peu des leurs (faible part vue) : ce sont les faux positifs habituels ;
• les pièces distinctives qu'aucun ensemble listé n'explique : un autre ensemble peut être dans le tas.

Demandez à l'utilisateur quels ensembles il reconnaît ou veut sur la liste de vérification. Le lien Rebrickable dans la liste montre l'image de la boîte de chaque ensemble.

8. Construire la page de liste de vérification

lsf.py page RUN --sets 10906,10931,10963 [--confirmed] [--title "Notre Duplo"]

Sans --sets, il prend le niveau probable. --confirmed étiquette chaque ensemble comme confirmé (utilisez-le après que l'utilisateur les a vérifiés). Le résultat est RUN/checklist.html, un fichier qui fonctionne lorsqu'il est ouvert depuis le disque. Dites à l'utilisateur comment l'utiliser : choisissez un ensemble ou passez en "Tas par couleur", appuyez sur le nombre d'une pièce au fur et à mesure qu'elle va dans son tas, "Masquer trouvé" pour voir ce qui reste, "Liste des pièces manquantes" pour copier ce qui manque encore, "Sauvegarder ou réinitialiser les coches" pour conserver les coches dans un fichier. Les coches se sauvegardent uniquement dans ce navigateur. Les images des pièces sont chargées depuis le serveur d'images de Rebrickable, donc une connexion est nécessaire.

9. Dire ce qui manque

Avant que l'utilisateur ne trie, dites-lui quels éléments distinctifs de chaque ensemble choisi ne sont pas apparus sur les photos :

lsf.py missing RUN --sets 10906,10931

Dites clairement que "pas dans les photos" ne veut pas dire "manquant" : seules les pièces distinctives ont été photographiées. Lorsqu'il nomme une extraction que vous avez laissée de côté (use = n) qui correspond à une pièce manquante, regardez à nouveau cette extraction et restaurez-la avec lsf.py fix RUN <crop> --use y si elle correspond ; puis classez à nouveau. Après le tri, prenez la liste que la page copie, ou le fichier de coches que la page sauvegarde (lsf.py missing RUN --sets ... --ticks <file>), et donnez les pièces manquantes par ensemble.

Limites à dire à l'utilisateur

• Testé sur une seule collection Duplo mélangée (12 ensembles), sur macOS. LEGO standard et Windows ne sont pas testés.
• Brickognize est un service tiers gratuit ; les découpes de pièces lui sont téléchargées et il peut les conserver et les utiliser (étape 1). Ses points d'accès predict sont marqués "legacy" dans sa description d'API, donc ils peuvent changer ou s'arrêter.
• Le catalogue Rebrickable est un téléchargement unique manuel (11 fichiers, environ 17 Mo ; l'index prend environ 115 Mo) et devient lentement obsolète ; pour le rafraîchir, téléchargez à nouveau les fichiers et exécutez à nouveau lsf.py data --from.
• Rebrickable et BrickLink numérotent certaines pièces différemment, les figurines Duplo surtout. Les figurines et impressions cartographiées portent une confiance ; vérifiez les douteuses à l'œil.