Cloudimage 360 View

2D Grid Mode is used for products photographed at multiple horizontal and vertical angles. It is automatically detected when you provide filenameGrid or imageListGrid. In this mode, dragging diagonally updates both axes simultaneously.

Using a filename pattern

Use filenameGrid with {indexX} and {indexY} placeholders (1-based indices). You can use indexZeroBase to specify zero-padding (e.g., 3 for 001). Use stopAtEdgesX or stopAtEdgesY to prevent looping on a specific axis.

Using an explicit image list

Alternatively, provide a flat array of image strings via imageListGrid. The images should be ordered by row (all X frames for the first Y angle, then all X frames for the second Y angle, etc.).

// Example: Filename pattern
CI360.init(document.getElementById('viewer'), {
  folder: 'https://your-domain.com/images/',
  filenameGrid: 'product_{indexY}_{indexX}.jpg',
  amountX: 24,        // horizontal angles
  amountY: 4,         // vertical angles
  indexZeroBase: 3,    // zero-pad to 3 digits: 001, 002, ...
  stopAtEdgesY: true,  // prevent Y from looping
});

// Example: Explicit image list
CI360.init(document.getElementById('viewer'), {
  imageListGrid: [
    // y=0 row (all X frames at first vertical angle)
    'img_001_001.jpg', 'img_001_002.jpg', /* ... */
    // y=1 row
    'img_002_001.jpg', 'img_002_002.jpg', /* ... */
  ],
  amountX: 24,
  amountY: 4,
});

Mobile browsers have strict memory limits. While the library automatically enables several optimizations for mobile (sequential loading, main-thread canvas rendering, reduced touch rate, capped pixel ratio, and automatic memory management), you should manually adjust your configuration for the best experience.

Recommended Mobile Settings

• amountX: Limit to 30-40 frames (Desktop can handle 60-100+).
• zoomMax: Limit to 2-3 (Desktop can handle 3-5).

Manual Memory Management

You can manually control the IntersectionObserver based memory management (which releases memory when viewers are off-screen or the page is backgrounded) using:

• viewer.enableMemoryManagement()
• viewer.disableMemoryManagement()

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
  zoomMax: isMobile ? 2 : 5,             // Lower zoom on mobile
});

Upgrading to v4 involves several breaking changes in CSS, initialization, and configuration.

1. CSS Handling

• CDN users: CSS is auto-injected.
• npm/bundler users: You must now import CSS explicitly: import '@cloudimage/360-view/css';

2. Initialization API

Switch from the global window.CI360 methods to the instance-based new CI360() pattern.

3. Deprecated Options Mapping

4. Hotspot Configuration

Hotspots no longer use individual properties like title or description. Instead, use the content property to provide flexible HTML.

v4 Hotspot Example:

const hotspot = {
  id: 'feature-1',
  orientation: 'x',
  containerSize: [1200, 800],
  positions: { 0: { x: 100, y: 200 } },
  content: `
    <div class="my-tooltip">
      <h3 class="title">Feature Title</h3>
      <p>Description text</p>
      <a href="https://example.com" target="_blank">Learn More</a>
    </div>
  `,
  onClick: () => console.log('Clicked!'),
};

Hotspots allow you to add interactive markers to highlight specific product features. You define an array of hotspot objects and pass it to the hotspots key in your configuration.

Key behaviors:

• Positioning: Use containerSize (e.g., [1200, 800]) to provide reference dimensions for pixel-based positions. If omitted, positions are treated as percentages (0-100) of the image area.
• Frame Mapping: The positions object maps frame indices to { x, y } coordinates. Setting a coordinate to null causes it to inherit the value from the previous frame.
• Interactivity: You can provide HTML content for a tooltip and an onClick handler.

const hotspots = [
  {
    id: 'feature-1',
    orientation: 'x',
    containerSize: [1200, 800], // Reference container size for positioning
    positions: {
      0: { x: 500, y: 300 },
      1: { x: 520, y: 300 },
      2: { x: 540, y: null }, // null inherits from previous frame
      3: { x: 560, y: null },
      // ... positions for frames where hotspot is visible
    },
    content: '<div class="tooltip"><strong>Premium Feature</strong><p>Description here</p></div>',
    onClick: () => {
      console.log('Hotspot clicked!');
    },
  },
];

const config = {
  folder: 'https://example.com/images/',
  filenameX: '{index}.jpg',
  amountX: 36,
  hotspots: hotspots,
};