Photo Sphere Viewer

项目地址： https://github.com/mistic100/Photo-Sphere-Viewer

文档： https://photo-sphere-viewer.js.org

演示： https://photo-sphere-viewer.js.org/demos/

API 参考： https://photo-sphere-viewer.js.org/api/

Playground： https://photo-sphere-viewer.js.org/playground.html

许可证： MIT

最新版本： v5.15.1（npm @photo-sphere-viewer/core，截至 2026-10）

概述

Photo-Sphere-Viewer (PSV) 是一个基于 Three.js 的纯 JavaScript 库，用于在 Web 浏览器中显示 360° 全景照片/球体图像。支持从简单的照片球体到复杂的带标记、导航、陀螺仪和 VR 的虚拟导览。

唯一运行时依赖： Three.js（^0.185.1）。所有适配器和插件作为 @photo-sphere-viewer/* 独立 NPM 包发布。

注意： 旧的无作用域包 photo-sphere-viewer 已标记 deprecated（停在 4.8.1），v5 一律用 @photo-sphere-viewer/core，不要装旧包。

环境准备与安装

安装核心包

bashCopy code
npm install @photo-sphere-viewer/core

安装适配器和插件（按需）

bashCopy code
# 适配器
npm install @photo-sphere-viewer/cubemap-adapter          # 立方体贴图
npm install @photo-sphere-viewer/equirectangular-video-adapter  # 360° 视频
npm install @photo-sphere-viewer/equirectangular-tiles-adapter  # 分块加载大图
npm install @photo-sphere-viewer/dual-fisheye-adapter     # 双鱼眼（Ricoh Theta 等）

# 常用插件
npm install @photo-sphere-viewer/markers-plugin           # 标记系统
npm install @photo-sphere-viewer/gallery-plugin           # 底部画廊
npm install @photo-sphere-viewer/virtual-tour-plugin      # 虚拟导览
npm install @photo-sphere-viewer/gyroscope-plugin         # 陀螺仪
npm install @photo-sphere-viewer/stereo-plugin            # 立体/VR
npm install @photo-sphere-viewer/autorotate-plugin        # 自动旋转
npm install @photo-sphere-viewer/video-plugin             # 视频控制条
npm install @photo-sphere-viewer/compass-plugin           # 罗盘
npm install @photo-sphere-viewer/map-plugin               # 地图集成

直接 HTML 引入

htmlCopy code
<div id="viewer" style="width: 100%; height: 100vh;"></div>

<script type="module">
  import { Viewer } from '@photo-sphere-viewer/core';
  import '@photo-sphere-viewer/core/index.css';

  const viewer = new Viewer({
    container: '#viewer',
    panorama: 'pano.jpg',
  });
</script>

注意： 需要 WebGL 支持（现代浏览器均支持）。移动端陀螺仪和立体 VR 功能需 HTTPS。

快速上手

基础全景查看器

tsCopy code
import { Viewer } from '@photo-sphere-viewer/core';
import '@photo-sphere-viewer/core/index.css';

const viewer = new Viewer({
  container: document.querySelector('#viewer'),
  panorama: 'https://example.com/panorama.jpg',
  caption: '山顶全景',
  description: '拍摄于 2026 年 7 月',
  defaultYaw: '45deg',
  defaultPitch: '10deg',
  defaultZoomLvl: 50,
  navbar: ['zoom', 'fullscreen', 'caption'],
  loadingTxt: '加载中...',
  lang: {
    zoom: '缩放',
    fullscreen: '全屏',
  },
});

带标记和画廊

tsCopy code
import { Viewer } from '@photo-sphere-viewer/core';
import { MarkersPlugin } from '@photo-sphere-viewer/markers-plugin';
import { GalleryPlugin } from '@photo-sphere-viewer/gallery-plugin';
import '@photo-sphere-viewer/markers-plugin/index.css';

const viewer = new Viewer({
  container: '#viewer',
  panorama: 'room1.jpg',
  navbar: ['zoom', 'fullscreen', 'markers', 'gallery'],
  plugins: [
    MarkersPlugin.withConfig({
      markers: [
        {
          id: 'door',
          position: { yaw: '30deg', pitch: 0 },
          image: 'pin.png',
          size: { width: 40, height: 40 },
          tooltip: '入口',
          content: '<h3>入口大门</h3><p>由此进入主展厅</p>',
        },
        {
          id: 'window',
          position: { yaw: '-90deg', pitch: '5deg' },
          html: '<div class="hotspot">窗</div>',
          tooltip: '落地窗 - 点击查看详情',
        },
      ],
    }),
    GalleryPlugin.withConfig({
      items: [
        { id: '1', name: '客厅', panorama: 'room1.jpg', thumbnail: 'thumb1.jpg' },
        { id: '2', name: '餐厅', panorama: 'room2.jpg', thumbnail: 'thumb2.jpg' },
        { id: '3', name: '卧室', panorama: 'room3.jpg', thumbnail: 'thumb3.jpg' },
      ],
      visibleOnLoad: true,
      hideOnClick: false,
    }),
  ],
});

viewer.addEventListener('ready', () => {
  console.log('全景加载完成');
});

立方体贴图

tsCopy code
import { Viewer } from '@photo-sphere-viewer/core';
import { CubemapAdapter } from '@photo-sphere-viewer/cubemap-adapter';

const viewer = new Viewer({
  container: '#viewer',
  adapter: CubemapAdapter,
  panorama: {
    left: 'cubemap/left.jpg',
    front: 'cubemap/front.jpg',
    right: 'cubemap/right.jpg',
    back: 'cubemap/back.jpg',
    top: 'cubemap/top.jpg',
    bottom: 'cubemap/bottom.jpg',
  },
});

核心 API

Viewer 类

new Viewer(config: ViewerConfig) — 创建查看器实例，返回已初始化的 Viewer。

关键配置项：

主要方法：

主要事件：

适配器（全景格式）

适配器的全景数据配置（PanoData）

tsCopy code
const viewer = new Viewer({
  adapter: EquirectangularAdapter,
  panorama: 'crop.jpg',
  panoData: {
    fullWidth: 4096,   // 源图像完整宽度
    fullHeight: 2048,   // 源图像完整高度
    croppedWidth: 2048, // 裁剪后宽度
    croppedHeight: 1024,// 裁剪后高度
    croppedX: 1024,     // 裁剪 X 偏移
    croppedY: 512,      // 裁剪 Y 偏移
  },
});

等距柱状图适配器默认使用 useXmpData: true 自动读取图像 XMP 元数据获取裁剪信息。v5.14.2+ 新增 shader 选项（默认 false，可设为 true 用像素着色器消除极点扭曲）。

插件系统、MarkersPlugin 与虚拟导览（VirtualTourPlugin）的完整用法见 reference/plugins.md

常见问题

典型工作流

工作流一：单场景全景查看器

1. npm install @photo-sphere-viewer/core，页面里放一个容器并设好宽高
2. new Viewer({ container, panorama, navbar, caption }) 初始化，defaultYaw/defaultPitch/defaultZoomLvl 定初始机位
3. 需要热点就加 MarkersPlugin（markers: [{ id, position: { yaw, pitch }, image | html, tooltip }]）
4. 监听 ready / click / position-updated 事件接业务逻辑
5. 切换图片用 setPanorama(url, options)（可带过渡动画），销毁页面时 destroy() 释放 Three.js 资源

工作流二：多场景虚拟导览

1. 装 virtual-tour-plugin（+ markers-plugin，导览箭头依赖它）
2. VirtualTourPlugin.withConfig({ nodes, startNodeId, positionMode })：每个 node 有自己的 panorama 与 links
3. 需要底部缩略图导航再叠 GalleryPlugin
4. 用 viewer.getPlugin(VirtualTourPlugin).gotoNode(id) 做程序化跳转

工作流三：大图 / 360° 视频 / 双鱼眼

1. 大图分块：equirectangular-tiles-adapter（或 cubemap 版），配好多级 tiles 尺寸
2. 视频：equirectangular-video-adapter（panorama: { source }）+ video-plugin 出控制条
3. 双鱼眼相机原片：dual-fisheye-adapter
4. 裁剪过的全景图用 panoData（fullWidth/fullHeight/croppedX/Y...）告诉适配器原图与裁剪关系，或依赖默认的 XMP 元数据读取

AI 使用建议

• 推荐工作流模式：AI 助手应将全景项目组织为「Viewer 核心配置 → 适配器选择 → 插件组合 → 标记定义」的结构。初始用 EquirectangularAdapter + MarkersPlugin + GalleryPlugin 组合覆盖 80% 场景，后续按需添加 VirtualTourPlugin 或 GyroscopePlugin。
• 关键注意事项：① panorama 路径需确保 CORS 头正确配置（Access-Control-Allow-Origin: *）；② 所有时长/速度参数以毫秒为单位（speed: 1500 = 1.5 秒）或 '3rpm' 格式（每分钟旋转次数计算）；③ MarkersPlugin 的 CSS 样式需通过 className + 外部 CSS 控制，不建议内联大量样式；④ setPanorama() 后标记需重新设置，除非使用 VirtualTourPlugin 管理节点。
• 常用代码模式：
  • 基础查看器：new Viewer({ container, panorama }) + @photo-sphere-viewer/core/index.css
  • 标记：MarkersPlugin.withConfig({ markers: [{ id, position, image, tooltip }] })
  • 画廊：GalleryPlugin.withConfig({ items: [{ id, name, panorama, thumbnail }] })
  • 导览：VirtualTourPlugin.withConfig({ nodes, startNodeId, positionMode: 'manual' })
  • 动画：viewer.animate({ yaw, pitch, zoom, speed: 1500 })
  • 获取插件：viewer.getPlugin(MarkersPlugin).addMarker(...)

相关技能

• cesiumjs — 3D 地球与大规模场景可视化：../../gis/cesiumjs/SKILL.md
• supersplat — 3D 高斯泼溅编辑器与查看器：../supersplat/SKILL.md

参考资源

• 官方文档：https://photo-sphere-viewer.js.org
• API 参考：https://photo-sphere-viewer.js.org/api/
• 在线演示：https://photo-sphere-viewer.js.org/demos/
• Playground：https://photo-sphere-viewer.js.org/playground.html
• GitHub 仓库：https://github.com/mistic100/Photo-Sphere-Viewer
• 发布说明：https://github.com/mistic100/Photo-Sphere-Viewer/releases
• React wrapper：https://www.npmjs.com/package/react-photo-sphere-viewer
• 中文教程（znlgis）：https://znlgis.github.io/3d/Photo-Sphere-Viewer/
• NPM（core）：https://www.npmjs.com/package/@photo-sphere-viewer/core