donataskasp/lego-set-finder

Was macht lego-set-finder?

Der Benutzer fotografiert die markanten Teile eines Haufens: Figuren, Tiere, bedruckte Steine, Fahrzeuge, ungewöhnliche Formen. Jedes Teil wird aus den Fotos ausgeschnitten, mit Brickognize (einem kostenlosen Bilderkennungsdienst) identifiziert und offline im öffentlichen Katalog von Rebrickable nachgeschlagen. Die Sets werden danach bewertet, wie viele unabhängige markante Teile auf sie verweisen. Gewöhnliche Steine und Platten eignen sich schlecht zur Unterscheidung von Sets, daher bleiben sie außen vor – sowohl auf den Fotos als auch in der Beweisführung.

Alle Befehle sind in einem einzigen Skript zusammengefasst. Jeder Schritt liest und schreibt Dateien in einem Ausführungsordner (RUN unten, z.B. ./lego-run):

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

Im Folgenden steht lsf.py für diesen vollständigen Befehl. lsf.py <step> -h listet alle Optionen auf. Falls python3 nicht gefunden wird (häufig unter Windows, das nicht getestet ist), verwenden Sie stattdessen py. Dateiformate, die Bewertung und Lösungen für häufige Probleme finden Sie in reference.md; lesen Sie diese Datei, wenn ein Schritt fehlschlägt oder bevor Sie eine Datei von Hand bearbeiten.

1. Auftrag mit dem Benutzer abstimmen

Fragen Sie in einer einzigen Nachricht:

1. Duplo oder normales LEGO? (Dieses Skill wurde nur mit Duplo getestet. Sagen Sie dies, wenn der Benutzer LEGO antwortet.)
2. Wo sind die Fotos? Falls es noch keine gibt, geben Sie die unten stehenden Fototipps.
3. Darf das Skill ein ausgeschnittenes Bild jedes einzelnen Teils an Brickognize, einen kostenlosen Bilderkennungsdienst eines Drittanbieters, senden? Nur diese Ausschnitte verlassen den Computer, niemals die vollständigen Fotos, und sie enthalten keine Metadaten (keine Kamera-, Zeit- oder Standortdaten). Die AGB von Brickognize gewähren diesem eine unbefristete, gebührenfreie Lizenz zur Nutzung hochgeladener Bilder, einschließlich zum Trainieren von Machine-Learning-Modellen; der Benutzer kann Brickognize um Entfernung bitten. Ohne Zustimmung wird hier abgebrochen.
4. Gibt es bereits vermutete Sets (Boxen, Anleitungen, Bestellhistorie)? Diese helfen bei der Überprüfung des Ergebnisses, ersetzen jedoch niemals die Beweisführung.

Fototipps (wörtlich so weitergeben):

• Trennen Sie nur die markanten Teile aus: Figuren, Tiere, bedruckte Steine, Fahrzeuge, ungewöhnliche Formen. Gewöhnliche Steine und Platten sind zur Unterscheidung von Sets unbrauchbar.
• Verteilen Sie so viele wie möglich auf einem großen, weißen Blatt Papier mit etwa 2 cm Abstand um jedes Teil herum, bedruckte Seite nach oben. Der Abstand ist wichtiger als die Anzahl: Teile, die sich berühren, werden als eines ausgeschnitten. Machen Sie so viele Fotos, wie der Haufen benötigt; das Skill fragt nach, bevor etwa 300 Teile in einem Durchlauf überschritten werden. Weiße, graue und durchsichtige Teile heben sich auf einem dunklen Blatt besser ab.
• Fotografieren Sie senkrecht von oben bei gutem Licht, mit dem gesamten Blatt im Bild.
• Bei normalem LEGO (kleinere Teile) legen Sie weniger Teile pro Foto und fotografieren Sie näher heran.
• Minifiguren und bedruckte Teile liefern die meisten Beweise.
• JPEG- oder PNG-Fotos sind ohne Weiteres verwendbar. HEIC-Fotos (iPhone) benötigen das pillow-heif-Paket, oder Sie exportieren sie als JPEG.

Abgeschlossen, wenn Sie die Art der Teile, die Fotodateien und die Zustimmung zu Brickognize kennen.

2. Installation prüfen und Katalog bereitstellen

lsf.py selftest          # offline, wenige Sekunden; muss mit "0 failed" enden
lsf.py data --info       # Exit 0: ein Katalog ist installiert, weiter zu Schritt 3

Fehlt Pillow, gibt das Skript an, wie es installiert wird.

Der Benutzer lädt den Rebrickable-Katalog einmalig von Hand herunter: Die AGB von Rebrickable verbieten automatisierte Downloads, daher niemals diese Dateien selbst herunterladen, mit keinem Tool. Führen Sie lsf.py data aus: Es gibt die Download-Seite und die genauen Dateien aus (Exit 1 ist beabsichtigt). Geben Sie dem Benutzer diese Liste, sagen Sie ihm, er solle die Dateien in einem Ordner speichern (Downloads ist in Ordnung), und warten Sie, bis er bestätigt, dass es erledigt ist. Dann:

lsf.py data --from ~/Downloads     # oder der von ihm verwendete Ordner; nennt alle noch fehlenden Dateien

Abgeschlossen, wenn lsf.py data --info mit Exit 0 endet. Die Downloads umfassen etwa 17 MB; der Index benötigt etwa 115 MB in ~/.cache/lego-set-finder (oder $LEGO_SET_FINDER_DATA). Zur späteren Aktualisierung lädt der Benutzer die Dateien erneut herunter, und Sie führen erneut data --from aus.

3. Teile finden

lsf.py detect RUN <fotos oder ordner>

Es erstellt RUN/overview/<photo>.jpg: das Foto mit nummerierten Kästchen und einem Raster mit Markierungen alle 100 Pixel. Öffnen Sie jede Übersicht und beurteilen Sie jedes Kästchen:

• ein Kästchen, das genau ein markantes Teil enthält, behalten;
• Kästchen mit gewöhnlichen Steinen und Platten, Hintergrund, Schatten, Blattrand und Teilfragmenten verwerfen;
• ein Kästchen, das zwei sich berührende Teile enthält, durch ein Kästchen pro Teil ersetzen;
• ein Kästchen für jedes markante Teil hinzufügen, das keines hat (blasse Teile auf hellem Untergrund werden oft übersehen).

lsf.py boxes RUN <photo> --only 3,7,12                  # diese automatischen Kästchen behalten, den Rest verwerfen
lsf.py boxes RUN <photo> --drop 9 --add 405,225,515,385:figure --add 395,380,500,500

Die Koordinaten sind Übersichtspixel (x0,y0,x1,y1), die Sie am Raster ablesen. Jeder Aufruf zeichnet die Übersicht neu mit nur den behaltenen Kästchen: automatische in Magenta, Ihre in Cyan. Überprüfen Sie nach jeder Korrektur erneut. Bei kleinen oder dicht beieinanderliegenden Teilen zeigt lsf.py zoom RUN <photo> x0,y0,x1,y1 diesen Bereich doppelt so groß mit denselben Koordinaten und einem Raster alle 50 Pixel; lesen Sie die Kästchenecken vom Zoom ab.

Abgeschlossen, wenn in jeder Übersicht jedes markante Teil in genau einem behaltenen Kästchen liegt und jedes behaltene Kästchen nur dieses Teil enthält.

4. Ausschnitte zuschneiden und prüfen

lsf.py crop RUN

Öffnen Sie jedes RUN/sheets/crops_<photo>.jpg. Jeder Ausschnitt muss ein vollständiges Teil zeigen. Korrigieren Sie Kästchen mit lsf.py boxes und schneiden Sie erneut zu, bis dies für alle zutrifft.

5. Identifizieren

lsf.py identify RUN

Sendet jeden Ausschnitt an Brickognize, standardmäßig 3 gleichzeitig (--workers, maximal 4). Antworten werden nach Bild und Endpunkt zwischengespeichert, sodass eine Wiederholung für bereits an diesen Endpunkt gesendete Ausschnitte nichts kostet. Es stoppt bei 300 neuen Aufrufen (Exit-Code 2): Fragen Sie den Benutzer, bevor Sie mit einem höheren --max-calls erneut starten.

Ausschnitte ohne Antwort werden aufgelistet. Brickognize findet bei großen oder weichen Teilen (Fahrzeugkarosserien, Waggons, Stoff) oft nichts. Versuchen Sie es einmal mit --endpoint predict/parts/ --only <crops>. Bei weiterhin fehlschlagenden Teilen benennen Sie das Teil in Schritt 6 selbst.

6. Jedes Teil zuordnen und überprüfen

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

Dies erstellt RUN/pieces.tsv, eine Zeile pro Ausschnitt: Brickognizes Antwort, das Rebrickable-Teil oder die Figur, dem es zugeordnet wird (rb, mehrere bei Unsicherheit), die Farbe und eine Konfidenz. Es gibt zuerst die Zeilen zur Überprüfung aus, jede Figur darunter: Bei Figuren werden engere Zweitplatzierte mitgelistet, die offensichtlich falsch sein können (ein Mädchen für einen Jungen). Öffnen Sie jedes RUN/sheets/review_<photo>.jpg (Ausschnitt, Konfidenz, Brickognizes Name, Rebrickable-Nummer und -Farbe) und vergleichen Sie jeden Ausschnitt mit seiner Beschriftung.

Korrigieren Sie Fehler mit den Katalog-Hilfsfunktionen:

lsf.py lookup yellow truck flatbed grille --duplo --colour Yellow   # Suche nach Name oder Teilenummer
lsf.py fix RUN p10-m1 --rb 15454pr0006 --colour Yellow
lsf.py fix RUN p08-27 --colour "Neon Yellow"     # Ihr Auge übertrifft Brickognize bei Farben
lsf.py fix RUN p08-m3 --use n                     # kann nicht identifiziert werden: weglassen
lsf.py set 10931                                  # Teile eines Sets, um eine Vermutung zu prüfen
lsf.py sets-of 14094 --colour "Medium Azure"      # welches Set ein Teil in einer Farbe enthält

Benennen Sie ein von Brickognize übersehenes Teil nach dem, was Sie sehen, und suchen Sie es mit lookup; wählen Sie den Kandidaten, dessen Name und Farben passen. Wenn zwei oder drei Kandidaten gleichermaßen passen, geben Sie alle an (--rb a;b;c): Die Bewertung kommt damit besser zurecht als mit einer falschen Vermutung. Ein Duplo-Teil, das als ein Nicht-Duplo-Teil beantwortet wird, ist in der Regel falsch.

Abgeschlossen, wenn jede Zeile mit use = y einen rb und eine Farbe hat, die Sie anhand des Ausschnitts für glaubwürdig halten, und jede Zeile, für die Sie nicht bürgen können, use = n hat.

7. Sets bewerten

lsf.py rank RUN

Lesen Sie RUN/sets.md. Für jedes Set werden die Stufe (wahrscheinlich, möglich, schwach), der Bewertungswert, die Anzahl der darauf hinweisenden Teile, die Anzahl davon, die kein anderes Set hat, der Anteil der eigenen markanten Teile des Sets, die auf den Fotos zu sehen sind, und die Beweise Teil für Teil angezeigt.

Präsentieren Sie dem Benutzer die wahrscheinlichen Sets als Tabelle (Set-Nummer, Name, Jahr, Teile, Nur-hier-Teile, gesehener Anteil), dann die möglichen Sets in je einer Zeile. Weisen Sie hin auf:

• Sets, die unter "Teilt Beweise mit" aufgeführt sind: Sie konkurrieren um dieselben Teile. Fragen Sie den Benutzer, welches er hat.
• Große Sets, die bei vielen gemeinsamen Teilen punkten, aber nur wenige eigene zeigen (niedriger gesehener Anteil): Dies sind die üblichen Fehlalarme.
• Markante Teile, die von keinem aufgeführten Set erklärt werden: Ein weiteres Set könnte im Haufen sein.

Fragen Sie den Benutzer, welche Sets er erkennt oder auf der Checkliste haben möchte. Der Rebrickable-Link in der Checkliste zeigt das Bild der Box jedes Sets.

8. Checklisten-Seite erstellen

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

Ohne --sets wird die Stufe "wahrscheinlich" verwendet. --confirmed kennzeichnet jedes Set als bestätigt (nachdem der Benutzer sie überprüft hat). Das Ergebnis ist RUN/checklist.html, eine Datei, die beim Öffnen von der Festplatte aus funktioniert. Erklären Sie dem Benutzer die Bedienung: Ein Set auswählen oder zu "Nach Farbhaufen" wechseln, auf die Anzahl eines Teils tippen, wenn es in seinen Haufen gelegt wird, "Gefunden ausblenden" um zu sehen, was noch fehlt, "Fehlende Teile-Liste" um zu kopieren, was noch fehlt, "Haker speichern oder zurücksetzen" um die Haker in einer Datei zu behalten. Die Haker werden nur in diesem Browser gespeichert. Teilbilder werden vom Rebrickable-Bildserver geladen, daher wird eine Internetverbindung benötigt.

9. Fehlende Teile auflisten

Bevor der Benutzer sortiert, teilen Sie ihm mit, welche markanten Teile jedes ausgewählten Sets auf den Fotos nicht aufgetaucht sind:

lsf.py missing RUN --sets 10906,10931

Machen Sie deutlich, dass "nicht auf den Fotos" nicht "fehlend" bedeutet: Es wurden nur markante Teile fotografiert. Wenn ein von Ihnen ausgelassener Ausschnitt (use = n) zu einem fehlenden Teil passt, sehen Sie sich diesen Ausschnitt erneut an und stellen Sie es mit lsf.py fix RUN <crop> --use y wieder her, wenn es passt; bewerten Sie dann neu. Nach dem Sortieren nehmen Sie die Liste, die die Seite kopiert, oder die Haker-Datei, die die Seite speichert (lsf.py missing RUN --sets ... --ticks <file>), und geben die fehlenden Teile pro Set aus.

Einschränkungen, die dem Benutzer mitzuteilen sind

• Getestet mit einer gemischten Duplo-Sammlung (12 Sets) auf macOS. Normales LEGO und Windows sind nicht getestet.
• Brickognize ist ein kostenloser Dienst eines Drittanbieters; die Teilausschnitte werden an ihn hochgeladen, und er kann sie behalten und nutzen (Schritt 1). Die predict-Endpunkte sind in der API-Beschreibung als "legacy" markiert, daher können sie sich ändern oder eingestellt werden.
• Der Rebrickable-Katalog ist ein einmaliger manueller Download (11 Dateien, etwa 17 MB; der Index benötigt etwa 115 MB) und wird langsam veralten; zur Aktualisierung laden Sie die Dateien erneut herunter und führen erneut lsf.py data --from aus.
• Rebrickable und BrickLink nummerieren einige Teile unterschiedlich, Duplo-Figuren am meisten. Zugeordnete Figuren und Bedruckungen haben eine Konfidenzangabe; überprüfen Sie die zweifelhaften per Augenschein.