donataskasp/lego-set-finder

Localizador de conjuntos LEGO

O usuário fotografa as peças distintivas de uma pilha: figuras, animais, tijolos impressos, veículos, formas estranhas. Cada peça é recortada das fotos, identificada pelo Brickognize (um serviço gratuito de reconhecimento de imagem) e pesquisada offline no catálogo público do Rebrickable. Os conjuntos são classificados por quantas peças distintivas independentes apontam para eles. Tijolos e placas lisas diferenciam mal os conjuntos, por isso ficam de fora das fotos e das evidências.

Todos os comandos são um único script. Cada passo lê e escreve arquivos em uma pasta de execução (RUN abaixo, por exemplo ./lego-run):

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

Abaixo, lsf.py representa esse comando completo. lsf.py <passo> -h lista todas as opções. Onde python3 não for encontrado (frequentemente no Windows, que não foi testado), use py em vez disso. Os formatos de arquivo, a pontuação e as correções para problemas comuns estão em reference.md; leia-o quando um passo der errado ou antes de editar um arquivo manualmente.

1. Acordar o trabalho com o usuário

Pergunte, em uma única mensagem:

1. Duplo ou LEGO normal? (Esta habilidade foi testada apenas em Duplo. Diga isso se a resposta for LEGO.)
2. Onde estão as fotos? Se ainda não houver nenhuma, dê as dicas de fotografia abaixo.
3. A habilidade pode enviar uma imagem recortada de cada peça individual para o Brickognize, um serviço de reconhecimento gratuito de terceiros? Apenas esses recortes saem do computador, nunca as fotos completas, e eles não carregam metadados (sem dados de câmera, hora ou localização). Os termos do Brickognize concedem a ele uma licença perpétua e isenta de royalties para usar imagens enviadas, inclusive para treinar modelos de machine learning; o usuário pode pedir ao Brickognize que as remova. Sem uma resposta positiva, pare aqui.
4. Algum conjunto que o usuário já suspeita (caixas, manuais, histórico de pedidos)? Isso ajuda a verificar o resultado, nunca substitui a evidência.

Dicas de fotografia (forneça-as exatamente como escritas):

• Separe apenas as peças distintivas: figuras, animais, tijolos impressos, veículos, formas estranhas. Tijolos e placas lisas são inúteis para diferenciar conjuntos.
• Espalhe quantas couberem em uma grande folha branca lisa com cerca de 2 cm de espaço ao redor de cada peça, lado impresso para cima. O espaço importa mais que a quantidade: peças que se tocam são recortadas como uma só. Tire quantas fotos a pilha precisar; a habilidade pergunta antes de ultrapassar cerca de 300 peças em uma execução. Peças brancas, cinzas e transparentes se destacam melhor em uma folha escura.
• Fotografe de cima para baixo, com boa iluminação, com a folha inteira no quadro.
• Para LEGO normal (peças menores), coloque menos peças em cada foto e fotografe mais de perto.
• Minifigures e peças impressas carregam a maior parte das evidências.
• Fotos JPEG ou PNG funcionam como estão. Fotos HEIC (iPhone) precisam do pacote pillow-heif, ou exporte-as como JPEG.

Concluído quando você souber o tipo de peças, os arquivos de foto e tiver a resposta positiva para o Brickognize.

2. Verificação de instalação e catálogo

lsf.py selftest          # offline, alguns segundos; deve terminar com "0 failed"
lsf.py data --info       # exit 0: um catálogo está instalado, vá para o passo 3

Se o Pillow estiver faltando, o script diz como instalá-lo.

O usuário baixa o catálogo do Rebrickable manualmente, uma vez: os termos do Rebrickable proíbem downloads automatizados, portanto nunca baixe esses arquivos você mesmo, com nenhuma ferramenta. Execute lsf.py data: ele imprime a página de download e os arquivos exatos (sai com código 1 propositalmente). Dê essa lista ao usuário, diga para salvar os arquivos em uma pasta (Downloads está ok) e aguarde até que ele diga que está pronto. Então:

lsf.py data --from ~/Downloads     # ou a pasta que ele usou; nomeia qualquer arquivo ainda faltando

Concluído quando lsf.py data --info sair com código 0. Os downloads têm cerca de 17 MB; o índice ocupa cerca de 115 MB em ~/.cache/lego-set-finder (ou $LEGO_SET_FINDER_DATA). Para atualizá-lo depois, o usuário baixa os arquivos novamente e você executa data --from novamente.

3. Encontrar as peças

lsf.py detect RUN <fotos ou pasta>

Isso escreve RUN/overview/<foto>.jpg: a foto com caixas numeradas e uma grade marcada a cada 100 pixels. Abra cada overview e julgue cada caixa:

• mantenha uma caixa que contenha exatamente uma peça distintiva;
• descarte caixas sobre tijolos e placas lisas, fundo, sombras, borda da folha e fragmentos de uma peça;
• substitua uma caixa que contenha duas peças tocantes por uma caixa para cada peça;
• adicione uma caixa para cada peça distintiva que não tenha nenhuma (peças claras em um fundo claro são frequentemente perdidas).

lsf.py boxes RUN <foto> --only 3,7,12                  # mantenha estas caixas automáticas, descarte o resto
lsf.py boxes RUN <foto> --drop 9 --add 405,225,515,385:figure --add 395,380,500,500

As coordenadas são pixels da overview (x0,y0,x1,y1), lidas na grade. Cada chamada redesenha a overview apenas com as caixas mantidas: as automáticas em magenta, as suas em ciano. Olhe novamente após cada correção. Onde as peças são pequenas ou estão muito próximas, lsf.py zoom RUN <foto> x0,y0,x1,y1 mostra aquela região com o dobro do tamanho, com as mesmas coordenadas e uma grade a cada 50 px; leia os cantos da caixa no zoom.

Concluído quando, em cada overview, toda peça distintiva estiver exatamente em uma caixa mantida e toda caixa mantida contiver apenas aquela peça.

4. Recortar e verificar os recortes

lsf.py crop RUN

Abra cada RUN/sheets/crops_<foto>.jpg. Cada recorte deve mostrar uma peça inteira. Corrija as caixas com lsf.py boxes e recorte novamente até que isso seja verdade para todos.

5. Identificar

lsf.py identify RUN

Envia cada recorte para o Brickognize, 3 de cada vez por padrão (--workers, no máximo 4). As respostas são armazenadas em cache por imagem e endpoint, então uma reexecução não custa nada para recortes já enviados para aquele endpoint. Ele para em 300 novas chamadas (código de saída 2): pergunte ao usuário antes de reexecutar com um --max-calls maior.

Recortes sem resposta são listados. O Brickognize frequentemente não encontra nada em peças grandes ou macias (corpos de veículos, carruagens, tecido). Tente uma vez com --endpoint predict/parts/ --only <recortes>. Para o que ainda falhar, você nomeia a peça manualmente no passo 6.

6. Mapear e revisar cada peça

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

Isso escreve RUN/pieces.tsv, uma linha por recorte: a resposta do Brickognize, a peça ou figura do Rebrickable a que mapeia (rb, vários quando incerto), a cor e uma confiança. Ele imprime as linhas para verificar primeiro, cada figura entre elas: correspondências de figuras mantêm concorrentes próximos que podem estar claramente errados (uma menina por um menino). Abra cada RUN/sheets/review_<foto>.jpg (recorte, confiança, nome do Brickognize, número e cor do Rebrickable) e compare cada recorte com sua legenda.

Corrija o que estiver errado com os ajudantes de catálogo:

lsf.py lookup caminhão amarelo carroceria grade --duplo --colour Amarelo   # pesquise por nome ou número de peça
lsf.py fix RUN p10-m1 --rb 15454pr0006 --colour Amarelo
lsf.py fix RUN p08-27 --colour "Amarelo Neon"     # seu olho vence o Brickognize em cor
lsf.py fix RUN p08-m3 --use n                     # não pode ser identificado: deixe de fora
lsf.py set 10931                                  # as peças de um conjunto, para verificar um palpite
lsf.py sets-of 14094 --colour "Medium Azure"      # quais conjuntos têm uma peça em uma cor

Nomeie uma peça que o Brickognize perdeu com base no que você vê, então faça lookup; escolha o candidato cujo nome e cores se encaixam. Quando dois ou três candidatos se encaixam igualmente, forneça todos (--rb a;b;c): a classificação lida com isso melhor do que com um palpite errado. Uma pilha Duplo respondida com uma peça não Duplo geralmente está errada.

Concluído quando toda linha com use = y tiver um rb e uma cor em que você acredita pelo recorte, e toda linha que você não pode garantir tiver use = n.

7. Classificar os conjuntos

lsf.py rank RUN

Leia RUN/sets.md. Para cada conjunto, mostra o nível (provável, possível, fraco), a pontuação, quantas peças apontam para ele, quantas dessas nenhum outro conjunto tem, a parcela dos itens distintivos do próprio conjunto vistos nas fotos e a evidência peça por peça.

Apresente os conjuntos prováveis ao usuário como uma tabela (número do conjunto, nome, ano, peças, peças exclusivas, parcela vista), depois os possíveis em uma linha cada. Destaque:

• conjuntos listados em "Compartilha evidências com": eles competem pelas mesmas peças, então pergunte ao usuário qual deles ele tem;
• conjuntos grandes que pontuam em muitas peças compartilhadas, mas mostram poucas das suas (baixa parcela vista): estes são os falsos positivos comuns;
• peças distintivas que nenhum conjunto listado explica: pode haver outro conjunto na pilha.

Pergunte ao usuário quais conjuntos ele reconhece ou deseja na checklist. O link do Rebrickable na checklist mostra a imagem da caixa de cada conjunto.

8. Construir a página de checklist

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

Sem --sets, ele pega o nível provável. --confirmed rotula cada conjunto como confirmado (use depois que o usuário os verificou). O resultado é RUN/checklist.html, um arquivo que funciona quando aberto do disco. Diga ao usuário como usá-lo: escolha um conjunto ou mude para "Por pilha de cor", toque na contagem de uma peça conforme cada peça vai para sua pilha, "Ocultar encontrados" para ver o que resta, "Lista de peças faltantes" para copiar o que ainda está faltando, "Salvar ou redefinir marcações" para manter as marcações em um arquivo. As marcações salvam apenas naquele navegador. As imagens das peças são carregadas do servidor de imagens do Rebrickable, então precisam de conexão.

9. Dizer o que está faltando

Antes de o usuário separar, diga a ele quais itens distintivos de cada conjunto escolhido não apareceram nas fotos:

lsf.py missing RUN --sets 10906,10931

Diga claramente que "não nas fotos" não é "faltando": apenas peças distintivas foram fotografadas. Quando nomear um recorte que você deixou de fora (use = n) que se encaixa em uma peça faltante, olhe para aquele recorte novamente e restaure-o com lsf.py fix RUN <recorte> --use y se ele couber; então classifique novamente. Após a separação, pegue a lista que a página copia, ou o arquivo de marcações que a página salva (lsf.py missing RUN --sets ... --ticks <arquivo>), e forneça as peças faltantes por conjunto.

Limites a informar ao usuário

• Testado em uma coleção mista de Duplo (12 conjuntos), no macOS. LEGO normal e Windows não foram testados.
• Brickognize é um serviço gratuito de terceiros; os recortes de peças são enviados para ele e ele pode mantê-los e usá-los (passo 1). Seus endpoints predict são marcados como "legado" na descrição da API, portanto podem mudar ou parar.
• O catálogo do Rebrickable é um download único feito manualmente (11 arquivos, cerca de 17 MB; o índice ocupa cerca de 115 MB) e fica desatualizado lentamente; para atualizá-lo, baixe os arquivos novamente e execute lsf.py data --from novamente.
• Rebrickable e BrickLink numeram algumas peças de forma diferente, figuras Duplo mais que tudo. Figuras e impressões mapeadas carregam uma confiança; verifique as duvidosas visualmente.