<!-- Three.js WebXR AR 应用 - 彩色圆锥体
🎯 功能概述
这是一个基于 Three.js 和 WebXR API 的增强现实（AR）交互式应用。用户可以在移动设备上通过摄像头查看真实世界，并在其中放置随机颜色的3D圆锥体。

主要交互流程：
启动AR：点击页面上的AR按钮启动增强现实模式

放置物体：在摄像头拍摄的真实场景中，点击屏幕即可在对应位置生成彩色圆锥体

自由创作：用户可以无限次点击，创建任意数量的圆锥体，每个圆锥体都有随机颜色

🏗️ 技术架构
核心框架：
Three.js v0.153+：3D图形渲染引擎

WebXR Device API：浏览器原生AR/VR接口

ES6 Modules：现代JavaScript模块系统

核心技术点：
1. WebXR AR 集成
javascript
// 关键配置
renderer.xr.enabled = true;  // 启用WebXR支持
ARButton.createButton(renderer)  // 创建标准AR启动按钮
自动检测设备AR兼容性

处理相机权限请求

提供标准化的AR会话管理

2. 3D场景构建
javascript
// 核心Three.js对象
scene = new THREE.Scene();  // 3D场景容器
camera = new THREE.PerspectiveCamera(...);  // 透视相机
renderer = new THREE.WebGLRenderer(...);  // WebGL渲染器
场景图架构：树形结构管理所有3D对象

透视投影：模拟人眼视觉的3D到2D转换

WebGL渲染：硬件加速的图形绘制

3. 交互系统
javascript
// 控制器事件处理
controller = renderer.xr.getController(0);
controller.addEventListener('select', onSelect);
XR控制器：抽象化AR输入设备（触摸屏、手柄等）

选择事件：响应用户的交互意图

空间定位：获取设备在真实世界中的位置和朝向

4. 几何体与材质
javascript
// 圆锥体创建
const geometry = new THREE.CylinderGeometry(0, 0.05, 0.2, 32);
const material = new THREE.MeshPhongMaterial({
    color: 0xffffff * Math.random()
});
参数化几何体：通过数学参数定义3D形状

Phong着色模型：支持镜面高光的光照模型

随机颜色生成：每次交互生成新的视觉效果

5. 空间坐标系转换
javascript
mesh.position.set(0, 0, -0.3).applyMatrix4(controller.matrixWorld);
mesh.quaternion.setFromRotationMatrix(controller.matrixWorld);
局部坐标到世界坐标：物体相对于控制器的位置

矩阵变换：高效处理3D空间中的旋转和平移

四元数旋转：避免万向节锁的旋转表示方式

6. 光照系统
javascript
const light = new THREE.HemisphereLight(0xffffff, 0xbbbbff, 3);
半球光源：模拟环境光照（天空和地面光）

冷色调环境：适合AR场景的自然光照效果

光照强度控制：平衡虚拟物体与真实环境的融合

7. 性能优化
javascript
renderer.setPixelRatio(window.devicePixelRatio);  // HiDPI适配
camera = new THREE.PerspectiveCamera(70, ..., 0.01, 20);  // 合理的裁剪范围
geometry = new THREE.CylinderGeometry(..., 32);  // 适中的几何复杂度
设备像素比适配：支持高分辨率显示屏

视锥体裁剪：只渲染可见范围内的物体

几何体优化：平衡视觉效果和渲染性能

8. 响应式设计
javascript
window.addEventListener('resize', onWindowResize);
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    renderer.setSize(window.innerWidth, window.innerHeight);
}
动态宽高比调整：适应不同屏幕尺寸

实时布局更新：支持设备旋转和窗口大小变化

🔧 开发技术栈亮点
现代Web标准
ES6模块化：清晰的代码组织和依赖管理

Import Maps：浏览器原生模块路径解析

严格模式：自动启用的ES6模块严格模式

跨平台兼容
移动设备优先：针对触控交互优化

渐进增强：在不支持AR的设备上优雅降级

标准化API：基于W3C WebXR标准

渲染优化
抗锯齿：提升视觉质量

透明背景：AR应用的必要设置

动画循环：高效的渲染调度机制

🚀 应用场景
这个演示应用虽然简单，但展示了构建复杂AR应用所需的核心技术：

教育领域：AR可视化教学工具

室内设计：虚拟家具摆放预览

游戏娱乐：AR互动游戏

艺术创作：3D空间绘画工具

商业展示：产品AR展示

📱 使用要求
支持平台：
Android：Chrome 81+（需要ARCore支持）

iOS：Safari 13+（需要ARKit支持）

桌面：有限支持（通常需要模拟器）

必需权限：
摄像头访问权限

运动传感器访问（用于设备姿态追踪）

🔍 技术深度解析
WebXR会话生命周期：
text
检测支持 → 创建会话 → 请求权限 → 启动渲染 → 处理输入 → 结束会话
Three.js渲染管线：
text
场景遍历 → 视锥体裁剪 → 材质准备 → 着色器编译 → WebGL绘制调用 → 合成输出
AR空间映射：
text
设备追踪 → 特征点检测 → 平面识别 → 空间锚定 → 虚实融合渲染 -->


<!DOCTYPE html>
<!-- 文档类型声明，告诉浏览器这是HTML5文档 -->
<html lang="zh-CN">
	<!-- 设置文档语言为中文简体 -->
	<head>
		<!-- 头部区域，包含元数据和资源引用 -->
		<!-- 页面标题，显示在浏览器标签页上 -->
		<title>Three.js增强现实演示 - 彩色圆锥体</title>
		<!-- 
			元数据部分：
			charset：设置字符编码为UTF-8，支持中文和特殊字符
			viewport：移动端视口设置，确保网页在移动设备上正确显示
				width=device-width: 宽度等于设备宽度
				initial-scale=1.0: 初始缩放比例为1
				user-scalable=no: 禁止用户手动缩放（AR应用通常需要固定比例）
		-->
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
		<!-- 
			外部CSS样式表链接
			type="text/css": 指定链接的资源是CSS样式表
			rel="stylesheet": 定义当前文档与链接资源的关系是样式表
			href="main.css": 样式表文件的路径
		-->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>
	<!-- 页面主体内容 -->
	<body>
		<!-- 
			信息显示区域
			id="info": 用于CSS样式和JavaScript操作的唯一标识
			包含Three.js的链接和简单的功能介绍
		-->
		<div id="info">
			<!-- 
				外部链接到Three.js官网
				target="_blank": 在新标签页打开链接
				rel="noopener": 安全设置，防止新页面访问原页面的window对象
			-->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> 增强现实演示 - 彩色圆锥体<br/>
			<!-- 操作说明 -->
			点击屏幕在AR空间中放置随机颜色的圆锥体
		</div>

		<!-- 
			导入映射表 (Import Map)
			现代JavaScript模块系统特性，用于定义模块路径别名
			浏览器通过这个映射来解析模块导入路径
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块
			type="module": 表示这是一个ES6模块，支持模块化导入导出
			模块中的代码默认在严格模式下运行，拥有自己的作用域
		-->
		<script type="module">
			// 使用ES6模块语法导入Three.js库
			// * as THREE: 将three模块的所有导出内容作为一个名为THREE的对象导入
			import * as THREE from 'three';
			
			// 从Three.js扩展模块中导入ARButton组件
			// ARButton是一个封装了WebXR AR会话启动逻辑的UI按钮组件
			import { ARButton } from 'three/addons/webxr/ARButton.js';

			// 全局变量声明（这里使用let而不是var，因为let有块级作用域）
			// camera：Three.js相机对象，定义观察3D场景的视角
			// scene：Three.js场景对象，是所有3D对象的容器
			// renderer：Three.js渲染器，负责将3D场景绘制到2D画布上
			let camera, scene, renderer;
			
			// controller：WebXR控制器对象，处理AR环境中的用户输入（如手势、点击）
			let controller;

			// 程序入口点：调用初始化函数
			// 这里使用函数调用而不是事件监听，因为模块脚本在加载后立即执行
			init();

			/**
			 * 初始化函数 - 整个应用的启动和设置入口
			 * 功能：创建和配置Three.js的核心组件、设置事件监听、准备AR环境
			 * 无参数，无返回值
			 */
			function init() {
				// 第一步：创建DOM容器
				// document.createElement('div')：动态创建div元素
				// 这个div将作为Three.js渲染器canvas的容器
				const container = document.createElement('div');
				// 将创建的div添加到body元素的末尾
				document.body.appendChild(container);

				// 第二步：创建Three.js场景
				// THREE.Scene()：创建一个新的3D场景
				// 场景是存储和跟踪所有要渲染的物体、光源、相机等的地方
				scene = new THREE.Scene();

				// 第三步：创建透视相机
				// THREE.PerspectiveCamera()：创建一个透视相机，模拟人眼的视觉效果
				// 参数说明：
				//   70 - 视野角度(FOV)：垂直方向的视野角度，单位是度
				//   window.innerWidth / window.innerHeight - 宽高比：渲染区域的宽高比
				//   0.01 - 近裁剪面：距离相机多近的物体开始渲染（太小可能产生Z-fighting）
				//   20 - 远裁剪面：距离相机多远的物体停止渲染
				camera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, 0.01, 20);

				// 第四步：创建和添加光源
				// THREE.HemisphereLight()：创建一个半球光源，模拟环境光效果
				// 参数说明：
				//   0xffffff - 天空颜色：白色（十六进制颜色表示）
				//   0xbbbbff - 地面颜色：淡蓝色，为AR环境增加一点冷色调
				//   3 - 光照强度：数值越大光越亮
				const light = new THREE.HemisphereLight(0xffffff, 0xbbbbff, 3);
				// 设置光源位置：x=0.5（右），y=1（上），z=0.25（前）
				// 这个位置会影响阴影和光照方向
				light.position.set(0.5, 1, 0.25);
				// 将光源对象添加到场景中
				scene.add(light);

				// 第五步：创建WebGL渲染器
				// THREE.WebGLRenderer()：创建一个基于WebGL的渲染器
				// 配置对象参数说明：
				//   antialias: true - 开启抗锯齿，让边缘更平滑
				//   alpha: true - 开启透明度，让canvas背景透明（对于AR应用很重要）
				renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
				
				// 设置渲染器的设备像素比
				// window.devicePixelRatio：获取设备的物理像素与CSS像素的比例
				// 设置这个值可以在高DPI屏幕上获得更清晰的渲染效果
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器的输出尺寸为整个浏览器窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环函数
				// setAnimationLoop()：替代传统的requestAnimationFrame，是Three.js的推荐方式
				// 参数animate是一个回调函数，会在每一帧被调用
				renderer.setAnimationLoop(animate);
				
				// 启用WebXR支持
				// 这是让Three.js支持AR/VR的关键设置
				renderer.xr.enabled = true;
				
				// 将渲染器的canvas元素（renderer.domElement）添加到之前创建的容器中
				container.appendChild(renderer.domElement);

				// 第六步：创建AR启动按钮
				// ARButton.createButton()：创建一个AR会话启动按钮
				// 这个函数会：
				//   1. 检查浏览器是否支持WebXR
				//   2. 检查设备是否支持AR
				//   3. 创建具有适当样式的按钮
				//   4. 处理按钮点击事件，启动AR会话
				//   5. 请求必要的权限（如相机权限）
				document.body.appendChild(ARButton.createButton(renderer));

				// 第七步：创建几何体（圆锥）
				// THREE.CylinderGeometry()：创建圆柱体/圆锥体几何体
				// 参数说明：
				//   0 - 顶部半径：设为0时形成圆锥尖
				//   0.05 - 底部半径：圆锥底面的半径
				//   0.2 - 高度：圆锥的高度
				//   32 - 分段数：圆形底面的分段数，越高越圆滑但性能消耗越大
				const geometry = new THREE.CylinderGeometry(0, 0.05, 0.2, 32)
					// .rotateX()：将几何体绕X轴旋转
					// Math.PI / 2：90度，将圆锥从垂直状态变为水平状态
					.rotateX(Math.PI / 2);

				/**
				 * XR控制器选择事件处理函数
				 * 当用户在AR环境中执行"选择"操作时调用（如点击屏幕、按下控制器按钮）
				 * 功能：在控制器位置创建随机颜色的圆锥体
				 * 无参数，无返回值
				 */
				function onSelect() {
					// 创建随机颜色的Phong材质
					// THREE.MeshPhongMaterial：一种具有镜面高光的材质类型
					// 配置对象：
					//   color：材质颜色
					//   0xffffff * Math.random()：生成随机颜色
					//   Math.random()返回0-1之间的随机数
					//   0xffffff是白色，乘以随机数得到各种颜色
					const material = new THREE.MeshPhongMaterial({ 
						color: 0xffffff * Math.random() 
					});
					
					// 创建网格对象（Mesh）
					// THREE.Mesh：Three.js中基本的可渲染对象，由几何体和材质组成
					// 参数：几何体对象和材质对象
					const mesh = new THREE.Mesh(geometry, material);
					
					// 设置圆锥体的位置
					// 1. set(0, 0, -0.3)：在控制器的局部坐标系中，设置在Z轴负方向0.3单位处
					//    (0,0,0)是控制器自身位置，(0,0,-1)是控制器正前方
					// 2. applyMatrix4(controller.matrixWorld)：将局部坐标转换为世界坐标
					//    matrixWorld是控制器的世界变换矩阵，包含位置、旋转、缩放信息
					mesh.position.set(0, 0, -0.3).applyMatrix4(controller.matrixWorld);
					
					// 设置圆锥体的旋转方向
					// 1. controller.matrixWorld：获取控制器的世界变换矩阵
					// 2. setFromRotationMatrix()：从矩阵中提取旋转部分并应用到四元数
					// 3. 四元数(quaternion)是Three.js表示旋转的方式，避免万向节锁问题
					// 这样圆锥体会与控制器保持相同的朝向
					mesh.quaternion.setFromRotationMatrix(controller.matrixWorld);
					
					// 将创建好的圆锥体网格添加到场景中
					// 只有添加到场景中的对象才会被渲染
					scene.add(mesh);
				}

				// 第八步：获取和设置XR控制器
				// renderer.xr.getController(0)：获取第一个XR控制器
				// 参数0：控制器索引，0表示主控制器或第一个控制器
				controller = renderer.xr.getController(0);
				
				// 为控制器添加选择事件监听器
				// 事件类型'select'：当用户执行选择操作时触发
				// 回调函数onSelect：事件触发时调用的函数
				controller.addEventListener('select', onSelect);
				
				// 将控制器添加到场景中
				// 这使得控制器在AR环境中可见（通常表现为一个光点或模型）
				scene.add(controller);

				// 第九步：添加窗口大小变化事件监听
				// window.addEventListener()：添加事件监听器
				// 事件类型'resize'：当浏览器窗口大小改变时触发
				// 回调函数onWindowResize：事件触发时调用的函数
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 窗口大小变化事件处理函数
			 * 功能：当浏览器窗口大小改变时，调整相机和渲染器的设置
			 * 无参数，无返回值
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				// camera.aspect：相机视野的宽高比
				// 必须与渲染区域的宽高比保持一致，否则物体会被拉伸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 当相机的属性（如aspect、fov等）改变后，必须调用此方法重新计算投影矩阵
				// 投影矩阵定义了3D坐标如何投影到2D屏幕
				camera.updateProjectionMatrix();

				// 更新渲染器的输出尺寸
				// 使canvas的大小与窗口大小保持一致
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 动画循环函数
			 * 功能：每一帧调用，渲染当前的3D场景
			 * 由renderer.setAnimationLoop()自动调用
			 * 无参数，无返回值
			 */
			function animate() {
				// renderer.render()：执行渲染操作
				// 参数：
				//   scene：要渲染的场景对象
				//   camera：用于渲染场景的相机
				// 这个函数会：
				//   1. 遍历场景中的所有对象
				//   2. 根据相机视角计算哪些对象可见
				//   3. 执行WebGL绘制命令
				//   4. 将3D场景渲染到canvas上
				renderer.render(scene, camera);
			}
		</script>
	</body>
</html>