rotate360 - Drehansicht aus Einzelbildern

rotate360 blättert eine Bildserie (z.B. 24 oder 36 Fotos vom Drehteller) per Maus, Touch, Tastatur oder Autoplay so schnell durch, dass sich das Objekt scheinbar dreht. Dazu kommen Multi-Row (Blick von oben/unten), Zoom mit Pan, Vollbild, Points of Interest mit Sprechblasen und Detailbild sowie eine kleine Button-Leiste. Keine Abhängigkeiten, Konfiguration über data-*-Attribute, Inline-JSON oder JavaScript. Auto-Init beim DOM-ready inklusive.

Quick Start

CSS und JS einbinden, ein Element mit Klasse .rotate360 anlegen, Bildmuster angeben.

<link rel="stylesheet" href="rotate360.css">
<script src="rotate360.js" defer></script>

<div class="rotate360"
     data-rotate-src="img/produkt_{i}.jpg"
     data-rotate-count="24"
     data-rotate-pad="2"></div>

{i} wird durch die Frame-Nummer ersetzt (Start bei data-rotate-index-start, Default 1), data-rotate-pad="2" füllt auf 01, 02, … auf. Bei mehreren Zeilen steht {r} für die Zeilennummer ab 0. Die Breite bestimmt das umgebende CSS, die Höhe folgt dem Seitenverhältnis des ersten Bildes - siehe Größe und Responsive.

Bilder als Liste

Statt eines Musters kann die Liste direkt angegeben werden - als Attribut oder als Inline-JSON im Host:

<div class="rotate360" data-rotate-frames='["a.jpg","b.jpg","c.jpg"]'></div>

<div class="rotate360">
  <script type="application/json" data-rotate-config>
  {
    "frames": [["r0_01.jpg", "r0_02.jpg"], ["r1_01.jpg", "r1_02.jpg"]],
    "pois": [ { "frame": 0, "x": 50, "y": 40, "label": "Logo" } ]
  }
  </script>
</div>

Ein zweidimensionales Array ergibt Multi-Row ([zeile][frame]). Alle Optionen aus dem Inline-JSON überschreiben die Data-Attribute; JavaScript-Optionen überschreiben beides.

Bedienung

• Ziehen waagerecht dreht; bei mehreren Zeilen kippt senkrechtes Ziehen die Blickhöhe. Beides geht gleichzeitig in einer Bewegung - eine diagonale Geste dreht und kippt zugleich, und die neue Zeile wird dabei direkt weitergedreht. Loslassen mit Schwung läuft nach (inertia, nur waagerecht).
• Mausrad zoomt zum Cursor, Doppelklick zoomt hinein bzw. wieder heraus, Zwei-Finger-Pinch zoomt auf Touch.
• Im Zoom dreht Ziehen weiterhin ganz normal (auch das Kippen bei Multi-Row). Verschoben wird der Ausschnitt mit der rechten Maustaste, mit gedrückter Strg- bzw. Cmd-Taste oder auf Touch mit zwei Fingern. Wer das alte Verhalten möchte (links ziehen verschiebt), setzt zoomDrag: 'pan'. Der Ausschnitt bleibt beim Bildwechsel identisch, weil Zoom und Pan auf einer Ebene über allen Frames liegen.
• Tastatur (Host ist fokussierbar): ← → drehen (Shift = 5 Frames), ↑ ↓ Zeile, + - 0 Zoom, Leertaste Play/Pause, F Vollbild, Esc schließt Detailbild, angeheftete Sprechblase bzw. Pseudo-Vollbild (in dieser Reihenfolge).
• Vollbild nutzt die Fullscreen-API; wo sie fehlt (iPhone), wird der Host als Overlay fixiert und mit Esc geschlossen.

Data-Attribute

Nach Themen gruppiert - was in einer Gruppe steht, wird meist zusammen gesetzt. Boolesche Attribute akzeptieren true, false oder das leere Attribut (data-rotate-reverse = an).

Points of Interest und Hotspots

Ein POI ist ein Marker an einer Bildposition, sichtbar in bestimmten Frames. Positionen sind Prozent der Bildfläche (0–100), damit sie unabhängig von Anzeigegröße, Zoom und Vollbild stimmen. Marker wandern mit Zoom und Pan mit, behalten aber ihre Größe. Weil sich die Bildposition mit jeder Drehung verschiebt, gehört ein POI in der Regel zu genau einem Frame.

Ein Hotspot ist die Sprechblase dazu: Text (HTML erlaubt), fester Ankerpunkt der Box, optional ein Detailbild. Ein Hotspot kann von beliebig vielen POIs genutzt werden - so wandert der Marker von Frame zu Frame, während Text und Detailbild nur einmal gepflegt werden. Eine Führungslinie verbindet Marker und Box; die Box liegt links oder rechts vom Anker, je nachdem, auf welcher Seite des Markers er sitzt - side: "left"|"right" legt sie fest -, und wird am Bildrand hineingeschoben statt umgeklappt. Ihr Anker ist Prozent des Bildes in seiner ungezoomten Lage: sie wandert also nicht mit Zoom und Pan, bleibt aber auch im Vollbild über dem Bild statt im Letterbox-Rand. Teilen sich mehrere POIs eines Frames einen Hotspot, liegen ihre Sprechblasen exakt übereinander - der erste POI entscheidet die Seite.

{
  "hotspots": [
    { "id": "flansch",
      "x": 14, "y": 40,               // Anker der Sprechblase (Prozent)
      "html": "Text mit <a href=…>Link</a>",   // oder "text": "…" (wird escaped)
      "open": "hover",                // "hover" (Default) | "auto" | "always"
      "side": "left",                 // Box fest links/rechts vom Anker (sonst automatisch)
      "detail": { "image": "img/flansch_gross.jpg", "caption": "Flanschdichtung" } }
  ],
  "pois": [
    { "id": "flansch_5", "frame": 4, "x": 41, "y": 82, "hotspot": "flansch" },
    { "id": "flansch_6", "frame": 5, "x": 44, "y": 81, "hotspot": "flansch" },
    { "id": "logo", "frames": [0, 1, 23], "x": 50, "y": 40, "label": "Logo" },   // nur Tooltip
    { "id": "inline", "frame": 12, "x": 60, "y": 30,
      "callout": { "x": 85, "y": 20, "text": "Inline-Sprechblase ohne Hotspot" },
      "detail": "img/inline.jpg" }
  ]
}

• open: "hover" - Sprechblase bei Hover/Fokus. Verlassen von Marker oder Box schließt sie erst nach data-rotate-hover-delay ms (Default 250), damit der Weg in die Box zu Links oder zum Detail-Button nicht abreißt. Ein Klick auf den Marker heftet sie an - sie bleibt bis Framewechsel, Esc oder Klick/Ziehen auf der Bühne. Ein zweiter Klick auf den angehefteten Marker öffnet das Detailbild, wenn eines da ist, sonst löst er die Blase.
• open: "auto" - öffnet sich, sobald der POI ins Bild kommt; während Autoplay bleibt sie zu. Klick öffnet das Detailbild.
• open: "always" - immer offen. Klick öffnet das Detailbild.
• side hält die Box auf einer Seite des Ankers, unabhängig davon, wo der Marker gerade liegt. Der Editor setzt es beim Verschieben der Sprechblase automatisch.
• label ohne Hotspot ergibt den kleinen Tooltip wie bisher. Mit Hotspot dient label nur noch als Aria-Label.
• callout direkt am POI ist die Inline-Variante bzw. überschreibt einzelne Felder des Hotspots (z.B. den Anker in einem bestimmten Frame).

Detailbild

detail darf am POI und/oder am Hotspot stehen - das POI gewinnt. So kann ein Hotspot, der über viele Frames wandert, ein gemeinsames Bild tragen, und ein einzelner POI trotzdem sein eigenes. Ist ein Detailbild wirksam, hängt die Sprechblase unten den Button „Detailbild" an (Beschriftung data-rotate-detail-label, leer = kein Button). Das Bild öffnet sich über diesen Button, über den Marker (bei hover mit dem zweiten Klick, sonst direkt) oder bei POIs ohne Sprechblase mit dem ersten Klick.

Es erscheint als Overlay in Viewergröße - im Vollbild also bildschirmfüllend. X-Button und Bildunterschrift sitzen dabei am eingepassten Bild, nicht am Overlay-Rand - bei einem schmalen Bild auf breitem Monitor also an dessen Ecke bzw. Unterkante. Geschlossen wird mit Esc, dem X-Button oder Klick auf den Hintergrund. Autoplay pausiert solange und läuft nach resumeDelay weiter. detail kann ein String (URL) oder { image, caption, alt } sein.

Das Overlay wächst aus dem Element heraus, über das es geöffnet wurde: rund aus dem Marker, rechteckig aus der Sprechblase (Button „Detailbild"). Beim Schließen schrumpft es dorthin zurück; ist das Element dann nicht mehr sichtbar, in den Marker bzw. in die Mitte. openDetail() wächst aus dem Marker, wenn der POI im aktuellen Frame zu sehen ist, sonst aus der Mitte. Wer das Bild aus einer hover-Blase heraus öffnet, heftet sie damit an - so kehrt das Bild in eine sichtbare Box zurück. Mit prefers-reduced-motion wird nur überblendet.

el.addEventListener('rotate360:poi', (e) => {
  const { poi, frame, row } = e.detail;
  console.log('POI geklickt:', poi.id, poi.hotspot);
});
el.addEventListener('rotate360:detailopen', (e) => { /* e.detail.poi, e.detail.detail */ });
el.addEventListener('rotate360:detailclose', (e) => { /* e.detail.poi */ });

r.openDetail('flansch_5');   // per id oder POI-Objekt
r.closeDetail();
r.setPois([ … ]);            // Listen zur Laufzeit ersetzen
r.setHotspots([ … ]);

JavaScript-API

const r = new Rotate360(element, {
  src: 'img/produkt_{i}.jpg',
  count: 36,
  pad: 2,
  sensitivity: 6,
  autoplay: true,
  fps: 15,
  resumeDelay: 3000,
  pois: [ … ],
  hotspots: [ … ]
});

r.next(); r.prev(); r.next(5);       // drehen
r.goTo(12); r.goTo(12, 2);           // Frame, optional Zeile
r.goTo(12, 0, { animate: true });    // sanft auf kürzestem Weg (goToDuration ms je Frame)
r.goToPoi('flansch_5').then(…);      // hindrehen + Sprechblase öffnen, Event rotate360:poifocus
// Kopplung ohne Attribute: opts.sync = 'gruppe', syncProps: 'frame zoom', syncRole: 'follow'
r.rowUp(); r.rowDown();              // Multi-Row
r.play(); r.pause(); r.isPlaying;    // Autoplay
r.zoomIn(); r.zoomOut(); r.resetZoom();
r.setZoom(2.5, x, y);                // Zoom, Fixpunkt in Bühnen-Pixeln
r.fullscreen(); r.exitFullscreen(); r.toggleFullscreen(); r.isFullscreen;
r.openDetail(poiOrId); r.closeDetail(); r.isDetailOpen;
r.frame; r.row; r.zoom;              // aktueller Zustand
r.destroy();

Rotate360.init();                    // alle .rotate360 nachträglich (idempotent)
element._rotate360;                  // Instanz-Backref
$('.rotate360').rotate360({ … });    // jQuery-Bridge, falls jQuery geladen

Events

Alle Events sind CustomEvents am Host, bubbeln und tragen detail.instance.

Buttons

Die Leiste bringt acht Icons als PNG mit (Base64, in rotate360.js). Sie werden als CSS-Maske gezeichnet, die Farbe kommt aus --r360-btn-fg. Wer eigene Buttons außerhalb des Widgets bauen will, setzt data-rotate-controls="false" und ruft die API auf - so wie in Demo 4. Die Icons stehen unter Rotate360.ICONS auch für eigene Buttons bereit.

Größe und Responsive

Die Breite kommt immer vom umgebenden CSS. Die Höhe folgt dem Seitenverhältnis des ersten Bildes; --r360-aspect setzt stattdessen ein festes Verhältnis. Eine height direkt am Host wirkt nicht - der Host schneidet dann nur unten ab, weil die Bühne ihre Seitenverhältnis-Höhe behält. Dafür gibt es zwei eigene Tokens:

/* Deckel: Breite bleibt fluid, Höhe wird begrenzt, Bild wird eingepasst */
.rotate360.produkt { --r360-max-height: 70dvh; }

/* feste Höhe: das Seitenverhältnis fällt weg */
.rotate360.karte   { --r360-height: 320px; }

/* Höhe kommt vom Host (Grid-/Flex-Zelle, Modal, Splitview) */
.viewer-zelle { height: 100%; }
.viewer-zelle .rotate360 { height: 100%; --r360-height: 100%; }

Das Bild wird in jedem Fall per contain in die Bühne gelegt - freie Fläche zeigt --r360-bg, genau wie im Vollbild. POIs, Sprechblasen und der Zoom-Ausschnitt rechnen sich über einen ResizeObserver sofort neu, auch in Tabs und Accordions. dvh ist vh vorzuziehen, sonst springt die Höhe auf iOS beim Ein- und Ausblenden der Browserleiste.

Wer den Viewer schmal werden lässt, sollte auch das Ziehen mitskalieren: data-rotate-sensitivity ist ein absoluter Pixelwert, ein auf dem Desktop eingestellter Wert lässt einen auf dem Handy also mehrfach absetzen und neu wischen. data-rotate-sweep="1" rechnet den Mausweg stattdessen relativ zur Bühne (einmal quer = eine Umdrehung) und fühlt sich auf jeder Größe gleich an; data-rotate-sensitivity-ref ist der Weg für Seiten, die ihren absoluten Wert behalten wollen. Beides lässt sich in der Spielwiese zusammen mit der Viewer-Breite ausprobieren.

Anpassen per CSS-Variablen

Das Painting ist gekapselt; angepasst wird ausschließlich über die --r360-*-Tokens am Host:

.rotate360.mein-viewer {
  --r360-bg: #fff;
  --r360-radius: 12px;
  --r360-aspect: 4 / 3;           /* statt Bild-Seitenverhältnis */
  --r360-max-height: 70dvh;       /* Höhendeckel, Bild wird eingepasst */
  /* --r360-height: 320px; */     /* feste Höhe statt Seitenverhältnis */
  --r360-btn-bg: rgba(0,0,0,.6);
  --r360-btn-fg: #fff;
  --r360-btn-opacity: 0.4;        /* erst bei Hover voll sichtbar */
  --r360-poi-bg: #ff5500;
  --r360-loader-color: #ff5500;

  /* Hotspots */
  --r360-leader-color: rgba(0,0,0,.55);  --r360-leader-width: 1.5px;  --r360-leader-dash: none;
  --r360-callout-bg: #fff;  --r360-callout-fg: #222;  --r360-callout-width: 240px;
  --r360-callout-radius: 6px;  --r360-callout-size: .85rem;  --r360-callout-link: #c0392b;
  --r360-callout-border: 1px solid rgba(0,0,0,.12);  --r360-callout-shadow: 0 2px 12px rgba(0,0,0,.18);
  --r360-callout-padding: .6em .85em;
  --r360-callout-detail-fg: #c0392b;  --r360-callout-detail-size: .92em;   /* Button „Detailbild" */
  --r360-callout-pinned-shadow: 0 0 0 2px rgba(59,130,246,.5);           /* angeheftet, optional */

  /* Detailbild */
  --r360-detail-bg: rgba(18,18,20,.94);
  --r360-detail-caption-bg: rgba(0,0,0,.55);  --r360-detail-caption-fg: #fff;  --r360-detail-caption-size: .9rem;
}

Alle Tokens mit Defaults stehen in rotate360.css; die Hotspot- und Detail-Tokens haben zusätzlich Fallbacks in der Library, funktionieren also auch mit einer älteren rotate360.css.

Editor

Der Tab Editor baut die Konfiguration, ohne dass JSON von Hand geschrieben werden muss. Der Arbeitsablauf: Bilder hineinziehen (oder „Bilder per URL"), die Reihenfolge im Filmstreifen prüfen, im großen Bild POIs setzen, ihnen einen Hotspot geben und sie mit „→ nächstes Bild" bzw. „Bereich" über die Frames mitführen. JSON und HTML-Schnipsel entstehen dabei live, die Vorschau darunter ist die echte Library. Der Knopf Rundgang zeigt das einmal an einem Beispiel; Hinweise setzt Nummern an die Bedienelemente zum Nachschlagen.

• Im großen Bild: Klick setzt einen POI, Marker und Sprechblasen lassen sich ziehen. Rechtsklick (Touch: lange drücken) öffnet ein Menü mit Beschriftung, Hotspot-Zuweisung, Kopieren und Löschen.
• Tasten: ← → wechseln das Bild, N / P kopieren den gewählten POI ins nächste bzw. vorherige Bild, H legt ihm einen Hotspot an, Entf löscht ihn, O schaltet Onion-Skin, Strg+Z / Strg+Y machen rückgängig bzw. wiederholen.
• Speicherung: Bilder und Stand bleiben in diesem Browser (IndexedDB) und überleben einen Reload; nach 24 Stunden ohne Besuch werden sie verworfen. Behalten wird, was man herunterlädt: JSON bzw. ZIP.
• Rundgang und eigener Stand: Der Rundgang arbeitet an einem Beispiel und legt den eigenen Stand so lange beiseite - nichts davon wird gespeichert. War der Editor vorher leer, lässt sich das Beispiel am Ende behalten.

Hinweise

• Bildserien: alle Frames einer Serie brauchen dieselbe Pixelgröße. Das Seitenverhältnis wird vom ersten geladenen Bild übernommen.
• Kein Sprite-Sheet: bewusst weggelassen. Einzelbilder lassen sich lazy laden, cachen und beliebig groß zoomen, ohne Textur-Limits zu reißen.
• Shadow DOM: Interna liegen in el.shadowRoot; für delegierte Listener am Host das echte Ziel über Rotate360.realTarget(e) ermitteln.
• Reduced Motion: die Puls-Animation der POI-Marker wird bei prefers-reduced-motion abgeschaltet.
• Höhe: eine height am Host bleibt wirkungslos; dafür sind --r360-height und --r360-max-height da (siehe Größe und Responsive).
• Versteckte Container: ein ResizeObserver misst den Bildrahmen neu, sobald das Element sichtbar wird (Tabs, Accordions, Modals).
• Produktseiten: eine Liste der Hotspots außerhalb des Viewers, die per goToPoi() das Objekt hindreht, ist mit wenigen Zeilen gebaut - siehe Demo 3.
• Esc im echten Vollbild: dort beendet der Browser zuerst das Vollbild; das Detailbild bleibt offen und schließt mit dem nächsten Esc.