LEGOセットファインダー

ユーザーは山の中の特徴的なピース（フィギュア、動物、プリントブロック、車両、変わった形状）を写真に撮ります。各ピースは写真から切り抜かれ、Brickognize（無料の画像認識サービス）によって識別され、Rebrickableの公開カタログとオフラインで照合されます。セットは、独立した特徴的なピースがいくつそのセットを指し示すかによってランク付けされます。プレーンなブロックやプレートはセットの区別にあまり役立たないため、写真や証拠からは除外されます。

すべてのコマンドは1つのスクリプトです。各ステップは1つの実行フォルダ（以下 RUN、例：./lego-run）内でファイルを読み書きします：

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

以下、lsf.py は上記の完全なコマンドを表します。lsf.py <step> -h ですべてのオプションを表示します。python3 が見つからない場合（Windowsではよくありますが、未テストです）、代わりに py を使用してください。ファイル形式、スコアリング、および一般的な問題の修正方法については reference.md を参照してください。ステップがうまくいかない場合や、手動でファイルを編集する前に読んでください。

1. ユーザーと作業内容を合意する

1つのメッセージで以下を尋ねてください：

デュプロですか、それとも通常のLEGOですか？（このスキルはデュプロでのみテストされています。ユーザーがLEGOと答えた場合はその旨を伝えてください。）
写真はどこにありますか？まだない場合は、以下の写真のヒントを伝えてください。
スキルは、個々のピースの切り抜き画像を無料のサードパーティ認識サービスBrickognizeに送信してもよいですか？送信されるのはそれらの切り抜きのみで、完全な写真は決してコンピュータの外に出ません。また、メタデータ（カメラ、時刻、位置情報）は含まれません。Brickognizeの利用規約では、アップロードされた画像に対する永久的かつロイヤリティフリーのライセンス（機械学習モデルのトレーニングを含む）をBrickognizeに付与することになります。ユーザーはBrickognizeに画像の削除を依頼できます。承諾がない場合は、ここで停止してください。
ユーザーがすでに疑っているセット（箱、説明書、注文履歴など）はありますか？これらは結果の確認に役立ちますが、証拠を置き換えるものではありません。

写真のヒント（そのまま伝えてください）：

特徴的なピースのみを取り出してください：フィギュア、動物、プリントブロック、車両、変わった形状。プレーンなブロックやプレートはセットの区別に役立ちません。
できるだけ多くのピースを、大きな無地の白いシートの上に、各ピースの周りに約2cmのスペースを空けて、プリント面を上にして広げてください。ピースの数よりも隙間の方が重要です：接触しているピースは1つとして切り抜かれます。山の大きさに応じて必要な枚数の写真を撮ってください。スキルは1回の実行で約300ピースを超える前に確認を求めます。白、グレー、透明のピースは、暗いシートの上でより良く際立ちます。
良い照明の下で真上から、シート全体がフレームに収まるように撮影してください。
通常のLEGO（より小さいピース）の場合は、各写真に配置するピースを少なくし、より近づいて撮影してください。
ミニフィギュアとプリントパーツが最も多くの証拠を提供します。
JPEGまたはPNG写真はそのまま使用できます。HEIC写真（iPhone）は、pillow-heifパッケージが必要か、JPEGとして書き出してください。

ピースの種類、写真ファイルがわかり、Brickognizeの使用許可を得たら、このステップは完了です。

2. インストール確認とカタログ

lsf.py selftest          # オフライン、数秒で完了。「0 failed」で終了する必要があります
lsf.py data --info       # 終了コード0：カタログがインストールされています。ステップ3へ進みます

Pillowがない場合、スクリプトはインストール方法を表示します。

ユーザーはRebrickableカタログを手動で一度ダウンロードします：Rebrickableの利用規約は自動ダウンロードを禁止しているため、あなた自身がこれらのファイルをいかなるツールでも決して取得しないでください。lsf.py data を実行します：ダウンロードページと正確なファイル名が表示されます（意図的に終了コード1で終了します）。そのリストをユーザーに提示し、ファイルを1つのフォルダ（ダウンロードフォルダで結構です）に保存するよう伝え、完了したと言うまで待ちます。その後：

lsf.py data --from ~/Downloads     # またはユーザーが使用したフォルダを指定。まだ見つからないファイルがあれば名前を表示します

lsf.py data --info が終了コード0で終了したら完了です。ダウンロードは約17MBです。インデックスは ~/.cache/lego-set-finder（または $LEGO_SET_FINDER_DATA）に約115MBを消費します。後で更新するには、ユーザーが再度ファイルをダウンロードし、あなたが再度 data --from を実行します。

3. ピースを見つける

lsf.py detect RUN <写真またはフォルダ>

RUN/overview/<写真>.jpg が書き出されます：番号付きのボックスと100ピクセルごとにラベル付きのグリッドが描かれた写真です。すべての概観画像を開き、各ボックスを判断します：

正確に1つの特徴的なピースを含むボックスは保持します；
プレーンなブロックやプレート、背景、影、シートの端、ピースの破片を含むボックスは削除します；
接触している2つのピースを含むボックスは、ピースごとに1つのボックスに置き換えます；
ボックスがない特徴的なピースごとにボックスを追加します（薄い色の床の上の薄い色のピースは見逃されがちです）。

lsf.py boxes RUN <写真> --only 3,7,12                  # これらの自動ボックスを保持し、残りは削除
lsf.py boxes RUN <写真> --drop 9 --add 405,225,515,385:figure --add 395,380,500,500

座標は概観画像のピクセル（x0,y0,x1,y1）で、グリッドから読み取ります。各呼び出しは、保持されたボックスのみで概観画像を再描画します：自動ボックスはマゼンタ、あなたが追加したボックスはシアンで表示されます。修正のたびに再度確認してください。ピースが小さいか密集している場合、lsf.py zoom RUN <写真> x0,y0,x1,y1 はその領域を同じ座標で2倍のサイズ、50ピクセルごとのグリッドで表示します。ズーム画像からボックスの角を読み取ってください。

すべての概観画像で、すべての特徴的なピースが正確に1つの保持されたボックスに収まり、すべての保持されたボックスがそのピースのみを含む状態になれば、このステップは完了です。

4. 切り抜きを切断して確認する

lsf.py crop RUN

RUN/sheets/crops_<写真>.jpg をすべて開きます。各切り抜きは1つのピース全体が写っていなければなりません。lsf.py boxes でボックスを修正し、すべての切り抜きが条件を満たすまで再度クロップします。

5. 識別

lsf.py identify RUN

各切り抜きをBrickognizeに送信します。デフォルトでは3つずつ（--workers、最大4つ）送信されます。回答は画像とエンドポイントごとにキャッシュされるため、同じエンドポイントにすでに送信された切り抜きに対して再実行してもコストはかかりません。300回の新しい呼び出しで停止します（終了コード2）：再実行する前に、より高い --max-calls を指定して再実行してもよいかユーザーに確認してください。

回答が得られなかった切り抜きがリスト表示されます。Brickognizeは、大きくて柔らかいピース（車体、客車、布など）では何も見つからないことがよくあります。--endpoint predict/parts/ --only <crops> を指定して一度試してください。それでも失敗する場合は、ステップ6で自分でピースに名前を付けます。

6. すべてのピースをマッピングして確認する

lsf.py match RUN --kind duplo        # または --kind lego

これにより RUN/pieces.tsv が書き出されます。1行が1つの切り抜きに対応します：Brickognizeの回答、それがマッピングされるRebrickableのパーツまたはフィギュア（rb、不明な場合は複数）、色、および信頼度です。まず、印刷された行（特にフィギュア）を確認します：フィギュアのマッチでは、明らかに間違っている（女の子のフィギュアに対して男の子など）惜しい候補も保持されます。RUN/sheets/review_<写真>.jpg（切り抜き、信頼度、Brickognizeの名前、Rebrickableの番号と色）を開き、各切り抜きをそのキャプションと比較します。

カタログヘルパーを使用して間違いを修正します：

lsf.py lookup yellow truck flatbed grille --duplo --colour Yellow   # 名前またはパーツ番号で検索
lsf.py fix RUN p10-m1 --rb 15454pr0006 --colour Yellow
lsf.py fix RUN p08-27 --colour "Neon Yellow"     # 色に関してはあなたの目がBrickognizeより優れています
lsf.py fix RUN p08-m3 --use n                     # 識別できない：除外する
lsf.py set 10931                                  # セットのパーツを表示、仮説を確認するため
lsf.py sets-of 14094 --colour "Medium Azure"      # 特定の色のパーツがどのセットに含まれるか

Brickognizeが見逃したピースに、あなたが見て名前を付け、lookup で検索します。名前と色が適合する候補を選びます。2つまたは3つの候補が同等に適合する場合は、すべてを指定します（--rb a;b;c）：間違った推測よりも、ランキングはそのような状況にうまく対応します。デュプロの山に対して非デュプロのパーツで回答された場合は、通常は間違っています。

use = y のすべての行に、切り抜きからあなたが信頼できる rb と色があり、保証できないすべての行に use = n が設定されていれば、このステップは完了です。

7. セットをランク付けする

lsf.py rank RUN

RUN/sets.md を読んでください。各セットについて、ティア（可能性が高い、可能性あり、弱い）、ランクスコア、そのセットを指し示すピースの数、他のセットにはない独自のピースの数、写真で見られたセット独自の特徴的アイテムの割合、および証拠をピースごとに表示します。

可能性の高いセットを表（セット番号、名前、年、ピース数、このセットのみのピース数、見られた割合）でユーザーに提示し、次に可能性のあるセットを1行ずつ提示します。以下を指摘してください：

「証拠を共有」にリストされているセット：同じピースを競合しているため、ユーザーにどちらを持っているか尋ねてください；
多くの共有パーツでスコアが高いが、独自のパーツが少ない（見られた割合が低い）大きなセット：これらは通常の誤検出です；
リストされたセットで説明されていない特徴的なピース：別のセットが山の中にある可能性があります。

ユーザーに、どのセットを認識しているか、またはチェックリストに追加したいかを尋ねてください。チェックリスト内のRebrickableリンクは、各セットの箱の画像を表示します。

8. チェックリストページを作成する

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

--sets を指定しない場合は、可能性の高いティアのセットが使用されます。--confirmed はすべてのセットを確認済みとしてラベル付けします（ユーザーが確認した後に使用します）。結果は RUN/checklist.html で、ディスクから開いたときに機能する単一のファイルです。使い方をユーザーに伝えてください：セットを選ぶか「色の山ごと」に切り替え、各ピースを該当する山に移動するときにパーツの数をタップし、「見つけたものを隠す」で残りを確認し、「不足パーツリスト」でまだ不足しているものをコピーし、「チェックを保存またはリセット」でチェックをファイルに保存します。チェックはそのブラウザにのみ保存されます。パーツの画像はRebrickableの画像サーバーから読み込まれるため、インターネット接続が必要です。

9. 不足しているものを伝える

ユーザーが仕分けを始める前に、各選択セットのどの特徴的アイテムが写真に写っていなかったかを伝えてください：

lsf.py missing RUN --sets 10906,10931

「写真にない」ことは「欠品」ではないことを明確に伝えてください：写真に撮られたのは特徴的なピースのみです。不足パーツに適合する、あなたが除外した（use = n）切り抜きがリストされた場合、その切り抜きをもう一度見て、適合する場合は lsf.py fix RUN <crop> --use y で復元してください。その後、再度ランク付けします。仕分け後、ページがコピーするリスト、またはページが保存するチェックファイル（lsf.py missing RUN --sets ... --ticks <file>）を使用して、セットごとの不足パーツを提供します。

ユーザーに伝えるべき制限事項

混合デュプロコレクション（12セット）でmacOS上でテストされました。通常のLEGOとWindowsは未テストです。
Brickognizeは無料のサードパーティサービスです。ピースの切り抜きがアップロードされ、Brickognizeはそれらを保持および使用する可能性があります（ステップ1）。そのpredictエンドポイントはAPI説明で「レガシー」とマークされているため、変更または停止される可能性があります。
Rebrickableカタログは手動で一度ダウンロードする必要があります（11ファイル、約17MB。インデックスは約115MBを消費します）。時間の経過とともに古くなります。更新するには、ファイルを再度ダウンロードし、lsf.py data --from を再度実行してください。
RebrickableとBrickLinkでは一部のパーツ、特にデュプロフィギュアの番号付けが異なります。マッピングされたフィギュアとプリントには信頼度が付与されます。疑わしいものは目視で確認してください。

レゴセットファインダー