<!-- 代码功能概述
这是一个基于 Three.js + WebXR 的增强现实（AR）应用，专门演示实时环境光照估计技术。应用通过手机摄像头分析真实环境的光照条件，并将这些光照数据应用到3D物体上，使虚拟物体看起来像是真实存在于用户的环境中。

核心功能
AR场景启动

提供"进入AR"按钮，一键启动WebXR会话

自动检测设备AR兼容性和浏览器支持

实时环境光照估计

通过手机摄像头分析真实环境的光照特性

自动检测主光源方向、强度和颜色

生成动态的环境立方体贴图用于反射效果

PBR材质展示

创建3×3网格的球体（共9个）

每个球体展示不同的粗糙度和金属度组合

粗糙度：从上到下递增（光滑 → 粗糙）

金属度：从左到右递增（非金属 → 金属）

交互功能

用户可在AR环境中点击屏幕重新放置球体组

球体会被放置到用户点击位置的稍前方

自适应显示

响应式设计，自动适应不同屏幕尺寸

高DPI屏幕优化，确保清晰显示

工作流程
主要技术点
1. WebXR API
功能：现代浏览器的AR/VR标准接口

实现：

renderer.xr.enabled = true 启用WebXR支持

ARButton.createButton() 创建标准化的AR启动按钮

optionalFeatures: ['light-estimation'] 请求光照估计权限

2. 光照估计系统
技术：XREstimatedLight 类

原理：

通过设备传感器和摄像头分析环境

估计光源方向、颜色、强度

生成环境立方体贴图

事件处理：

estimationstart：开始接收光照数据

estimationend：光照估计停止

3. PBR渲染（基于物理的渲染）
材质：MeshStandardMaterial

参数：

roughness：粗糙度（0=镜面，1=漫反射）

metalness：金属度（0=非金属，1=金属）

color：基础颜色

环境反射：scene.environment 设置环境贴图

4. HDR环境贴图
加载器：UltraHDRLoader

格式：.hdr.jpg 格式的HDR图像

映射方式：EquirectangularReflectionMapping

作用：提供高质量的默认环境反射

5. 场景管理
场景图结构：

text
Scene
├── HemisphereLight (默认光源)
├── XREstimatedLight (动态光源)
├── Group (球体组)
│   ├── Mesh × 9 (9个球体)
└── Controller (XR控制器)
6. 相机系统
类型：PerspectiveCamera 透视相机

参数：70°视野，0.01-20单位裁剪范围

自适应：根据窗口大小动态调整宽高比

7. 渲染优化
抗锯齿：antialias: true

透明背景：alpha: true

像素比：setPixelRatio(window.devicePixelRatio)

动画循环：setAnimationLoop() 替代传统RAF

8. 交互系统
控制器：renderer.xr.getController(0)

事件监听：select 事件处理重新定位

位置计算：applyMatrix4(controller.matrixWorld)

9. 资源加载与管理
异步加载：HDR纹理的异步加载

错误处理：光照估计失败时的降级方案

资源切换：默认与估计环境贴图的动态切换

10. 移动设备适配
视口设置：禁止用户缩放，确保稳定AR体验

触摸交互：针对触摸屏优化的交互方式

性能考虑：平衡视觉效果与移动设备性能

技术难点与解决方案
难点1：实时光照估计的精度
解决方案：使用XREstimatedLight类，它封装了设备传感器的数据处理

优势：无需手动处理传感器数据，直接获得高质量光照估计

难点2：AR会话的生命周期管理
解决方案：事件驱动架构（estimationstart/estimationend）

优势：清晰的状态切换，避免资源泄漏

难点3：跨设备兼容性
解决方案：

使用WebXR标准API

提供降级方案（默认HDR环境）

可选特性请求

优势：在支持程度不同的设备上都能运行

难点4：性能优化
解决方案：

合理的几何体复杂度（32×32分段）

使用Group批量管理物体

按需加载资源

优势：在移动设备上保持流畅的60fps渲染

应用场景
AR产品展示：在真实环境中预览产品的材质效果

室内设计：查看家具在不同光照条件下的外观

教育培训：理解PBR材质和光照的工作原理

游戏开发：测试游戏模型在真实环境中的表现

电商应用：AR试穿/试用，查看真实的光照反射效果

技术栈总结
技术组件	作用	关键类/API
Three.js	3D渲染引擎	Scene, Camera, WebGLRenderer
WebXR	AR标准接口	XRSession, XRButton
光照估计	环境分析	XREstimatedLight
材质系统	物理渲染	MeshStandardMaterial
纹理加载	HDR处理	UltraHDRLoader
交互系统	用户输入	XRController, select事件 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面标题：描述页面内容和功能
			更新为中文：Three.js AR - 光照估计演示
		-->
		<title>Three.js AR - 光照估计技术演示</title>
		<!-- 
			字符编码设置：UTF-8确保支持中文字符
		-->
		<meta charset="utf-8">
		<!-- 
			视口元标签：针对移动设备优化
			width=device-width: 宽度等于设备宽度
			initial-scale=1.0: 初始缩放比例为1
			user-scalable=no: 禁止用户手动缩放，确保AR体验稳定
		-->
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
		<!-- 
			外部CSS样式表链接：用于页面样式美化
			type="text/css": 指定MIME类型为CSS
			rel="stylesheet": 定义当前文档与链接资源的关系为样式表
			href="main.css": 样式表文件路径
		-->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>
	<body>

		<!-- 
			信息展示区域：显示页面标题、描述和操作指引
			id="info": 用于CSS样式和JavaScript操作的唯一标识符
			更新为中文内容，提供更友好的用户指引
		-->
		<div id="info">
			<!-- 
				Three.js官方链接：点击跳转到Three.js官网
				target="_blank": 在新标签页中打开链接
				rel="noopener": 安全特性，防止新页面访问原页面的window对象
			-->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> 
			AR增强现实 - 实时环境光照估计技术演示<br/>
			<br/>
			<small>支持设备：具备AR功能的iOS/Android智能手机</small>
		</div>

		<!-- 
			模块导入映射配置（Import Maps）
			作用：定义JavaScript模块的导入路径映射
			允许在代码中使用简化的导入路径，而不需要使用完整的URL
			这是现代浏览器支持的ES模块特性
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块
			type="module": 声明这是一个ES6模块，支持模块化导入导出
			模块中的代码在严格模式下运行，有独立的作用域
		-->
		<script type="module">

			// ========== 模块导入区域 ==========
			// 使用ES6模块语法导入所需依赖
			
			// 导入Three.js核心库的所有功能并命名为THREE
			// Three.js是一个功能强大的3D图形渲染库
			import * as THREE from 'three';
			
			// 导入UltraHDRLoader：专门用于加载HDR（高动态范围）图像
			// HDR图像包含更广泛的亮度信息，适合真实感渲染
			import { UltraHDRLoader } from 'three/addons/loaders/UltraHDRLoader.js';
			
			// 导入ARButton：创建WebXR AR会话按钮的辅助工具
			// 封装了复杂的WebXR API调用，提供简单的AR启动接口
			import { ARButton } from 'three/addons/webxr/ARButton.js';
			
			// 导入XREstimatedLight：WebXR光照估计的核心组件
			// 可以从AR设备（如手机摄像头）获取环境光照信息
			import { XREstimatedLight } from 'three/addons/webxr/XREstimatedLight.js';

			// ========== 全局变量声明 ==========
			// 这些变量将在多个函数中共享使用
			
			// Three.js三大核心对象：
			let camera;      // 相机：定义观察3D场景的视角和投影方式
			let scene;       // 场景：包含所有3D对象的容器
			let renderer;    // 渲染器：负责将3D场景渲染到2D画布上
			
			let controller;  // XR控制器：处理AR/VR设备的输入交互
			
			// 默认环境贴图：当AR光照估计不可用时使用的后备环境贴图
			let defaultEnvironment;

			// ========== 初始化函数调用 ==========
			// 页面加载完成后立即执行初始化
			init();

			/**
			 * 初始化函数 - 整个应用的入口点
			 * 职责：创建和配置所有Three.js对象、设置事件监听器、加载资源
			 * 这是一个自执行函数，组织所有初始化逻辑
			 */
			function init() {

				// ========== 创建页面容器 ==========
				// 创建一个div元素作为Three.js渲染器的容器
				// 这允许我们更好地控制渲染器的位置和样式
				const container = document.createElement( 'div' );
				
				// 将容器添加到body元素的末尾
				// 这样渲染器将在其他HTML元素之后显示
				document.body.appendChild( container );

				// ========== 创建Three.js场景 ==========
				// 场景是所有3D对象的根容器，类似一个虚拟世界
				// 可以添加灯光、物体、相机等所有可见和不可见对象
				scene = new THREE.Scene();
				// 注意：Three.js的场景默认使用右手坐标系
				// X轴向右，Y轴向上，Z轴朝向观察者

				// ========== 创建透视相机 ==========
				// 透视相机模拟人眼的视角，有近大远小的效果
				// 参数说明：
				// 1. 视野角度(FOV)：70度，接近人眼的自然视野
				// 2. 宽高比：根据窗口尺寸动态计算
				// 3. 近裁剪面：0.01，相机能看到的最小距离
				// 4. 远裁剪面：20，相机能看到的20单位外的物体将被裁剪
				camera = new THREE.PerspectiveCamera( 
					70, 
					window.innerWidth / window.innerHeight, 
					0.01, 
					20 
				);
				// 透视相机默认位置在(0,0,0)，朝向Z轴负方向

				// ========== 创建默认光源（备用光源） ==========
				// HemisphereLight（半球光）模拟天空和地面的环境光照
				// 在没有AR光照估计时的备用光源
				// 参数说明：
				// 1. 天空颜色：白色(0xffffff)，模拟天空光
				// 2. 地面颜色：浅蓝色(0xbbbbff)，模拟地面反射光
				// 3. 光照强度：1.0，标准强度
				const defaultLight = new THREE.HemisphereLight( 0xffffff, 0xbbbbff, 1 );
				
				// 设置光源位置：稍微倾斜以创建更自然的光照方向
				// 参数：X轴0.5，Y轴1.0，Z轴0.25
				defaultLight.position.set( 0.5, 1, 0.25 );
				
				// 将默认光源添加到场景中
				// 此时光源立即生效，照亮场景中的所有物体
				scene.add( defaultLight );

				// ========== 创建WebGL渲染器 ==========
				// WebGLRenderer是Three.js的核心渲染组件
				// 使用WebGL API在HTML Canvas上渲染3D图形
				// 配置选项：
				// 1. antialias: true - 开启抗锯齿，使边缘更平滑
				// 2. alpha: true - 启用透明背景，允许显示页面背景
				renderer = new THREE.WebGLRenderer( { antialias: true, alpha: true } );
				
				// 设置设备像素比：确保在高DPI屏幕（如Retina）上清晰显示
				// window.devicePixelRatio获取屏幕的物理像素与CSS像素比
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为浏览器窗口尺寸
				// 确保3D场景填满整个视口
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环函数：这是Three.js的渲染核心
				// animate函数将在每次屏幕刷新时被调用（通常60fps）
				// 替代传统的requestAnimationFrame手动管理
				renderer.setAnimationLoop( animate );
				
				// 启用WebXR支持：这是AR功能的基础
				// 开启后，渲染器可以处理XR设备的输入和输出
				renderer.xr.enabled = true;
				
				// 将渲染器的DOM元素（canvas画布）添加到容器中
				// 此时canvas元素被插入到页面，可以显示3D内容
				container.appendChild( renderer.domElement );

				// ========== XR光照估计系统设置 ==========
				// 创建XREstimatedLight实例，但不立即添加到场景
				// 因为在AR会话开始前，它没有可用的光照数据
				// 参数：需要传入渲染器以访问WebXR会话
				const xrLight = new XREstimatedLight( renderer );
				
				// XREstimatedLight的工作原理：
				// 1. 通过设备的摄像头和传感器分析真实环境
				// 2. 估计环境的主光源方向、强度和颜色
				// 3. 生成环境立方体贴图用于反射效果
				// 4. 实时更新以匹配用户在环境中的移动

				// ========== 监听光照估计开始事件 ==========
				// 当AR会话开始并且系统开始提供光照估计数据时触发
				xrLight.addEventListener( 'estimationstart', () => {
					// 这个箭头函数在光照估计开始时执行
					
					// 步骤1：将估计的光源添加到场景
					// 此时xrLight包含从真实环境估计的光照数据
					scene.add( xrLight );
					
					// 步骤2：从场景中移除默认光源
					// 因为现在有更准确的真实环境光照
					scene.remove( defaultLight );
					
					// 步骤3：应用估计的环境贴图
					// XREstimatedLight不仅提供光源，还提供环境立方体贴图
					// 这个贴图用于PBR（基于物理的渲染）材质的环境反射
					if ( xrLight.environment ) {
						// 将场景的环境属性设置为估计的环境贴图
						// 这会影响所有使用PBR材质的物体的反射效果
						scene.environment = xrLight.environment;
						// 注意：环境贴图是HDR格式，包含完整的光照信息
					}
					
					// 此时场景的光照和反射完全基于真实环境
					// 3D物体将看起来像是真实存在于用户的环境中
					console.log('光照估计已启动：使用真实环境光照');
				} );

				// ========== 监听光照估计结束事件 ==========
				// 当AR会话结束或光照估计停止时触发
				xrLight.addEventListener( 'estimationend', () => {
					// 这个箭头函数在光照估计结束时执行
					
					// 步骤1：重新添加默认光源到场景
					// 作为没有真实环境光照时的备用方案
					scene.add( defaultLight );
					
					// 步骤2：从场景中移除估计光源
					// 因为它不再提供有效的光照数据
					scene.remove( xrLight );
					
					// 步骤3：恢复默认环境贴图
					// 切换回预加载的HDR环境贴图
					scene.environment = defaultEnvironment;
					
					// 此时场景恢复到AR会话前的状态
					console.log('光照估计已结束：恢复默认光照');
				} );

				// ========== 加载默认HDR环境贴图 ==========
				// 创建UltraHDRLoader实例
				// UltraHDRLoader专门用于加载HDR图像格式
				// HDR（High Dynamic Range）图像包含更宽的亮度范围
				// 适合模拟真实世界的光照环境
				new UltraHDRLoader()
					// 设置纹理文件的目录路径
					// 'textures/equirectangular/' 相对于HTML文件的路径
					.setPath( 'textures/equirectangular/' )
					
					// 加载指定的HDR图像文件
					// 'royal_esplanade_2k.hdr.jpg' 是一个2K分辨率的HDR环境贴图
					// 这是一个等距柱状投影的HDR图像，覆盖360度环境
					.load( 'royal_esplanade_2k.hdr.jpg', function ( texture ) {
						// 加载完成后的回调函数
						// texture参数是加载成功的Three.js纹理对象
						
						// 设置纹理映射方式为等距柱状反射映射
						// 这种映射方式将2D的HDR图像包裹在虚拟球体内部
						// 物体表面的反射会基于这个球体内的图像内容
						texture.mapping = THREE.EquirectangularReflectionMapping;
						
						// 存储为默认环境贴图变量
						// 在AR会话非活动时使用
						defaultEnvironment = texture;
						
						// 立即应用到场景环境
						// 初始状态下使用这个高质量的HDR环境贴图
						scene.environment = defaultEnvironment;
						
						// 注意：纹理加载是异步的
						// 在加载完成前，场景可能没有环境贴图
						console.log('默认HDR环境贴图加载完成');
					}, 
					// 可选的加载进度回调（未实现）
					undefined, 
					// 可选的加载错误回调（未实现）
					undefined );

				// ========== 创建AR启动按钮 ==========
				// 使用ARButton.createButton创建标准化的AR按钮
				// 参数1: renderer - 需要绑定AR会话的渲染器
				// 参数2: 配置对象
				document.body.appendChild( 
					ARButton.createButton( renderer, { 
						// optionalFeatures: 可选特性数组
						// 'light-estimation' 必须包含在可选或必需特性中
						// 才能启用WebXR的光照估计功能
						optionalFeatures: [ 'light-estimation' ] 
					} ) 
				);
				// ARButton完成的工作：
				// 1. 检测浏览器是否支持WebXR
				// 2. 创建符合平台规范的AR按钮（iOS/Android）
				// 3. 处理AR会话的启动和结束
				// 4. 处理权限请求和设备兼容性

				// ========== 创建3D物体 - 球体网格 ==========
				// 创建球体几何体：用于展示不同材质属性的网格
				// 参数说明：
				// 1. 半径: 0.175单位（Three.js中的单位是抽象的）
				// 2. 宽度分段: 32，控制球体平滑度
				// 3. 高度分段: 32，控制球体平滑度
				// 分段数越高，球体越平滑，但性能开销越大
				const ballGeometry = new THREE.SphereGeometry( 0.175, 32, 32 );
				
				// 创建组(Group)：用于组织和管理多个球体
				// 组可以将多个物体作为一个整体进行变换（移动、旋转、缩放）
				const ballGroup = new THREE.Group();
				
				// 设置球体组的初始位置：相机前方2单位处
				// Z轴负方向是相机的正前方（右手坐标系）
				ballGroup.position.z = -2;

				// 定义网格布局参数
				const rows = 3;    // 行数：控制粗糙度变化维度
				const cols = 3;    // 列数：控制金属度变化维度

				// 创建3x3的球体网格，展示不同的材质属性
				// 外层循环：控制行（粗糙度变化）
				for ( let i = 0; i < rows; i ++ ) {
					// 内层循环：控制列（金属度变化）
					for ( let j = 0; j < cols; j ++ ) {
						// 创建MeshStandardMaterial（标准网格材质）
						// 这是一种PBR（基于物理的渲染）材质
						// 会根据环境光照产生真实的反射和折射效果
						const ballMaterial = new THREE.MeshStandardMaterial( {
							color: 0xdddddd,        // 基础颜色：浅灰色
							roughness: i / rows,    // 粗糙度：从0到1递增
							metalness: j / cols     // 金属度：从0到1递增
						} );
						// 粗糙度解释：0表示完全光滑（镜子），1表示完全粗糙（白垩）
						// 金属度解释：0表示非金属（塑料），1表示金属（金属）
						
						// 创建网格对象：将几何体与材质结合
						const ballMesh = new THREE.Mesh( ballGeometry, ballMaterial );
						
						// 计算当前球体在网格中的位置
						// 公式解释：
						// (i + 0.5 - rows * 0.5) * 0.4
						// 1. i + 0.5: 将索引转换为中心位置
						// 2. - rows * 0.5: 使网格居中（减去一半宽度）
						// 3. * 0.4: 球体之间的间距
						ballMesh.position.set( 
							( i + 0.5 - rows * 0.5 ) * 0.4,  // X轴位置
							( j + 0.5 - cols * 0.5 ) * 0.4,  // Y轴位置
							0                                 // Z轴位置（在同一平面）
						);
						
						// 将球体添加到组中
						ballGroup.add( ballMesh );
					}
				}

				// 将球体组添加到场景中
				// 现在9个球体作为一个整体存在于3D场景中
				scene.add( ballGroup );

				// ========== 设置XR控制器交互 ==========
				/**
				 * 控制器选择事件处理函数
				 * 当用户在AR中执行"选择"操作时调用
				 * （通常是点击屏幕、扳机键或手势）
				 * 作用：将球体组重新定位到控制器的当前位置
				 */
				function onSelect() {
					// 计算新的球体组位置：
					// 1. 首先设置到控制器前方2单位处(0, 0, -2)
					// 2. 然后应用控制器的世界变换矩阵
					// 这样球体会出现在控制器指向的位置前方
					ballGroup.position.set( 0, 0, -2 ).applyMatrix4( controller.matrixWorld );
					
					// 设置球体组的旋转与控制器一致
					// 这样球体组会面向与控制器相同的方向
					ballGroup.quaternion.setFromRotationMatrix( controller.matrixWorld );
					
					// 实现效果：用户可以通过点击/选择操作将球体放置在任何位置
					console.log('球体组已重新定位');
				}

				// 获取XR控制器实例
				// 参数0表示第一个控制器（对于手机AR，通常只有一个控制器）
				controller = renderer.xr.getController( 0 );
				
				// 监听控制器的"select"事件
				// 当用户执行选择操作时调用onSelect函数
				controller.addEventListener( 'select', onSelect );
				
				// 将控制器添加到场景中（可选）
				// 如果取消注释，可以看到控制器的可视化表示
				// scene.add( controller );

				// ========== 窗口大小变化监听 ==========
				// 当浏览器窗口大小改变时，需要更新相机和渲染器
				// 以确保3D场景正确适应新的窗口尺寸
				window.addEventListener( 'resize', onWindowResize );
				
				// 初始化完成日志
				console.log('Three.js AR应用初始化完成');
				console.log('支持的功能：光照估计、环境反射、PBR材质、WebXR交互');

			}

			/**
			 * 窗口大小调整事件处理函数
			 * 当用户调整浏览器窗口大小时自动调用
			 * 确保3D场景始终正确适应窗口尺寸
			 */
			function onWindowResize() {
				// 更新相机宽高比
				// 宽高比 = 窗口宽度 / 窗口高度
				// 如果宽高比不正确，场景会被拉伸或压缩
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 在Three.js中，修改相机参数后必须调用此方法
				// 否则更改不会生效
				camera.updateProjectionMatrix();
				
				// 更新渲染器尺寸
				// 确保canvas画布与窗口大小一致
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 可选：性能考虑
				// 对于频繁的resize事件，可以考虑使用防抖(debounce)优化
				console.log('窗口大小已调整：' + window.innerWidth + 'x' + window.innerHeight);
			}

			/**
			 * 动画循环函数 - Three.js的核心
			 * 在每一帧自动调用，负责渲染当前场景状态
			 * 这是游戏和交互式3D应用的标准模式
			 * 
			 * 工作原理：
			 * 1. 浏览器准备绘制新帧时调用此函数
			 * 2. 函数执行所有渲染逻辑
			 * 3. 完成后浏览器显示新帧
			 * 4. 重复上述过程（通常60次/秒）
			 */
			function animate() {
				// 核心渲染调用
				// 参数1: scene - 要渲染的3D场景
				// 参数2: camera - 从哪个视角渲染场景
				// 内部完成的工作：
				// 1. 清理上一帧的绘制
				// 2. 计算所有物体的位置、旋转、缩放
				// 3. 应用所有材质和纹理
				// 4. 执行光照计算
				// 5. 将3D场景渲染到2D画布上
				renderer.render( scene, camera );
				
				// 注意：这里没有更新物体动画的代码
				// 因为本例中的物体是静态的
				// 如果需要动画，可以在这里更新物体位置/旋转
			}

			// ========== 额外的性能优化建议（注释） ==========
			// 1. 对于复杂的场景，可以使用LOD（Level of Detail）系统
			// 2. 考虑使用glTF格式的3D模型，而不是在代码中创建几何体
			// 3. 实现资源加载状态显示，改善用户体验
			// 4. 添加错误处理，特别是WebXR API可能因权限或兼容性失败
			// 5. 考虑移动设备的性能限制，特别是低端设备

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