<!-- Three.js WebXR 变换控制器演示 - 详细功能描述与技术分析
🎯 项目概述
这是一个基于Three.js的WebXR交互式3D场景演示，用户可以通过VR控制器在虚拟现实中操作和变换3D物体。项目展示了现代WebXR技术的核心功能，包括空间追踪、双手交互、物理渲染和后期处理效果。

📋 主要功能模块
1. WebXR环境搭建
设备兼容性：支持主流VR设备（Oculus Quest、HTC Vive等）和AR设备

会话管理：通过XRButton提供一键进入/退出XR模式

双控制器支持：完整的左右手控制器实现

2. 3D场景构建
虚拟世界：创建包含地板、灯光、阴影的完整3D环境

随机物体生成：自动生成16个不同类型、颜色、大小、位置的几何体

物理渲染：使用PBR材质实现真实感表面效果

3. 交互控制系统
物体选择：通过控制器射线与3D物体交互

变换操作：提供移动、旋转、缩放三种变换模式

实时反馈：控制器射线可视化显示选择状态

4. 视觉效果增强
动态阴影：实时光影投射，增强场景深度感

后期处理：Unreal风格辉光效果，提升视觉冲击力

色调映射：ACES Filmic算法，实现电影级色彩表现

🔧 核心技术点详解
1. WebXR API 集成
javascript
// WebXR核心配置
renderer.xr.enabled = true; // 启用XR支持
XRButton.createButton(renderer); // 创建标准XR切换按钮

// 控制器获取
controller1 = renderer.xr.getController(0); // 左手控制器
controller2 = renderer.xr.getController(1); // 右手控制器

// 控制器模型
const controllerModelFactory = new XRControllerModelFactory();
controllerGrip1.add(controllerModelFactory.createControllerModel(controllerGrip1));
技术要点：

使用W3C标准WebXR API，无需插件

自动检测设备能力并选择合适的渲染模式

控制器空间位置和旋转的实时追踪

2. 变换控制器 (TransformControls)
javascript
// 创建变换控制器
controls = new TransformControls(camera, renderer.domElement);

// 操作模式
controls.setMode('translate'); // 移动模式
controls.setMode('rotate');    // 旋转模式  
controls.setMode('scale');     // 缩放模式

// 事件映射
controls.pointerDown(null);   // VR控制器选择开始
controls.pointerUp(null);     // VR控制器选择结束
核心特性：

三种操作模式：通过UI界面切换

空间约束：支持局部和世界坐标系

手柄控制：适配VR控制器的操作习惯

3. 光线投射交互系统
javascript
// 光线投射器设置
raycaster.setFromXRController(controller);

// 碰撞检测
const intersects = raycaster.intersectObjects(group.children);

// 射线可视化
const line = new THREE.Line(geometry);
line.scale.z = 5; // 射线长度
controller.add(line);
交互流程：

控制器发射虚拟射线

检测射线与物体的交点

最近的交点物体被选中

变换控制器附加到选中物体

4. 物理渲染系统
javascript
// PBR材质配置
const material = new THREE.MeshStandardMaterial({
    color: Math.random() * 0xffffff,
    roughness: 0.7,    // 表面粗糙度
    metalness: 0.0,    // 金属质感
});

// 阴影系统
light.castShadow = true;
object.castShadow = true;
object.receiveShadow = true;
renderer.shadowMap.enabled = true;
渲染特性：

实时阴影：4096x4096高分辨率阴影贴图

环境光照：半球光模拟天空和地面反射

直接光照：平行光模拟主光源

5. 后期处理管线
javascript
// 辉光效果配置
bloomPass = new UnrealBloomPass(
    new THREE.Vector2(window.innerWidth, window.innerHeight),
    1.5,   // 强度
    0.4,   // 半径
    0.85   // 阈值
);

// 渲染器效果链
renderer.setEffects([bloomPass]);
renderer.toneMapping = THREE.ACESFilmicToneMapping;
视觉效果：

辉光泛光：模拟HDR高光溢出效果

色调映射：将HDR颜色映射到显示器范围

抗锯齿：MSAA抗锯齿平滑边缘

6. 性能优化技术
javascript
// 半浮点缓冲区（节省显存）
renderer = new THREE.WebGLRenderer({ 
    outputBufferType: THREE.HalfFloatType 
});

// 高效几何体
const geometries = [
    new THREE.BoxGeometry(0.2, 0.2, 0.2),
    new THREE.ConeGeometry(0.2, 0.4, 64), // 优化分段数
    // ...
];

// 渲染循环优化
renderer.setAnimationLoop(animate); // VR优化的动画循环
🎮 用户交互流程
进入XR环境：点击XR按钮进入VR模式

控制器定位：系统识别并显示双手控制器模型

物体选择：用控制器射线指向物体并按下选择键

变换操作：

移动：拖动坐标轴箭头

旋转：拖动旋转环

缩放：拖动缩放方块

模式切换：通过控制器界面切换变换模式

退出XR：再次点击XR按钮返回2D视图

📊 技术架构优势
前端技术栈
Three.js r128+：成熟的WebGL框架

ES6 Modules：模块化代码组织

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

跨平台兼容
VR设备：Oculus、Vive、Windows Mixed Reality

AR设备：支持WebXR的移动设备

桌面浏览器：Chrome、Firefox、Edge

开发友好特性
响应式设计：自动适应窗口大小

调试支持：Three.js调试工具集成

性能监控：Frame rate和内存使用可监控

🔍 关键技术挑战与解决方案
挑战1：VR控制器事件映射
问题：VR控制器事件与传统鼠标事件不兼容
解决方案：创建适配层，将XR事件转换为变换控制器能理解的事件

挑战2：空间交互精度
问题：3D空间中选择物体需要高精度
解决方案：使用光线投射+碰撞检测，提供视觉反馈

挑战3：性能优化
问题：VR渲染需要高帧率（72-90FPS）
解决方案：

使用半浮点缓冲区减少显存占用

优化几何体复杂度

合理设置阴影分辨率 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题，显示在浏览器标签页上 -->
		<title>Three.js XR 变换控制器演示</title>
		<!-- 指定HTML文档的字符编码为UTF-8，支持中文字符 -->
		<meta charset="utf-8">
		<!-- 
			视口设置：
			- width=device-width: 视口宽度等于设备宽度
			- initial-scale=1.0: 初始缩放比例为1.0
			- user-scalable=no: 禁止用户手动缩放页面
			这些设置确保在移动设备上正确显示和操作
		-->
		<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操作的唯一标识符
			内容：显示Three.js网站链接和当前功能描述
		-->
		<div id="info">
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> 
			WebXR 变换控制器演示 - 使用VR控制器操作3D物体
		</div>

		<!-- 
			ES模块导入映射配置：
			- type="importmap": 定义JavaScript模块导入的路径映射
			作用：将模块名称映射到实际的URL路径，简化导入语句
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			- type="module": 表示这是一个ES6模块，支持import/export语法
			模块化组织代码，避免全局变量污染，支持异步加载
		-->
		<script type="module">
			// ==================== 模块导入区域 ====================
			// 导入Three.js核心库的所有功能，THREE作为命名空间
			import * as THREE from 'three';
			// 导入变换控制器：提供物体的移动、旋转、缩放控制界面
			import { TransformControls } from 'three/addons/controls/TransformControls.js';
			// 导入XR按钮组件：创建进入/退出XR会话的HTML按钮
			import { XRButton } from 'three/addons/webxr/XRButton.js';
			// 导入XR控制器模型工厂：为XR控制器生成3D可视化模型
			import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';
			// 导入虚幻引擎风格的辉光后期处理效果
			import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';

			// ==================== 全局变量声明区域 ====================
			// 容器变量：用于存放Three.js渲染器创建的canvas元素
			let container;
			// Three.js三大核心对象：
			let camera;     // 相机：定义观察者的视角和投影方式
			let scene;      // 场景：包含所有3D对象、灯光、相机的容器
			let renderer;   // 渲染器：将3D场景渲染到2D屏幕的引擎
			
			// 后期处理效果：辉光效果增强视觉表现
			let bloomPass;
			
			// XR控制器相关变量：
			let controller1;    // 左手XR控制器（索引0）
			let controller2;    // 右手XR控制器（索引1）
			let line;           // 控制器射线：可视化选择目标
			let controllerGrip1; // 左手控制器握把模型
			let controllerGrip2; // 右手控制器握把模型
			
			// 光线投射器：用于检测控制器射线与3D物体的交点
			let raycaster;
			
			// 变换控制相关：
			let controls;   // 变换控制器实例
			let group;      // 3D物体分组容器

			// ==================== 主初始化函数调用 ====================
			// 调用初始化函数，开始构建3D场景和XR环境
			init();

			/**
			 * 初始化函数 - 整个应用的入口点
			 * 功能：创建场景、相机、渲染器、控制器、物体等所有必要组件
			 * 执行流程：按照依赖顺序构建3D世界
			 */
			function init() {
				// ---------- 1. 创建DOM容器 ----------
				// 创建一个div元素作为Three.js渲染的画布容器
				container = document.createElement('div');
				// 将容器添加到网页body中，渲染器生成的canvas将放在这个div里
				document.body.appendChild(container);

				// ---------- 2. 创建Three.js场景 ----------
				// Scene对象是所有3D对象、灯光、相机的容器
				scene = new THREE.Scene();
				// 设置场景背景颜色为中性灰色（十六进制颜色值）
				scene.background = new THREE.Color(0x808080);

				// ---------- 3. 创建并配置相机 ----------
				/**
				 * 透视相机（PerspectiveCamera）参数：
				 * - fov: 50，视场角（Field of View），单位是度
				 * - aspect: 宽高比，使用窗口宽高比实现响应式
				 * - near: 0.1，近剪切平面，距离相机0.1单位内的物体不显示
				 * - far: 10，远剪切平面，距离相机10单位外的物体不显示
				 */
				camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.1, 10);
				// 设置相机位置：
				// - x: 0，左右方向中心
				// - y: 1.6，模拟人眼高度（约1.6米）
				// - z: 0，前后方向中心
				camera.position.set(0, 1.6, 0);

				// ---------- 4. 创建地面 ----------
				// 创建平面几何体：宽度6单位，高度6单位
				const floorGeometry = new THREE.PlaneGeometry(6, 6);
				// 创建阴影材质：专门用于接收和显示阴影
				const floorMaterial = new THREE.ShadowMaterial({
					opacity: 0.25,           // 阴影透明度
					blending: THREE.CustomBlending, // 自定义混合模式
					transparent: false       // 非透明材质
				});
				// 将几何体和材质组合成网格（Mesh）对象
				const floor = new THREE.Mesh(floorGeometry, floorMaterial);
				// 将平面旋转-90度，使其从垂直变为水平（Three.js中Y轴向上）
				floor.rotation.x = -Math.PI / 2;
				// 启用阴影接收：地面可以显示其他物体投射的阴影
				floor.receiveShadow = true;
				// 将地面添加到场景中
				scene.add(floor);

				// ---------- 5. 设置场景照明 ----------
				/**
				 * 半球光（环境光）：
				 * 模拟天空和地面的环境反射光
				 * - skyColor: 0xbcbcbc，天空颜色（浅灰色）
				 * - groundColor: 0xa5a5a5，地面颜色（深灰色）
				 * - intensity: 3，光照强度
				 */
				scene.add(new THREE.HemisphereLight(0xbcbcbc, 0xa5a5a5, 3));

				/**
				 * 平行光（主光源）：
				 * 模拟太阳光，所有光线平行且方向相同
				 */
				const light = new THREE.DirectionalLight(0xffffff, 3); // 白色光，强度3
				light.position.set(0, 6, 0); // 设置在场景正上方6单位处
				light.castShadow = true;     // 启用阴影投射
				
				// 配置阴影相机（控制阴影的渲染范围）：
				// 定义阴影相机的视锥体范围
				light.shadow.camera.top = 3;      // 上边界
				light.shadow.camera.bottom = -3;  // 下边界
				light.shadow.camera.right = 3;    // 右边界
				light.shadow.camera.left = -3;    // 左边界
				
				// 设置阴影贴图分辨率，影响阴影质量
				// 值越高阴影越清晰，但性能消耗越大
				light.shadow.mapSize.set(4096, 4096);
				
				// 将平行光添加到场景
				scene.add(light);

				// ---------- 6. 创建3D物体分组 ----------
				// Group对象用于组织和管理多个3D物体
				group = new THREE.Group();
				scene.add(group);

				// 定义5种基本几何体类型，用于随机创建物体
				const geometries = [
					new THREE.BoxGeometry(0.2, 0.2, 0.2),        // 立方体：长宽高各0.2
					new THREE.ConeGeometry(0.2, 0.4, 64),        // 圆锥体：底面半径0.2，高度0.4，侧面分段64
					new THREE.CylinderGeometry(0.2, 0.2, 0.2, 64), // 圆柱体：上下半径0.2，高度0.2，侧面分段64
					new THREE.IcosahedronGeometry(0.2, 8),       // 二十面体：半径0.2，细分等级8
					new THREE.TorusGeometry(0.2, 0.04, 64, 32)   // 圆环体：半径0.2，管径0.04，主要分段64，管状分段32
				];

				// 循环创建16个随机物体
				for (let i = 0; i < 16; i++) {
					// 随机选择一种几何体类型
					const geometry = geometries[Math.floor(Math.random() * geometries.length)];
					
					// 创建物理渲染材质（PBR材质）
					const material = new THREE.MeshStandardMaterial({
						color: Math.random() * 0xffffff, // 随机生成RGB颜色
						roughness: 0.7,  // 表面粗糙度（0.0-1.0），值越大越粗糙
						metalness: 0.0   // 金属质感（0.0-1.0），0为非金属，1为全金属
					});

					// 将几何体和材质组合成可渲染的网格对象
					const object = new THREE.Mesh(geometry, material);

					// 设置随机位置：
					// x: -0.5到0.5之间，y: 0.5到2.5之间，z: -2.5到-1.5之间
					object.position.x = Math.random() - 0.5;
					object.position.y = Math.random() * 2 + 0.5;
					object.position.z = Math.random() - 2.5;

					// 设置随机旋转（欧拉角）：
					// 每个轴旋转0-360度（0-2π弧度）
					object.rotation.x = Math.random() * 2 * Math.PI;
					object.rotation.y = Math.random() * 2 * Math.PI;
					object.rotation.z = Math.random() * 2 * Math.PI;

					// 设置随机缩放：0.5-1.5倍
					object.scale.setScalar(Math.random() + 0.5);

					// 启用阴影功能：
					object.castShadow = true;    // 物体可以投射阴影
					object.receiveShadow = true; // 物体可以接收阴影

					// 将物体添加到分组中
					group.add(object);
				}

				// ---------- 7. 创建WebGL渲染器 ----------
				/**
				 * WebGLRenderer配置选项：
				 * - antialias: true，启用抗锯齿，平滑边缘
				 * - outputBufferType: THREE.HalfFloatType，使用半浮点缓冲区，提高性能
				 */
				renderer = new THREE.WebGLRenderer({ antialias: true, outputBufferType: THREE.HalfFloatType });
				
				// 设置渲染器像素比，适配高DPI屏幕（如Retina显示屏）
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数（每帧自动调用animate函数）
				renderer.setAnimationLoop(animate);
				
				// 启用阴影映射功能
				renderer.shadowMap.enabled = true;
				
				// 设置色调映射：ACES Filmic，提供电影级的色彩表现
				renderer.toneMapping = THREE.ACESFilmicToneMapping;
				
				// 启用WebXR支持
				renderer.xr.enabled = true;
				
				// 将渲染器的canvas元素添加到容器中
				container.appendChild(renderer.domElement);

				// ---------- 8. 配置后期处理效果 ----------
				/**
				 * UnrealBloomPass辉光效果参数：
				 * - 分辨率：使用窗口尺寸
				 * - strength: 1.5，辉光强度
				 * - radius: 0.4，辉光半径
				 * - threshold: 0.85，辉光阈值（亮度超过此值才会产生辉光）
				 */
				bloomPass = new UnrealBloomPass(
					new THREE.Vector2(window.innerWidth, window.innerHeight),
					1.5,
					0.4,
					0.85
				);
				
				// 将辉光效果添加到渲染器的后期处理链
				renderer.setEffects([bloomPass]);

				// ---------- 9. 创建XR交互界面 ----------
				// 创建进入/退出XR模式的按钮，并添加到页面
				document.body.appendChild(XRButton.createButton(renderer));

				// ---------- 10. 设置XR控制器 ----------
				
				// 左手控制器（索引0）
				controller1 = renderer.xr.getController(0);
				// 添加事件监听器：
				controller1.addEventListener('select', onSelect);        // 选择/触发按钮按下
				controller1.addEventListener('selectstart', onControllerEvent); // 按钮开始按下
				controller1.addEventListener('selectend', onControllerEvent);   // 按钮释放
				controller1.addEventListener('move', onControllerEvent);        // 控制器移动
				controller1.userData.active = false; // 初始状态为非激活
				scene.add(controller1); // 将控制器添加到场景

				// 右手控制器（索引1）
				controller2 = renderer.xr.getController(1);
				controller2.addEventListener('select', onSelect);
				controller2.addEventListener('selectstart', onControllerEvent);
				controller2.addEventListener('selectend', onControllerEvent);
				controller2.addEventListener('move', onControllerEvent);
				controller2.userData.active = true; // 初始状态为激活
				scene.add(controller2);

				// 创建控制器模型工厂，用于生成控制器的3D可视化模型
				const controllerModelFactory = new XRControllerModelFactory();

				// 左手控制器握把模型
				controllerGrip1 = renderer.xr.getControllerGrip(0);
				// 创建控制器模型并添加到握把对象
				controllerGrip1.add(controllerModelFactory.createControllerModel(controllerGrip1));
				scene.add(controllerGrip1);

				// 右手控制器握把模型
				controllerGrip2 = renderer.xr.getControllerGrip(1);
				controllerGrip2.add(controllerModelFactory.createControllerModel(controllerGrip2));
				scene.add(controllerGrip2);

				// ---------- 11. 创建控制器射线 ----------
				/**
				 * 射线可视化：从控制器向前延伸的直线
				 * 用于显示控制器的指向方向和选择目标
				 */
				// 创建包含两个点的几何体：起点(0,0,0)和终点(0,0,-1)
				const geometry = new THREE.BufferGeometry().setFromPoints([
					new THREE.Vector3(0, 0, 0),    // 起点：控制器位置
					new THREE.Vector3(0, 0, -1)    // 终点：控制器前方1单位
				]);

				// 创建线对象
				line = new THREE.Line(geometry);
				line.name = 'line';   // 设置对象名称，便于调试和查找
				line.scale.z = 5;     // 将射线长度缩放为5倍

				// ---------- 12. 创建光线投射器 ----------
				/**
				 * 光线投射器：用于检测3D空间中射线与物体的交点
				 * 原理：从起点沿方向发射不可见射线，检测与哪些物体相交
				 */
				raycaster = new THREE.Raycaster();

				// ---------- 13. 创建变换控制器 ----------
				/**
				 * TransformControls：提供GUI界面控制物体的位置、旋转、缩放
				 * 参数：
				 * - camera：控制界面需要相机信息来计算投影
				 * - domElement：事件监听的DOM元素（通常是渲染器的canvas）
				 */
				controls = new TransformControls(camera, renderer.domElement);
				
				// 将变换控制器附加到第一个物体上（默认选中的物体）
				controls.attach(group.children[0]);
				
				// 获取变换控制器的辅助对象（显示控制手柄）并添加到场景
				scene.add(controls.getHelper());

				// ---------- 14. 添加窗口大小变化监听 ----------
				// 当浏览器窗口大小改变时，重新调整相机和渲染器
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 控制器选择事件处理函数
			 * 当用户按下控制器上的"选择/触发"按钮时调用
			 * 
			 * 功能：
			 * 1. 激活当前控制器，禁用另一个控制器
			 * 2. 为激活的控制器添加射线可视化
			 * 3. 检测射线与物体的交点
			 * 4. 如果选中物体，将变换控制器附加到该物体
			 * 
			 * @param {Object} event - 事件对象，包含触发事件的控制器信息
			 */
			function onSelect(event) {
				// 获取触发事件的控制器
				const controller = event.target;

				// 重置两个控制器的激活状态
				controller1.userData.active = false;
				controller2.userData.active = false;

				// 根据触发事件的控制器激活相应的控制器
				if (controller === controller1) {
					// 激活左手控制器
					controller1.userData.active = true;
					// 为控制器添加射线可视化
					controller1.add(line);
				}

				if (controller === controller2) {
					// 激活右手控制器
					controller2.userData.active = true;
					controller2.add(line);
				}

				/**
				 * 设置光线投射器的起点和方向：
				 * 起点：控制器的位置
				 * 方向：控制器的朝向（通常是用户手指指向的方向）
				 */
				raycaster.setFromXRController(controller);

				/**
				 * 检测射线与物体的交点：
				 * intersectObjects方法检测射线与指定物体数组的交点
				 * 返回交点数组，按距离排序（最近的在前面）
				 */
				const intersects = raycaster.intersectObjects(group.children);

				// 如果有交点（射线碰到了物体）
				if (intersects.length > 0) {
					// 将变换控制器附加到第一个（最近的）交点的物体上
					// intersects[0].object 是被射线击中的物体
					controls.attach(intersects[0].object);
				}
			}

			/**
			 * 控制器事件通用处理函数
			 * 处理控制器的selectstart、selectend、move事件
			 * 将这些事件转换为变换控制器的相应操作
			 * 
			 * @param {Object} event - 控制器事件对象
			 */
			function onControllerEvent(event) {
				// 获取触发事件的控制器
				const controller = event.target;

				// 如果控制器未激活，不处理事件
				if (controller.userData.active === false) return;

				/**
				 * 设置变换控制器的内部光线投射器：
				 * 变换控制器也需要知道控制器的位置和方向来响应用户操作
				 */
				controls.getRaycaster().setFromXRController(controller);

				// 根据事件类型调用变换控制器的相应方法
				switch (event.type) {
					case 'selectstart':
						// 模拟鼠标/触摸按下事件：null表示使用控制器的位置
						controls.pointerDown(null);
						break;

					case 'selectend':
						// 模拟鼠标/触摸释放事件
						controls.pointerUp(null);
						break;

					case 'move':
						// 模拟鼠标悬停和移动事件
						controls.pointerHover(null);
						controls.pointerMove(null);
						break;
				}
			}

			/**
			 * 窗口大小变化事件处理函数
			 * 当浏览器窗口大小改变时调用，确保3D场景正确适配新窗口尺寸
			 */
			function onWindowResize() {
				// 更新相机宽高比，防止图像拉伸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 应用新的相机参数
				camera.updateProjectionMatrix();
				
				// 更新渲染器尺寸为新的窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 注意：辉光效果等后期处理也需要更新分辨率
				// 这里为了简化没有更新，实际项目中可能需要
			}

			/**
			 * 动画循环函数
			 * 每帧自动调用，驱动3D场景的渲染
			 * 在WebXR中，这个函数由渲染器的XR管理器控制
			 */
			function animate() {
				// 渲染场景和相机到画布
				renderer.render(scene, camera);
				
				// 注意：变换控制器的更新在内部自动处理
				// Three.js会自动处理控制器位置、物体动画等更新
			}
		</script>
	</body>
</html>