Getting Started

• Install Photo Sphere Viewer
• Dependencies
• Your first viewer

New version

Photo Sphere Viewer 4 is not compatible with previous versions. If you are using version 3 , please follow the migration guide. You can also read the version 3 documentation.

Install Photo Sphere Viewer

With npm or yarn

npm install photo-sphere-viewer

yarn add photo-sphere-viewer

Via CDN

Photo Sphere Viewer is available on jsDelivr

Manually

You can also download the latest release

Dependencies

Required

• three.js (use build/three.min.js file)
• uEvent 2 (use browser.js file)

Optionals

• promise-polyfill for IE compatibility (use dist/polyfill.min.js file)

Your first viewer

Include all JS & CSS files in your page manually or with your favorite bundler and init the viewer.

The panorama must be an equirectangular projection of your photo. You can also use cubemap projection with a special syntax.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/photo-sphere-viewer@4/dist/photo-sphere-viewer.min.css"/>

<script src="https://cdn.jsdelivr.net/npm/three/build/three.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/uevent@2/browser.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/photo-sphere-viewer@4/dist/photo-sphere-viewer.min.js"></script>

<div id="viewer"></div>

<style>
  /* the viewer container must have a defined size */
  #viewer {
    width: 100vw;
    height: 50vh;
  }
</style>

<script>
  var viewer = new PhotoSphereViewer.Viewer({
    container: document.querySelector('#viewer'),
    panorama: 'path/to/panorama.jpg'
  });
</script>

Import photo-sphere-viewer/dist/photo-sphere-viewer.css with the prefered way depending on your tooling.

<div id="viewer"></div>

<style>
  /* the viewer container must have a defined size */
  #viewer {
    width: 100vw;
    height: 50vh;
  }
</style>

import { Viewer } from 'photo-sphere-viewer';

const viewer = new Viewer({
  container: document.querySelector('#viewer'),
  panorama: 'path/to/panorama.jpg'
});

---

Cropped panoramas

If your image is not covering a full 360°×180° sphere, it will be deformed. You can fix it by providing cropping data.

Caching

Previous version of Photo Sphere Viewer had a caching system, which was buggy and thus disabled by default.

Photo Sphere Viewer 4 uses THREE.js Cache, enabled by default. You can disable this cache by calling THREE.Cache.enabled = false; after importing Photo Sphere Viewer.