3D Product Viewer - Schnellstart-Anleitung

1. Fuer Anfaenger

Noch nie mit Webentwicklung gearbeitet? Kein Problem. Hier ist alles Schritt fuer Schritt erklaert.

Was ist der 3D Product Viewer?

Der 3D Product Viewer ist eine einzelne JavaScript-Datei (stl-viewer.js), die du in jede Website einbinden kannst. Besucher koennen dann 3D-Modelle direkt im Browser drehen, zoomen und betrachten — ohne Installation, ohne Plugins, ohne Server.

Unterstuetzte Formate: STL, GLB, GLTF, OBJ, PLY, FBX, 3MF — Sprachen: Deutsch, Englisch, Spanisch, Franzoesisch (automatisch)

Was brauche ich?

Nur zwei Dinge:

1. stl-viewer.js

Die Viewer-Datei (ca. 45 KB)

2. Eine HTML-Datei

Deine Webseite, in die der Viewer eingebettet wird

1

stl-viewer.js herunterladen

Lade die Datei stl-viewer.js herunter und speichere sie in einem Ordner auf deinem Computer, z.B. in mein-projekt/.

2

HTML-Datei erstellen

Erstelle eine neue Datei namens index.html im selben Ordner und kopiere diesen kompletten Code hinein:

<!DOCTYPE html>
<html lang="de">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Mein 3D-Viewer</title>
</head>
<body>

    <!-- 3D-Viewer Container -->
    <div data-stl-viewer
         data-stl="mein-modell.stl"
         data-background="studio"
         style="width:100%; height:500px">
    </div>

    <!-- Viewer-Script (einmal pro Seite, vor </body>) -->
    <script src="stl-viewer.js"></script>

</body>
</html>

Anpassen: Ersetze mein-modell.stl mit dem Dateinamen deiner 3D-Datei. Die Datei muss im selben Ordner liegen wie die HTML-Datei.

3

Im Browser oeffnen

Oeffne die index.html Datei mit einem Doppelklick — dein Standardbrowser zeigt den 3D-Viewer an.

Hinweis: Manche Browser blockieren lokale Dateien aus Sicherheitsgruenden. Falls das Modell nicht laedt, lege die Dateien auf einen einfachen Webserver (z.B. mit python -m http.server) oder lade sie auf deinen Webspace hoch.

Ordnerstruktur

mein-projekt/
  index.html        <-- Deine Webseite
  stl-viewer.js     <-- Der Viewer
  mein-modell.stl   <-- Dein 3D-Modell

2. Fuer Website-Besitzer

Integration auf verschiedenen Plattformen — ueberall nur ein Script-Tag und ein Container-Element.

Statische HTML-Website

Lade stl-viewer.js auf deinen Webserver und fuege diesen Code dort ein, wo der Viewer erscheinen soll:

<!-- 3D-Viewer Container -->
<div data-stl-viewer
     data-stl="/pfad/zu/modell.stl"
     data-color="#4fc3f7"
     data-background="studio"
     style="width:100%; height:500px">
</div>

<!-- Einmal pro Seite, vor </body> -->
<script src="/js/stl-viewer.js"></script>

WordPress

Verwende den Shortcode im Gutenberg-Editor oder im Classic Editor:

[stl_viewer src="/modell.stl" height="500"]

Oder fuege einen Custom HTML Block im Gutenberg-Editor hinzu und verwende den HTML-Code oben. Lade stl-viewer.js ins Theme-Verzeichnis oder verlinke es per Plugin.

Shopify

1. Lade stl-viewer.js unter Einstellungen > Dateien hoch.
2. Fuege auf der Produktseite einen Custom HTML Block hinzu.
3. Verwende den Container-Code mit der Shopify-CDN-URL der hochgeladenen JS-Datei.

Squarespace

1. Gehe zu Seite bearbeiten > Code Block einfuegen.
2. Fuege den Viewer-HTML-Code ein.
3. Unter Einstellungen > Erweitert > Code Injection das Script im Footer einfuegen.

Wix

1. Fuege ein HTML iFrame / Embed Element hinzu.
2. Klicke auf "Code eingeben" und fuege die vollstaendige HTML-Seite ein (inklusive <!DOCTYPE html>).
3. Hoste stl-viewer.js auf einem externen Server und verlinke per vollstaendiger URL.

3. Fuer Entwickler

JavaScript API, programmatische Kontrolle, Events und Custom Styling.

JavaScript API Referenz

Der Viewer registriert sich als window.STLViewer. Jedes Viewer-Element speichert seine Instanz in el._stlViewer.

// Viewer manuell erstellen
const container = document.querySelector('#mein-viewer');
const viewer = new STLViewer(container, {
    stl: 'modell.stl',
    color: '#4fc3f7',
    background: 'studio',
    autoRotate: true,
    showGrid: true,
    adminMode: false,
    materialPreset: 'metallic',
    rotateSpeed: 1.5,
    maxFileSize: 50
});

Programmatische Kontrolle

// Instanz holen (bei data-attribute Init)
const viewer = document.querySelector('[data-stl-viewer]')._stlViewer;

// Farbe aendern
viewer.setColor('#e91e63');

// Material wechseln
viewer.setMaterial('gold');       // default|matte|glossy|metallic|plastic|gold|chrome|clay

// Hintergrund wechseln
viewer.setBackground('ocean');   // dark|light|studio|warm|ocean|sunset|forest|night|neon
viewer.setBackground('#ff0000'); // oder beliebiger HEX-Wert

// Auto-Rotation
viewer.toggleAutoRotate();       // ein/aus, gibt Boolean zurueck
viewer.setRotateSpeed(3.0);      // Geschwindigkeit (Standard: 1.5)

// Ansicht
viewer.toggleGrid();              // Raster ein/aus
viewer.toggleWireframe();         // Drahtgitter ein/aus
viewer.toggleFullscreen();        // Vollbild ein/aus
viewer.resetCamera();             // Kamera zuruecksetzen
viewer.zoomFit();                 // Modell einpassen

// Screenshot
viewer.takeScreenshot();          // PNG herunterladen

// Neues Modell laden (URL oder File-Objekt)
viewer.loadModel('neues-modell.glb');

// Viewer zerstoeren
viewer.dispose();

Custom Styling

Der Viewer nutzt die CSS-Klasse .stl-viewer-root. Du kannst das Aussehen ueberschreiben:

<style>
/* Eigener Rahmen */
.stl-viewer-root {
    border-radius: 0;         /* Ecken eckig statt rund */
    border: 2px solid #4fc3f7;
}
/* Toolbar-Buttons anpassen */
.sv-toolbar .sv-btn:hover {
    background: rgba(79,195,247,.3);
}
</style>

Mehrere Viewer pro Seite

Einfach mehrere Container-Elemente mit data-stl-viewer anlegen. Jeder wird automatisch initialisiert:

<div data-stl-viewer data-stl="modell-a.stl" data-color="#e91e63"
     style="height:400px"></div>

<div data-stl-viewer data-stl="modell-b.glb" data-background="ocean"
     style="height:400px"></div>

<!-- Script nur EINMAL einbinden -->
<script src="stl-viewer.js"></script>

Multi-File Viewer (Datei-Umschalter)

Zeige mehrere Modelle in einem Viewer mit Umschalter-Buttons:

<div data-stl-viewer
     data-files="modell-a.stl, modell-b.glb, modell-c.obj"
     data-labels="Variante A, Variante B, Variante C"
     style="height:500px"></div>

4. Fuer WooCommerce Shops

3D-Produktvorschau direkt in deinem WooCommerce-Shop — mit dem mitgelieferten WordPress-Plugin.

1

Plugin installieren

1. Gehe zu WordPress > Plugins > Installieren > Plugin hochladen.

2. Lade die Plugin-ZIP-Datei stl-product-viewer.zip hoch und aktiviere das Plugin.

3. Das Plugin erscheint unter Einstellungen > STL Product Viewer.

2

Produkt mit 3D-Viewer einrichten

1. Bearbeite ein WooCommerce-Produkt.

2. Im Tab 3D-Viewer lade deine STL/GLB-Datei hoch oder gib eine URL ein.

3. Waehle optionale Einstellungen (Farbe, Hintergrund, Material).

4. Speichere das Produkt — der 3D-Viewer erscheint automatisch auf der Produktseite.

3

Shortcode verwenden

Alternativ kannst du den Viewer ueberall per Shortcode einbinden:

<!-- Einfacher Viewer -->
[stl_viewer src="/wp-content/uploads/modell.stl"]

<!-- Mit Optionen -->
[stl_viewer src="/modell.stl" color="#e91e63" background="studio" height="600" rotate="true"]

<!-- Admin-Modus (Drag & Drop, Einstellungen) -->
[stl_viewer src="/modell.stl" admin="true"]

Shortcode-Optionen

Option	Werte	Beschreibung
`src`	URL/Pfad	Pfad zur 3D-Datei (Pflicht)
`color`	HEX-Farbe	Modellfarbe, z.B. `#4fc3f7`
`background`	Preset-Name	Hintergrund-Preset
`height`	Pixel	Viewer-Hoehe, Standard: 500
`rotate`	true/false	Auto-Rotation aktivieren
`grid`	true/false	Raster anzeigen
`admin`	true/false	Admin-Modus (alle Steuerungen)
`material`	Preset-Name	Material-Preset

Automatische Einbindung auf Produktseiten

Wenn im Produkt eine 3D-Datei hinterlegt ist, ersetzt der Viewer automatisch die Produktbildgalerie. Der Kunde kann das 3D-Modell live drehen und zoomen. Klickt er auf ein Produktbild, wechselt die Ansicht zurueck.

Bulk-Aktionen fuer viele Produkte

Unter Produkte > Alle Produkte kannst du mehrere Produkte auswaehlen und ueber die Bulk-Aktion "3D-Viewer-Einstellungen" gleichzeitig Hintergrund, Farbe und Material fuer alle ausgewaehlten Produkte festlegen.

5. Alle Optionen Referenz

Vollstaendige Liste aller data-Attribute, Hintergruende, Materialien und Tastenkuerzel.

Data-Attribute

Attribut	Werte	Standard	Beschreibung
`data-stl-viewer`	(leer)	—	Markiert das Element als Viewer-Container (Pflicht)
`data-stl`	URL / Pfad	—	Pfad zur 3D-Datei (STL, GLB, OBJ, PLY, FBX, 3MF)
`data-color`	HEX-Farbe	`#4fc3f7`	Farbe des 3D-Modells
`data-background`	Preset oder HEX	`dark`	Hintergrund-Preset oder eigene Farbe
`data-autorotate`	true / false	`false`	Automatische Rotation beim Start
`data-grid`	true / false	`true`	Bodenraster anzeigen
`data-admin`	true / false	`false`	Admin-Modus: Drag&Drop, Einstellungen, Dateiverwaltung
`data-placeholder`	Text	"3D-Vorschau"	Platzhalter-Text wenn kein Modell geladen
`data-lang`	de / en / es / fr	auto	Sprache erzwingen (sonst automatisch per Browser)
`data-files`	URLs (Komma-getrennt)	—	Mehrere Modelle mit Umschalter
`data-labels`	Texte (Komma-getrennt)	1, 2, 3...	Labels fuer die Datei-Umschalter-Buttons

Hintergrund-Presets

Vorschau	Name	Beschreibung
	`dark`	Dunkler Hintergrund (Standard)
	`light`	Heller Hintergrund
	`studio`	Studio-Verlauf (Blau-Dunkel)
	`warm`	Warme Rot-/Braun-Toene
	`ocean`	Tiefsee-Blau
	`sunset`	Sonnenuntergang
	`forest`	Wald-Gruen
	`night`	Nacht / Dunkelblau
	`neon`	Neon / Dunkles Violett
	`transparent`	Durchsichtiger Hintergrund
	`camera`	Live-Webcam als Hintergrund

Material-Presets

Name	Metalness	Roughness	Clearcoat	Beschreibung
`default`	0.3	0.4	0.3	Standard-Material
`matte`	0	0.9	0	Matt / stumpf
`glossy`	0.1	0.05	0.8	Hochglaenzend
`metallic`	0.9	0.15	0.4	Metallisch
`plastic`	0	0.3	0.5	Plastik / Kunststoff
`gold`	1.0	0.2	0.3	Gold (feste Farbe #FFD700)
`chrome`	1.0	0.05	0.6	Chrom (feste Farbe #C0C0C0)
`clay`	0	1.0	0	Ton / Lehm (feste Farbe #C4A882)

Tastenkuerzel

Hinweis: Der Viewer muss fokussiert sein (einmal anklicken), damit Tastenkuerzel funktionieren.

Taste	Aktion
`R`	Auto-Rotation ein/aus
`G`	Raster ein/aus
`W`	Drahtgitter ein/aus
`F`	Vollbild ein/aus
`D`	Abmessungen ein/aus
`0`	Kamera zuruecksetzen
`Leertaste`	Animation abspielen/pausieren
`Strg + S`	Screenshot speichern
`Escape`	Vollbild verlassen / Popups schliessen
`Doppelklick`	Modell einpassen (Zoom to Fit)

Maus- und Touch-Steuerung

Eingabe	Aktion
Linke Maustaste ziehen	Modell drehen
Mausrad / Pinch	Zoomen
Rechte Maustaste ziehen	Verschieben (Pan)
Touch: Finger ziehen	Drehen
Touch: Zwei Finger ziehen	Zoomen und Verschieben

6. Fehlerbehebung

Haeufige Probleme und Loesungen.

Viewer zeigt nichts an / bleibt schwarz

1. Script-Pfad pruefen: Stelle sicher, dass der <script src="...">-Pfad auf die richtige Datei zeigt. Oeffne die URL im Browser — du solltest JavaScript-Code sehen.

2. Container-Hoehe setzen: Der Viewer braucht eine definierte Hoehe. Fuege style="height:500px" zum Container hinzu.

3. Browser-Konsole pruefen: Oeffne mit F12 die Entwicklertools und schaue nach Fehlermeldungen in der Konsole.

4. WebGL pruefen: Besuche get.webgl.org. Wenn dort kein drehender Wuerfel erscheint, unterstuetzt dein Browser kein WebGL.

3D-Datei laedt nicht / Fehler beim Laden

1. Dateipfad pruefen: Oeffne den data-stl-Pfad direkt im Browser. Wird die Datei heruntergeladen? Falls nicht, stimmt der Pfad nicht.

2. CORS-Probleme: Wenn die Datei auf einem anderen Server liegt, muss dieser CORS-Header senden (Access-Control-Allow-Origin). Lege die Datei am besten auf denselben Server.

3. Dateiformat pruefen: Unterstuetzt werden: STL, GLB, GLTF, OBJ, PLY, FBX, 3MF. Die Dateiendung muss korrekt sein.

4. Dateigroesse: Standard-Limit ist 50 MB. Bei groesseren Dateien im Admin-Modus das Limit erhoehen.

5. Lokale Dateien: Beim Oeffnen von file://-Seiten blockieren Browser oft das Laden externer Dateien. Verwende einen lokalen Webserver.

Performance-Probleme / Viewer ist langsam

1. Polygon-Anzahl: Modelle mit mehr als 500.000 Dreiecken koennen langsam sein. Reduziere die Polygone in deiner 3D-Software (Decimate/Remesh).

2. Dateiformat: GLB/GLTF-Dateien sind oft schneller als STL, da sie komprimiert und optimiert sind.

3. Mehrere Viewer: Jeder Viewer erstellt einen eigenen WebGL-Kontext. Bei mehr als 3-4 Viewern auf einer Seite kann die Performance leiden.

4. Raster deaktivieren: Bei schwacher Grafik kann data-grid="false" etwas Performance bringen.

Mobile Probleme / Touch funktioniert nicht

1. Viewport Meta-Tag: Stelle sicher, dass <meta name="viewport" content="width=device-width, initial-scale=1.0"> im <head> steht.

2. Container-Groesse: Auf Mobilgeraeten sollte der Container width:100% haben, damit er sich anpasst.

3. iOS Safari: Touch-Gesten funktionieren automatisch. Falls Scrollen blockiert wird, pruefe ob der Container nicht die ganze Seite einnimmt.

4. Speicher: Mobile Geraete haben weniger RAM. Halte die Modellgroesse unter 10 MB / 200.000 Dreiecke.

7. Live Demo

Ein vollstaendiger Viewer mit Admin-Modus. Drag & Drop zum Testen beliebiger 3D-Dateien.

Admin-Modus / Studio-Hintergrund — Drag & Drop oder Klick zum Laden

Code fuer diese Demo

<div data-stl-viewer
     data-admin="true"
     data-background="studio"
     data-stl="models/chess-pawn.stl"
     style="height:520px">
</div>

<script src="stl-viewer.js"></script>