Presentation

Photo Sphere Viewer is a JavaScript library which renders 360° panoramas shots with Photo Sphere, the new camera mode of Android 4.2 Jelly Bean and above. It also supports cube panoramas.

Photo Sphere Viewer is pure JS and based on Three.js, allowing very good performances on WebGL enabled systems (most recent browsers) and reasonably good performances on other systems supporting HTML Canvas.

And it works with touch screens too !

Getting started

Dependencies

• three.js >= 0.97 + examples files
• doT.js
• uEvent 1 (version 2 is not supported)
• promise-polyfill for IE compatibility

Let's go!

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

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

<style>
  #viewer {
    width: 100vw;
    height: 50vh;
  }
</style>

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

Usage

Options

Name	type	default	description
container	HTMLElement String	required	HTML element which will contain the panorama, or identifier of the element.
panorama	String String[] Object<String, String>	required	Path to the panorama image(s). It must be a single string for equirectangular panoramas and an array or an object for cubemaps. More Equirectangular panorama : panorama: 'path/to/panorama.jpg' Cubemap as array : panorama: [ 'path/to/left.jpg', 'path/to/front.jpg', 'path/to/right.jpg', 'path/to/back.jpg', 'path/to/top.jpg', 'path/to/bottom.jpg' ] Cubemap as object : panorama: { left: 'path/to/left.jpg', front: 'path/to/front.jpg', right: 'path/to/right.jpg', back: 'path/to/back.jpg', top: 'path/to/top.jpg', bottom: 'path/to/bottom.jpg' }
caption	String	null	A text (can contain HTML) displayed in the navbar. If the navbar is disabled it will be shown anyway but with no button.
markers	Array	[]	List of markers.
min_fov	integer	30	Minimal field of view (corresponds to max zoom), between 1 and 179.
max_fov	integer	90	Maximal field of view (corresponds to min zoom), between 1 and 179.
default_fov	integer	max_fov	Initial field of view, between min_fov and max_fov.
fisheye	boolean|integer	false	Enable fisheye effect with true or specify effect strength (true = 1.0). This mode can have side-effects on markers rendering.
default_long	double	0	Initial longitude, between 0 and 2π.
default_lat	double	0	Initial latitude, between -π/2 and π/2.
sphere_correction	object	{pan:0, tilt:0, roll: 0}	Sphere rotation angles, in radians. More
longitude_range	double[]		Viewable longitude range. Examples: [0, Math.PI], [-3*Math.PI/4, 3*Math.PI/4].
latitude_range	double[]	[π/2, -π/2]	Viewable latitude range.
time_anim	integer boolean	2000	Idle time (milliseconds) before the panorama automatically starts rotating. false to deactivate.
anim_speed	string	'2rpm'	Automatic rotation speed in radians/degrees/revolutions per second/minute. More Different units are possible for the anim_speed parameter : rpm revolutions per minute rps revolutions per second dpm degrees per minute dps degrees per second radians per minute radians per second
anim_lat	double	default_lat	Latitude at which the automatic rotation is performed.
navbar	boolean|array		Enable or disable the navigation bar, you can also choose which buttons are displayed and even add custom buttons. See below.
lang	Object	View lang: { autorotate: 'Automatic rotation', zoom: 'Zoom', zoomOut: 'Zoom out', zoomIn: 'Zoom in', download: 'Download', fullscreen: 'Fullscreen', markers: 'Markers', gyroscope: 'Gyroscope', stereo: 'Stereo view', stereo_notification: 'Click anywhere to exit stereo view.', please_rotate: ['Please rotate your device', '(or tap to continue)'], two_fingers: ['Use two fingers to navigate'] }	Text of navbar buttons tooltips.
loading_img	String	null	Path to an image displayed in the center of the loading circle.
loading_txt	String	'Loading...'	Text displayed in the center of the loading circle, only if loading_img is not provided.
mousewheel	boolean	true	Enables zoom with the mouse wheel.
mousemove	boolean	true	Enables panorama rotation with the mouse cursor.
mousemove_hover	boolean	false	Rotate the panorama just by moving the cursor above the view instead of click+move.
touchmove_two_fingers	boolean	false	Requires two fingers to rotate the panorama. This allows standard touch-scroll navigation in the page containing the viewer. If enabled, an overlay asking the user to use two fingers is displayed when only one touch is detected.
keyboard	Object | boolean	View keyboard: { 'ArrowUp': 'rotateLatitudeUp', 'ArrowDown': 'rotateLatitudeDown', 'ArrowRight': 'rotateLongitudeRight', 'ArrowLeft': 'rotateLongitudeLeft', 'PageUp': 'zoomIn', 'PageDown': 'zoomOut', '+': 'zoomIn', '-': 'zoomOut', ' ': 'toggleAutorotate' }	Enable and configure keyboard navigation in fullscreen. It is a map defining key code->action. Set to false to disable.
size	Object	null	The final size if the panorama container (e.g. {width: 500, height: 300}. By default the size of container is used and is followed during window resizes.
transition	Object	View transition: { duration: 1500, // duration of transition in milliseconds loader: true // should display the loader ? }	Configuration of the transition effect between panoramas.
with_credentials	boolean	false	Set to true to use credentials for HTTP requests.

Advanced options

pano_data: {
  full_width: 6000,
  full_height: 3000,
  cropped_width: 4000,
  cropped_height: 2000,
  cropped_x: 1000,
  cropped_y: 500
}

tooltip: {
    offset: 5,
    arrow_size: 7,
    delay: 100
}

Methods

All useful methods are documented in the API documentation

To call a method you need to keep a reference to the viewer (created with new keyword). It's good practice to wait for the ready event before doing anything.

viewer.on('ready', function() {
  viewer.rotate({
    x: 1500,
    y: 1000
  });
});

Events

On the viewer you can also use the on method to listen to various events.

Navbar customization

navbar is an array which can contain the following core buttons: autorotate, zoom, download, markers, gyroscope, stereo, fullscreen, as well as caption and objects to create custom buttons :

This example uses some core buttons and a custom one.

new PhotoSphereViewer({
  container: 'container-id',
  panorama: 'path/to/panorama.jpg',
  navbar: [
    'autorotate',
    'zoom',
    'markers',
    {
      id: 'my-button',
      title: 'Hello world',
      className: 'custom-button',
      content: 'Custom',
      onClick: function() {
        alert('Hello from custom button');
      }
    },
    'caption',
    'fullscreen'
  ]
});

Altering the buttons

After the viewer creation you cannot add or remove buttons but you can change their visibility. Use the getNavbarButton(id) method the get a button by its id (works for core buttons too). You will get an object with the following methods: disable(), enable(), hide(), show().

viewer.getNavbarButton('my-button').hide();