Photo Sphere Viewer
Compiled and minified files with examples and sources.Download
You can also get all necessary files and dependencies with Bower.
You can also get all necessary files and dependencies with npm.
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 !
Include all JS & CSS files in your page and you are ready.
PSV can also be used with CommonJS :
In order to get Photo Sphere Viewer working on browsers without WebGL you will need some additional files from
Three.js examples (also available in
three.js-examples Bower package) :
In order to be able to respond to device gyroscope (
gyroscope option), Photo Sphere Viewer requires
the following files from Three.js examples (also available in
three.js-examples Bower package) :
Photo Sphere Viewer uses a lot of angles for it's configuration, most of them can be defined in radians by using
a simple number (
3.5) or in degrees using the "deg" prefix (
Some methods take a
position parameter. It is an object with either
latitude properties (radians or degrees) or
(corresponding to the pixel position on the source panorama file).
|required||HTML element which will contain the panorama, or identifier of the element.|
|required||Path to the panorama image(s). It must be a single string for equirectangular panoramas and an array or an
object for cubemaps.
Equirectangular panorama :
Cubemap as array :
Cubemap as object :
|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.|
|autoload||boolean||true||Automatically load the panorama, if
|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.|
||Initial field of view, between
|fisheye||boolean|integer||false||Enable fisheye effect with
|default_long||double||0||Initial longitude, between 0 and 2π.|
|default_lat||double||0||Initial latitude, between -π/2 and π/2.|
|panorama_roll||double||0||Sphere angle from the horizon, between -π/2 and π/2.|
|longitude_range||double||Viewable longitude range. Examples:
|latitude_range||double||[π/2, -π/2]||Viewable latitude range.|
|2000||Idle time (milliseconds) before the panorama automatically starts rotating.
|anim_speed||string||'2rpm'||Automatic rotation speed in radians/degrees/revolutions per second/minute.
Different units are possible for the
||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.|
||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
|mousewheel||boolean||true||Listen to mouse wheel events to zoom in and out.|
|mousemove||boolean||true||Listen to mouse click+move events to rotate the view.|
|keyboard||boolean||true||Enabled keyboard navigation in fullscreen.|
|gyroscope||boolean||false||Enable gyroscope navigation and add a navbar button when the device supports it.|
|size||Object||null||The final size if the panorama container (e.g.
||Configuration of the transition effect between panoramas.|
|move_speed||double||1||Speed multiplicator for manual moves.|
|usexmpdata||boolean||true||Read real image size from XMP data, must be kept
|pano_data||object||Manually define cropping config (if
In this example a 4000x2000 image is used as a portion of a 6000x3000 panorama, the remaining space will be rendered black.
|cache_texture||integer||5||Number of texture objects to cache into memory, this is to prevent network overload when calling
||Configuration of the tooltip. This only needs to be changed if the CSS is modified.|
|move_inertia||boolean||true||Enabled smooth animation after a manual move.|
|click_event_on_marker||boolean||false||A click on a marker will trigger a
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.
On the viewer you can also use the
on method to listen to
navbar is an array which can contain the following core buttons:
caption and objects to create custom buttons :
|id||The unique identifier of the button.|
|title||The button tooltip.|
|content||The content of the button.|
|className||A CSS class added to the button element.|
|onClick||Function called when the button is clicked.|
|disabled||If the button must be disabled by default.|
|hidden||If the button must be hidden by default.|
This example uses some core buttons and a custom one.
After the viewer creation you cannot add or remove buttons but you can change their visibility. Use the
method the get a button by its id (works for core buttons too). You will get an object with the following methods: