Pannellum全景查看器JSON配置参数详解

Pannellum全景查看器JSON配置参数详解

pannellum Pannellum is a lightweight, free, and open source panorama viewer for the web. 项目地址: https://gitcode.com/gh_mirrors/pa/pannellum

前言

Pannellum是一个轻量级的全景查看器，支持多种全景格式。本文将全面解析Pannellum的JSON配置文件参数，帮助开发者更好地定制全景展示效果。

基础配置参数

全景类型设置

type参数定义了全景图的类型，支持三种格式：

• equirectangular：等距柱状投影（最常见）
• cubemap：立方体贴图
• multires：多分辨率格式

元信息配置

可以设置全景图的标题、作者等信息：

• title：全景图标题
• author：作者信息
• authorURL：作者链接（需配合author使用）

加载控制

• autoLoad：是否自动加载全景图
• basePath：设置图片加载的基础路径
• preview：设置预览图URL
• crossOrigin：跨域请求设置（anonymous或use-credentials）

视角控制

• yaw：初始水平角度（0-360度）
• pitch：初始垂直角度（-90到90度）
• hfov：初始水平视野（50-120度）
• minYaw/maxYaw：限制水平视角范围
• minPitch/maxPitch：限制垂直视角范围
• minHfov/maxHfov：限制视野范围

交互控制

• draggable：是否允许拖拽
• mouseZoom：鼠标滚轮缩放控制
• keyboardZoom：键盘缩放控制
• showControls：是否显示控制按钮
• showFullscreenCtrl：是否显示全屏按钮
• friction：拖拽后的惯性阻尼系数

高级功能配置

自动旋转

• autoRotate：自动旋转速度（度/秒）
• autoRotateInactivityDelay：用户停止操作后的旋转延迟
• autoRotateStopDelay：加载后停止旋转的延迟

交互点配置

interactionPoints数组定义了交互点，支持：

• scene类型：场景跳转
• info类型：信息提示

交互点可配置属性包括：

• 位置（pitch/yaw）
• 文本提示（text）
• 目标场景ID（sceneId）
• 目标视角（targetPitch/targetYaw/targetHfov）
• 自定义CSS类（cssClass）
• 可拖拽（draggable）

背景设置

• backgroundColor：设置背景颜色（RGB数组）
• avoidShowingBackground：避免显示背景区域

特定格式配置

等距柱状投影(equirectangular)

• panorama：图片URL或图像对象
• haov：水平视角（默认360）
• vaov：垂直视角（默认180）
• vOffset：垂直偏移量
• ignoreGPanoXMP：是否忽略XMP元数据

立方体贴图(cubemap)

• cubeMap：6个面图片URL数组（顺序：前、右、后、左、上、下）

多分辨率(multires)

multiRes对象包含：

• basePath：基础路径
• path：瓦片路径格式
• tileResolution：瓦片分辨率
• maxLevel：最大级别
• cubeResolution：立方体分辨率

动态内容配置

• dynamic：标记为动态内容（如视频）
• dynamicUpdate：是否自动更新

场景切换配置

用于创建全景导览：

• default：默认配置（必须包含firstScene）
• scenes：场景字典
• sceneFadeDuration：场景切换淡入淡出时间

最佳实践建议

1. 对于大型全景图，推荐使用multires格式提高性能
2. 设置合理的minHfov和maxHfov保证用户体验
3. 使用interactionPoints创建交互式导览
4. 为移动设备考虑orientationOnByDefault设置
5. 使用preview提高加载体验

通过合理配置这些参数，可以创建出功能丰富、性能优异的全景展示应用。

pannellum Pannellum is a lightweight, free, and open source panorama viewer for the web. 项目地址: https://gitcode.com/gh_mirrors/pa/pannellum