Photo Sphere Viewer (PSV) Deep-Dive: Building Production-Grade 360° Experiences on the Web

Photo Sphere Viewer (PSV) is a modern JavaScript library for rendering 360°/VR panoramas and videos directly in the browser. It is powered by Three.js/WebGL, offers a clean plugin architecture (markers, map/plan, virtual tours, compass, etc.), and ships as modular NPM packages (core, adapters, plugins) under the MIT license. (Photo Sphere Viewer, npm)

Below, you’ll find a hands-on technical guide that covers architecture, data formats, APIs, plugins, framework integration (including SPFx), performance tips, and a market comparison versus Pannellum, Marzipano and A-Frame.

1) What PSV Is (and Isn’t)

• Core purpose. A viewer for equirectangular and cubemap panoramas; it also supports 360° videos. (Photo Sphere Viewer, Photo Sphere Viewer)
• Modular design. The @photo-sphere-viewer/core package provides the viewer; adapters (equirectangular, cubemap, etc.) and plugins (markers, compass, plan, map, virtual tour, …) are optional. (Photo Sphere Viewer)
• License & versions. Distributed under MIT; the core package is actively maintained (e.g., 5.13.x in 2025). (npm)

Useful background: WebGL, Three.js, Equirectangular projection, Cubemap.

2) System Architecture (Three.js under the hood)

PSV wraps a Three.js renderer and scene graph. You provide a panorama (image or video) and an adapter that knows how to map it to geometry (sphere for equirectangular, cube for cubemaps). The viewer exposes a rich event/method surface and can be extended via plugins that receive full access to internal APIs and the Three.js renderer. (Photo Sphere Viewer)

Rendering pipeline (high level)

1. Adapter prepares geometry + material (texture from image/video).
2. Core viewer mounts a <canvas> and orchestrates controls (drag, zoom, inertia).
3. Plugins hook into lifecycle (init, render, user events) to add UI and logic. (Photo Sphere Viewer)

3) Data Formats & Adapters

• Equirectangular (common 360×180 PNG/JPG): simple, one texture.
• Cubemap (6 faces): improved sampling at poles, useful for certain pipelines and video.
  Adapters are provided as @photo-sphere-viewer/***-adapter packages and selected via the adapter option. (Photo Sphere Viewer)

Concept links: Equirectangular projection, Cube mapping.

4) Install & Minimal Code

Install (NPM/CDN).
npm i @photo-sphere-viewer/core (plus your adapter and any plugins). A CDN option is available in the docs. (Photo Sphere Viewer)

Hello, PSV (equirectangular).

<div id="viewer" style="width:100%;height:500px"></div>
<script type="module">
  import { Viewer } from '@photo-sphere-viewer/core';
  import { EquirectangularAdapter } from '@photo-sphere-viewer/equirectangular-adapter';

  const viewer = new Viewer({
    container: document.getElementById('viewer'),
    adapter: EquirectangularAdapter,
    panorama: '/assets/panos/plant-room-01.jpg',
    defaultYaw: '90deg', // see “Angles” below
    navbar: ['zoom', 'fullscreen'],
  });
</script>

Angles. PSV accepts angles in radians or degrees with the 'deg' suffix (e.g., '55deg'). (Photo Sphere Viewer)

5) Core API: Options, Methods, Events

PSV exposes:

• Options: FOV range, yaw/pitch defaults, mouse/touch inertia, navbar items, renderer parameters.
• Methods: programmatic zoom/pan, go to marker, screenshot, toggle controls/panorama changes.
• Events: camera updates, interactions (click, dblclick), marker hover/leave, plugin events.
  See the docs’ “Configuration” and “Guide” sections for concrete signatures. (Photo Sphere Viewer)

6) Official Plugins (Why the Ecosystem Matters)

PSV’s plugin model keeps the core lean and lets you opt into features:

• Markers Plugin. Add labels/icons/images/videos with interactivity; includes navbar buttons (markers, markersList). Great for digital twins, plant walk-throughs, or map pin-drops. (Photo Sphere Viewer)
• Map/Plan/Compass Plugins. Overlay a 2D map or blueprint, show camera heading, and sync with markers for spatial context. (Photo Sphere Viewer)
• VirtualTourPlugin. Define a graph of “nodes” (panoramas) and directional links (manual or GPS-based) to build multi-scene tours; integrates nicely with Gallery/Map/Plan/Compass. (Photo Sphere Viewer)
• Panel Component. Add a right-side HTML panel (e.g., metadata, SOPs, or checklist UI). (Photo Sphere Viewer)

7) Video Support

PSV can render 360° video in equirectangular or cubemap layouts. You configure the same way as images but pass a video source to the adapter; see the demo pages for concrete examples. (Photo Sphere Viewer)

Concept links: Equirectangular projection, Cube mapping.

8) Input & Interaction: Mobile, Sensors, VR-like UX

Out of the box: mouse/touch gestures, double-click zoom, keyboard actions, fullscreen, and optional device orientation/gyroscope on supported devices—useful for phone/tablet “window into the scene” behavior. See the Demos section for concrete recipes like custom navbar items or screenshots. (Photo Sphere Viewer)

9) Framework Integration (React, Angular, SPFx)

• React. You can wrap the viewer in a component or use community bindings such as react-photo-sphere-viewer (mind plugin compatibility details). (npm)
• Angular. Install @photo-sphere-viewer/core and three, then instantiate in ngAfterViewInit targeting a ViewChild container. (Stack Overflow)
• SharePoint Framework (SPFx).
  • Add packages to the web part project and import Viewer + adapters inside your component.
  • Mount into a dedicated DOM node in render(), dispose on onDispose().
  • If you ship assets inside the package, load them via webpack’s asset pipeline; for tenant assets, store in a CDN or Site Assets and resolve absolute URLs before passing to panorama.
  • Use the Markers and Panel plugins to show live process tags, maintenance procedures, or links to lists/pages.

10) Performance & Quality Tips

• Pick the right format. Equirectangular (simple, single texture) vs. cubemap (more uniform sampling near poles). (Photo Sphere Viewer)
• Texture sizing. Keep source textures sized for your target devices to avoid GPU memory spikes (e.g., cap to 8K/16K depending on device class and scene detail).
• Lazy initialization. Defer creating viewers until visible; teardown on navigation to free GPU/CPU.
• Markers & UI. Prefer vector/texture-atlas icons; batch updates when adding many markers.
• Video. Use browser-friendly codecs, enable playsinline on iOS, and test energy impact.

(PSV does not market itself as a multi-resolution/tiled engine; if you need deep zoom over gigapixel imagery, benchmark against alternatives below.)

11) Security & Compliance

• License: MIT for the library; docs under CC BY 3.0. Ensure your own assets are licensed appropriately. (Photo Sphere Viewer)
• Privacy: If you record device orientation, treat it as telemetry; comply with local privacy policies.
• Accessibility: Provide keyboard actions and alt/UI affordances for critical interactions.

12) Market Landscape: Where PSV Fits

Interpretation.

• Choose PSV when you want a focused, production-ready 360° viewer with first-class markers, map/plan overlays, and a guided multi-scene Virtual Tour plugin. (Photo Sphere Viewer)
• Choose Pannellum for lightweight deployments or where multi-resolution is important out of the box. (pannellum.org)
• Choose Marzipano for a free toolchain that exports a complete tour site and provides low-level control. (marzipano.net)
• Choose A-Frame if you need full 3D/VR scenes beyond panoramas. (A-Frame)

13) Practical Recipes

A) Markers with custom tooltip and click

Use the MarkersPlugin to overlay pins, labels, or polygons; subscribe to marker events to open side panels or navigate to another node in a virtual tour. (Photo Sphere Viewer)

B) Multi-scene Virtual Tour

Define a node list with links (manual or GPS). Integrate Gallery/Map/Plan/Compass for context and navigation. (Photo Sphere Viewer)

C) “Engineering Twin” Overlay

Combine Markers (equipment IDs), Plan (floor blueprint), and Panel (SOP markdown) to build an interactive plant walkthrough without leaving the panorama viewer. (Photo Sphere Viewer)

14) Troubleshooting Notes

• Black canvas / nothing renders. Check the adapter import and that the source path resolves (CORS for remote assets).
• iOS video autoplay. Use muted + playsinline and handle user gesture requirements.
• Angular/React teardown. Call dispose/unmount to release GPU resources.
• Markers not showing in navbar. Add markers/markersList to your custom navbar; the plugin only injects buttons into the default navbar. (Photo Sphere Viewer)

15) Key Documentation Waypoints

• Getting Started (installation, playground). (Photo Sphere Viewer)
• Configuration (angles, standard options). (Photo Sphere Viewer)
• Demos (zoom, keyboard, screenshots, compass/map/plan). (Photo Sphere Viewer)
• Plugins (intro + per-plugin pages). (Photo Sphere Viewer)
• Adapters (how to choose/import Equirectangular or Cubemap). (Photo Sphere Viewer)
• License & packages (MIT; @photo-sphere-viewer/core). (npm)

Concept links for your glossary:
Panorama, Field of view, Gyroscope, Virtual tour.

Summary Table