Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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


360 degree equirectangular image viewer







No releases published


No packages published