Pedrovbm1/biblioteca

Biblioteca 3D comunitária

HOME3D = $EXPLICADORES_3D ou ~/.explicadores-3d. A biblioteca está em HOME3D/biblioteca/: CATALOGO.md (uma linha por modelo com miniatura, parâmetros e defeitos), manifiesto.json, modelos/, piezas/, base/ (estilos, lib2d, painel de ajustes), aportes/ (o que a comunidade adiciona), vendor/ (three.js, three.quarks, Tweakpane, fonte Fredoka) e vista.html.

Tudo é processual e determinístico: nada de texturas baixadas nem Math.random. Escala padrão 1 u = 1 cm.

Buscar e usar um modelo

1. Busque por nome ou ideia sem ler o catálogo inteiro (são ~200 linhas): grep -i "mosquito\|insecto" HOME3D/biblioteca/CATALOGO.md. Leia a linha: o que é, arquivo → export(parâmetros), estilo de cor e defeitos conhecidos (principalmente "⚠ olhos").
2. Veja-o (opcional): sirva a pasta (python -m http.server 8795 dentro de biblioteca/) e abra localhost:8795/vista.html?m=<id>; com &ajustes=1 aparece o painel para mover câmera, cores e luzes. Ou veja a miniatura miniaturas/<id>.png (em um subagente se seu harness permitir, para não carregar imagens no seu contexto).
3. Copie-o para o projeto (escena/modelos/), nunca o importe da biblioteca, e ajuste o import do estilo (../../base/estilo3d.js → ../estilo3d.js). Se usar partículas (piezas/particulas/), copie também vendor/quarks/ e adicione "quarks.core" ao importmap.
4. Cada arquivo traz em cima sua API (eixos, escala, métodos .poner* / .update(t)): isso vai em uma linha na solicitação do construtor.

Contribuir com modelos novos: vem ativado (ao final de cada vídeo)

Contribuir é o normal: ao final de um vídeo sempre é oferecido, e o usuário só precisa dizer não se não quiser. A licença é MIT para o código e CC BY 4.0 para os modelos, com crédito visível para quem contribui.

1. Detecte os modelos e peças novas do projeto (não gasta tokens; compara contra a biblioteca):

   python "SKILL_DIR/nuevos.py" <projeto>
   

   Se disser "não há modelos novos" ou "o usuário já disse que não", não pergunte nada e termine.
2. Prepare tudo antes de perguntar, um por modelo. Extraia --nome e --que-e do comentário no topo do arquivo e --fn do seu export principal. Verifique antes que não traga nada pessoal (clientes, marcas, logotipos, textos do seu canal), que seja determinístico e que não tenha formas que pareçam olhos; o que não cumprir, não é preparado.

   python "SKILL_DIR/aportar.py" --arquivo <projeto>/escena/modelos/regadera.js --fn criarRegadera --id regadera \
     --nome "Regadera" --que-e "Regadera de jardim com alça e bico" [--autor "<nome ou @usuário>"] --estilo casa
   

   O autor é solicitado apenas uma vez (como ele quer aparecer no crédito) e fica em ~/.explicadores-3d/autor.txt. Isso gera miniatura 400x400, ficha.json (autor, data, CC BY 4.0), linha do manifesto e do catálogo, e passa no validador. Nada é enviado ainda.
3. Pergunte, em uma linha, com a lista do que foi preparado: Envio para a biblioteca? (S/n). Enter, "s", "sim" ou "vai" = sim. Apenas "n" ou "não" (ou algo que claramente rejeite) = não.
4. Sim → um único PR com todos:

   python "SKILL_DIR/aportar.py" --publicar regadera,maceta
   python "SKILL_DIR/nuevos.py" <projeto> --subido escena/modelos/regadera.js escena/modelos/maceta.js
   

   Dê o link do PR. Não → python "SKILL_DIR/nuevos.py" <projeto> --no e não pergunte novamente nesse projeto (também em novas sessões: fica em <projeto>/.biblioteca.json).

• Sem gh: --publicar deixa tudo pronto e explica os 3 passos manualmente (fork na web, commit em um branch, PR). Para instalar gh: winget install GitHub.cli / brew install gh / cli.github.com, e depois gh auth login.
• Cada PR é validado por um GitHub Action (navegador headless, determinismo, sem rede, tamanho, miniatura, linha e autor) e aprovado por uma pessoa. Ao ser mesclado, o autor aparece em CATALOGO.md, na galeria index.html e no ranking APORTADORES.md. Quem contribui recebe primeiro os pacotes novos ou destacados (ver README, "Contribui e recebe").

Corrigir um defeito

Se em um vídeo você corrigir um defeito de um modelo da biblioteca, proponha a correção ao repositório também (PR normal, explicando o antes e o depois); as alterações fora de aportes/ são revisadas manualmente por quem mantém o repositório.