<!-- Three.js 带深度信息的全景VR应用 - 功能描述与技术要点
一、项目功能概述
1. 核心功能
这是一个基于Three.js的WebGL全景查看器，具有以下主要功能：

全景展示：将2D全景图像投影到3D球体内表面，创建沉浸式的全景观看体验

深度增强：通过深度图（位移贴图）技术，为平面全景图像添加3D深度感知

VR支持：集成WebXR API，支持VR头戴式设备（如Oculus Quest、HTC Vive等）

响应式设计：自动适应不同屏幕尺寸和设备像素比

交互体验：

VR模式下：用户可通过头部移动自由观察全景

非VR模式下：自动旋转和平移动画展示深度效果

2. 用户体验流程
页面加载时显示深灰色背景

异步加载全景图和对应的深度图

资源加载完成后显示具有3D深度的全景球体

用户可选择进入VR模式或直接在浏览器中查看

非VR模式下球体缓慢旋转并轻微移动，突出深度效果

二、主要技术实现
1. Three.js核心架构
javascript
// 三大核心组件
scene        // 3D场景容器 - 存放所有要渲染的对象
camera       // 透视相机 - 定义观察视角和投影方式
renderer     // WebGL渲染器 - 将3D场景渲染到2D画布
2. 全景球体创建技术
几何体配置
javascript
new THREE.SphereGeometry(6, 256, 256)
// 参数说明：
// 半径6：适中的观看距离
// 细分256x256：高精度几何体，确保位移贴图效果平滑
材质配置
javascript
new THREE.MeshStandardMaterial({
    side: THREE.BackSide,          // 渲染内表面（全景需从内部观看）
    displacementScale: -4.0        // 负值：向内位移，模拟真实深度
})
3. 深度图技术实现
原理说明
深度图：单通道灰度图像，记录场景中每个像素的深度信息

白色（255）：表示"近"或"高"的区域

黑色（0）：表示"远"或"低"的区域

中间灰度：根据亮度值插值的中间深度

技术实现
javascript
// 位移贴图（Displacement Mapping）
sphere.material.displacementMap = depthTexture;
// 根据深度图像素的亮度值移动对应顶点的位置
// 创造凹凸表面效果，无需增加实际几何复杂度
4. 纹理加载与管理
javascript
const manager = new THREE.LoadingManager();
const loader = new THREE.TextureLoader(manager);

// 关键优化配置
texture.minFilter = THREE.NearestFilter;    // 保持纹理清晰度
texture.generateMipmaps = false;            // 禁用Mipmap（全景图不需要）
texture.colorSpace = THREE.SRGBColorSpace;  // 正确的颜色空间
5. WebXR/VR集成
VR系统初始化
javascript
renderer.xr.enabled = true;                           // 启用XR功能
renderer.xr.setReferenceSpaceType('local');          // 设置参考空间类型
VRButton.createButton(renderer);                      // 创建VR进入按钮
参考空间类型说明
'local'：原点在用户头部初始位置，适合站立/坐姿体验

'local-floor'：原点在地板平面，支持房间尺度VR

'viewer'：原点跟随用户头部，最简单的参考空间

6. 动画与渲染循环
渲染循环机制
javascript
renderer.setAnimationLoop(animate);  // 替代传统的requestAnimationFrame
// 每帧自动调用animate()函数
智能动画逻辑
javascript
if (renderer.xr.isPresenting === false) {
    // 仅非VR模式添加动画，避免VR晕动症
    sphere.rotation.y += 0.001;  // 缓慢旋转
    // 轻微平移动画展示深度效果
}
7. 性能优化策略
优化点	技术实现	效果
几何体复杂度	256x256细分	平衡视觉质量与性能
纹理过滤	NearestFilter	保持图像清晰，避免模糊
Mipmap处理	禁用generateMipmaps	减少内存占用和加载时间
设备适配	setPixelRatio(devicePixelRatio)	适配高DPI屏幕
资源管理	LoadingManager	确保所有资源加载完成再显示
三、关键技术要点详解
1. 位移贴图 vs 法线贴图
位移贴图：实际修改顶点位置，创建真正的几何凹凸

法线贴图：只改变表面法线方向，模拟光影效果

本项目使用位移贴图，因为它能：

创建真实的3D深度感

与视差产生正确的交互效果

在VR中提供更真实的深度感知

2. 全景投影的数学原理
text
球形坐标 ↔ 平面图像坐标
(θ, φ) → (u, v) 映射：
u = 0.5 + θ/(2π)
v = 0.5 + φ/π
这种映射将球面坐标转换为2D纹理坐标，实现全景图的无缝包裹。

3. VR模式下的渲染优化
异步时间扭曲：WebXR运行时自动处理

多视口渲染：为每只眼睛渲染不同视角

预测追踪：基于头部运动预测下一帧位置

4. 深度图生成技术
本项目使用的深度图通常通过以下方式生成：

立体相机拍摄：左右眼图像计算视差

激光雷达扫描：精确的深度测量

AI算法估算：从单张图像估计深度

四、应用场景与扩展
1. 适用场景
虚拟旅游：博物馆、景点、房地产展示

教育培训：解剖学、地理学、建筑学教学

产品展示：汽车、家具等360度查看

艺术展览：沉浸式艺术体验

2. 可能的扩展功能
交互功能
javascript
// 添加点击热点
const hotspot = new THREE.Mesh(geometry, material);
hotspot.userData = { url: 'info.html' };  // 自定义数据
多场景切换
javascript
// 预加载多个全景场景
const scenes = {
    'lobby': { texture: 'lobby.jpg', depth: 'lobby_depth.jpg' },
    'garden': { texture: 'garden.jpg', depth: 'garden_depth.jpg' }
};
音频集成
javascript
// 空间音频（Web Audio API）
const listener = new THREE.AudioListener();
camera.add(listener);
const sound = new THREE.PositionalAudio(listener);
sphere.add(sound);
3. 性能监控与调试
javascript
// 添加性能统计
import Stats from 'three/addons/libs/stats.module.js';
const stats = new Stats();
document.body.appendChild(stats.dom);
五、兼容性与注意事项
1. 浏览器兼容性
WebXR支持：Chrome 79+、Firefox Reality、Oculus Browser

回退方案：非VR设备自动降级为普通3D查看器

移动端适配：支持陀螺仪控制的移动端全景查看

2. 性能注意事项
内存使用：高分辨率全景图可能占用大量内存

GPU要求：位移贴图需要足够的顶点处理能力

网络优化：建议使用WebP格式压缩纹理 -->


<!DOCTYPE html>
<!-- 声明文档类型为HTML5 -->
<html lang="en">
	<head>
		<!-- 页面标题：使用中文描述内容 -->
		<title>Three.js虚拟现实 - 带深度信息的全景图像</title>
		<!-- 设置文档字符编码为UTF-8，支持多语言字符显示 -->
		<meta charset="utf-8">
		<!-- 响应式网页设计视口设置： 
			 width=device-width: 视口宽度等于设备宽度
			 initial-scale=1.0: 初始缩放比例为1倍
			 user-scalable=no: 禁止用户手动缩放（在VR/全景应用中常见，避免缩放干扰体验） -->
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
		<!-- 引入外部CSS样式表文件，用于页面样式定义 -->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>
	<body>
		<!-- Three.js渲染器的主要容器元素，WebGL画布将被插入到此div中 -->
		<div id="container"></div>

		<!-- 页面信息展示区域：显示项目信息和版权信息 -->
		<div id="info">
			<!-- 项目技术栈信息 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> 虚拟现实 - 带深度图的全景展示<br />
			<!-- 项目作者和图片来源信息 -->
			项目作者：<a href="https://orfleisher.com" target="_blank" rel="noopener">@juniorxsound</a>。全景图来源：<a href="https://krpano.com/examples/?depthmap" target="_blank" rel="noopener">krpano深度图示例</a>。<br />
			<!-- 项目功能说明 -->
			本项目展示了使用深度图的全景3D效果，通过位移贴图技术将2D全景图转换为具有深度感的3D场景。
		</div>

		<!-- ES模块导入映射（Import Maps）：现代浏览器中的模块解析配置 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 主JavaScript代码模块，使用ES6模块语法 -->
		<script type="module">

			// 导入Three.js核心库的所有功能
			// Three.js是一个流行的WebGL 3D图形库
			import * as THREE from 'three';
			
			// 从Three.js附加组件中导入VR按钮组件
			// 这个组件会创建一个进入VR模式的按钮
			import { VRButton } from 'three/addons/webxr/VRButton.js';

			// 全局变量声明（在函数外部声明，以便在多个函数中访问）
			let camera;      // 3D相机对象，定义观察3D场景的视角
			let scene;       // 3D场景对象，包含所有要渲染的3D对象
			let renderer;    // WebGL渲染器，负责将3D场景绘制到2D画布上
			let sphere;      // 全景球体网格对象，将全景图映射到球体内部
			let clock;       // Three.js时钟对象，用于时间跟踪和动画计时

			// 程序入口点：调用初始化函数开始设置3D场景
			init();

			/**
			 * 初始化函数
			 * 这是整个应用程序的起点，负责创建和配置所有必要的Three.js组件
			 * 包括场景、相机、渲染器、光照、几何体、材质和纹理
			 */
			function init() {

				// 获取HTML文档中的容器元素
				// 这个div将作为Three.js渲染器的挂载点
				const container = document.getElementById( 'container' );

				// 创建Three.js时钟对象
				// 时钟用于跟踪从创建开始经过的时间，常用于动画和基于时间的计算
				clock = new THREE.Clock();

				// 创建3D场景对象
				// 场景是所有3D对象（网格、光源、相机等）的容器
				scene = new THREE.Scene();
				
				// 设置场景的背景颜色
				// 0x101010是十六进制颜色表示，对应深灰色（RGB: 16, 16, 16）
				// 在VR应用中，深色背景可以减少视觉干扰和眼睛疲劳
				scene.background = new THREE.Color( 0x101010 );

				// 创建环境光并添加到场景中
				// 环境光均匀地照亮场景中的所有物体，没有明确的方向
				// 参数1: 光的颜色（0xffffff = 白色）
				// 参数2: 光的强度（3.0 = 3倍标准强度，确保全景图足够明亮）
				const light = new THREE.AmbientLight( 0xffffff, 3 );
				scene.add( light );

				// 创建透视投影相机
				// 透视相机模拟人眼的视觉效果，远处的物体看起来更小
				camera = new THREE.PerspectiveCamera( 
					70,                            // 视野角度（Field of View）
				                                   // 70度是一个自然的视野角度，接近人眼舒适范围
					window.innerWidth / window.innerHeight, // 纵横比（Aspect Ratio）
				                                   // 根据浏览器窗口尺寸计算，确保渲染不变形
					1,                             // 近裁剪面（Near Clipping Plane）
				                                   // 距离相机1个单位以内的物体不会被渲染
					2000                           // 远裁剪面（Far Clipping Plane）
				                                   // 距离相机2000个单位以外的物体不会被渲染
				);
				// 将相机添加到场景中（相机本身也是一个3D对象）
				scene.add( camera );

				// =============== 创建全景球体 ===============
				// 全景展示的核心：将全景图映射到球体的内表面
				// 当用户在球体内部观看时，会看到无缝的全景环境

				// 创建球体几何体
				// 参数说明：
				// 6: 球体半径（单位）。半径大小影响全景的"包裹感"，6是一个适中的值
				// 256: 宽度分段数（经度方向）。值越高，球体表面越平滑，但性能开销越大
				// 256: 高度分段数（纬度方向）。高分段数对于位移贴图效果很重要
				const panoSphereGeo = new THREE.SphereGeometry( 6, 256, 256 );

				// 创建球体材质
				// 使用MeshStandardMaterial以获得PBR（基于物理的渲染）效果
				const panoSphereMat = new THREE.MeshStandardMaterial( {
					side: THREE.BackSide,            // 渲染球体的内表面
				                                   // 对于全景应用，我们需要从球体内部观看
				                                   // BackSide表示只渲染多边形的背面
					
					displacementScale: - 4.0         // 位移贴图的缩放系数
				                                   // -4.0表示：
				                                   //   1. 负号：向内位移（凹陷效果）
				                                   //   2. 4.0：位移强度因子
				                                   // 深度图的白色区域位移最大，黑色区域位移最小
				} );

				// 创建网格（Mesh）对象：几何体 + 材质 = 可渲染的3D对象
				sphere = new THREE.Mesh( panoSphereGeo, panoSphereMat );

				// =============== 纹理加载系统 ===============
				// 使用Three.js的纹理加载器加载全景图和对应的深度图

				// 创建加载管理器
				// LoadingManager可以跟踪多个资源的加载状态，并在所有资源加载完成后触发回调
				const manager = new THREE.LoadingManager();
				
				// 创建纹理加载器实例，并传入加载管理器进行资源管理
				const loader = new THREE.TextureLoader( manager );

				// 加载全景图纹理（颜色纹理）
				// './textures/kandao3.jpg' 是全景图像文件的相对路径
				loader.load( './textures/kandao3.jpg', function ( texture ) {
					// 加载完成后的回调函数，参数texture是加载的纹理对象
					
					// 设置纹理的颜色空间为sRGB
					// sRGB是标准的颜色空间，确保颜色在不同设备上显示一致
					// Three.js r152+版本开始需要显式设置颜色空间
					texture.colorSpace = THREE.SRGBColorSpace;
					
					// 设置纹理的缩小过滤器（当纹理被缩小时如何采样）
					// NearestFilter使用最近邻采样，保持纹理清晰，避免模糊
					// 适合用于需要保持清晰度的全景图
					texture.minFilter = THREE.NearestFilter;
					
					// 禁用Mipmap生成
					// Mipmap是纹理的预缩小版本，用于改善远处物体的渲染质量
					// 但在全景应用中，我们通常希望保持最高清晰度，所以禁用
					texture.generateMipmaps = false;
					
					// 将加载的纹理赋给球体材质的map属性
					// map属性是材质的基础颜色纹理
					sphere.material.map = texture;

				} );

				// 加载深度图纹理（位移贴图）
				// 深度图是一张灰度图像，其中白色表示"近"，黑色表示"远"
				loader.load( './textures/kandao3_depthmap.jpg', function ( depth ) {
					// 加载完成后的回调函数，参数depth是深度图纹理对象
					
					// 设置深度图的缩小过滤器
					// 同样使用NearestFilter保持深度图的清晰度
					depth.minFilter = THREE.NearestFilter;
					
					// 禁用深度图的Mipmap生成
					// 深度图需要精确的灰度值，模糊会影响位移效果
					depth.generateMipmaps = false;
					
					// 将深度图赋给球体材质的displacementMap属性
					// displacementMap会根据纹理的灰度值移动几何体的顶点
					// 灰度值越高（越白），位移越大
					sphere.material.displacementMap = depth;

				} );

				// 设置加载管理器的完成回调
				// 当所有通过这个管理器加载的资源都完成后，会执行这个函数
				manager.onLoad = function () {
					// 只有当全景图和深度图都加载完成后，才将球体添加到场景
					// 这样可以避免显示未加载纹理的白色球体
					scene.add( sphere );
				};

				// =============== 渲染器设置 ===============
				// 创建WebGL渲染器，这是Three.js与WebGL API交互的核心

				// 创建WebGL渲染器实例
				renderer = new THREE.WebGLRenderer();
				
				// 设置设备像素比
				// 在高DPI设备（如Retina显示屏）上，devicePixelRatio > 1
				// 设置这个值可以确保渲染清晰，不模糊
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器的输出canvas大小
				// 使用浏览器窗口的完整宽度和高度
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环函数
				// animate函数将被每一帧调用，用于更新场景和重新渲染
				// 这是Three.js的渲染循环机制
				renderer.setAnimationLoop( animate );
				
				// 启用WebXR（扩展现实）功能
				// WebXR是用于VR和AR的Web API标准
				renderer.xr.enabled = true;
				
				// 设置XR参考空间类型为'local'
				// 'local'参考空间意味着：
				// - 原点在用户头部初始位置
				// - 适用于站立或坐姿的VR体验
				// - Y轴向上，支持基本的头部追踪
				renderer.xr.setReferenceSpaceType( 'local' );
				
				// 将渲染器的DOM元素（canvas画布）添加到容器div中
				// 这样Three.js的渲染输出就会显示在网页上
				container.appendChild( renderer.domElement );

				// 创建VR按钮并添加到页面
				// VRButton.createButton()会创建一个按钮，点击后进入VR模式
				// 按钮会根据浏览器支持的VR API自动调整（WebXR或旧版WebVR）
				document.body.appendChild( VRButton.createButton( renderer ) );

				// =============== 事件监听器 ===============
				// 添加窗口大小变化事件监听器
				// 当浏览器窗口大小改变时，调整相机和渲染器设置
				window.addEventListener( 'resize', onWindowResize );

			}

			/**
			 * 窗口大小变化事件处理函数
			 * 当用户调整浏览器窗口大小时，需要更新相机和渲染器的设置
			 * 以保持正确的纵横比和渲染尺寸
			 */
			function onWindowResize() {
				// 更新相机的纵横比
				// 窗口大小变化后，需要重新计算宽度/高度比例
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 更改相机参数后，必须调用updateProjectionMatrix()来应用更改
				// 投影矩阵定义了3D空间如何投影到2D屏幕上
				camera.updateProjectionMatrix();

				// 更新渲染器的尺寸以匹配新的窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			/**
			 * 动画循环函数
			 * 这是Three.js的主渲染循环，在每一帧都会被调用
			 * 函数中更新场景状态，然后渲染新的一帧
			 */
			function animate() {

				// 检查当前是否处于VR呈现模式
				// renderer.xr.isPresenting表示用户是否正在使用VR头显查看场景
				if ( renderer.xr.isPresenting === false ) {
					// 如果不在VR模式中，添加一些轻微的动画效果
					// 这有助于展示深度贴图的效果，让用户看到3D感
					
					// 获取从时钟启动到现在经过的时间（秒）
					// 用于创建基于时间的动画
					const time = clock.getElapsedTime();

					// 缓慢旋转球体
					// 每帧旋转0.001弧度，创建一个缓慢的旋转效果
					// 这使全景图看起来像是在缓慢转动
					sphere.rotation.y += 0.001;
					
					// 在X轴上添加正弦波运动
					// Math.sin(time)产生-1到1之间的波动
					// 乘以0.2限制运动幅度，避免运动过于剧烈
					// 这种轻微的运动可以增强3D深度感
					sphere.position.x = Math.sin( time ) * 0.2;
					
					// 在Z轴上添加余弦波运动
					// 与X轴运动相位差90度，形成圆周运动
					sphere.position.z = Math.cos( time ) * 0.2;

					// 注意：在VR模式下，我们通常不添加这些动画
					// 因为VR模式下用户通过头部移动来控制视角
					// 自动动画可能导致晕动症（VR sickness）
				}

				// 渲染场景
				// 这是最关键的步骤：将3D场景通过相机视角渲染到2D画布上
				// 参数1: 要渲染的场景对象
				// 参数2: 用于渲染的相机对象
				renderer.render( scene, camera );
			}

		</script>
	</body>
</html>