O que lamina faz?
Uma máquina, um modelo, uma página. O leitor rola uma breve explicação e encontra a máquina várias vezes: inteira, aberta, apenas seu mecanismo, em movimento, desmontada. Cada figura é o mesmo modelo 3D auditado, então nada na página pode discordar de nada mais nela.
SKILL_DIR é a pasta onde este arquivo está. examples/colibri/ é uma página completa (um beija-flor robótico de 12 g, 44
peças, seis figuras): leia antes de começar e copie sua estrutura.
cd "$SKILL_DIR" && npm install && npx playwright install chromium # uma vez
python examples/colibri/model.py --audit # modelo → colibri.glb, deve imprimir `audit passed`
node build.mjs examples/colibri # → out/colibri.html, um arquivo offline
node scripts/shots.mjs out/colibri.html # capturas de cada figura + verificações de controle
Com Blender em vez do módulo bpy: blender -b -P examples/colibri/model.py -- --audit.
Fluxo de trabalho
Trabalhe nesta ordem. A maior parte da qualidade é decidida nas etapas 1 a 3, antes de qualquer malha.
- A verdade primeiro. Colete os números reais: tamanhos, massas, velocidades, contagens de dentes, relações, limites. Pesquise por eles.
Coloque-os em um pequeno módulo puro (
kin.js) e diga na página de onde eles vêm. Peças inventadas recebem nomes inventados: um produto fictício com um código de modelo, nunca uma marca real. - Uma entrada. Nomeie a única variável que aciona a máquina (um ângulo de manivela, um curso, uma posição de válvula). Cada pose e cada leitura é uma função dela.
- Lista de peças e layout, no papel. 40+ peças agrupadas por conjunto, cada uma com o que ela fica apoiada. Disponha o mecanismo
com números antes de modelar: centros de engrenagens em (z1 + z2)·m / 2, posições de eixos, o que tem que desobstruir o quê, onde
cada eixo cruza uma carcaça. Escreva a lista no topo de
model.py. - Modele no Blender com
blender/tdb.py(veja "Modelagem"). - Audite até zerar.
python model.py --auditaté imprimiraudit passed. - Escreva a página com
kit/page.js(veja "A página"): 4 a 7 figuras, cada uma respondendo a uma pergunta. - Observe-a.
node scripts/shots.mjs out/<nome>.htmldeve imprimirchecks passed. Depois leia cada PNG que ele gerou. Corrija e repita até que uma passagem completa não encontre nada.
Mostre uma figura ao usuário cedo (a máquina inteira, construída e capturada) antes de escrever o resto da página.
Modelagem
Qualquer coisa com um corpo curvo, uma carcaça sobre um mecanismo, ou peças que se movem umas sobre as outras é modelada no Blender, não digitada como primitivas do three.js. Primitivas posicionadas a olho são como as peças acabam se penetrando.
- Um corpo é uma superfície analítica, nunca uma esfera ou um torno que a representa. Defina seções de controle, junte-as
com
splinee corte a superfície em painéis compatch(surf, u0, u1, v0, v1, thick=0.7): espessura real, lacunas reais onde você deixa intervalos de parâmetros de fora, um chanfro em cada aresta. part(name, bmesh, mat, asm, bevel, cut, explode, open, mats)registra uma peça fechada no quadro de seu pai.cut=[…]subtrai com booleanos exatos: um furo para cada eixo, perna, olho ou cabo que atravessa uma carcaça.carve()corta uma peça antes dela ser soldada em uma parte.- Uma estrutura soldada é uma peça (
join): quilha, armações de anel, placas, postes, bossas. Parafusos, escotilhas e aberturas são fundidos ao painel ao qual pertencem. A auditoria é entre peças, então decida deliberadamente o que é uma peça. - Movimento:
joint(part, 'rev' | 'slide', axis, law, input)comvalue = k·q + a·sin(h·q + p) + c + b·tanh(g·cos q).rig_input(name, lo, hi, samples, rest)declara o que a auditoria varre.mate(a, b, depth)declara dentes em malha;gear_info(...)declara engrenagens e cremalheiras;frame(...)é um vazio que carrega uma junta;anchor(name, at)é um ponto nomeado. - Contatos são nivelados (folga de 0,05 mm), tangentes, ou borda-sob-superfície. Nada está afundado em nada. Uma peça que flutua é um bug: dê a ela um suporte.
- Materiais são nomes (
shell,orange= o destaque,ink,dark,steel,brass,carbon,lens,membrane,pcb); a página lhes dá a aparência.mats={'orange': predicate}pinta uma região de uma peça.
A auditoria
blender/audit.py coloca o modelo em cada entrada com as mesmas leis de junta que a página usa e prova nas malhas reais:
| Verificação | Significado |
|---|---|
| interferência | Nenhuma peça atravessa outra em repouso, em cada pose amostrada, ou explodida. Um acoplamento declarado pode sobrepor-se até sua profundidade. |
| suporte | Cada peça toca outra e todas se mantêm juntas como um conjunto. |
| engrenagens | Distância entre centros (z1 + z2)·m / 2, relação de velocidade inversa, deslocamento da cremalheira = ângulo do pinhão × raio primitivo. |
| fechada | Cada peça é um volume fechado; uma chapa tem espessura. |
Cada falha nomeia o par, a pose, a profundidade e o ponto. Corrija a geometria: mova-a, encolha-a, corte um furo,
altere o layout, reduza um curso. Nunca alargue um acoplamento, delete uma peça ou pule uma pose para silenciá-la. Se a auditoria
mostrar que os números reais não cabem, os números na página também mudam. Se você não puder executá-la (sem Blender, sem
bpy), diga isso e não considere o modelo finalizado.
A página
kit/rig.js carrega o GLB e o posiciona: rig.pose(inputs, {explode, focus, open}). kit/page.js é a página:
import {createPage} from 'lamina-kit/page.js';
const P = await createPage({title, model}); // model: {root, meshes, update(state)}
P.header({code, kicker, name, sub}); P.lead('…'); P.h2('01 — O conjunto', '…'); P.text('…');
P.figure({n: 1, title, cam: {az, el, d, ty, tz}, controls, step: (fig, dt) => state, readout: (fig, state) => html});
P.caption('<b>Fig 1.</b> …'); P.chain([...]); P.table([...]); P.footer(left, right); P.start();
- Um renderizador para cada figura. Cada cartão visível é posicionado, renderizado e copiado para seu próprio canvas. Nunca um contexto WebGL por figura.
- O
stepde uma figura retorna o estado paramodel.update.state.look(part, asm)retorna'solid','ghost'ou'hide'para cada malha: é assim que um modelo se torna a máquina inteira, a máquina aberta e apenas o mecanismo. - Controles são poucos e reais: no máximo uma pausa, três velocidades e um controle deslizante por figura (
P.range,P.speeds,data-pp). Apenas entradas nativas. Nenhum console, painel, linha do tempo ou painel de status. - Peças nomeadas:
...P.partsPanel(PARTS)adiciona um botão por peça com uma linha sobre ela; selecionar uma (ou clicar nela na figura) torna o resto fantasma e aproxima a câmera dela.PARTSé[name, /regex/, line]. - As figuras a considerar, nesta ordem: a máquina inteira funcionando · o interior (um controle deslizante levanta a carcaça) · apenas o mecanismo, lento, com uma fase que você pode percorrer · o movimento que importa, traçado · uma compensação ou um limite · a vista explodida com as peças nomeadas. Depois, uma tabela dos números.
Escrita
Espanhol por padrão (corresponda ao idioma do usuário). Curta. Uma introdução de duas frases, depois por figura: um título, duas ou três frases que dizem o que olhar e por que é assim, a figura, e uma legenda com um fato. Cada número no texto vem do modelo. Diga o que é fictício e de onde vêm os números reais.
Aparência
Escuro, sempre. Página #0e0f11, texto #ece8df, um destaque: dourado #d4a94e. Cada cartão tem um suave halo de luz atrás
do modelo para que partes escuras mantenham um contorno. O modelo é branco e dourado: carcaças brancas brilhantes, dourado para o que o
material orange marca, grafite e aço por baixo. Inter para texto, JetBrains Mono em versalete para rótulos,
números e botões.
Partes escuras em uma página escura perdem suas bordas. Mantenha o preto para algumas peças; faça a mecânica interna em aço, alumínio ou
latão, e verifique cada peça selecionada contra o fundo em fig*-part.png.
Revisão
Você não pode assistir à página; você pode ler quadros. scripts/shots.mjs escreve top.png, figN.png, figN-part.png e
phone.png, pressiona cada pausa, move cada controle deslizante, seleciona uma peça e relata erros de console. Depois observe:
- O modelo.
audit passedno arquivo atual. Ele parece real à primeira vista; nenhuma face nua em 4×. - Cada figura. Um assunto, preenchendo metade do cartão, não cortado; sua sombra dentro do cartão; a leitura verdadeira.
- Cada controle. Ele muda o que a legenda diz que muda.
- O texto. Cada número corresponde às leituras e à tabela.
- Celular. Uma coluna a 390 px, nada rolando lateralmente.
Diga o que você não pôde verificar (a taxa de quadros de uma GPU real, por exemplo).
Créditos
lamina unifica ideias de teardown (elvarofficial),
anatomy (Ryan) e
claude-motion (whaleyxbt), todos MIT. Veja CREDITS.md.