레고 세트 파인더

LEGO 세트 파인더

사용자는 조각 더미에서 특색 있는 조각(피규어, 동물, 인쇄 벽돌, 차량, 특이한 모양)을 사진으로 찍습니다. 각 조각은 사진에서 잘려져 Brickognize(무료 이미지 인식 서비스)로 식별되고, 오프라인에서 Rebrickable의 공개 카탈로그를 통해 조회됩니다. 세트는 얼마나 많은 독립적인 특색 조각이 그 세트를 가리키는지에 따라 순위가 매겨집니다. 일반 벽돌과 플레이트는 세트를 구별하는 데 도움이 되지 않으므로 사진과 증거에서 제외됩니다.

모든 명령어는 하나의 스크립트로 실행됩니다. 각 단계는 하나의 실행 폴더(RUN, 예: ./lego-run)에서 파일을 읽고 씁니다:

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

아래에서 lsf.py는 위의 전체 명령어를 나타냅니다. lsf.py <단계> -h는 모든 옵션을 보여줍니다. python3가 없으면(Windows에서 자주 발생, 테스트되지 않음) 대신 py를 사용하세요. 파일 형식, 점수 매기기 및 일반적인 문제 해결 방법은 reference.md에 있습니다. 단계가 잘못되거나 파일을 수동으로 편집하기 전에 읽어보세요.

1. 작업 동의 받기

한 메시지로 다음을 물어보세요:

1. 듀플로인가요, 일반 레고인가요? (이 스킬은 듀플로에서만 테스트되었습니다. 레고라고 답하면 그렇게 말하세요.)
2. 사진이 어디에 있나요? 아직 사진이 없다면 아래 사진 촬영 팁을 알려주세요.
3. 스킬이 각 조각의 잘라낸 사진을 무료 제3자 인식 서비스인 Brickognize에 보내도 되나요? 컴퓨터를 떠나는 것은 잘라낸 사진뿐이며, 전체 사진은 절대 전송되지 않으며 메타데이터(카메라, 시간, 위치 데이터)도 포함되지 않습니다. Brickognize의 이용 약관은 업로드된 이미지(머신러닝 모델 훈련 포함)에 대한 영구적, 로열티 프리 라이선스를 부여합니다. 사용자는 Brickognize에 이미지 삭제를 요청할 수 있습니다. 동의 없이는 여기서 중단하세요.
4. 사용자가 이미 의심하는 세트(상자, 설명서, 주문 내역)가 있나요? 이는 결과를 확인하는 데 도움이 되며, 증거를 대체하지는 않습니다.

사진 촬영 팁 (있는 그대로 알려주세요):

• 특색 있는 조각만 골라내세요: 피규어, 동물, 인쇄 벽돌, 차량, 특이한 모양. 일반 벽돌과 플레이트는 세트를 구별하는 데 쓸모가 없습니다.
• 가능한 한 많은 조각을 큰 흰색 시트 위에 약 2cm 간격으로 펼쳐서 인쇄된 면이 위로 가게 하세요. 간격이 개수보다 중요합니다. 붙어 있는 조각은 하나로 잘려집니다. 더미가 필요로 하는 만큼 사진을 찍으세요. 스킬은 한 번에 약 300개를 넘어가기 전에 물어봅니다. 흰색, 회색, 투명 조각은 어두운 시트에서 더 잘 보입니다.
• 좋은 조명 아래에서 바로 위에서 촬영하고, 전체 시트가 프레임 안에 들어오게 하세요.
• 일반 레고(더 작은 조각)의 경우 사진당 조각 수를 줄이고 더 가까이 찍으세요.
• 미니피규어와 인쇄 부품이 가장 많은 증거를 제공합니다.
• 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로 종료). 사용자에게 그 목록을 알려주고, 파일을 한 폴더(Downloads 폴더면 충분함)에 저장하도록 한 후 완료했다고 말할 때까지 기다리세요. 그런 다음:

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/<photo>.jpg를 생성합니다: 번호가 매겨진 상자와 100픽셀 간격의 격자가 있는 사진입니다. 각 개요를 열고 각 상자를 평가하세요:

• 정확히 하나의 특색 있는 조각이 들어 있는 상자는 유지;
• 일반 벽돌, 플레이트, 배경, 그림자, 시트 가장자리, 조각 조각이 있는 상자는 제거;
• 두 개의 붙어 있는 조각이 있는 상자는 조각당 하나의 상자로 교체;
• 상자가 없는 특색 있는 조각 각각에 대해 상자 추가(밝은 바닥의 희미한 조각은 종종 놓칩니다).

lsf.py boxes RUN <photo> --only 3,7,12                  # 이 자동 상자들만 유지, 나머지 제거
lsf.py boxes RUN <photo> --drop 9 --add 405,225,515,385:figure --add 395,380,500,500

좌표는 개요 픽셀(x0,y0,x1,y1)이며, 격자에서 읽습니다. 각 호출은 유지된 상자만 있는 개요를 다시 그립니다: 자동 상자는 자홍색, 사용자 상자는 청록색입니다. 각 수정 후 다시 확인하세요. 조각이 작거나 밀집된 경우 lsf.py zoom RUN <photo> x0,y0,x1,y1을 사용하면 해당 영역을 같은 좌표로 두 배 크기와 50픽셀 간격 격자로 보여줍니다. 확대된 이미지에서 상자 모서리를 읽으세요.

모든 개요에서 각 특색 있는 조각이 정확히 하나의 유지된 상자에 있고, 각 유지된 상자가 해당 조각만 포함할 때 완료됩니다.

4. 잘라내기 및 확인

lsf.py crop RUN

각 RUN/sheets/crops_<photo>.jpg를 엽니다. 각 잘라낸 이미지는 하나의 전체 조각을 보여야 합니다. 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를 작성합니다. 각 행은 하나의 잘라낸 이미지에 해당: Brickognize의 답변, 매핑된 Rebrickable 부품 또는 피규어(rb, 불확실할 경우 여러 개), 색상, 신뢰도. 먼저 모든 행과 그중 피규어를 출력합니다: 피규어 일치 항목은 명백히 잘못된(여자 대신 남자) 근접 후보를 유지합니다. 각 RUN/sheets/review_<photo>.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으로 검색하세요. 이름과 색상이 맞는 후보를 선택하세요. 두세 개의 후보가 동등하게 맞으면 모두 지정하세요(--rb a;b;c): 잘못된 추측보다 순위가 더 잘 처리합니다. 듀플로 더미에서 듀플로가 아닌 부품으로 답변된 경우는 일반적으로 잘못된 것입니다.

use = y인 모든 행에 대해 잘라낸 이미지에서 믿을 수 있는 rb와 색상이 있고, 보장할 수 없는 모든 행은 use = n이면 완료됩니다.

7. 세트 순위 매기기

lsf.py rank RUN

RUN/sets.md를 읽으세요. 각 세트에 대해 계층(가능성 높음, 가능성 있음, 약함), 순위 점수, 세트를 가리키는 조각 수, 다른 세트가 없는 조각 수, 사진에서 본 세트 고유 특색 항목의 비율, 조각별 증거를 보여줍니다.

가능성 높은 세트를 표(세트 번호, 이름, 연도, 부품 수, 독점 조각 수, 발견 비율)로 사용자에게 제시한 다음, 가능성 있는 세트를 각각 한 줄로 표시하세요. 다음을 지적하세요:

• "증거 공유" 아래에 나열된 세트: 같은 조각을 두고 경쟁하므로 사용자에게 어떤 세트를 가지고 있는지 물어보세요.
• 공유 부품에서 높은 점수를 받았지만 고유 부품이 적은(낮은 발견 비율) 큰 세트: 일반적인 오탐지입니다.
• 나열된 세트로 설명되지 않는 특색 있는 조각: 더미에 다른 세트가 있을 수 있습니다.

사용자에게 인식하거나 체크리스트에 추가하려는 세트를 물어보세요. 체크리스트의 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에서 테스트되었습니다. 일반 레고와 Windows는 테스트되지 않았습니다.
• Brickognize는 무료 제3자 서비스입니다. 조각 잘라낸 이미지가 업로드되며 서비스가 이를 보관하고 사용할 수 있습니다(1단계). predict 엔드포인트는 API 설명에서 "레거시"로 표시되어 있으므로 변경되거나 중단될 수 있습니다.
• Rebrickable 카탈로그는 한 번 수동으로 다운로드(11개 파일, 약 17MB, 인덱스는 약 115MB)하며 천천히 오래됩니다. 새로 고치려면 파일을 다시 다운로드하고 lsf.py data --from을 다시 실행하세요.
• Rebrickable과 BrickLink는 일부 부품, 특히 듀플로 피규어의 번호를 다르게 매깁니다. 매핑된 피규어와 인쇄 부품에는 신뢰도가 함께 표시되므로 의심스러운 것은 눈으로 확인하세요.