360 Image Player

A framework-agnostic equirectangular image player built with Three.js, TypeScript, and Vite.

Features

• Mouse, touch, pinch, inertia, zoom controls, compass, and WebXR.
• Runtime color filters and configurable nadir covers.
• Typed hotspots for links, quizzes, clues, locked content, and products.
• Branded and MLS-friendly unbranded rendering modes.
• Local canvas snapshots and high-resolution server snapshot requests.
• Serializable player state and ZIP export for offline self-hosting.
• React wrapper with typed callbacks.
• GPL-3.0 licensed.

Hosting your source media

This player renders whatever equirectangular image URL you give it — you still need somewhere to upload, store, and serve the actual panorama files. Mirame360 is a free 360° photo/video hosting platform built by the same team: upload once, get optimized web-ready URLs and secure embeds, and drop them straight into this player (or use the Mirame360 WordPress plugin if your site runs WordPress).

Installation

npm install 360-image-player three

React is an optional peer dependency.

Basic Usage

import { Image360Player } from '360-image-player';

const player = new Image360Player({
  container: document.getElementById('viewer')!,
  imageUrl: [
    'https://example.com/panorama.webp',
    'https://example.com/panorama.jpeg',
  ],
  showControls: true,
  compass: true,
  initialView: { yaw: 20, pitch: 0, hfov: 80 },
  nadir: {
    imageUrl: 'https://example.com/logo.png',
    radius: 55,
  },
});

player.addHTMLOverlay({
  id: 'product-1',
  type: 'product',
  yaw: 45,
  pitch: 5,
  product: {
    id: 'chair-1',
    title: 'Chair',
    price: '$99',
    vendor: 'shopify',
  },
});

player.on('addtocart', ({ product }) => {
  // Delegate the actual cart mutation to Shopify, PrestaShop, or the host app.
  console.log(product);
});

imageUrl accepts either one URL or an ordered list. When a source cannot be loaded or decoded, the player tries the next URL and emits error only after all configured sources have failed. Existing integrations using a string do not need to change.

Viewport And Snapshots

player.setView({ yaw: 30, pitch: -5, hfov: 70 });
const viewport = player.getView();

// Optional low-cost motion for visible previews.
player.startAutoRotate(2);
player.setRenderingActive(false); // suspend GPU work while offscreen
player.setRenderingActive(true);
player.stopAutoRotate();

// Browser-resolution PNG from the current canvas.
const localBlob = await player.takeSnapshot();

// High-resolution image generated by the Mirame360 backend.
const result = await player.requestSnapshot({
  endpoint: `/api/media/${mediaId}/snapshot/`,
  width: 4096,
  height: 2304,
  format: 'jpeg',
  headers: { Authorization: `Bearer ${token}` },
});

The backend endpoint queues an FFmpeg v360 task and the player polls its authenticated status URL until the generated storage URL is available.

Gamification

player.addHTMLOverlay({
  id: 'question-1',
  type: 'quiz',
  yaw: 10,
  pitch: 0,
  title: 'Which door is correct?',
  quizChoices: [
    { id: 'left', label: 'Left' },
    { id: 'right', label: 'Right', correct: true },
  ],
  unlocks: ['exit-door'],
});

player.addHTMLOverlay({
  id: 'exit-door',
  type: 'locked',
  yaw: 90,
  pitch: 0,
  requires: ['exit-door'],
  text: 'Exit',
});

player.setGameState(savedState);
const stateToPersist = player.getGameState();

Branding And Security

Use brandingMode: 'unbranded' to hide hotspots unless they explicitly set branded: false. External URL opening can also be disabled with allowExternalLinks: false.

Custom hotspot HTML is sanitized by default. Supply sanitizeHTML to integrate a stricter application sanitizer.

Offline Export

const zip = await player.exportOffline({
  playerScriptUrl: '/assets/360-image-player.standalone.umd.min.js',
  fetchAssets: true,
});

The ZIP contains the standalone player, panorama, optional nadir image, config.json, and a ready-to-host index.html. Remote assets must allow CORS.

Main Options

| Option | Default | Description | | --- | --- | --- | | imageUrl | required | Panorama URL or ordered list of primary and fallback URLs. | | autoLoad | true | Load the panorama immediately. | | showControls | true | Render zoom and reset controls. | | compass | false | Render a heading compass. | | initialView | { yaw: 0, pitch: 0, hfov: 90 } | Initial viewport. | | brandingMode | branded | Hide branded content in unbranded mode. | | allowExternalLinks | true | Allow URL hotspots to open new pages. | | nadir | none | Circular nadir image configuration. | | snapshotEndpoint | none | Default high-resolution snapshot endpoint. | | colorFilters | neutral | WebGL color adjustments. |

Development

• npm run build
• npm run lint
• npm run typecheck
• npm run test:unit