anatomy-threejs

Anatomy Three.js — Figuras Técnicas 3D Interativas

Crie ilustrações técnicas 3D isométricas e interativas em Three.js + GLSL. Cada figura explica uma ideia técnica como um instrumento de bancada físico ou uma maquete seccionada que você poderia colocar sobre uma mesa: uma base pesada e chanfrada sobre pés torneados, carcaças e ligações autênticas ao domínio, um herói rotor interno ou peça móvel, controles 3D diretamente arrastáveis e instrumentos construídos especificamente para aquela máquina, e um shader GLSL personalizado restrito estritamente ao meio físico (fogo, plasma, fluido, downwash, feixe) dentro da máquina.

Em vez de escrever um arquivo HTML monolítico de 1.500 linhas e adivinhar coordenadas 3D mentalmente, primeiro você alinha com o usuário sobre o aparato e as interações (Estágio 0), depois constrói cada figura em seis estágios isolados dentro de figures/<slug>/, apoiado pelo motor imutável kit/ e verificado a cada passo por um Arnês de Verificação Espacial 3D + Ortonográfico de dois níveis.

---

Estrutura de Diretórios

anatomy-threejs/
├── SKILL.md                    # Brief do Estágio 0 + fluxo de 6 estágios & ponto de entrada do agente
├── kit/                        # MOTOR IMUTÁVEL — importe daqui; nunca edite por figura
│   ├── shaders.mjs             # 5 temas, shader cel de 4 tons + topo, casca invertida, vincos
│   ├── primitives.mjs          # Slabs, cilindros, engrenagens, parafusos, serrilhados, marcas
│   ├── registry.mjs            # Recorder3D: .group(), .part(), .anchor(), .tube(), .interactable(), .tag()
│   ├── audit3d.mjs             # Auditoria 3D headless Node (colisões, flutuantes, furos, tubos)
│   ├── runtime.mjs             # Rig ortonográfico, arrasto 3D por raycast, controles personalizados, molas, __ANATOMY_DEBUG__
│   ├── bundle.mjs              # Compila módulos da figura em um único arquivo HTML autocontido
│   └── shell.html              # Chrome do cartão responsivo, variáveis CSS de 5 temas, controles com detecção de recursos
├── scripts/
│   ├── inspect.mjs             # Sobreposição ortonográfica 2x2 e articulação do Chrome headless (CDP)
│   ├── drive.mjs               # Folha de contato interativa + fotos principais + verificação móvel 390px
│   └── chrome-port.mjs         # WebSocket sem dependências + montador de PNG para Chrome headless
├── references/
│   ├── craft-3d.md             # Sistema de coordenadas 3D, hierarquia de tons, controles personalizados, antipadrões
│   ├── kit-3d.md               # Referência da API para Recorder3D, primitivas, shaders e runtime
│   └── verify-3d.md            # Como interpretar e corrigir [COLLISION], [FLOATING], [TUBE KINK] e vistas orto
└── figures/
    └── <slug>/                 # Seu espaço de trabalho para uma figura (ex.: figures/wankel-engine/)
        ├── model.mjs           # Estágio 1: Matemática pura, dimensões, SPEC.features, SPEC.controls, âncoras
        ├── base.mjs            # Estágio 2: Base, pés, halo, régua, placa de latão
        ├── structure.mjs       # Estágio 3: Pedestais, estrutura/carcaça, portas, fixadores
        ├── subject.mjs         # Estágio 4: Conjunto móvel principal (rotor, pás, vedações, engrenagens)
        ├── mechanism.mjs       # Estágio 5: Controles personalizados, instrumentos, interativos 3D, tubos, updateKinematics()
        ├── shader.mjs          # Estágio 6: Shader GLSL personalizado confinado ao meio físico ativo
        ├── build.mjs           # Entrada CLI: --test-model, --audit e pacote HTML completo
        └── dist/
            └── <slug>.html     # Figura interativa autocontida compilada

Regra 1 — Nunca reescreva kit/: A câmera Three.js, shaders cel, manipulador de arrasto por raycast, resolvedor de molas, chrome do DOM e arnês de depuração vivem em kit/. Seus arquivos de figura definem apenas a matemática do domínio, peças 3D, cinemática, interativos e o shader de meio personalizado.

Regra 2 — Leia as referências antes de escrever geometria:

• Leia references/craft-3d.md antes do Estágio 0/1 para projetar o rig físico, controles personalizados, flags de recursos, hierarquia de tons e quadro de coordenadas 3D.
• Leia references/kit-3d.md antes do Estágio 2 para as assinaturas exatas de Recorder3D e kit/primitives.mjs.
• Leia references/verify-3d.md sempre que --audit, inspect.mjs ou drive.mjs relatar um problema.

---

Estágio 0 — Brief do Aparato e Interação (Alinhar Antes de Construir)

Antes de criar arquivos ou escrever código do Estágio 1, proponha um Brief do Aparato e Interação conciso ao usuário e alinhe sobre o que a máquina faz e como o leitor interage com ela (pule a espera apenas se o usuário disser explicitamente para construir imediatamente sem perguntas):

1. Aparato de Bancada e Sujeito Herói: Nomeie o mecanismo físico e qual conjunto carrega o destaque lit.
2. Manipulação 3D Direta (reg.interactable): Identifique quais conjuntos ou controles 3D o leitor pode agarrar e arrastar diretamente no visor (ex.: arrastar um prato oscilante para incliná-lo/levantá-lo e ver as pás do rotor se ajustarem, deslizar um carro vernier, puxar uma alavanca), inclusive enquanto a rotação/simulação está pausada.
3. Controles Autênticos ao Domínio e Telemetria (SPEC.controls): Escolha hardware de bancada e controles deslizantes que pertencem a esta máquina (ex.: manche cíclico de 2 eixos, manete de passo coletivo, arco transferidor, tambor micrométrico, escala vernier, tubo manométrico). Nunca copie o botão rotativo, manômetro Bourdon ou caixa hidráulica de outra figura, a menos que o sujeito realmente use esse instrumento exato.
4. Modos de Visualização (SPEC.features): Decida explicitamente quais modos opcionais merecem seu lugar:
   • explode: Ativar (true) apenas para máquinas concêntricas fechadas com camadas axiais empilhadas (ex.: motores, caixas de engrenagens, bombas). Defina explode: false para ligações mecânicas abertas, pratos oscilantes, bancos ópticos ou rigs de superfície onde separar peças quebra a geometria da ligação e adiciona poluição visual.
   • cutaway: Ativar (true) quando uma carcaça externa esconde peças internas móveis; defina false para mecanismos de estrutura aberta.
   • shader: Ativar (true) quando um meio físico confinado (gás de combustão, esteira do rotor, feixe, fluxo de fluido) esclarece o mecanismo.

Portão do Estágio 0: O usuário confirma ou refina o brief (ou instrui explicitamente uma construção imediata não interativa).

---

O Fluxo de Trabalho em Seis Estágios

Execute estes estágios em ordem. Cada estágio termina com um Portão de Verificação — execute o comando, corrija quaisquer erros e inspecione visualmente o PNG renderizado com sua ferramenta de leitura de arquivos antes de passar para o próximo estágio.

Estágio 1 — Modelo e Cinemática (model.mjs + build.mjs)

Traduza o brief acordado em um módulo de matemática física pura antes de tocar no Three.js:

1. Codifique a Metáfora Física em figures/<slug>/model.mjs:
   • SPEC.features: { explode: boolean, cutaway: boolean, shader: boolean, crank: boolean } correspondendo ao Estágio 0.
   • SPEC.interactionHint: Dica curta mostrada no canto inferior esquerdo informando ao usuário quais peças 3D podem ser arrastadas diretamente (ex.: "Arraste o prato oscilante, manche ou manete coletivo").
   • SPEC.controls: Array de controles deslizantes específicos do domínio ({ id, label, min, max, step, initial, title }). runtime.mjs renderiza estes na barra de controle, suaviza-os com molas e os passa para updateKinematics e formatReadout.
   • SPEC.auditPoses & SPEC.drivePoses: Poses representativas do domínio (ângulos de controle extremos, manipulação pausada, verificações de corte/tema) usadas por --audit e scripts/drive.mjs. Omita poses explodidas quando features.explode === false.
   • SPEC: Todas as dimensões críticas (BASE_W, BASE_D, BASE_H, BASE_Y, topSurfaceY, isoElevDeg: 30, isoAzimDeg: -36, initialZoom, initialPanY, minVertSpan, minHorizSpan).
   • ANCHORS: Coordenadas de montagem nomeadas [x, y, z] na base (plaqueCenter, rulerCenter e suas âncoras de controle/instrumento personalizadas da figura). Lembre-se de que na isometria canônica (30° elev, -36° azim), a borda +Z é a frente e os cantos -X, +Z / +X, +Z são os cantos frontais desobstruídos.
   • Funções de estado e cinemática puras (zero importações Three.js) orientadas por theta e os params ao vivo de SPEC.controls.
   • formatReadout({ theta, effectiveRpm, params }) retornando strings { readout, phase } para a barra de telemetria.
2. Crie o esqueleto figures/<slug>/build.mjs (consulte figures/wankel-engine/build.mjs ou figures/helicopter-swashplate/build.mjs) e ajuste título, subtítulo, leitura inicial e legenda.

Portão do Estágio 1:

node figures/<slug>/build.mjs --test-model

Critério de aprovação: Sai com código 0 com todas as âncoras finitas e leitura/estado verificados em um ciclo completo de $0 \dots 6\pi$.

---

Estágio 2 — A Base (base.mjs)

Construa a pesada base de referência que fundamenta todo o instrumento:

1. Crie base.group (stage: "base").
2. Adicione a sombra suave do solo (makeHaloMesh) em BASE_Y - 0.24.
3. Adicione base.plate usando buildSlabGeometry(BASE_W, BASE_D, BASE_H, { radius: 0.26, bevel: true, bevelSize: 0.025, bevelThickness: 0.025 }) com ramp: "lo", mountOn: "ground". Observe que topSurfaceY = BASE_Y + BASE_H + 0.025 contabiliza a espessura do chanfro superior para que as peças montadas em topSurfaceY fiquem niveladas na face superior sem afundar.
4. Registre todas as âncoras de montagem da base via reg.anchor(id, x, y, z, baseGroup) para que os Estágios 3 e 5 se encaixem diretamente em base.plate.
5. Adicione ranhuras perimetrais rebaixadas (makePlanOutline), 4 pés de canto torneados (base.foot.collar.i + base.foot.pad.i) com parafusos escareados (makeScrewDetail), uma escala graduada (base.ruler + makeRulerTicks) e uma placa de especificação brass rebitada (base.plaque) na frente visível (+Z) com uma etiqueta gravada (reg.tag("tag-plate", ...)).

Portão do Estágio 2:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base --ortho --out figures/<slug>/dist/inspect-base.png

Leia inspect-base.png para verificar se os pés estão posicionados corretamente sob a base e a placa de latão + régua estão desobstruídas na frente.

---

Estágio 3 — A Estrutura (structure.mjs)

Construa os suportes estacionários de carga, a estrutura principal ou carcaça de corte, portas/manifolds e fixadores:

1. Monte pedestais de suporte ou caixas de engrenagens sobre base.plate com bases flangeadas, detalhes de parafusos, colunas cônicas e selas de mancal.
2. Construa a carcaça ou estrutura principal (ramp: "mid", outline: "hi"). Deixe a frente (+Z) aberta ou equipada com uma cobertura de corte (cutawayHide: true) para que os mecanismos internos permaneçam completamente visíveis a partir da câmera isométrica canônica quando features.cutaway estiver ativado.
3. Adicione portas, gabinetes de atuadores ou suportes estacionários autênticos ao domínio, apontando para fora de forma limpa. Registre âncoras 3D de porta/terminal com suas normais de porta locais para fora (reg.anchor("plug.leading.tip", 0, 0.68, 0, spGroup, { dir: [0, 1, 0] })) dentro de cada subgrupo local para que os tubos do Estágio 5 se encaixem em suas posições mundiais exatas e entrem/saiam coaxialmente.
4. Defina vetores explode: [ex, ey, ez] em subgrupos removíveis apenas quando SPEC.features.explode for true e o aparato tiver camadas concêntricas fechadas destinadas a se separar axialmente.

Portão do Estágio 3:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base,structure --ortho --out figures/<slug>/dist/inspect-structure.png

Leia inspect-structure.png (TOP, FRONT, RIGHT, CANONICAL ISO): verifique se as portas apontam para fora, se os pedestais tocam a base e a carcaça sem sobreposição e se nada flutua.

---

Estágio 4 — O Sujeito (subject.mjs)

Construa o conjunto interno herói que comanda o foco visual:

1. Atribua ramp: "hi" ao corpo móvel principal (ex.: corpo do rotor, jugo do cubo), ramp: "lit" aos elementos de trabalho ativos (rotor.apexSeal.i, blade.airfoil.*) e ramp: "brass" a engrenagens e pivôs de precisão.
2. Crie grupos cinemáticos aninhados (orbit -> spin, ou azimuth -> flap -> pitch) para que o movimento hierárquico se componha de forma limpa sem trava de cardan de Euler.
3. Passe insideBoreOf e boreClearanceFn em peças que se movem dentro de um furo para que audit3d.mjs verifique matematicamente a penetração zero na parede em cada pose auditada.
4. Adicione bolsos usinados, ranhuras faciais, costuras de longarinas ou padrões de parafusos para que o movimento seja inconfundível.

Portão do Estágio 4:

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate subject --ortho --out figures/<slug>/dist/inspect-subject.png

Leia inspect-subject.png para confirmar que a silhueta, chanfros e juntas do sujeito são lidos claramente de todos os ângulos.

---

Estágio 5 — Mecanismo, Controles Personalizados e Interação 3D Direta (mechanism.mjs)

Conecte o sujeito a controles de operador autênticos ao domínio, instrumentos de telemetria, interação de arrasto 3D direta e roteamento:

1. Construa controles autênticos ao domínio em suas ANCHORS do Estágio 0/1 (por exemplo: um manche cíclico gimbal de 2 eixos, uma alavanca de manete de passo coletivo com entalhes, um fuso vernier ou um tambor de aceleração serrilhado). Nunca copie o botão serrilhado ou bloco de manifold de outra figura quando a máquina exigir seu próprio hardware de controle.
2. Construa telemetria autêntica ao domínio (por exemplo: um arco transferidor curvo de ângulo de pá, escala de curso linear, coluna de manômetro ou mostrador) posicionada na frente em +Z ou longe da silhueta principal em CANONICAL ISO.
3. Registre manipulação 3D direta com reg.interactable(targetId, { cursor, hint, onDrag }) no mecanismo principal e/ou alavancas físicas para que o usuário possa arrastar peças 3D diretamente no visor via setParam(...), mesmo quando a rotação estiver pausada (RPM = 0 ou PAUSED).
4. Roteie todos os tubos e cabos usando reg.tube(id, fromAnchorId, waypoints, toAnchorId, opts):
   • Consulte reg.getAnchorWorldPos(anchorId) e reg.getAnchorWorldDir(anchorId) para construir waypoints de arco 3D suaves (length / chord >= 1.12) que evitem peças adjacentes e entrem coaxialmente ao longo da normal externa de cada porta.
5. Construa o trem de força e as ligações articuladas. Passe cutawayHide: true em tampas de carcaça ou coberturas frontais que ocultam o mecanismo interno.

Portão do Estágio 5:

node figures/<slug>/build.mjs --audit
node scripts/drive.mjs figures/<slug>/dist/<slug>.html

Leia a folha de contato gerada para confirmar o arrasto 3D, range de controle, modos de visualização e que todos os tubos entram nos portos sem dobras.

---

Estágio 6 — Shader (shader.mjs)

Opicional — apenas se SPEC.features.shader === true:

1. Confine toda a lógica GLSL ao meio físico que existe dentro da carcaça (chama, plasma, esteira de vórtice, fluido). Nunca substitua os shaders de superfície de kit/shaders.mjs.
2. Defina uniforms que se vinculam a params ao vivo do usuário e theta para evoluir dinamicamente o meio físico.
3. Registre o shader via recorder.setCustomShader({ material: new THREE.ShaderMaterial({ ... }), parts: [ subject.rotorChamber, subject.combustionVolume ], uniforms: { ... }, vertexShader, fragmentShader })

Portão do Estágio 6:

node figures/<slug>/build.mjs --audit
node scripts/drive.mjs figures/<slug>/dist/<slug>.html --shader-off --shader-on

Leia a folha de contato comparativa para confirmar que aplicar/remover o shader não danifica a geometria próxima nem introduz artefatos de renderização.

---

Construção Final e Envio

Após passar em todos os portões dos 6 estágios:

node figures/<slug>/build.mjs                # compila figura completa
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --ortho --out figures/<slug>/dist/final-inspect.png
node scripts/drive.mjs figures/<slug>/dist/<slug>.html          # contato completo

Valide que:

• A figura cabe em um cartão responsivo e o layout de grade de 2 ou 3 colunas lê static/css/theme.css.
• A telemetria, controles e dica de interação são apresentados sem sobreposição com a silhueta 3D.
• O modo escuro e todos os 5 temas trocam sem quebrar a interface do usuário.

---

Instalação

npm install           # three, jszip (shader embedding), puppeteer (headless inspection)
# Nenhuma configuração de ambiente ou chave de API necessária

Resumo dos Comandos

Comando	Finalidade
node figures/<slug>/build.mjs --test-model	Verificar especificações do modelo, âncoras, leitura
node figures/<slug>/build.mjs --audit	Executar auditoria 3D headless (colisões, flutuantes, furos)
node figures/<slug>/build.mjs	Compilar figura HTML autocontida final
node scripts/inspect.mjs <html> --ortho --out <png>	Salvar blueprint 2x2 ortonográfico (TOP, FRONT, RIGHT, ISO)
node scripts/inspect.mjs <html> --isolate <stages> --ortho --out <png>	Isolar estágios específicos nas vistas orto
node scripts/drive.mjs <html>	Gerar folha de contato interativa + fotos principais + verificação móvel
node scripts/drive.mjs <html> --shader-off --shader-on	Comparar figura com/sem shader personalizado
node scripts/inspect.mjs <html> --joints --out <png>	Mostrar sobreposição de etiquetas de articulação e âncora

---

Temas

O shell suporta 5 temas CSS (shell.html):

1. Light: Fundo claro, superfícies cinza claro, detalhes em latão
2. Dark: Fundo escuro, superfícies cinza escuro, detalhes em cobre
3. Blueprint: Fundo azul, linhas brancas, realce ciano
4. Paper: Fundo sépia, superfícies bege, traços a tinta
5. X-Ray: Fundo preto, superfícies translúcidas, articulações brilhantes

Troque temas via menu de canto ou pressionando T.

---

Variáveis de Ambiente

Nenhuma variável de ambiente ou chave de API é necessária para o uso principal. Para depuração:

• __ANATOMY_DEBUG__=true ativa FPS, log de parâmetros e sobreposições de wireframe durante build.mjs.
• PUPPETEER_HEADLESS=“new” pode ser definido para inspeção headless mais rápida.

---

Boas Práticas

• Nunca edite kit/: Ele é imutável por design. Toda a personalização da figura ocorre nos arquivos do Estágio 1-6 dentro de figures/<slug>/.
• Sempre leia as referências primeiro: craft-3d.md (filosofia de design), kit-3d.md (API) e verify-3d.md (correção de auditoria) são obrigatórios antes de escrever geometria.
• Cada figura começa com o Estágio 0: Alinhe o aparato, controles e modo de visualização antes de codificar.
• Passe em cada portão antes de prosseguir: O pipeline de verificação garante correção espacial e evita refatoração tardia.
• Controles personalizados não genéricos: Cada figura obtém hardware de controle único adequado ao seu mecanismo (manche de helicóptero, alavanca de motor, seletor de engrenagens).
• Shader apenas para meios físicos: Shaders personalizados descrevem fogo, fluido, plasma ou feixes dentro da máquina — nunca substituem os shaders de superfície.

---

Limitações

• Requer Node.js 18+ e uma GPU compatível com WebGL2.
• Cada figura compila em um único HTML autocontido (~2-5 MB com shaders e geometria embutidos).
• Não suporta áreas de clique de textura de mapa HDR ou cena baseada em física (PBR) — o cel shading estilizado é o estilo visual fixo.
• A inspeção headless (inspect.mjs, drive.mjs) requer Puppeteer e um binário Chrome compatível.
• Figuras são projetadas para telas de desktop/móvel (390px+) em orientação retrato. Telas abaixo de 390px podem truncar os controles.

---

Licença

Interno — use para explicar qualquer conceito técnico como um instrumento de bancada 3D interativo.