nachoiannella/scroll-3d-landing

Landing 3D avec défilement (pour n'importe quel objet)

Cette compétence sert à construire une landing page d'une seule page où un objet 3D est le protagoniste. L'objet reste fixe derrière le contenu et change de pose, de style de rendu et de contexte à mesure que l'utilisateur fait défiler la page. Elle fonctionne pour tout ce qui peut être affiché comme objet : une bouteille de vin, un casque audio, une chaise, une guitare, une montre, une voiture, une maquette de bâtiment, une sculpture, un appareil photo ancien, un flacon de parfum, un outil ou un jouet.

Le cas de référence est toppervenom.com, d'Evil Rabbit (post original), et c'est de ce projet qu'est née l'idée de cette compétence. Il montre une chaussure de basket Topper des années 90 ; son modèle 3D n'est pas un scan, mais une reconstruction faite avec IA à partir de matériel d'archive et d'images générées de toutes ses vues. La page commence comme un plan technique (wireframe blanc sur grille bleue), se 'remplit' avec le matériau réel, montre ses mesures et ses parties, change de couleur et se termine en tournant. La chaussure n'est qu'un exemple ; ce qui est reproduit, c'est la façon de construire la page et son niveau de qualité. Chaque projet choisit son propre concept visuel, sa séquence d'actes et l'effet de révélation qui convient le mieux à son objet (voir 'Adapter à l'objet' ci-dessous).

Pourquoi ces sites sont si beaux (lisez ceci avant de commencer)

La qualité ne vient pas de la stack technique. toppervenom.com fait environ 90 Ko de HTML/CSS/JS + Three.js (selon son auteur, la page a été générée par une IA d'un seul coup) : pas de framework, ni GSAP, ni bundler. La qualité vient de cinq choses, et chaque décision du projet doit servir l'une d'elles :

1. Un asset 3D réel et bien préparé. Un scan avec texture photographique, une reconstruction IA bien soignée (comme celle de toppervenom) ou un modèle avec un détail réel, propre, léger et à l'échelle réelle. Si le modèle est mauvais, rien d'autre ne pourra le sauver. → references/3d-capture.md, references/3d-alternatives.md
2. Un rendu avec un critère photographique. Éclairage à trois points, environment map, tone mapping neutre, ombre de contact et matériaux corrigés (un scan apporte souvent un metalness faux qui fait ressembler le cuir à du plastique). → references/rendering.md
3. Un concept de direction artistique poussé jusqu'au moindre détail. 'Plan technique' chez toppervenom : la grille, les cotes, la typographie monospace, le loader dit 'PLOTTING DRAWING Nº 01', le rail dit 'REV. 0 — BLUEPRINT'. Tout raconte la même histoire. → references/art-direction.md
4. Un mouvement avec de la physique, pas avec des keyframes. Les poses sont déclarées par section ; le JS interpole avec smoothstep et amortit chaque valeur avec une décroissance exponentielle. Cela donne du poids et de l'inertie. → references/choreography.md
5. Des effets de shader qui justifient la 3D. Révélation wireframe→solide avec un plan qui balaie l'objet, surface fantôme avec fresnel, recoloration par luminance. Ce sont des choses qu'une vidéo ne peut pas faire. → references/shaders.md

Si l'utilisateur demande 'quelque chose comme ça', le vrai travail est : obtenir un bon modèle + choisir un concept + ajuster avec patience. Le template résout l'ingénierie.

Adapter à l'objet (ne copiez pas la chaussure)

Le template apporte une séquence d'exemple (plan → mesures → parties → révélation → nombres → origine → fermeture), mais la forme de l'objet et son histoire décident de la composition, de l'effet et des actes. Avant d'écrire les poses, placez l'objet dans ce tableau :

Forme de l'objet	Exemples	Composition	Révélation qui fonctionne le mieux	Actes typiques
Allongé horizontal	chaussure, voiture, guitare, couteau, stylo, train	Objet d'un côté et texte de l'autre ; profil pur pour les cotes	Balayage longitudinal (pointe → queue)	Profil technique, détail des pièces, vitesse ou usage
Vertical / de révolution	bouteille, parfum, lampe, vase, trophée, bâtiment	Objet centré ou au tiers, texte sur les côtés en deux colonnes ; plan contre-plongée pour le climax	Balayage de bas en haut ('se remplit') ou coupe transversale	Silhouette, matériau ou contenu, origine, rituel d'utilisation
Compact / boîte	casque, appareil photo, enceinte, montre, console, bijou	Gros plans (scale 1.4–2) qui parcourent l'objet comme une macro	Vue éclatée ou balayage diagonal	Design, intérieur/composants, matériaux, spécifications
Plat / à lecture frontale	livre, disque, tableau, carte, tablette	Rotations courtes (±0.4 rad) pour montrer l'épaisseur ; jamais de chant longtemps	Points qui se condensent, ou peinture qui 'apparaît'	Recto, verso, détail de texture, contexte
Organique / sculptural	sculpture, nourriture, plante, fossile, jouet	Tours lents et amples, beaucoup de lumière de contour	Nuage de points → surface, ou fantôme avec fresnel	Forme, texture, histoire, échelle humaine
Assemblage de pièces	meuble, machine, maquette, produit modulaire	Vue 3/4 haute, tout l'ensemble dans le cadre	Vue éclatée par défilement : chaque pièce se sépare sur son axe et revient	Ensemble → éclaté → pièce par pièce → assemblage
Grande échelle	maison, bâtiment, terrain, bateau	Caméra plus loin, rotation de 'maquette' sur la table	Balayage vertical par étages, coupes de section	Implantation, plans, coupes, matériaux

Choisissez également le concept visuel en fonction de l'objet, pas par défaut. 'Plan technique' convient à tout ce qui est conçu ou fabriqué ; un vin peut demander 'fiche de cave' ; une sculpture, 'catalogue de musée' ; un gadget, 'laboratoire' ; un objet vintage, 'catalogue d'époque'. Le menu complet se trouve dans references/art-direction.md, et les effets alternatifs (éclaté, points, coupe, remplissage) dans references/shaders.md.

Flux de travail

Suivez ces phases dans l'ordre. Avant d'écrire du code, confirmez avec l'utilisateur les décisions des phases 1 et 2, car elles changent tout ce qui suit.

Phase 1 — Brief et concept (5 minutes avec l'utilisateur)

Demandez ou déduisez :

• Quel objet c'est et de quel matériau (cuir, verre, métal, plastique mat, tissu). Le matériau définit comment le capturer et comment l'éclairer.
• L'histoire en 5–8 actes. Chaque acte est une section et une pose de l'objet. Exemple typique : présentation → plan/mesures → anatomie (parties) → révélation → nombres → origine/histoire → fermeture.
• Le concept visuel, c'est-à-dire la métaphore qui unifie tout. Ne copiez pas 'blueprint' par défaut : choisissez la métaphore qui a du sens pour ce produit. Dans references/art-direction.md, il y a un menu de concepts (plan technique, fiche de musée, laboratoire, catalogue des années 90, éditorial de mode, éclaté industriel) avec sa palette, ses typographies et comment chacun se traduit en 3D.
• Contenu réel. Données, mesures, matériaux, histoire et crédits. Les sites de référence sonnent authentiques car ils utilisent des données réelles du catalogue original et du scan. S'il n'y a pas de données, demandez-les ; n'inventez pas de spécifications pour un produit réel.
• Langues (es/en) et s'il y a des variantes de couleur.

Phase 2 — Obtenir le modèle 3D

C'est la phase qui affecte le plus la qualité finale. Utilisez cet arbre de décision et lisez la référence correspondante :

L'utilisateur a-t-il l'objet physique ?
├─ Oui → LE SCANNER (references/3d-capture.md)
│   ├─ Objet mat/texturé (chaussure, nourriture, pierre, bois, tissu) → photogrammétrie avec smartphone ou appareil photo
│   ├─ Brillant, noir ou transparent → spray matifiant temporaire + photogrammétrie, ou le modéliser
│   └─ Très petit/fin (bijoux, câbles) → photogrammétrie macro ou le modéliser
└─ Non → ALTERNATIVES (references/3d-alternatives.md)
    ├─ Il y a un CAD/STEP du fabricant → convertir et texturer
    ├─ Il y a de bonnes photos sous plusieurs angles → IA image-to-3D (Meshy, Tripo, Rodin, Hunyuan3D, TRELLIS) + nettoyage
    ├─ Forme géométrique (bouteille, canette, lampe, meuble) → modéliser dans Blender (révolution/extrusion), 1–4 h
    ├─ Produit générique → acheter ou télécharger avec licence (Fab, Sketchfab, CGTrader, Poly Haven)
    └─ Aucun modèle possible → objet procédural/stylisé (tour, extrusion de SVG, points, line-art)

Quelle que soit l'origine, le modèle passe par le pipeline d'optimisation (references/asset-pipeline.md) : nettoyage, décimation à 100–300 k triangles, texture de 2048–4096 en WebP, compression Meshopt, échelle réelle, origine et orientation correctes, et un maillage séparé très décimé pour le wireframe. Ce détail est très important : le wireframe d'un maillage dense ressemble à du bruit gris, pas à un dessin.

Il y a un script prêt pour cette étape : scripts/prepare-model.sh <entrée.glb|.obj|.fbx> <nom>. Il génère models/<nom>.glb optimisé et models/<nom>-wire.glb pour les lignes. Avec la Stratocaster d'exemple, il est passé de 22,2 Mo à 1,8 Mo.

Scan ou modèle fait à la main. Le maillage wire décimé est pour les scans, où les arêtes sont du bruit. Dans un modèle fait à la main (CAD, Sketchfab, Blender), le maillage décimé se transforme en longs triangles qui traversent les surfaces et se lit comme un maillage, pas comme un dessin. Là, utilisez wireMode: 'edges' sur le maillage principal et wireModel: null, sans générer le wire. Ça se lit comme un dessin technique et vous économisez un fichier.

Téléchargements de Sketchfab : nécessitent une session ouverte (compte gratuit). Si vous utilisez le navigateur intégré, demandez à l'utilisateur de se connecter et confirmez le nom, la taille et le format (GLB) avant de télécharger. Sauvegardez l'original dans un dossier source/ séparé et créditez l'auteur (CC BY) dans le footer.

Phase 3 — Monter le projet à partir du template

Copiez assets/template/ dans le dossier du projet. Voici ce qu'il contient :

Fichier	Ce qu'il fait
index.html	Structure : fond fixe (grille + papier), <canvas> fixe, <svg> de superposition, loader, nav, rail de progression, sélecteur de colorway et sections avec attributs de pose (data-ry, data-x, data-reveal…).
styles.css	Système visuel : tokens, typographie fluide avec clamp(), grille CSS, fond papier, révélations avec blur, courbes d'easing, mobile.
main.js	Moteur : renderer, lumières, chargement avec progression, shaders de révélation et colorway, wireframe et fantôme, ombres, chorégraphie de défilement, glisser avec ressort, superpositions SVG (cotes et callouts), compteurs, colorways. Le tout configurable depuis CONFIG au début du fichier.

Pas besoin de build. Il se sert avec n'importe quel serveur statique (npx serve, python -m http.server). Ne fonctionne pas avec file:// à cause des modules ES. Three.js vient de jsDelivr avec une version fixe dans l'importmap ; pour la production, il est conseillé de le copier dans vendor/ et d'ajouter modulepreload (voir references/performance.md).

Testez-le sans modèle : index.html?model=<url d'un .glb>, ou sans paramètre pour voir l'objet procédural de remplacement. Un bon glb de test est MaterialsVariantsShoe.glb de KhronosGroup/glTF-Sample-Assets.

Phase 4 — Ajuster le modèle à la scène

Dans main.js → CONFIG :

1. orient : tournez jusqu'à ce que l'objet ait Y vers le haut et la longueur sur X (par exemple, [0, 0, -Math.PI/2] pour coucher une guitare qui arrive debout). L'orientation s'applique au modèle avant de le mesurer, donc la boîte, les cotes, sweepDir, les callouts et l'éclaté s'expriment toujours dans l'espace déjà orienté. Utilisez ?debug pour voir les axes.
2. realSizeCm : la mesure réelle du côté le plus long, en cm. De là viennent toutes les cotes affichées.
3. sweepDir : la direction du balayage de révélation. Qu'elle suive la 'lecture' naturelle de l'objet : le long d'un objet allongé ([1,0,0] ou [0,0,1]), de bas en haut pour une bouteille ou un bâtiment ([0,1,0]) et en diagonale pour un objet compact ([0.3,0.3,1]).
4. callouts : les positions des parties, comme fractions de la boîte (f, 0..1) ou comme coordonnées exactes du modèle (p, dans ses unités). Le code les accroche au sommet le plus proche. Ordonnez-les de haut en bas pour que les lignes ne se croisent pas. Avec ?debug, cliquez sur le modèle et la console imprime la fraction exacte du point.
5. colorways : définissez sombre/clair par variante (ou supprimez le sélecteur si l'objet n'a pas de variantes). Le shader recolore par luminance et préserve les détails saturés ; si l'objet lui-même est d'une couleur saturée, mettez keepSaturated: 0.
6. Sections : ajoutez, supprimez ou réordonnez librement <section>. Le moteur lit les poses de n'importe quelle quantité de sections, dans n'importe quel ordre.
7. Options du moteur pour cas spéciaux :
   • procedural: () => Object3D construit l'objet par code au lieu de charger un glb.
   • wireMode: 'edges' dessine uniquement les arêtes de dessin. C'est le meilleur pour les objets durs, CAD ou procéduraux.
   • extraKeys: ['screen'] + onFrame(cur, dt, t) servent pour des effets propres contrôlés par section (data-screen). Par exemple, un écran qui s'allume, une lumière ou un couvercle qui s'ouvre.
   • Éclaté avec data-explode : chaque pièce bouge selon son userData.explode = [x,y,z] (ou s'éloigne du centre si elle ne l'a pas).
   • Par pièce : userData.noRecolor (ignore les colorways), userData.noWire (n'apparaît pas dans le plan) et userData.keepPbr (le moteur ne touche pas à son matériau).
   • recolorOnly: ['BodyMaterial'] : seuls ces matériaux (par nom du glb) prennent les colorways. Sur la guitare, le corps se peint et le pickguard, le manche et les ferrures restent intacts.
   • keepPbr: true respecte le PBR des modèles faits à la main (métaux réels, vernis avec clearcoat). Par défaut, le moteur corrige le metalness faux des scans et IA, et cela ruine un modèle bien fait.
   • wireColors: [couleur avec papier 0, couleur avec papier 1] et edgeColor adaptent le plan à n'importe quel concept, par exemple encre sur papier de brevet au lieu de blanc sur bleu. Les deux états du fond (backdrop__grid et backdrop__paper) ne sont que des noms : ils peuvent être stylés comme plaque → scène, vitrine → nuit, etc.
   • data-rz (roulis) pour poser les objets longs, comme une guitare sur son support. Les ombres au sol s'éteignent automatiquement en le posant.
8. **

…

[Le contenu du fichier original a été tronqué pour la traduction.]