nachoiannella/scroll-3d-landing

Landing 3D mit Scroll (für jedes Objekt)

Diese Skill dient zum Bau einer Einseiten-Landingpage, bei der ein 3D-Objekt der Star ist. Das Objekt bleibt fest im Hintergrund und ändert Pose, Render-Stil und Kontext, während der Benutzer scrollt. Es funktioniert für alles, was sich als Objekt zeigen lässt: eine Weinflasche, ein Kopfhörer, ein Stuhl, eine Gitarre, eine Uhr, ein Auto, ein Gebäudemodell, eine Skulptur, eine alte Kamera, ein Parfümflakon, ein Werkzeug oder ein Spielzeug.

Das Referenzbeispiel ist toppervenom.com von Evil Rabbit (Originalbeitrag), und aus diesem Projekt entstand die Idee für diese Skill. Es zeigt einen Topper-Basketballschuh aus den 90ern; sein 3D-Modell ist kein Scan, sondern eine KI-Rekonstruktion aus Archivmaterial und generierten Bildern aller Ansichten. Die Seite beginnt als technische Zeichnung (weißes Drahtgitter auf blauem Raster), füllt sich mit dem echten Material, zeigt Maße und Teile, wechselt die Farbe und endet mit einer Drehung. Der Schuh ist nur das Beispiel; repliziert wird die Art, die Seite zu bauen, und ihr Qualitätsniveau. Jedes Projekt wählt sein eigenes visuelles Konzept, seine Abfolge von Akten und den Enthüllungseffekt, der am besten zu seinem Objekt passt (siehe „An das Objekt anpassen“ weiter unten).

Warum diese Seiten so gut aussehen (lies dies vor dem Start)

Die Qualität kommt nicht vom Stack. toppervenom.com besteht aus etwa 90 KB HTML/CSS/JS plus Three.js (laut Autor wurde die Seite auf einen Schlag von einer KI generiert): kein Framework, kein GSAP, kein Bundler. Die Qualität kommt von fünf Dingen, und jede Entscheidung im Projekt sollte einem davon dienen:

1. Ein echtes und gut vorbereitetes 3D-Asset. Ein Scan mit fotografischer Textur, eine sorgfältig bearbeitete KI-Rekonstruktion (wie bei toppervenom) oder ein Modell mit echtem Detail, sauber, leicht und mit korrektem Maßstab. Wenn das Modell schlecht ist, rettet nichts anderes es. → references/3d-capture.md, references/3d-alternatives.md
2. Render mit fotografischem Anspruch. Drei-Punkt-Beleuchtung, Environment Map, neutrales Tone Mapping, Kontaktschatten und korrigierte Materialien (ein Scan bringt oft falsche Metalness mit, die Leder wie Plastik aussehen lässt). → references/rendering.md
3. Ein Art-Direction-Konzept, das bis ins letzte Detail durchdacht ist. „Technische Zeichnung“ bei toppervenom: das Raster, die Bemaßungen, die Monospace-Schriftart, der Loader sagt „PLOTTING DRAWING Nº 01“, der Fortschrittsbalken sagt „REV. 0 — BLUEPRINT“. Alles erzählt die gleiche Geschichte. → references/art-direction.md
4. Bewegung mit Physik, nicht mit Keyframes. Die Posen werden pro Abschnitt deklariert; das JS interpoliert mit Smoothstep und dämpft zusätzlich jeden Wert mit exponentiellem Abfall. Das verleiht Gewicht und Trägheit. → references/choreography.md
5. Shader-Effekte, die das 3D rechtfertigen. Enthüllung Drahtgitter→Festkörper mit einer Ebene, die das Objekt überstreicht, Geisteroberfläche mit Fresnel, Neufärbung nach Luminanz. Das sind Dinge, die ein Video nicht kann. → references/shaders.md

Wenn der Benutzer „so etwas“ verlangt, besteht die eigentliche Arbeit darin: ein gutes Modell besorgen + ein Konzept wählen + geduldig anpassen. Die Vorlage löst die Ingenieursarbeit.

An das Objekt anpassen (kopiere nicht den Schuh)

Die Vorlage bringt eine Beispielsequenz mit (Zeichnung → Maße → Teile → Enthüllung → Zahlen → Ursprung → Abschluss), aber die Form des Objekts und seine Geschichte bestimmen die Komposition, den Effekt und die Akte. Bevor du Posen schreibst, ordne das Objekt in dieser Tabelle ein:

Form des Objekts	Beispiele	Komposition	Am besten geeignete Enthüllung	Typische Akte
Länglich horizontal	Schuh, Auto, Gitarre, Messer, Stift, Zug	Objekt auf einer Seite, Text auf der anderen; reines Profil für die Maße	Längsüberstreichung (Spitze → Ende)	Technisches Profil, Teiledetail, Geschwindigkeit oder Nutzung
Vertikal / Rotationskörper	Flasche, Parfüm, Lampe, Vase, Trophäe, Gebäude	Objekt zentriert oder zu einem Drittel, Text in zwei Spalten an den Seiten; leichte Untersicht für den Höhepunkt	Überstreichung von unten nach oben („füllt sich“) oder Querschnitt	Silhouette, Material oder Inhalt, Ursprung, Gebrauchsritual
Kompakt / Kasten	Kopfhörer, Kamera, Lautsprecher, Uhr, Konsole, Schmuck	Große Nahaufnahmen (scale 1.4–2), die das Objekt wie eine Makroaufnahme abfahren	Explosionszeichnung (auseinandergezogene Ansicht) oder diagonale Überstreichung	Design, Inneres/Komponenten, Materialien, Spezifikationen
Flach / für Frontales Lesen	Buch, Schallplatte, Bild, Platine, Karte, Tablet	Kurze Rotationen (±0.4 rad), um die Dicke zu zeigen; niemals lange von der Seite	Punkte, die sich verdichten, oder Farbe, die „erscheint“	Vorderseite, Rückseite, Texturdetail, Kontext
Organisch / Skulptural	Skulptur, Essen, Pflanze, Fossil, Spielzeug	Langsame und weite Drehungen, viel Konturlicht	Punktwolke → Oberfläche oder Geist mit Fresnel	Form, Textur, Geschichte, menschlicher Maßstab
Aus Teilen montiert	Möbel, Maschine, Modell, modulares Produkt	Schräge 3/4-Ansicht von oben, gesamte Baugruppe im Bild	Explosion durch Scrollen: Jedes Teil trennt sich entlang seiner Achse und kehrt zurück	Baugruppe → Explosion → Teil für Teil → Montage
Großer Maßstab	Haus, Gebäude, Grundstück, Schiff	Kamera weiter weg, Drehung als „Modell“ auf dem Tisch	Vertikale Überstreichung pro Etage, Schnittdarstellungen	Standort, Grundrisse, Schnitte, Materialien

Wähle auch das visuelle Konzept basierend auf dem Objekt, nicht standardmäßig. „Technische Zeichnung“ passt zu allem, was entworfen oder hergestellt ist; ein Wein kann „Weingut-Blatt“ verlangen; eine Skulptur, „Museumskatalog“; ein Gadget, „Labor“; etwas Vintage, „Katalog aus der Zeit“. Das vollständige Menü findest du in references/art-direction.md, alternative Effekte (Explosionszeichnung, Punkte, Schnitt, Füllung) in references/shaders.md.

Arbeitsablauf

Befolge diese Phasen in der Reihenfolge. Bevor du Code schreibst, bestätige mit dem Benutzer die Entscheidungen der Phasen 1 und 2, da sie alles Weitere beeinflussen.

Phase 1 – Brief und Konzept (5 Minuten mit dem Benutzer)

Frage oder leite ab:

• Welches Objekt es ist und aus welchem Material (Leder, Glas, Metall, mattes Plastik, Stoff). Das Material bestimmt, wie es erfasst und wie es beleuchtet wird.
• Die Geschichte in 5–8 Akten. Jeder Akt ist ein Abschnitt und eine Pose des Objekts. Typisches Beispiel: Einführung → Zeichnung/Maße → Anatomie (Teile) → Enthüllung → Zahlen → Ursprung/Geschichte → Abschluss.
• Das visuelle Konzept, also die Metapher, die alles vereint. Kopiere nicht standardmäßig „Blueprint“: wähle die Metapher, die für dieses Produkt sinnvoll ist. In references/art-direction.md gibt es ein Menü von Konzepten (technische Zeichnung, Museumskatalog, Labor, Katalog der 90er, Mode-Editorial, industrielle Explosionszeichnung) mit ihrer Palette, Schriftarten und wie jedes in 3D übersetzt wird.
• Echte Inhalte. Daten, Maße, Materialien, Geschichte und Credits. Die Referenzseiten wirken authentisch, weil sie echte Daten aus dem Originalkatalog und vom Scan verwenden. Wenn es keine Daten gibt, fordere sie an; erfinde keine Spezifikationen eines realen Produkts.
• Sprachen (es/en) und ob es Farbvarianten gibt.

Phase 2 – Das 3D-Modell beschaffen

Diese Phase hat den größten Einfluss auf die endgültige Qualität. Verwende diesen Entscheidungsbaum und lies die entsprechende Referenz:

Hat der Benutzer das physische Objekt?
├─ Ja → SCANNEN (references/3d-capture.md)
│   ├─ Matte/strukturierte Objekte (Schuh, Essen, Stein, Holz, Stoff) → Fotogrammetrie mit Handy oder Kamera
│   ├─ Glänzende, schwarze oder transparente Objekte → temporäres Mattierungsspray + Fotogrammetrie, oder Modellieren
│   └─ Sehr kleine/dünne Objekte (Schmuck, Kabel) → Makro-Fotogrammetrie oder Modellieren
└─ Nein → ALTERNATIVEN (references/3d-alternatives.md)
    ├─ CAD/STEP-Dateien vom Hersteller vorhanden → Konvertieren und Texturieren
    ├─ Gute Fotos aus mehreren Winkeln vorhanden → KI-Bild-zu-3D (Meshy, Tripo, Rodin, Hunyuan3D, TRELLIS) + Reinigung
    ├─ Geometrische Form (Flasche, Dose, Lampe, Möbel) → Modellieren in Blender (Rotation/Extrusion), 1–4 h
    ├─ Generisches Produkt → Kaufen oder herunterladen mit Lizenz (Fab, Sketchfab, CGTrader, Poly Haven)
    └─ Kein Modell möglich → prozedurales/stilisiertes Objekt (Drehteil, SVG-Extrusion, Punkte, Line-Art)

Unabhängig vom Ursprung durchläuft das Modell die Optimierungs-Pipeline (references/asset-pipeline.md): Reinigung, Reduzierung auf 100–300k Dreiecke, Textur von 2048–4096 in WebP, Meshopt-Kompression, korrekter Maßstab, korrekter Ursprung und Ausrichtung, und ein separates, stark reduziertes Netz für das Drahtgitter. Dieses Detail ist sehr wichtig: das Drahtgitter eines dichten Netzes sieht aus wie graues Rauschen, nicht wie eine Zeichnung.

Es gibt ein fertiges Skript für diesen Schritt: scripts/prepare-model.sh <eingabe.glb|.obj|.fbx> <name>. Es erzeugt models/<name>.glb optimiert und models/<name>-wire.glb für die Linien. Bei der Beispiel-Stratocaster wurde die Datei von 22,2 MB auf 1,8 MB reduziert.

Scan oder handgemachtes Modell. Das reduzierte Drahtgitter-Netz ist für Scans, bei denen die Kanten Rauschen sind. Bei einem handgemachten Modell (CAD, Sketchfab, Blender) wird das reduzierte Netz zu langen Dreiecken, die die Oberflächen durchqueren und als Netz gelesen werden, nicht als Zeichnung. Verwende in diesem Fall wireMode: 'edges' auf dem Hauptnetz und wireModel: null, ohne das Drahtgitter zu erzeugen. Es liest sich wie eine technische Zeichnung und spart eine Datei.

Downloads von Sketchfab: erfordern eine angemeldete Sitzung (kostenloser Account). Wenn du den integrierten Browser verwendest, bitte den Benutzer, sich anzumelden, und bestätige Name, Größe und Format (GLB) vor dem Herunterladen. Speichere das Original in einem separaten Ordner source/ und nenne den Autor (CC BY) in der Fußzeile.

Phase 3 – Projekt aus der Vorlage erstellen

Kopiere assets/template/ in den Projektordner. Das ist der Inhalt:

Datei	Funktion
index.html	Struktur: fester Hintergrund (Raster + Papier), <canvas> fixiert, <svg> Overlay, Loader, Nav, Fortschrittsbalken, Colorway-Auswahl und Abschnitte mit Posendaten (data-ry, data-x, data-reveal …).
styles.css	Visuelles System: Tokens, fließende Typografie mit clamp(), CSS-Raster, Papierhintergrund, Enthüllungen mit Blur, Easing-Kurven, Mobilansicht.
main.js	Motor: Renderer, Lichter, Laden mit Fortschritt, Enthüllungs- und Colorway-Shader, Drahtgitter und Geist, Schatten, Scroll-Choreografie, Drag mit Feder, SVG-Overlays (Bemaßungen und Callouts), Zähler, Colorways. Alles über CONFIG am Anfang der Datei konfigurierbar.

Es ist kein Build erforderlich. Es wird mit jedem statischen Server bereitgestellt (npx serve, python -m http.server). Funktioniert nicht mit file:// wegen der ES-Module. Three.js kommt von jsDelivr mit fester Version im importmap; für die Produktion sollte es in vendor/ kopiert und modulepreload hinzugefügt werden (siehe references/performance.md).

Teste es ohne Modell: index.html?model=<url eines .glb>, oder ohne Parameter, um das prozedurale Ersatzobjekt zu sehen. Ein gutes Test-GLB ist MaterialsVariantsShoe.glb von KhronosGroup/glTF-Sample-Assets.

Phase 4 – Modell an die Szene anpassen

In main.js → CONFIG:

1. orient: rotiere, bis das Objekt mit der Y-Achse nach oben und der Länge auf der X-Achse liegt (z. B. [0, 0, -Math.PI/2] zum Hinlegen einer Gitarre, die aufrecht kommt). Die Ausrichtung wird vor dem Messen auf das Modell angewendet, sodass die Box, Bemaßungen, sweepDir, Callouts und die Explosionszeichnung immer im bereits ausgerichteten Raum ausgedrückt werden. Verwende ?debug, um die Achsen zu sehen.
2. realSizeCm: das tatsächliche Maß der längsten Seite in cm. Daraus ergeben sich alle angezeigten Bemaßungen.
3. sweepDir: die Richtung des Enthüllungs-Sweeps. Sie sollte der natürlichen „Lese“-Richtung des Objekts folgen: längs bei einem länglichen Objekt ([1,0,0] oder [0,0,1]), von unten nach oben bei einer Flasche oder einem Gebäude ([0,1,0]) und diagonal bei einem kompakten Objekt ([0.3,0.3,1]).
4. callouts: die Positionen der Teile, entweder als Bruchteile der Box (f, 0..1) oder als exakte Koordinaten des Modells (p, in seinen Einheiten). Der Code klebt sie an den nächstgelegenen Scheitelpunkt. Ordne sie von oben nach unten, damit sich die Linien nicht kreuzen. Mit ?debug klicke auf das Modell und die Konsole gibt den exakten Bruchteil des Punktes aus.
5. colorways: definiere Dunkel/Hell pro Variante (oder lösche den Selektor, wenn das Objekt keine Varianten hat). Der Shader färbt nach Luminanz um und behält gesättigte Details bei; wenn das Objekt selbst eine gesättigte Farbe hat, setze keepSaturated: 0.
6. Abschnitte: füge <section> nach Belieben hinzu, entferne sie oder ordne sie neu. Der Motor liest die Posen einer beliebigen Anzahl von Abschnitten in beliebiger Reihenfolge.
7. Motoroptionen für Sonderfälle:
   • procedural: () => Object3D erstellt das Objekt per Code, anstatt ein GLB zu laden.
   • wireMode: 'edges' zeichnet nur die Zeichnungskanten. Am besten für harte Objekte, CAD oder prozedurale Objekte.
   • extraKeys: ['screen'] + onFrame(cur, dt, t) dienen für eigene, abschnittsgesteuerte Effekte (data-screen). Zum Beispiel ein Bildschirm, der sich einschaltet, ein Licht oder eine Klappe, die sich öffnet.
   • Explosionszeichnung mit data-explode: jedes Teil bewegt sich gemäß seinem userData.explode = [x,y,z] (oder vom Zentrum weg, wenn es nicht vorhanden ist).
   • Pro Teil: userData.noRecolor (ignoriert Colorways), userData.noWire (erscheint nicht in der Zeichnung) und userData.keepPbr (der Motor verändert sein Material nicht).
   • recolorOnly: ['BodyMaterial']: nur diese Materialien (anhand des Namens im GLB) übernehmen die Colorways. Bei der Gitarre wird der Korpus bemalt, während Schlagbrett, Hals und Hardware intakt bleiben.
   • keepPbr: true respektiert das PBR von handgemachten Modellen (echte Metalle, Klarlack). Standardmäßig korrigiert der Motor die falsche Metalness von Scans und KI, was ein gut gemachtes Modell ruiniert.
   • wireColors: [Farbe mit Papier 0, Farbe mit Papier 1] und edgeColor passen die Zeichnung an jedes Konzept an, z. B. Tinte auf Patentpapier statt Weiß auf Blau. Die beiden Hintergrundzustände (backdrop__grid und backdrop__paper) sind nur Namen: sie können als Folie → Bühne, Vitrine → Nacht usw. gestylt werden.
   • data-rz (Roll) zum Aufstellen langer Objekte, wie eine Gitarre auf ihrem Ständer. Die Boden-Schatten werden beim Aufstellen automatisch deaktiviert.
8. **