Marzipano 是基于WebGL技术的全景图展示器，是国外开发的一款插件。学习发现该插件只有英文文档，中文资料也并不多。故对其文档进行中文翻译。文章如有翻译不对的地方，请多包涵并指出。

入门

Marzipano 工具

开始使用 Marzipano 的最简单方法是使用Marzipano 工具。
它会处理您的全景图并生成一个 Web 应用程序，该应用程序可以按原样部署，也可以用作更为复杂应用程序的样板。Marzipano Tool 目前免费，不需要创建帐户。

从头开始设置

独立脚本

下载最新版本。
将marzipano.js文件在放在你的 HTML 代码的body部分中

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

以Node.js 包形式

npm install marzipano

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

用法

Marzipano.Viewer和Marzipano.Scene类是常见应用示例中的高级API。

初始化

基于一个DOM元素初始化一个Viewer对象

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

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

创建场景

以下代码示例，通过使用 tiles/ 目录下的图片，来初始化一个多层级的立方体场景。

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
});

下面还有更复杂的例子：

配置了（cubeMap）预览图，他会在场景被创景时候缓存下来
初始化视图
将视野范围限制为最大 120°
限制视野到最小视角，同时面部分辨率不超过1024×1024

请注意，y轴、x轴和视野范围的值都是以弧度为单位。

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
});

场景变换

Scene.switchTo()方法利用补间动画改变场景。请注意：这些值都是以弧度为单位。

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);

每个场景scene上都有试图对象view,可以通过 scene.view() 方式获取得到。

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);

自动移动和自动旋转

Viewer.setIdleMovement(): 当视图在一段时间内没有发生改变时自动移动。
Viewer.startMovement()和Viewer.stopMovement()允许您手动开启和停止运动。
autorotate(): 自动旋转，该方法和上面三个方法结合使用。

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();

热点

热点其实就是位于全景图中某个固定位置的DOM元素。因此当场景发生变化时候，他们的位置也会随之发生变化。
热点是和场景关联在一起的，他会自动跟随场景展示。

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

以下示例创建了图片DOM元素，并将其作为热点对象。

  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);

依赖项

Marzipano 使用到了一些依赖，它们已经包含在marzipano.js中。因此，你不需要在单独安装他们了。

Marzipano 中文文档

入门