360度全景图像查看器技术文档

本文档旨在详细介绍如何使用360-image-viewer库，一个轻量级的WebGL全景图像查看器，适合桌面和移动设备。该库通过使用regl，提供了仅140KB的压缩版本（或46KB的gzipped版本），作为对比，ThreeJS大小约为500KB，非常适合对体积有要求的项目。

安装指南

要将此全景图像查看器集成到您的项目中，请通过npm进行安装：

npm install 360-image-viewer --save

这将把360-image-viewer添加为项目的依赖项。

使用说明

快速启动

一旦安装完成，您可以通过以下简短代码片段来初始化并展示一个全屏的360度全景图像查看器。

首先，确保您的图片已经加载完毕：

const image = new Image();
image.src = 'panosphere.jpg';

然后，在图片加载完成后设置查看器：

image.onload = () => {
  const viewer = create360Viewer({ image });
  document.body.appendChild(viewer.canvas);
  
  const fit = canvasFit(viewer.canvas, window, window.devicePixelRatio);
  window.addEventListener('resize', fit, false);
  fit();
  viewer.start();
};

高级使用

create360Viewer函数允许传递一个选项对象以自定义查看器的行为：

const viewer = create360Viewer({
  image,
  fov: 60, // 默认视场角为45度
  rotateSpeed: 0.2, // 控制旋转速度
});

核心方法

• viewer.start(): 启动渲染循环。
• viewer.stop(): 停止渲染循环。
• viewer.render(): 渲染当前帧，适用于手动控制渲染的情况。
• viewer.enableControls(): 开启控件，使鼠标和触摸事件生效。
• viewer.disableControls(): 禁用控件。
• viewer.texture(newImage): 更换当前显示的图像。

API使用文档

• 创建查看器: create360Viewer([opt])

  • image: 图像元素，也可以稍后设置。
  • 可选参数包括canvas, fov, rotateSpeed, damping, 和 clearColor等，支持自定义配置。

• 核心属性与方法：

  • viewer.canvas: 获取用于渲染的canvas元素。
  • viewer.fov, viewer.phi, viewer.theta: 分别表示视角角度和旋转角度。
  • viewer.texture: 动态更换图像源。

项目安装方式回顾

通过命令行输入npm install 360-image-viewer --save即可完成项目的安装，随后即可在您的应用中利用以上说明进行高效的全景图展示。

---

本文档提供了一站式的解决方案，从安装到高级使用的步骤，以便于开发者快速上手并深度定制360-image-viewer，实现丰富多样的全景图像浏览体验。