See also the reference for more detailed documentation.

Getting started

Marzipano Tool

The easiest way to get started with Marzipano is with the Marzipano Tool.

It processes your panoramas and generates a web application that can be deployed as-is or used as a boilerplate for a more complex application. The Marzipano Tool is currently free and does not require creating an account.

Setting up from scratch

As a standalone script

  1. Download the latest release.

  2. Include the marzipano.js file in body section of your HTML code

    <html>
 <body>
   <script src="marzipano.js"></script>
 </body>
</html>

As a Node.js package

npm install marzipano
var Marzipano = require('./marzipano');

Usage

The Marzipano.Viewer and Marzipano.Scene classes provide a high-level API for the most common use cases.

Initializing

A Viewer is initialized on a DOM element

var panoElement = document.getElementById('pano');
var viewerOpts = {
  controls: {
    mouseViewMode: 'drag'    // drag|qtvr
  }
};

var viewer = new Marzipano.Viewer(panoElement, viewerOpts)

Create Scene

The example below initializes a multiresolution cube scene which uses images inside the tiles/ directory.

var levels = [
  { tileSize: 512, size: 512 },
  { tileSize: 512, size: 1024 }
];

var geometry = new Marzipano.CubeGeometry(levels);
var source = Marzipano.ImageUrlSource.fromString("tiles/{z}/{f}/{y}/{x}.jpg");
var view = new Marzipano.RectilinearView();

var scene = viewer.createScene({
  source: source,
  geometry: geometry,
  view: view
});

The more complex example below also:

  • adds a (cubeMap) preview level which is cached when the scene is created
  • initializes the view
  • limits the view to a maximum fov of 120°
  • limits the view to a minimum fov for a maximum face resolution of 1024x1024

Note that the yaw, pitch and fov values are in radians.

var levels = [
  { tileSize: 256, size: 256, fallbackOnly: true },
  { tileSize: 512, size: 512 },
  { tileSize: 512, size: 1024 }
];

var geometry = new Marzipano.CubeGeometry(levels);

var source = Marzipano.ImageUrlSource.fromString("tiles/{z}/{f}/{y}/{x}.jpg", {
  cubeMapPreviewUrl: "tiles/preview.jpg"
});

var initialView = {
  yaw: 90 * Math.PI/180,
  pitch: -30 * Math.PI/180,
  fov: 90 * Math.PI/180
};

var limiter = Marzipano.RectilinearView.limit.traditional(1024, 120*Math.PI/180);

var view = new Marzipano.RectilinearView(initialView, limiter);

var scene = viewer.createScene({
  source: source,
  geometry: geometry,
  view: view,
  pinFirstLevel: true
});

Change Scene

The Scene.switchTo() method displays the scene on its viewer, performing a fade in transition.

scene.switchTo({
  transitionDuration: 1000
});

Change View

The Scene.lookTo() method changes the view by performing a tweening animation. Note that the values are in radians.

var destinationViewParameters = {
  yaw: 10 * Math.PI/180,
  pitch: 15 * Math.PI/180,
  fov: 60 * Math.PI/180
};

var options = {
  transitionDuration: 2000
}

scene.lookTo(destinationViewParameters, options);

For more control each Scene has a View object which can be acessed by the view() getter.

var scene = viewer.scene(); // get the current scene
var view = scene.view();    // get the scene's view


// Get the view values

var yaw = view.yaw();
var pitch = view.pitch();
var fov = view.fov();      // fov is horizontal
var vfov = view.vfov();
var hfov = view.hfov();    // same as view.fov()


// Change the values

view.setYaw(45 * Math.PI/180);
view.setPitch(30 * Math.PI/180);
view.setFov(60 * Math.PI/180);

view.setParameters({
  yaw: 45 * Math.PI/180,
  pitch: 30 * Math.PI/180,
  fov: 60 * Math.PI/180
});


// Offset the values by some amount

view.offsetYaw(10 * Math.PI/180);
view.offsetPitch(10 * Math.PI/180);
view.offsetFov(10 * Math.PI/180);

Automatic movement and autorotate

Viewer.setIdleMovement() defines a movement to be automatically started when the view has not changed for some amount of time.

The Viewer.startMovement() and Viewer.stopMovement() methods allow you to start and stop a movement manually.

The autorotate() method creates an automatic rotation movement which can be used with the methods above.

var autorotate = Marzipano.autorotate({
  yawSpeed: 0.1,         // Yaw rotation speed
  targetPitch: 0,        // Pitch value to converge to
  targetFov: Math.PI/2   // Fov value to converge to
});

// Autorotate will start after 3s of idle time
viewer.setIdleMovement(3000, autorotate);  
// Disable idle movement
viewer.setIdleMovement(Infinity);

// Start autorotation immediately
viewer.startMovement(autorotate); 
// Stop any ongoing automatic movement
viewer.stopMovement();

Hotspots

Hotspots are DOM elements which are positioned at a fixed point in the panorama, so that their position on the screen changes when the scene view changes.

Hotspots are associated with a scene and are automatically displayed with that scene.

var element = document.getElementById('spot');
var position = { yaw: Math.PI/4, pitch, Math.PI/8 };
scene.hotspotContainer().createHotspot(element, position)

The example below creates an image and uses it as a hotspot

  var imgHotspot = document.createElement('img');
  imgHotspot.src = 'img/hotspot.png';
  imgHotspot.classList.add('hotspot');
  imgHotspot.addEventListener('click', function() {
    switchScene(findSceneById(hotspot.target));
  });

  var position = { yaw: Math.PI/4, pitch: Math.PI/8 };

  marzipanoScene.hotspotContainer().createHotspot(imgHotspot, position);

Dependencies

Marzipano has a few dependencies. These are included in marzipano.js, so you do not have to set them up separately.

APIs and Reference

The Viewer and Scene classes above are a high level API designed to make Marzipano simple to use. However the lower level components that they use, such as the Layer and Stage classes, are also exposed. These can be used when more control is necessary or to implement features which are not present on the high level API yet.

See the reference for more detailed documentation.