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.
Permalink
Failed to load latest commit information.
dist
examples
icons
pics
src
test
.gitignore
CNAME
Gruntfile.js
LICENSE
README.md
bower.json
index.html
package.json

README.md

Marble - 360° image viewer

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

Installation

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:

https://cdn.rawgit.com/jsguy/marble/master/dist/marble-latest.min.js

Usage

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>

Manually

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

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 "|".

Options

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

Examples

See the examples directory for some examples