js-cloudimage-360-view 4.1.4 → 4.3.0

package/README.md

@@ -443,6 +443,7 @@ All options can be set via JavaScript config or HTML data attributes.
 | `lazyload` | `data-lazyload` | `true` | Enable lazy loading |
 | `hints` | `data-hints` | `true` | Show interaction hints on load |
 | `theme` | `data-theme` | `null` | Color theme: `'light'` or `'dark'` |
+| `hotspotTrigger` | `data-hotspot-trigger` | `'hover'` | Hotspot trigger mode: `'hover'` or `'click'` |
 | `hotspotTimelineOnClick` | `data-hotspot-timeline-on-click` | `true` | Show hotspot popup when clicking timeline dot |
 
 ### Cloudimage CDN Options
@@ -842,14 +843,31 @@ viewer.updateView('my-viewer', { speed: 50, autoplay: true });
 ```javascript
 const view = viewer.getViewById('my-viewer');
 
-// Programmatically rotate the view
-view.onMoveHandler('right', 1, 0); // Move right by 1 frame
-view.onMoveHandler('left', 5, 0);  // Move left by 5 frames
-view.onMoveHandler('up', 0, 1);    // Move up by 1 frame (Y-axis)
-view.onMoveHandler('down', 0, 1);  // Move down by 1 frame (Y-axis)
+// Playback control
+view.play();                    // Start autoplay
+view.stopAutoplay();            // Stop autoplay
 
-// Destroy the viewer
-view.destroy();
+// Rotation (stopAtEdges: boolean, steps: number)
+view.moveLeft(false, 5);        // Rotate left by 5 frames
+view.moveRight(false, 5);       // Rotate right by 5 frames
+view.moveTop(false, 1);         // Rotate up by 1 frame (Y-axis)
+view.moveBottom(false, 1);      // Rotate down by 1 frame (Y-axis)
+
+// Navigation
+view.animateToFrame(36);        // Animate to frame 36
+view.animateToFrame(10, 'hotspot-1'); // Go to frame and show hotspot
+
+// UI control
+view.hideAllIcons();            // Hide all overlay icons
+
+// State
+view.activeImageX;              // Current X-axis frame (0-indexed)
+view.activeImageY;              // Current Y-axis frame (0-indexed)
+view.amountX;                   // Total X-axis frames
+view.amountY;                   // Total Y-axis frames
+
+// Cleanup
+view.destroy();                 // Destroy the viewer
 ```
 
 ---
@@ -897,6 +915,67 @@ const config = {
 
 ---
 
+## Mobile Considerations
+
+### Memory Limitations
+
+Mobile browsers (especially Safari) have strict memory limits that can cause tab crashes when loading many high-resolution images. The library includes built-in optimizations for mobile that are **automatically enabled**:
+
+- **Sequential image loading** (3 concurrent on mobile vs 6 on desktop)
+- **Main-thread canvas rendering** (avoids OffscreenCanvas memory issues on Safari)
+- **Reduced touch event rate** (30fps vs 100fps on desktop)
+- **Capped device pixel ratio** (max 2x on mobile)
+- **Automatic memory management** (releases off-screen viewers, frees memory when page backgrounded)
+
+### Recommended Settings for Mobile
+
+| Setting | Desktop | Mobile | Notes |
+|---------|---------|--------|-------|
+| `amountX` | 60-100+ | 30-40 max | Each image uses ~4MB GPU memory |
+| `pointerZoom` | ✅ | ❌ | Loads higher-res images |
+| `magnifier` | ✅ | ❌ | Loads higher-res images |
+
+### Detecting Mobile Devices
+
+The library automatically detects mobile devices, but you can also adjust your configuration:
+
+```javascript
+const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(
+  navigator.userAgent
+);
+
+const viewer = new CI360();
+viewer.init(container, {
+  folder: 'https://example.com/images/',
+  filenameX: '{index}.jpg',
+  amountX: isMobile ? 36 : 72,           // Fewer images on mobile
+  pointerZoom: isMobile ? false : 2,     // Disable zoom on mobile
+  magnifier: isMobile ? false : 3,       // Disable magnifier on mobile
+});
+```
+
+### Memory Management API
+
+Memory management is **automatically enabled on mobile**. For desktop or manual control:
+
+```javascript
+const viewer = new CI360();
+viewer.initAll();
+
+// Manually enable (already auto-enabled on mobile)
+viewer.enableMemoryManagement();
+
+// Disable if needed
+viewer.disableMemoryManagement();
+```
+
+This uses IntersectionObserver to:
+- Release memory when viewers scroll off-screen
+- Reload images when viewers become visible again
+- Release all viewer memory when the page is backgrounded
+
+---
+
 ## Migration Guide (v3 → v4)
 
 Version 4 introduces significant improvements in performance, customization, and developer experience. This guide helps you upgrade from v3.