360 degree equirectangular image viewer
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Marble - 360° image viewer

This image viewer displays equirectangular 360° images, and is based on three.js


You can install marble via bower:

bower install marble

Then reference the marble js file like so:

<script src="bower_components/marble/dist/marble-latest.min.js"></script>

Or use the CDN file from here:



These examples will each show a 360 degree image at 100% width, 480px height, or if the script tag is inside a container with a height and/or width set, it will use that.

Unobtrusively with a preview image

<img src="pic-preview.jpg" data-previewimg="pic-preview.jpg" data-img="pic.jpg">
<script src="marble-latest.min.js"></script>

With a single script tag:

<script src="marble-latest.min.js" data-img="pic.jpg"></script>


<span id='target'></span>
<script src="marble-latest.min.js"></script>
	marble.init(document.getElementById('target'), {
		img: 'pic.jpg'

As a slideshow

<script src="../src/marble.js" data-img="pic1.jpg|pic2.jpg|pic3.jpg"></script>

Note: to specify that you want a slideshow, simply include multiple images separated by a vertical bar "|".


You can specify options using data attributes on the script tag, or passed into the init function, here is a list of options:

  • img - URL to the 360° image(s) you want to display
  • imgcube - Is this an image cube from 6 images, default is false, see the [Cube naming convention] below for how to name your images
  • imgcubekrmode - When using a KRPano based image cube, we horizontally flip l,r,f,b, vertically flip d,u, default is false
  • imgcubeorder - The order the images should be shown in the cube, default is "r,l,u,d,f,b", unless KR mode, in which case default is "r,l,u,d,b,f"
  • previewimg - optional URL to a preview image, this will cause the player to lazy load the image when the user clicks
  • forceinit - initialize even when a preview image is specified, useful for older browsers, default is false
  • horizontal - horizontal degrees offset to start displaying the image, eg: 180 means show the "back" of the image initially, default is 0
  • vertical - vertical degrees offset to start displaying the image, eg: -20 means "look down by 20 degrees", default is 0
  • zoom - amount to zoom in/out - positive is zoom in, negative is zoom out, default value is 0
  • zoommax - maximum amount of zoom, beyond 50, the image starts to look quite blurry, default is 50
  • zoommin - minimum amount of zoom, the user will see a spherical shape with your 360 image, when the value is below -110 or so, depending on the diemnsions of your image viewport, default is -250
  • width - the width of the image in pixels, default is to use the container width, or the full width, if no width is set
  • height - the height of the image in pixels, uses the container height, or 480px if no height is set on the container
  • spin - how many degrees to turn per second, when spinning is enabled, default is 3, set to 0 to disable spinning
  • startspin - start spinning when the photo loads
  • animate - decelerate animation when the photo loads
  • allowmousewheel - do we allow the mouse wheel to zoom in/out, default is true
  • allowcrossorigin - do we allow the image to be loaded from a different domain, (domain must support CORS), default is true
  • addcdnparameter - add a cdn parameter to the URL of the image request, useful for when CORS headers are being ignored, due to CDN prefretch caching, default is false
  • cdnparameter - the cdn parameter to (optionally) add, (the value of the key is set to the hash of the image URL), default is "cdnkey"
  • allowfullscreen - allow the user to go full-screen - only available if the browser supports fullscreen, default is true
  • showspinbutton - Do we show a button that allows the user to start/pause the spin of the image, default is true
  • showsavefilebutton - Do we show a button that allows the user to save an image from the current view, default is false
  • savefilepassthrough - If the save pic button is shown, do we simply allow the use to subscribe to the "saveFile" event, rather than having the browser handle it, default is false
  • allowuserinteraction - do we allow the user to interact with the image, default is true
  • clicktotogglespin - does clicking stop/start spinning, default is false
  • behave - don't render if there is another image 360° animating/spinning, or the user is interacting with another 360° image on the same page: this provides the best UX when there are several images on the page at once, default is true
  • overlay - overlay a pixel mask to darken the image slightly - the can help with the visual apperance of some images, and is useful for background images, default is false
  • menutimeout - how long till the menu auto-hides after mouseover in ms, default is 3500
  • fps - specify how many FPS to use, (1-60), default is 60, this might be useful to limit CPU/GPU usage if you have several spinning 360° images on the page at once
  • usedeviceorientation - allow mobile devices to move the image using the accelerometer, default is true
  • slideshowdelay - time to show each picture in milliseconds, default is 9000
  • slideshowindex - what slide to start on (0-indexed), default is 0

Cube naming convention

The 6 images to be used in a cube must be named with an underscore, ("_"), followed by one of the following letters at the end of the file name:

  • r - right face of cube
  • l - left face of cube
  • u - up face of cube
  • d - down face of cube
  • f - front face of cube
  • b - back face of cube

So for example you might name the images: cube_r.jpg, cube_l.jpg, etc...

Note: if your images do not follow this convention, we assume they are sorted in the imgcubeorder


See the examples directory for some examples