Fork me on GitHub

Pannellum

字数统计: 3k字   |   阅读时长≈ 11分

介绍

Pannellum是基于WEB的轻量级VR全景图阅读器

特性

有如下良好的特性支持不同的需要：

  1. 支持自动载入和手动载入全景图
  2. 支持全景图的自动旋转和手动旋转方式
  3. 支持预览图设定
  4. 支持标注作者和标题
  5. 支持罗盘指示
  6. 支持Cube map（定义多张图片，组成全景图）
  7. 支持初始视角的定义
  8. 支持部分全景展示
  9. 支持自定义的全景移动控制
  10. 支持自定义热点
  11. 支持多分辨率
  12. 支持tour模式（从一全景图切换到另一全景图）
  13. 支持全景视频

兼容性

Pannellum兼容性良好，基本能支持主流的浏览器，基本能够完全支持的浏览器如下：

  • Firefox 10+
  • Chrome 15+
  • Safari 8+
  • Internet Explorer 11+
  • Edge

使用代码

初始化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
//多场景，需要scenes及firstScene指定默认场景
const viewer = pannellum.viewer(容器元素或id, {
    firstScene: 'firstScene', 
    showControls: false, 
    autoLoad: true,
    //autoRotate: -1,
    //autoRotateInactivityDelay: 2000, 
    //orientationOnByDefault: true, 
    //mouseZoom: false 
    //minPitch: -100, 
    //maxPitch: 100, 
    //hfov: 100, 
    //minHfov: 60, 
    //maxHfov: 60, 
    scenes: {
      firstScene: {
        title: "第一个场景",
        type: "cubemap",
        cubeMap: [
          "./example_front.jpg",
          "./example_right.jpg",
          "./example_behind.jpg",
          "./example_left.jpg",
          "./example_up.jpg",
          "./example_down.jpg"
        ],
        hotSpots: [
          {
            //热点，以全景为坐标系的固定点，可以设置链接跳转和点击事件，也可以跳转到不同的场景，该属性的值为对象
            pitch: -12,
            yaw: 170,
            type: "scene",
            sceneId: "secondScene", //sceneId 需要切换的场景id
            text: "点击前往第二个场景."
          }
        ]
      },
      secondScene: {
        title: "第二个场景",
        panorama: 'example2.jpg',
        hotSpots: [
          {
            pitch: 0,
            yaw: 100,
            type: "scene",
            text: "前往第一个场景",
            sceneId: "firstScene",
            clickHandlerFunc(e) {
              //监听点击
            },
            createTooltipFunc(e) {
              //调整热点dom
              e.style.width = "100px";
              e.style.height = "100px";
              e.style.background = "red";
            }
            //cssClass: "pnlm-hotspot pnlm-model pnlm-scene1 pnlm-type1" //添加热点css类
          }
        ]
      }
    }
  });
1
2
3
4
5
6
7
//单个场景,主要设置panorama
const viewer = pannellum.viewer(容器元素或id, {
  type: "equirectangular", //图片类型
  panorama: 'example.jpg', //全景图
  autoLoad: true, //自动加载，否则需要点击
  showControls: false //是否显示控制按钮
});

config

pannellum.viewer初始化参数。类型为Object，其属性配置项如下：

  • id: string 热点id，供 removeHotSpot 删除热点使用

  • type:string 指定全景图类型，默认 equirectangular

    • equirectangular 等矩形
    • cubemap 立方体 - 六个方向
    • multires 多分辨率 - 根据缩放的程度（改变Hfov）来显示不同清晰度的照片

  • title:string 左下角标题

  • firstScene:string 指定首次展示的场景sceneId

  • compass:boolean 显示指南针

  • draggable:boolean 是否可拖动

  • showControls:boolean 显示控制按钮

  • autoLoad: boolean 自动加载，否则需要点击

  • autoRotate: number 自动旋转，正数向右，负数向左，绝对值越大速度越快

  • autoRotateInactivityDelay: number 停止操作多久(ms)继续旋转

  • orientationOnByDefault: boolean 开启重力感应查看模式

  • mouseZoom: boolean 鼠标滚轮缩放

  • minPitch: number 俯仰角度最小值

  • maxPitch: number 俯仰角度最大值

  • hfov: number 视野(远近缩放)

  • minHfov: number 视野最小值

  • maxHfov: number 视野最大值

  • hotSpots: object 设置热点，配置属性如下:

    • pitch: number 俯仰角度 - 绕x轴旋转
    • yaw: number 偏移角度 - 绕y轴旋转
    • type: string 热点类型:
      • "scene" 场景链接
      • "info" 信息热点
    • text: string hover时显示的文本
    • sceneId: string 目标场景id，热点type为"scene"时指定跳转的场景
    • targetPitch:number 热点type为"scene"时指定跳转场景的初始俯仰角
    • targetYaw:number 热点type为"scene"时指定跳转场景的初始偏移角
    • targetHfov :number 热点type为"scene"时指定跳转场景的初始视野
    • scale:boolean 是否缩放热点以匹配视野变化(近大远小)，默认false
    • URL:string 设置后点击该热点会跳转到对应外部链接
    • image:string 设置后热点tooltip会弹出对应图片，图片太大会超出屏幕
    • video:string 设置后热点tooltip会弹出对应视频，视频太大会超出屏幕
    • cssClass :number指定热点元素的css类，而不是默认的类
    • clickHandlerArgs:any clickHandlerFunc热点点击参数
    • clickHandlerFunc(event, clickHandlerArgs):function 监听热点点击
    • createTooltipArgs:any createTooltipFunc自定义热点工具参数
    • createTooltipFunc(iconDom, createTooltipArgs):function 用于自定义热点工具提示dom, 配置后默认tooltip消失 (直接对参数 - 热点图标dom操作)

  • hotSpotDebug:boolean 开启场景热点调试模式，中间会出现准心，单击时会打印俯仰和偏移等点信息

  • scenes:object 场景组，其属性名代表着场景的id（sceneId），属性值为viewer的配置参数(config)，其参数会覆盖默认（上述中的default对象）设置的参数

在function类型的配置项中, this可获取场景及热点、位置等信息clickHandlerFunc回调中的this对添加热点时自定义的属性也会保留

特定选项

type为不同值时特有选项: equirectangular, cubemap, 或 multires

equirectangular

  • panorama:string 全景图路径
  • haov:number 全景水平视角，默认360。如果图像在水平方向未覆盖360度可设置此项
  • vaov:number 全景垂直视角，默认180。如果图像在垂直方向上未完全覆盖180度可设置此项
  • vOffset:number 图形中心相对于地平线的垂直偏移，默认0。vaov小于180且图像源未对称剪裁时使用
  • ignoreGPanoXMP:boolean 为true忽略任何嵌入的Photo Sphere XMP 数据，否则会覆盖现有设置

cubemap

  • cubeMap:array 设置六个立方体面图像URL，顺序为前、右、后、左、上、下

针对拆分全景图片的投影方式，即将整个投影空间看作一个立方体，具有前后左右上下6个面，分别将各个拆分全景图片渲染在对应的各个面上，在感官上也能够达到柱面投影的效果

multires

  • multiRes:object

    • basePath 设置一个公用路径，后面的path只需要写相对于basePath的相对路径即可，这里需要注意的是path的值，path的值是一个格式化的字符串，其中 %l 代表缩放等级，**%s** 代表立方体的面 ，**%x** 和 %y 代表了该瓦片在这一个面中的位置。 其文件结构如图：

      )

      当缩放等级为1时，就会在“1”文件夹中将各个面对应的图片投影到对应的立方体面上（对应%s），然后根据每一个瓦片的坐标来确定瓦片在每一个面中的位置，这里由于坐标是（0,0），且每一面只有一个瓦片，所以是铺满整面，多个瓦片的效果可以看上面的实例。

    • fallbackPath 当某些浏览器不支持multires功能的时候能够回退到fallbackPath指定的文件夹下加载默认的全景图

    • extension指定瓦片的图片格式，不需要加前面的 “.” 符号

    • ileResolution指定瓦片的像素，单位为px。

    • maxLevel指定最多支持几个缩放等级。

    • cubeResolution指定立方体面的总像素，单位为px。

如此就能够根据不同的缩放等级来显示不同的清晰度的图像，这样的好处是如果要加载一张4k的全景图，不需要一次性就将整个全景图都加载进来，可以先加载一个缩放等级低的全景，然后当使用者进行缩放查看细节的时候再加载清晰度更高的图像，这样就可以明显提高加载速度，避免因为图片过大使得加载时间过长和不必要的流量浪费。不足之处就是需要为一张全景图额外准备不同清晰度的图片，增加了图片处理的工作量，也增加了图片存储的空间占用。

动态内容

当前仅支持 equirectangular

  • dynamic:boolean 将全景图视为动态源，默认false。比如全景源为视频的情况需要设置true
  • dynamicUpdate:boolean 使查看器对动态内容自动更新。如果更新是通过setUpdate方法控制则设为false

事件

事件通过viewer.on(eventName, callback)监听，eventName:string如下:

  • load 全景图加载完成
  • scenechange 新场景初始化完成
  • fullscreenchange 全屏状态切换
  • zoomchange 场景 hfov 视野变化
  • scenechangefadedone 若指定了场景淡入淡出间隔，则在淡入淡出完成后触发
  • animatefinished 任何动画/移动完成时触发，也就是渲染器停止渲染新帧。将最终pitch、yaw、hfov值传递给回调
  • error 发生错误
  • errorcleared 清除错误
  • mousedown 鼠标按下
  • mouseup 鼠标抬起
  • touchstart 触摸开始(移动端)
  • touchend 触摸结束(移动端)

全局api

通过viewer调用，这里只介绍常用api

方法

  • addHotSpot(hs, sceneId)添加热点

    • parameters：hs - 热点参数, sceneId - 添加目标场景id(默认是当前场景id)
    • return: viewer

  • mouseEventToCoords(MouseEvent) 根据鼠标事件参数获取在全景图中的位置

    • parameters：鼠标事件参数MouseEvent

  • return: 数组 - [pitch, yaw]

  • resize 容器大小改变后需要调用此方法重新布局全景

  • destroy 销毁

  • getContainer 获取容器dom

  • getConfig 获取配置对象

  • getPitch 获取全景图中心点俯仰角

  • setPitch(pitch, animated, callback, callbackArgs) 设置全景图中心点俯仰角

    • parameters：
      • pitch:number 俯仰角
      • animated:(boolean|number) 移动动画时间(ms)，默认1000，设为false则没有动画
      • callback(callbackArgs):function 移动动画完成
      • callbackArgs:any 传给callback的参数
    • return: viewer

  • getPitchBounds 获取俯仰角范围，返回 - [minpitch, maxpitch]

  • setPitchBounds 获取俯仰角范围，参数 - [minpitch, maxpitch]

  • getYaw 获取全景图中心点偏移角

  • setYaw(yaw, animated, callback, callbackArgs) 设置全景图中心点偏移角

    • parameters：
      • yaw:number 偏移角
      • animated:(boolean|number) 移动动画时间(ms)，默认1000，设为false则没有动画
      • callback(callbackArgs):function 移动动画完成
      • callbackArgs:any 传给callback的参数
    • return: viewer

  • getYawBounds 获取偏移角范围，返回 - [minyaw, maxyaw]

  • setYawBounds 获取偏移角范围，参数 - [minyaw, maxyaw]

  • getHfov 获取全景图水平视野

  • setHfov(hfov, animated, callback, callbackArgs) 设置全景图水平视野

    • parameters：
      • hfov:number 水平视野
      • animated:(boolean|number) 移动动画时间(ms)，默认1000，设为false则没有动画
      • callback(callbackArgs):function 移动动画完成
      • callbackArgs:any 传给callback的参数
    • return: viewer

  • getHfovBounds 获取水平视野范围，返回 - [minhfov, maxhfov]

  • setHfovBounds 获取水平视野范围，参数 - [minhfov, maxhfov]

  • lookAt(pitch, yaw, hfov, animated, callback, callbackArgs)

    将视图中心聚焦到指定位置

    • parameters：

      • pitch:number 目标pitch

      • yaw:number 目标yaw

      • hfov:number 目标hfov

      • animated:(boolean|number) 移动动画时间(ms)，默认1000，设为false则没有动画

      • callback(callbackArgs):function 移动动画完成

      • callbackArgs:any 传给callback的参数

    • return: viewer

  • startAutoRotate(speed, pitch) 开始自动旋转

    • parameters：
      • speed:number 旋转速度/方向
      • pitch:number 旋转俯仰角
    • return: viewer

  • stopAutoRotate 停止自动旋转

  • stopMovement 停止所有移动

  • loadScene(sceneId, pitch, yaw, hfov) 加载指定场景

  • getScene 获取当前场景sceneId

  • addScene(sceneId, config) 添加场景

  • removeScene(sceneId) 移除场景

  • toggleFullscreen 切换全屏

  • isLoaded 全景图是否加载完成

  • on(eventName, callback) 监听事件，详情见上文事件

  • on(eventName, callback) 移除事件

自定义热点图标

自定义热点图标可用以下两种方式：

  • createTooltipFunc 直接对参数(图标dom)进行dom操作，是在默认图标的基础上调整
  • cssClass 通过添加自定义css类来完全自定义图标样式，高度定制化样式则推荐这种方式

动态添加热点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
viewer.on("mouseup", e => {
  const [pitch, yaw] = viewer.mouseEventToCoords(e);
  viewer.addHotSpot({
    type: "scene",
    pitch,
    yaw,
    text: "提示内容",
    sceneId: "secondScene",
    cssClass: "mark", //自定义样式class
    clickHandlerFunc(e) {
      viewer.removeHotSpot(this.id);//删除点击的热点
    }
  });
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
//上面直接监听mouseup在拖动位置时会意外触发,可封装点击事件解决:
export function onPnlmClick(viewer, callback) {
  let timer = null;
  viewer.on("mousedown", e => {
    timer = setTimeout(() => {
      clearTimeout(timer);
      timer = null;
    }, 120);
    e.preventDefault();
  });
  viewer.on("mouseup", e => {
    if (timer) callback(e);
  });
}
赏

谢谢你请我吃糖

支付宝
微信

扫一扫，分享到微信

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia-plus根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

主要涉及技术：
前端开发、Hexo博客、Vue、微信小程序爱好者