<!-- Three.js WebGL 轨迹球控制器演示 - 代码功能和技术点分析
🎯 核心功能概述
这是一个交互式3D图形演示应用，使用Three.js库创建了一个包含500个随机分布圆锥体的3D场景，用户可以通过鼠标和键盘自由控制视角，体验两种不同的相机模式（透视/正交投影）。

🔧 主要技术点
1. Three.js核心架构
场景(Scene)：所有3D对象的容器，包含几何体、灯光、雾效

相机(Camera)：实现双相机系统（透视相机和正交相机）

渲染器(Renderer)：WebGL渲染器，将3D场景渲染到2D画布

控制器(Controls)：轨迹球控制器，提供自然的3D交互体验

2. 性能优化技术
实例化网格(InstancedMesh)：使用单个Draw Call渲染500个圆锥体

javascript
const mesh = new THREE.InstancedMesh(geometry, material, 500);
传统方法：500次绘制调用

实例化：1次绘制调用，极大提升渲染性能

3. 交互控制系统
轨迹球控制器(TrackballControls)：

支持三键鼠标操作（左键旋转/中键缩放/右键平移）

键盘快捷键映射（A键旋转/S键缩放/D键平移）

平滑的惯性效果（拖动后继续缓动）

GUI控制面板：

实时切换透视/正交相机模式

参数即时生效，无需刷新页面

4. 视觉特效系统
光照系统：

双方向平行光（白色+蓝色），创建立体感和对比度

环境光填充阴影，避免死黑区域

雾效(FogExp2)：

javascript
scene.fog = new THREE.FogExp2(0xcccccc, 0.002);
指数平方雾效，随距离增加浓度呈指数增长

增强场景深度感和氛围

5. 响应式设计
窗口自适应：

实时监听resize事件

动态更新相机投影矩阵和渲染器尺寸

保持正确的宽高比，避免图像拉伸

6. 两种相机模式对比
透视相机(PerspectiveCamera)：

模拟人眼视觉效果

近大远小，符合真实世界透视规律

参数：视野角度60°，适合大多数3D应用

正交相机(OrthographicCamera)：

无透视变形，保持物体尺寸恒定

常用于CAD设计、工程制图

适合需要精确尺寸表现的场景

7. 数学计算原理
相机投影矩阵计算：

javascript
// 透视相机：基于视野角度和宽高比
perspectiveCamera.aspect = window.innerWidth / window.innerHeight;

// 正交相机：基于视锥体大小和宽高比
orthographicCamera.left = -frustumSize * aspect / 2;
实例位置计算：

javascript
// 在-500到500范围内随机分布
dummy.position.x = (Math.random() - 0.5) * 1000;
8. 现代Web技术应用
ES6模块化：使用import/export语法组织代码

Import Maps：浏览器原生模块路径映射

动画循环：requestAnimationFrame实现流畅动画

性能监控：集成Stats.js显示帧率和性能指标

🚀 关键技术亮点
亮点1：实例化渲染(Instanced Rendering)
javascript
// 传统方法：500个独立Mesh对象，500次绘制调用
// 实例化方法：1个InstancedMesh对象，1次绘制调用
性能提升：减少99.8%的绘制调用

内存优化：共享几何体和材质数据

适用场景：大量重复几何体（如森林、人群、星空）

亮点2：轨迹球交互设计
自然交互：模拟真实球体旋转的交互体验

多设备支持：同时支持鼠标三键和键盘操作

平滑过渡：惯性动画提供流畅的操作反馈

亮点3：双相机实时切换
javascript
// 一键切换相机类型
controls.dispose(); // 销毁旧控制器
createControls(value ? orthographicCamera : perspectiveCamera);
即时生效：无需重新初始化场景

平滑过渡：控制器状态保持连续

教学价值：直观展示两种投影方式的区别

亮点4：完整的调试工具链
Stats.js：实时监控帧率(FPS)、渲染时间

lil-gui：轻量级参数控制面板

错误处理：控制器正确的销毁和重建

📊 性能特征
指标	传统方法	实例化方法	提升倍数
绘制调用	500次	1次	500倍
CPU负担	高	极低	显著
GPU负担	中等	极低	显著
内存占用	高	极低	显著
🎨 视觉设计特点
低多边形(Low-poly)风格：

4面锥体几何体

平面着色(Flat Shading)

简洁的视觉语言

色彩方案：

白色几何体（中性背景）

双色照明（白色主光+蓝色补光）

灰色雾效（统一色调）

空间布局：

500个圆锥随机分布在1000³空间

避免重叠和规律分布

创建自然的空间感 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 
			页面标题：显示在浏览器标签页上的标题
			中文标题：Three.js WebGL 轨迹球控制器演示
		-->
		<title>Three.js WebGL 轨迹球控制器演示</title>
		<!-- 
			字符编码设置：指定文档使用的字符编码为UTF-8
			UTF-8支持中文字符，确保中文正常显示
		-->
		<meta charset="utf-8">
		<!-- 
			视口设置：用于移动设备适配和响应式设计
			width=device-width: 视口宽度等于设备宽度
			user-scalable=no: 禁止用户缩放页面（保持固定比例）
			minimum-scale=1.0: 最小缩放比例为1.0
			maximum-scale=1.0: 最大缩放比例为1.0
			这些设置确保3D场景在不同设备上保持一致的显示效果
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 
			外部CSS样式表链接：引用外部CSS文件
			rel="stylesheet": 指定链接类型为样式表
			href="main.css": 样式表文件路径
			注：实际使用时需要确保main.css文件存在
		-->
		<link type="text/css" rel="stylesheet" href="main.css">
		<!-- 
			内联CSS样式：直接在HTML文件中定义样式
			这些样式会覆盖外部样式表中的相同属性
		-->
		<style>
			/* 
				页面主体样式设置：
				background-color: #ccc - 设置页面背景颜色为浅灰色（十六进制#ccc）
				color: #000 - 设置默认文字颜色为黑色
				这些样式为3D场景提供了一个中性背景
			*/
			body {
				background-color: #ccc;
				color: #000;
			}
			/* 
				链接样式设置：
				color: #f00 - 设置链接颜色为红色
				a标签的默认样式会被这个规则覆盖
			*/
			a {
				color: #f00;
			}
		</style>
	</head>

	<body>
		<!-- 
			信息提示区域：显示操作说明和链接
			id="info": 为这个div元素指定唯一的id，便于CSS或JavaScript操作
			这个区域通常固定在页面的某个位置，不会随3D场景移动
		-->
		<div id="info">
			<!-- 
				Three.js官网链接：
				href="https://threejs.org": 链接到Three.js官方网站
				target="_blank": 在新标签页中打开链接
				rel="noopener": 安全设置，防止新页面通过window.opener访问原页面
				链接文本：Three.js - 一个流行的WebGL 3D图形库
			-->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js - WebGL 3D图形库</a> - 轨迹球控制器演示<br />
			<!-- 
				操作指南：详细说明如何操作3D场景
				鼠标操作：
					- 左键拖动/A键：旋转场景
					- 中键拖动/S键：缩放场景（推拉镜头）
					- 右键拖动/D键：平移场景（移动视角）
				这个提示帮助用户了解如何与3D场景交互
			-->
			操作指南：鼠标拖动 + 按键<br />
			左键/A键: 旋转视角 &nbsp;|&nbsp; 中键/S键: 缩放视角 &nbsp;|&nbsp; 右键/D键: 平移视角
		</div>

		<!-- 
			importmap配置：定义JavaScript模块的导入路径
			type="importmap": 指定脚本类型为导入映射
			这个功能允许浏览器理解模块导入语句中的路径映射
			在现代浏览器中支持，用于模块化JavaScript开发
		-->
		<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.js是一个用于创建3D图形的JavaScript库
			import * as THREE from 'three';

			// 导入性能监控工具（Stats）
			// Stats显示FPS（帧率）、渲染时间等性能指标
			import Stats from 'three/addons/libs/stats.module.js';
			
			// 导入GUI库（lil-gui）
			// 用于创建简单的控制面板，可以实时调整参数
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// 导入轨迹球控制器（TrackballControls）
			// 提供类似轨迹球的3D场景交互方式
			import { TrackballControls } from 'three/addons/controls/TrackballControls.js';

			// ============ 全局变量声明 ============
			
			// 声明变量但不初始化，在init函数中赋值
			let perspectiveCamera;  // 透视相机：模拟人眼视角，有近大远小的透视效果
			let orthographicCamera; // 正交相机：无透视效果，物体大小不随距离变化
			let controls;           // 轨迹球控制器：处理用户输入，控制相机移动
			let scene;              // 场景对象：包含所有3D对象（网格、灯光、相机等）
			let renderer;           // 渲染器：将3D场景渲染到2D canvas上
			let stats;              // 性能监控器：显示性能指标

			// ============ 配置参数对象 ============
			
			// 用于GUI控制的参数对象，属性值会被GUI控件修改
			const params = {
				orthographicCamera: false  // 是否使用正交相机的标志，默认false（使用透视相机）
			};

			// 正交相机的视锥体大小（frustum size）
			// 视锥体定义了相机能够看到的3D空间范围
			const frustumSize = 400;

			// ============ 初始化函数调用 ============
			
			// 程序入口点：初始化所有Three.js组件
			init();

			/**
			 * 初始化函数 - 整个程序的入口点
			 * 这个函数创建了所有Three.js的核心组件：
			 * 1. 相机（透视和正交）
			 * 2. 场景和3D对象
			 * 3. 灯光系统
			 * 4. 渲染器
			 * 5. 控制器和GUI
			 * 6. 事件监听器
			 */
			function init() {

				// 计算屏幕的宽高比（aspect ratio）
				// 宽高比 = 窗口宽度 / 窗口高度
				// 这个值用于设置相机的投影矩阵
				const aspect = window.innerWidth / window.innerHeight;

				// ============ 创建透视相机 ============
				
				// 透视相机构造函数参数：
				// 1. fov（视野角度）：60度，表示相机能够看到的角度范围
				// 2. aspect（宽高比）：使用计算出的屏幕宽高比
				// 3. near（近裁剪面）：1，距离相机小于1的物体不会被渲染
				// 4. far（远裁剪面）：1000，距离相机大于1000的物体不会被渲染
				perspectiveCamera = new THREE.PerspectiveCamera(60, aspect, 1, 1000);
				// 设置相机在Z轴上的位置（沿着Z轴向后移动500个单位）
				// 在Three.js中，默认相机看向Z轴负方向
				perspectiveCamera.position.z = 500;

				// ============ 创建正交相机 ============
				
				// 正交相机构造函数参数（定义了一个长方体视锥体）：
				// 1. left（左裁剪面）：视锥体左侧边界
				// 2. right（右裁剪面）：视锥体右侧边界
				// 3. top（上裁剪面）：视锥体上侧边界
				// 4. bottom（下裁剪面）：视锥体下侧边界
				// 5. near（近裁剪面）：1
				// 6. far（远裁剪面）：1000
				// 这些参数计算基于frustumSize和屏幕宽高比
				orthographicCamera = new THREE.OrthographicCamera(
					frustumSize * aspect / -2,  // 左边界：负值表示在中心左侧
					frustumSize * aspect / 2,   // 右边界：正值表示在中心右侧
					frustumSize / 2,            // 上边界：正值表示在中心上方
					frustumSize / -2,           // 下边界：负值表示在中心下方
					1, 1000                     // 近裁剪面和远裁剪面
				);
				orthographicCamera.position.z = 500;  // 设置相机位置

				// ============ 创建场景和3D对象 ============

				// 创建场景对象，场景是所有3D对象的容器
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅灰色（与页面背景色一致）
				scene.background = new THREE.Color(0xcccccc);
				// 添加指数雾效（exponential squared fog）
				// 参数：雾的颜色（浅灰色），雾的密度（0.002）
				// 指数雾随着距离增加，雾的浓度呈指数增长
				scene.fog = new THREE.FogExp2(0xcccccc, 0.002);

				// 创建圆锥几何体：
				// 参数1：底面半径（10个单位）
				// 参数2：高度（30个单位）
				// 参数3：底面分段数（4段，形成正方形底面）
				// 参数4：高度分段数（1段，侧面不分段）
				const geometry = new THREE.ConeGeometry(10, 30, 4, 1);
				
				// 创建Phong材质（冯氏光照模型）：
				// Phong材质支持高光反射，使物体看起来更真实
				// 参数对象：
				//   color: 0xffffff - 白色（十六进制表示）
				//   flatShading: true - 使用平面着色（每个面一个颜色，不是平滑渐变）
				//   平面着色会产生明显的面片效果，适合低多边形风格
				const material = new THREE.MeshPhongMaterial({
					color: 0xffffff,
					flatShading: true
				});

				// 创建实例化网格（InstancedMesh）：
				// 这是一种高效的渲染技术，用于绘制大量相同的几何体
				// 参数：
				//   1. geometry: 几何体（所有实例共享）
				//   2. material: 材质（所有实例共享）
				//   3. 500: 实例数量（创建500个圆锥）
				// 与传统方法（创建500个独立Mesh）相比，实例化渲染性能更高
				const mesh = new THREE.InstancedMesh(geometry, material, 500);
				
				// 创建虚拟对象（dummy object）
				// 这是一个临时的3D对象，用于计算每个实例的变换矩阵
				const dummy = new THREE.Object3D();

				// 循环创建500个圆锥实例的位置
				for (let i = 0; i < 500; i++) {

					// 为每个圆锥生成随机位置：
					// Math.random()返回0-1的随机数，减去0.5得到-0.5到0.5的范围
					// 乘以1000得到-500到500的范围
					// 这样圆锥会随机分布在1000×1000×1000的立方体空间内
					dummy.position.x = (Math.random() - 0.5) * 1000;
					dummy.position.y = (Math.random() - 0.5) * 1000;
					dummy.position.z = (Math.random() - 0.5) * 1000;

					// 更新虚拟对象的变换矩阵
					// 当修改了位置、旋转或缩放后，需要调用此方法更新矩阵
					dummy.updateMatrix();
					
					// 将虚拟对象的变换矩阵设置到实例化网格的第i个实例
					// 每个实例都有自己独立的变换矩阵，但共享几何体和材质
					mesh.setMatrixAt(i, dummy.matrix);

				}

				// 将实例化网格添加到场景中
				scene.add(mesh);

				// ============ 创建灯光系统 ============

				// 创建第一个平行光（directional light）：
				// 平行光模拟远处光源（如太阳），所有光线平行
				// 参数1：光的颜色（0xffffff - 白色）
				// 参数2：光的强度（3 - 较高的强度值）
				const dirLight1 = new THREE.DirectionalLight(0xffffff, 3);
				// 设置灯光方向向量（1, 1, 1）
				// 这个向量表示光从(1,1,1)方向照射到原点(0,0,0)
				dirLight1.position.set(1, 1, 1);
				// 将灯光添加到场景
				scene.add(dirLight1);

				// 创建第二个平行光（蓝色光）：
				// 颜色：0x002288 - 深蓝色
				// 强度：3
				const dirLight2 = new THREE.DirectionalLight(0x002288, 3);
				// 设置与第一个灯光相反的方向（-1, -1, -1）
				// 这创建了对比照明效果
				dirLight2.position.set(-1, -1, -1);
				scene.add(dirLight2);

				// 创建环境光（ambient light）：
				// 环境光均匀照射所有物体，没有方向性
				// 用于模拟间接光照，填充阴影区域
				// 颜色：0x555555 - 中等灰色，强度适中
				const ambientLight = new THREE.AmbientLight(0x555555);
				scene.add(ambientLight);

				// ============ 创建渲染器 ============

				// 创建WebGL渲染器：
				// 参数对象：{ antialias: true } - 开启抗锯齿
				// 抗锯齿可以减少图形边缘的锯齿状像素
				renderer = new THREE.WebGLRenderer({ antialias: true });
				
				// 设置设备像素比（device pixel ratio）
				// 这个值考虑了高DPI屏幕（如Retina显示屏）
				// 设置后可以确保在高DPI屏幕上清晰显示
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器的尺寸为窗口的完整尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置动画循环回调函数
				// setAnimationLoop是requestAnimationFrame的Three.js封装
				// animate函数会在每一帧被调用
				renderer.setAnimationLoop(animate);
				
				// 将渲染器的canvas元素添加到页面body中
				// renderer.domElement是渲染器创建的<canvas>元素
				document.body.appendChild(renderer.domElement);

				// ============ 创建性能监控器 ============

				// 创建Stats对象（性能监控器）
				stats = new Stats();
				// 将Stats的DOM元素添加到页面body中
				// stats.dom是一个<div>元素，包含FPS等性能指标
				document.body.appendChild(stats.dom);

				// ============ 创建GUI控制面板 ============

				// 创建GUI实例
				// GUI提供简单的控制面板，可以实时调整参数
				const gui = new GUI();
				
				// 添加相机类型切换控件：
				// 参数1：params对象
				// 参数2：'orthographicCamera'属性名
				// 方法链：
				//   .name('使用正交相机') - 设置控件显示名称（中文）
				//   .onChange() - 值变化时的回调函数
				gui.add(params, 'orthographicCamera')
					.name('使用正交相机')  // 控件显示名称改为中文
					.onChange(function (value) {
						// 当用户切换相机类型时执行
						
						// 销毁当前的控制器
						// 这是必要的，因为控制器绑定到特定的相机
						controls.dispose();
						
						// 根据用户选择创建新的控制器
						// 如果value为true，使用正交相机；否则使用透视相机
						createControls(value ? orthographicCamera : perspectiveCamera);
					});

				// ============ 事件监听器设置 ============

				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时，onWindowResize函数会被调用
				window.addEventListener('resize', onWindowResize);

				// ============ 创建初始控制器 ============

				// 使用透视相机创建初始的轨迹球控制器
				createControls(perspectiveCamera);

			}

			/**
			 * 创建轨迹球控制器
			 * 这个函数根据传入的相机对象创建并配置轨迹球控制器
			 * 
			 * @param {THREE.Camera} camera - 要控制的相机对象
			 * 可以是透视相机或正交相机
			 */
			function createControls(camera) {

				// 创建轨迹球控制器实例
				// 参数1：要控制的相机对象
				// 参数2：渲染器的DOM元素（canvas），控制器会监听这个元素上的事件
				controls = new TrackballControls(camera, renderer.domElement);

				// 配置控制器参数：

				// 旋转速度：1.0（默认值）
				// 值越大，鼠标拖动时旋转越快
				controls.rotateSpeed = 1.0;

				// 缩放速度：1.2（比默认稍快）
				// 控制鼠标滚轮或中键拖动的缩放速度
				controls.zoomSpeed = 1.2;

				// 平移速度：0.8（比默认稍慢）
				// 控制右键拖动的平移速度
				controls.panSpeed = 0.8;

				// 设置键盘按键映射：
				// 数组包含三个按键代码，分别对应：
				// [0]：旋转按键（默认是KeyA，对应A键）
				// [1]：缩放按键（默认是KeyS，对应S键）
				// [2]：平移按键（默认是KeyD，对应D键）
				// 这样用户可以用A、S、D键配合鼠标操作
				controls.keys = ['KeyA', 'KeyS', 'KeyD'];

			}

			/**
			 * 窗口大小变化事件处理函数
			 * 当浏览器窗口大小改变时，这个函数会被调用
			 * 它负责更新相机、渲染器和控制器的设置，确保3D场景正确适配新窗口大小
			 */
			function onWindowResize() {

				// 重新计算窗口的宽高比
				const aspect = window.innerWidth / window.innerHeight;

				// ============ 更新透视相机 ============

				// 更新透视相机的宽高比
				perspectiveCamera.aspect = aspect;
				// 必须调用updateProjectionMatrix()来应用宽高比的变化
				// 如果不调用，相机不会使用新的宽高比进行渲染
				perspectiveCamera.updateProjectionMatrix();

				// ============ 更新正交相机 ============

				// 更新正交相机的视锥体边界
				// 这些计算确保正交相机在任何窗口比例下都能显示正确的范围
				orthographicCamera.left = -frustumSize * aspect / 2;
				orthographicCamera.right = frustumSize * aspect / 2;
				orthographicCamera.top = frustumSize / 2;
				orthographicCamera.bottom = -frustumSize / 2;
				// 应用更新后的投影矩阵
				orthographicCamera.updateProjectionMatrix();

				// ============ 更新渲染器 ============

				// 将渲染器的尺寸更新为新的窗口尺寸
				// 这确保canvas元素填满整个窗口
				renderer.setSize(window.innerWidth, window.innerHeight);

				// ============ 更新控制器 ============

				// 通知控制器窗口大小已变化
				// 控制器需要知道新的窗口尺寸来处理用户输入
				controls.handleResize();

			}

			/**
			 * 动画循环函数
			 * 这个函数在每一帧都会被调用（通常每秒60次）
			 * 它负责更新控制器状态、渲染场景和更新性能监控器
			 * 这是Three.js应用程序的核心循环
			 */
			function animate() {

				// 更新轨迹球控制器状态
				// 这个方法处理所有待处理的用户输入（鼠标、键盘）
				// 并更新相机的位置和方向
				// 必须在每一帧调用，否则控制器不会响应用户输入
				controls.update();

				// 调用渲染函数，将3D场景绘制到canvas上
				render();

				// 更新性能监控器显示
				// 这会更新FPS计数和其他性能指标
				stats.update();

			}

			/**
			 * 渲染函数
			 * 这个函数执行实际的渲染工作
			 * 它根据当前选择的相机类型，使用相应的相机渲染场景
			 */
			function render() {

				// 根据params.orthographicCamera的值选择当前使用的相机
				// 如果为true，使用正交相机；否则使用透视相机
				const camera = (params.orthographicCamera) ? orthographicCamera : perspectiveCamera;

				// 执行渲染操作：
				// 参数1：要渲染的场景（包含所有3D对象和灯光）
				// 参数2：使用的相机（决定观察视角）
				// 这个方法将3D场景从相机的视角渲染到canvas上
				renderer.render(scene, camera);

			}

			// ============ 注释结束 ============
			// 整个Three.js应用程序的结构：
			// 1. 初始化（init）: 创建所有组件
			// 2. 动画循环（animate）: 持续运行，更新和渲染
			// 3. 事件处理（onWindowResize）: 响应用户交互
			// 4. 模块化设计：使用ES6模块，代码结构清晰

		</script>

	</body>
</html>