anatomy-threejs

Anatomy Three.js — Figures Techniques 3D Interactives

Créez des illustrations techniques 3D isométriques interactives dans Three.js + GLSL. Chaque figure explique une idée technique comme un instrument physique de paillasse ou un banc d'essai en coupe que l'on pourrait poser sur un bureau : un socle biseauté lourd sur pieds tournés, des boîtiers et liaisons authentiques au domaine, un rotor interne héroïque ou un sujet mobile, des commandes et instruments 3D directement manipulables conçus spécifiquement pour cette machine, et un shader GLSL personnalisé restreint strictement au milieu physique (feu, plasma, fluide, souffle, faisceau) à l'intérieur de la machine.

Au lieu d'écrire un fichier HTML monolithique de 1 500 lignes et de deviner les coordonnées 3D de tête, vous vous alignez d'abord avec l'utilisateur sur l'appareil et les interactions (Étape 0), puis construisez chaque figure en six étapes isolées dans figures/<slug>/, soutenues par le moteur immuable kit/ et vérifiées à chaque étape par un Harness de vérification 3D spatial + orthographique à deux niveaux.

---

Structure du Répertoire

anatomy-threejs/
├── SKILL.md                    # Brief Étape 0 + workflow en 6 étapes et point d'entrée agent
├── kit/                        # MOTEUR IMMUABLE — importer depuis ici ; ne jamais modifier par figure
│   ├── shaders.mjs             # 5 thèmes, ombrage cel 4 tons + calotte supérieure, silhouette inversée, plis
│   ├── primitives.mjs          # Dalles, cylindres, engrenages, vis, moletages, graduations
│   ├── registry.mjs            # Recorder3D : .group(), .part(), .anchor(), .tube(), .interactable(), .tag()
│   ├── audit3d.mjs             # Audit spatial 3D headless Node (collisions, flottement, alésages, tubes)
│   ├── runtime.mjs             # Rendu orthographique, glisser 3D par raycasting, commandes personnalisées, ressorts, __ANATOMY_DEBUG__
│   ├── bundle.mjs              # Compile les modules de la figure en un seul fichier HTML autonome
│   └── shell.html              # Chrome de carte responsive, variables CSS pour 5 thèmes, commandes adaptées aux fonctionnalités
├── scripts/
│   ├── inspect.mjs             # Navigation headless Chrome (CDP) superposition orthographique 2x2 et joints
│   ├── drive.mjs               # Planche contact interactive + portraits héroïques + vérification mobile 390px
│   └── chrome-port.mjs         # WebSocket sans dépendance + assembleur PNG pour Chrome headless
├── references/
│   ├── craft-3d.md             # Système de coordonnées 3D, hiérarchie des tons, commandes sur mesure, anti-patrons
│   ├── kit-3d.md               # Référence API pour Recorder3D, primitives, shaders et runtime
│   └── verify-3d.md            # Comment interpréter et corriger [COLLISION], [FLOTTEMENT], [COUDE DE TUBE] et vues ortho
└── figures/
    └── <slug>/                 # Votre espace de travail pour une figure (ex. figures/wankel-engine/)
        ├── model.mjs           # Étape 1 : Mathématiques pures, dimensions, SPEC.features, SPEC.controls, ancres
        ├── base.mjs            # Étape 2 : Socle, pieds, halo, règle, plaque en laiton
        ├── structure.mjs       # Étape 3 : Piédestaux, cadre/boîtier, ports, fixations
        ├── subject.mjs         # Étape 4 : Assemblage central mobile (rotor, pales, joints, engrenages)
        ├── mechanism.mjs       # Étape 5 : Commandes sur mesure, instruments, interactifs 3D, tubes, updateKinematics()
        ├── shader.mjs          # Étape 6 : Shader GLSL personnalisé confiné au milieu physique actif
        ├── build.mjs           # Point d'entrée CLI : --test-model, --audit, et bundle HTML complet
        └── dist/
            └── <slug>.html     # Figure interactive autonome compilée

Règle 1 — Ne jamais réécrire kit/ : La caméra Three.js, les shaders cel, le gestionnaire de glisser par raycasting, le solveur de ressorts, le chrome DOM et le harness de débogage vivent dans kit/. Vos fichiers de figure ne définissent que les mathématiques du domaine, les pièces 3D, la cinématique, les interactifs et le shader de milieu personnalisé.

Règle 2 — Lire les références avant d'écrire la géométrie :

• Lire references/craft-3d.md avant l'Étape 0/1 pour concevoir le banc physique, les commandes sur mesure, les indicateurs de fonctionnalités, la hiérarchie des tons et le repère 3D.
• Lire references/kit-3d.md avant l'Étape 2 pour les signatures exactes de Recorder3D et kit/primitives.mjs.
• Lire references/verify-3d.md à chaque fois que --audit, inspect.mjs ou drive.mjs rapporte un problème.

---

Étape 0 — Brief Appareil & Interaction (S'aligner avant de construire)

Avant de créer des fichiers ou d'écrire du code d'Étape 1, proposez un Brief Appareil & Interaction concis à l'utilisateur et alignez-vous sur ce que la machine fait et comment le lecteur interagit avec (ne pas attendre uniquement si l'utilisateur dit explicitement de construire immédiatement sans questions) :

1. Appareil de Paillasse & Sujet Héroïque : Nommez le mécanisme physique et quel assemblage porte l'accent lit.
2. Manipulation Directe 3D (reg.interactable) : Identifiez quels assemblages ou commandes 3D le lecteur peut saisir et glisser directement dans la fenêtre (par exemple, glisser un plateau cyclique pour l'incliner/le soulever et regarder les pales du rotor s'orienter, faire coulisser un chariot vernier, tirer un levier de liaison), y compris lorsque la rotation/simulation est en pause.
3. Commandes et Télémétrie Authentiques au Domaine (SPEC.controls) : Choisissez du matériel de banc et des curseurs de barre de contrôle qui appartiennent à cette machine (par exemple, manche cyclique 2 axes, quadrant de pas collectif, arc rapporteur, tambour micrométrique, échelle vernier, tube manomètre). Ne copiez jamais le bouton rotatif, le manomètre Bourdon ou le boîtier hydraulique d'une autre figure à moins que le sujet n'utilise réellement cet instrument exact.
4. Modes d'Affichage (SPEC.features) : Décidez explicitement quels modes optionnels méritent leur place :
   • explode : Activer (true) uniquement pour les machines concentriques fermées avec des couches axiales empilées (par exemple, moteurs, boîtes de vitesses, pompes). Mettre explode: false pour les liaisons mécaniques ouvertes, les plateaux cycliques, les bancs optiques ou les structures de surface où séparer les pièces brise la géométrie des liaisons et ajoute du désordre.
   • cutaway : Activer (true) lorsqu'un carter extérieur cache des pièces internes mobiles ; mettre false pour les mécanismes à cadre ouvert.
   • shader : Activer (true) lorsqu'un milieu physique confiné (gaz de combustion, sillage de rotor, faisceau, écoulement de fluide) clarifie le mécanisme.

Porte Étape 0 : L'utilisateur confirme ou affine le brief (ou a explicitement demandé une construction immédiate non interactive).

---

Le Workflow en Six Étapes

Exécutez ces étapes dans l'ordre. Chaque étape se termine par une Porte de Vérification — exécutez la commande, corrigez les erreurs, et inspectez visuellement le PNG rendu avec votre outil de lecture de fichier avant de passer à l'étape suivante.

Étape 1 — Modèle & Cinématique (model.mjs + build.mjs)

Traduisez le brief convenu en un module mathématique physique pur avant de toucher à Three.js :

1. Encodagez la Métaphore Physique dans figures/<slug>/model.mjs :
   • SPEC.features : { explode: booléen, cutaway: booléen, shader: booléen, crank: booléen } correspondant à l'Étape 0.
   • SPEC.interactionHint : Indice court affiché en bas à gauche indiquant à l'utilisateur quelles pièces 3D il peut glisser directement (par exemple "Glisser plateau cyclique, manche ou levier collectif").
   • SPEC.controls : Tableau de curseurs de contrôle spécifiques au domaine ({ id, label, min, max, step, initial, title }). runtime.mjs les affiche dans la barre de contrôle, les lisse avec des ressorts et les transmet à updateKinematics et formatReadout.
   • SPEC.auditPoses & SPEC.drivePoses : Poses représentatives du domaine (angles de contrôle extrêmes, manipulation en pause, vérifications cutaway/thème) utilisées par --audit et scripts/drive.mjs. Omettre les poses éclatées lorsque features.explode === false.
   • SPEC : Toutes les dimensions critiques (BASE_W, BASE_D, BASE_H, BASE_Y, topSurfaceY, isoElevDeg: 30, isoAzimDeg: -36, initialZoom, initialPanY, minVertSpan, minHorizSpan).
   • ANCHORS : Coordonnées de montage nommées [x, y, z] sur le socle (plaqueCenter, rulerCenter, et vos ancres de commandes/instruments sur mesure). Rappelez-vous qu'en isométrique canonique (30° elev, -36° azim), le bord +Z est la face avant et les coins avant dégagés sont -X, +Z / +X, +Z.
   • Fonctions d'état pur et cinématiques (zéro import Three.js) pilotées par theta et les params vivants de SPEC.controls.
   • formatReadout({ theta, effectiveRpm, params }) renvoyant les chaînes { readout, phase } pour la barre de télémétrie.
2. Échafaudez figures/<slug>/build.mjs (référez-vous à figures/wankel-engine/build.mjs ou figures/helicopter-swashplate/build.mjs) et ajustez le titre, le sous-titre, l'affichage initial et la légende.

Porte Étape 1 :

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

Critère de réussite : Sortie 0 avec toutes les ancres finies et l'état/l'affichage vérifié sur un cycle complet de $0 \dots 6\pi$.

---

Étape 2 — La Base (base.mjs)

Construisez le socle de référence lourd qui ancre l'ensemble de l'instrument :

1. Créez base.group (stage: "base").
2. Ajoutez l'ombre au sol douce (makeHaloMesh) à BASE_Y - 0.24.
3. Ajoutez base.plate en utilisant buildSlabGeometry(BASE_W, BASE_D, BASE_H, { radius: 0.26, bevel: true, bevelSize: 0.025, bevelThickness: 0.025 }) avec ramp: "lo", mountOn: "ground". Notez que topSurfaceY = BASE_Y + BASE_H + 0.025 tient compte de l'épaisseur du biseau supérieur afin que les pièces montées à topSurfaceY reposent à fleur sur la face supérieure sans s'enfoncer.
4. Enregistrez toutes les ancres de montage du socle via reg.anchor(id, x, y, z, baseGroup) afin que les Étape 3 et 5 s'accrochent directement à base.plate.
5. Ajoutez des rainures périphériques encastrées (makePlanOutline), 4 pieds d'angle tournés (base.foot.collar.i + base.foot.pad.i) avec vis de fixation à lamage supérieur (makeScrewDetail), une échelle graduée (base.ruler + makeRulerTicks), et une plaque signalétique rivetée en laiton (base.plaque) sur la face avant visible (+Z) avec une étiquette gravée (reg.tag("tag-plate", ...)).

Porte Étape 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

Lisez inspect-base.png pour vérifier que les pieds reposent proprement sous le socle et que la plaque en laiton + la règle sont dégagées sur la face avant.

---

Étape 3 — La Structure (structure.mjs)

Construisez les supports fixes porteurs, le cadre principal ou le carter en coupe, les ports/manifolds et les fixations :

1. Montez les piédestaux de support ou les boîtes de vitesses sur base.plate avec des bases à brides, des détails de boulons, des colonnes effilées et des berceaux de paliers.
2. Construisez le carter ou cadre principal (ramp: "mid", outline: "hi"). Laissez la face avant (+Z) ouverte ou équipée d'un couvercle en coupe (cutawayHide: true) afin que les mécanismes intérieurs restent complètement visibles depuis la caméra isométrique canonique lorsque features.cutaway est activé.
3. Ajoutez des ports authentiques au domaine, des boîtiers d'actionneurs ou des supports fixes pointant proprement vers l'extérieur. Enregistrez les ancres de ports/terminaisons 3D avec leurs normales de port locales sortantes (reg.anchor("plug.leading.tip", 0, 0.68, 0, spGroup, { dir: [0, 1, 0] })) à l'intérieur de chaque sous-groupe local afin que les tubes de l'Étape 5 s'accrochent à leurs positions mondiales exactes et entrent/sortent coaxialement.
4. Définissez les vecteurs explode: [ex, ey, ez] sur les sous-groupes amovibles uniquement lorsque SPEC.features.explode est true et que l'appareil a des couches concentriques fermées destinées à se séparer axialement.

Porte Étape 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

Lisez inspect-structure.png (DESSUS, FACE, DROITE, ISO CANONIQUE) : vérifiez que les ports pointent vers l'extérieur, que les piédestaux touchent à la fois le socle et le carter sans clipping, et que rien ne flotte.

---

Étape 4 — Le Sujet (subject.mjs)

Construisez l'assemblage interne héroïque qui attire le regard :

1. Assignez ramp: "hi" au corps mobile principal (par exemple, le corps de rotor, la chape de moyeu), ramp: "lit" aux éléments actifs de travail (rotor.apexSeal.i, blade.airfoil.*), et ramp: "brass" aux engrenages et pivots de précision.
2. Créez des groupes cinématiques imbriqués (orbit -> spin, ou azimuth -> flap -> pitch) afin que le mouvement hiérarchique se compose proprement sans blocage de cardan d'Euler.
3. Passez insideBoreOf et boreClearanceFn sur les pièces se déplaçant à l'intérieur d'un alésage afin que audit3d.mjs vérifie mathématiquement qu'il n'y a pas de pénétration de paroi à chaque pose auditée.
4. Ajoutez des poches usinées, des rainures de face, des coutures de longeron ou des motifs de boulons pour que le mouvement soit indubitable.

Porte Étape 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

Lisez inspect-subject.png pour confirmer que la silhouette du sujet, ses biseaux et ses joints se lisent clairement sous tous les angles.

---

Étape 5 — Mécanisme, Commandes Sur Mesure & Interaction Directe 3D (mechanism.mjs)

Connectez le sujet à des commandes opérateur authentiques au domaine, des instruments de télémétrie, une interaction par glissement direct 3D et le routage :

1. Construisez des commandes authentiques au domaine à leurs ANCHORS de l'Étape 0/1 (par exemple : un manche cyclique à cardan 2 axes, un levier de quadrant de pas collectif cranté, une vis mère vernier, ou un tambour d'accélérateur moleté). Ne copiez jamais le bouton moleté ou le bloc manifold d'une autre figure lorsque la machine nécessite son propre matériel de commande.
2. Construisez une télémétrie authentique au domaine (par exemple : un arc rapporteur de pas de pale incurvé, une échelle de course linéaire, une colonne manométrique, ou un comparateur à cadran) positionnée vers l'avant en +Z ou dégagée de la silhouette principale en ISO CANONIQUE.
3. Enregistrez la manipulation directe 3D avec reg.interactable(targetId, { cursor, hint, onDrag }) sur le mécanisme principal et/ou les leviers physiques afin que l'utilisateur puisse glisser des pièces 3D directement dans la fenêtre via setParam(...), même lorsque la rotation est en pause (RPM = 0 ou PAUSÉ).
4. Routez tous les tuyaux et câbles en utilisant reg.tube(id, fromAnchorId, waypoints, toAnchorId, opts) :
   • Interrogez reg.getAnchorWorldPos(anchorId) et reg.getAnchorWorldDir(anchorId) pour construire des points de passage 3D lisses (length / chord >= 1.12) qui balayent sans toucher les pièces adjacentes et entrent coaxialement le long de la normale sortante de chaque port.
5. Construisez la chaîne de transmission et les liaisons articulées. Passez cutawayHide: true sur les couvercles ou les écrans de carter côté face avant qui cachent le mécanisme intérieur.