<!-- Three.js WebGPU 粗线条演示 - 详细功能与技术分析
一、核心功能概述
1. 主要演示内容
这是一个基于Three.js WebGPU版本的交互式3D演示，专门展示"粗线条"（Fat Lines）的渲染和光线投射检测功能。

2. 交互体验
用户移动鼠标时，程序会实时检测鼠标射线与3D线条的交点

显示两个可视化球体：

红色球体：表示光线与线条的实际交点（考虑线条宽度）

绿色球体：表示线条几何体上的最近点（线条中心线）

提供完整的参数调节面板，让用户可以实验不同设置的效果

3. 视觉展示
渲染一条彩虹色渐变的3D螺旋线条

支持两种线条类型：连续线条和线段集合

线条可自动旋转，展示3D效果

二、主要技术特性
1. WebGPU渲染引擎
javascript
// 使用Three.js的WebGPU后端
import * as THREE from 'three/webgpu';
const renderer = new THREE.WebGPURenderer({ antialias: true, alpha: true });
下一代图形API：WebGPU是新的Web图形标准，提供比WebGL更底层的GPU访问

性能优势：更好的多线程支持、更高效的资源管理

现代特性：支持计算着色器、光线追踪等高级功能

2. 粗线条渲染技术
javascript
// 专门的粗线条材质和几何体
import { Line2 } from 'three/addons/lines/webgpu/Line2.js';
import { LineGeometry } from 'three/addons/lines/LineGeometry.js';
const matLine = new THREE.Line2NodeMaterial({
    linewidth: 1,
    worldUnits: true,
    vertexColors: true
});
可变宽度线条：不像传统线条只有1像素宽，可以设置任意宽度

两种单位模式：

世界单位：线条宽度随距离变化（透视正确）

像素单位：线条在屏幕上保持固定像素宽度

GPU加速：使用专门的着色器进行高效渲染

3. 精确的光线投射算法
javascript
// 针对粗线条的特殊光线投射设置
raycaster.params.Line2 = {};
raycaster.params.Line2.threshold = 0;
const intersects = raycaster.intersectObject(obj);
阈值检测：可以设置检测范围，提高用户体验

双交点计算：

point：实际交点（考虑线条宽度）

pointOnLine：线条中心线上的最近点

性能优化：针对粗线条几何体优化的相交检测算法

4. 高级抗锯齿技术
javascript
// Alpha-to-coverage抗锯齿
matLine.alphaToCoverage = true;
MSAA集成：利用多重采样抗锯齿改善透明边缘

线条边缘平滑：特别适合粗线条的边缘抗锯齿

WebGPU原生支持：比传统后处理抗锯齿更高效

5. 动态几何生成
javascript
// 使用Catmull-Rom样条曲线生成平滑螺旋线
const spline = new THREE.CatmullRomCurve3(points);
for (let i = 0; i < divisions; i++) {
    const t = i / l;
    spline.getPoint(t, point);
    // ... 生成顶点和颜色数据
}
样条曲线插值：使用Catmull-Rom曲线生成平滑路径

顶点属性分离：位置和颜色数据分别存储和传输

HSL色彩空间：使用HSL更容易创建平滑的颜色渐变

6. 模块化架构
javascript
// ES6模块导入
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { Inspector } from 'three/addons/inspector/Inspector.js';
ES6模块：现代JavaScript模块系统

导入映射：使用importmap配置模块路径

代码分离：功能模块化，便于维护和扩展

三、关键技术实现细节
1. 坐标系统转换
javascript
// 屏幕坐标到NDC（标准化设备坐标）转换
pointer.x = (event.clientX / window.innerWidth) * 2 - 1;
pointer.y = -(event.clientY / window.innerHeight) * 2 + 1;
屏幕坐标：左上角原点，像素单位

NDC坐标：中心原点，范围[-1, 1]

射线构建：从相机通过NDC点构建3D射线

2. 动画系统
javascript
// 基于时间的动画，帧率无关
const delta = clock.getDelta();
line.rotation.y += delta * 0.1;
时钟对象：THREE.Clock提供精确的时间测量

Delta时间：确保动画速度在不同帧率下保持一致

矩阵更新：自动处理变换矩阵的更新

3. 内存管理优化
javascript
// 重用临时对象，减少垃圾回收
const point = new THREE.Vector3();
const color = new THREE.Color();
// 在循环中重复使用，而不是每次创建新对象
对象池模式：重用临时对象

缓冲区重用：几何体数据使用ArrayBuffer高效存储

GPU内存管理：WebGPU自动管理GPU资源

4. 调试和监控
javascript
// 集成调试检查器
renderer.inspector = new Inspector();
// 性能监控
renderer = new THREE.WebGPURenderer({ trackTimestamp: true });
实时检查：可以查看场景图、材质属性等

性能分析：跟踪渲染时间和其他性能指标

参数实时调整：GUI面板允许运行时修改参数

四、应用场景和扩展性
1. 实际应用场景
数据可视化：科学计算、金融图表的时间序列

CAD/CAM软件：工程制图的线条渲染

游戏开发：特殊效果、轨迹绘制

地图应用：路径规划、导航线路

2. 可扩展功能
虚线/点线支持：扩展材质支持多种线条样式

线条动画：流动效果、生长动画

多线条交互：复杂线条网络的选择和交互

LOD系统：根据距离调整线条细节级别

3. 性能优化方向
实例化渲染：同时渲染大量相似线条

GPU计算：使用计算着色器处理复杂几何

视锥剔除：只渲染视野内的线条

压缩格式：减少几何数据传输量

五、技术价值和学习意义
1. 教育价值
WebGPU入门：展示了现代Web图形API的基本用法

3D数学应用：实际应用了射线-几何体相交算法

图形管线理解：展示了从JavaScript到GPU的完整流程

性能优化范例：提供了实时图形应用的优化模式

2. 技术前瞻性
下一代Web标准：基于WebGPU，代表未来Web图形方向

跨平台潜力：可在桌面、移动设备、甚至原生应用中运行

向后兼容：Three.js提供了WebGL回退方案

3. 代码质量示范
模块化设计：清晰的功能分离

可配置性：通过参数控制大部分行为

错误处理：内置的边界检查和默认值

文档完整性：详细的注释和说明 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：显示应用的主题和功能 -->
		<title>Three.js WebGPU - 粗线条演示：光线投射与交互检测</title>
		<!-- 字符编码设置：使用UTF-8支持多语言字符 -->
		<meta charset="utf-8">
		<!-- 视口设置：确保页面在移动设备上正确显示 -->
		<!-- width=device-width: 宽度等于设备宽度 -->
		<!-- user-scalable=no: 禁止用户缩放 -->
		<!-- minimum-scale=1.0, maximum-scale=1.0: 固定缩放比例为1.0 -->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 引入外部CSS样式表：用于页面布局和样式 -->
		<link type="text/css" rel="stylesheet" href="example.css">
	</head>

	<body>
		<!-- 主渲染容器：Three.js渲染器将把WebGPU画布放在这里 -->
		<div id="container"></div>

		<!-- 信息显示区域：展示标题、说明和链接 -->
		<div id="info">
			<!-- Three.js官方网站链接，带logo样式 -->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题包装器：包含主标题和子标题 -->
			<div class="title-wrapper">
				<!-- 主标题链接到Three.js官网 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 子标题：当前演示的名称 -->
				<span>粗线条演示：光线投射检测</span>
			</div>

			<!-- 详细说明文字：解释演示的功能和使用方法 -->
			<small>
				粗线条的光线投射检测演示。移动鼠标测试光线投射功能。<br>
				红色球体显示实际交点，绿色球体显示线上最近点。<br>
				右侧面板可调整线条参数和检测设置。
			</small>
		</div>

		<!-- 导入映射配置：告诉浏览器如何解析模块导入语句 -->
		<!-- 这是现代JavaScript模块系统的配置 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.webgpu.js",
					"three/webgpu": "../build/three.webgpu.js",
					"three/tsl": "../build/three.tsl.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 主JavaScript模块：使用module类型支持ES6模块 -->
		<script type="module">
			// ============== 模块导入部分 ==============
			// 导入Three.js的WebGPU版本核心库
			// WebGPU是下一代Web图形API，提供更底层的GPU访问
			import * as THREE from 'three/webgpu';

			// 导入调试检查器：用于运行时检查和调试Three.js场景
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入轨道控制器：允许用户通过鼠标拖拽、滚轮缩放来旋转相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入粗线条相关模块：
			// LineSegments2: 基于GPU的线段集合渲染器，支持可变的线条宽度
			import { LineSegments2 } from 'three/addons/lines/webgpu/LineSegments2.js';
			// LineSegmentsGeometry: 线段集合的几何数据容器
			import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
			// Line2: 基于GPU的连续线条渲染器
			import { Line2 } from 'three/addons/lines/webgpu/Line2.js';
			// LineGeometry: 连续线条的几何数据容器
			import { LineGeometry } from 'three/addons/lines/LineGeometry.js';

			// ============== 全局变量声明 ==============
			// 线条对象变量：
			let line;           // 主要的连续线条对象（Line2实例）
			let thresholdLine;  // 用于可视化检测阈值的连续线条
			let segments;       // 主要的线段集合对象（LineSegments2实例）
			let thresholdSegments; // 用于可视化检测阈值的线段集合
			
			// Three.js核心对象：
			let renderer;  // WebGPU渲染器实例，负责将3D场景绘制到画布上
			let scene;     // 场景对象，包含所有3D对象、灯光、相机等
			let camera;    // 相机对象，定义观察3D场景的视角
			let controls;  // 轨道控制器，处理用户交互
			
			// 交互可视化对象：
			let sphereInter;   // 红色球体：显示光线与线条的实际交点
			let sphereOnLine;  // 绿色球体：显示线条上的最近点
			
			// UI相关：
			let gui;    // GUI控制面板实例，用于参数调整
			let clock;  // 时钟对象，用于时间计算和动画控制

			// ============== 辅助对象创建 ==============
			// 创建颜色对象，用于临时存储和操作颜色值
			// THREE.Color提供了多种颜色空间转换和操作方法
			const color = new THREE.Color();

			// 创建二维向量表示鼠标指针位置
			// 初始化为(Infinity, Infinity)表示鼠标不在屏幕上
			// 标准化设备坐标(NDC)：x和y的范围从-1到1
			const pointer = new THREE.Vector2(Infinity, Infinity);

			// 创建光线投射器(Raycaster)
			// 用于计算鼠标发出的射线与3D对象的交点
			const raycaster = new THREE.Raycaster();
			// 为Line2类型的对象设置特定的光线投射参数
			// Line2是Three.js的粗线条实现，需要特殊处理
			raycaster.params.Line2 = {};
			// 设置检测阈值：允许检测到离线条一定距离内的点
			// 阈值越大，检测范围越宽，用户体验越好但精度降低
			raycaster.params.Line2.threshold = 0;

			// ============== 材质创建 ==============
			// 创建主要线条材质（Line2NodeMaterial）
			// Line2NodeMaterial是专门为粗线条设计的材质，支持GPU加速
			const matLine = new THREE.Line2NodeMaterial({
				color: 0xffffff,       // 线条基础颜色：白色（十六进制表示）
				linewidth: 1,          // 线条宽度：1个单位（根据worldUnits设置决定单位类型）
				worldUnits: true,      // true: 使用世界单位（随距离变化）
				// false: 使用像素单位（固定屏幕像素宽度）
				vertexColors: true,    // 启用顶点颜色：允许几何体的每个顶点有自己的颜色
				alphaToCoverage: true, // 启用alpha-to-coverage抗锯齿技术
				// 这项技术使用多重采样抗锯齿(MSAA)来改善透明边缘的质量
			});

			// 创建阈值可视化线条材质
			// 这个材质用于显示光线检测的实际范围
			const matThresholdLine = new THREE.Line2NodeMaterial({
				color: 0xffffff,       // 基础颜色：白色
				linewidth: matLine.linewidth, // 宽度与主线条保持一致
				worldUnits: true,      // 使用世界单位
				// vertexColors: true,  // 注释掉：使用单一颜色而不是顶点颜色
				transparent: true,     // 启用透明度：允许材质半透明显示
				opacity: 0.2,          // 不透明度：20%，半透明效果
				depthTest: false,      // 禁用深度测试：始终显示在最前面
				visible: false,        // 初始不可见：需要时才显示
			});

			// ============== GUI控制参数定义 ==============
			// 这些参数将通过GUI面板暴露给用户调整
			const params = {
				'线条类型': 1,                     // 0: 连续线条，1: 线段集合
				'使用世界单位': matLine.worldUnits,   // 切换宽度单位类型
				'显示检测阈值': matThresholdLine.visible, // 显示/隐藏阈值可视化
				'线条宽度': matLine.linewidth,       // 调整线条的视觉宽度
				'启用Alpha抗锯齿': matLine.alphaToCoverage, // 切换抗锯齿技术
				'检测阈值': raycaster.params.Line2.threshold, // 调整光线检测的灵敏度
				'线条平移': 0,                       // 沿X轴移动线条位置
				'启用动画': true                     // 开启/关闭自动旋转动画
			};

			// ============== 初始化函数调用 ==============
			// 程序入口点：初始化所有Three.js对象和设置
			init();

			// ============== 主要函数定义 ==============
			/**
			 * 初始化函数：创建和设置所有Three.js组件
			 * 这是整个应用的启动函数，按顺序执行：
			 * 1. 创建渲染器和场景
			 * 2. 设置相机和控制器
			 * 3. 创建几何体和材质
			 * 4. 添加事件监听器
			 * 5. 初始化GUI
			 */
			function init() {
				// 创建时钟对象：用于精确的时间计算和动画控制
				// THREE.Clock可以计算帧间时间差(delta time)
				clock = new THREE.Clock();

				// 创建WebGPU渲染器
				// WebGPURenderer是Three.js的WebGPU后端实现
				renderer = new THREE.WebGPURenderer({
					antialias: true,      // 启用抗锯齿：平滑边缘
					alpha: true,          // 启用alpha通道：支持透明背景
					trackTimestamp: true  // 跟踪时间戳：用于性能监控
				});
				
				// 设置设备像素比：确保在高DPI屏幕上清晰显示
				// window.devicePixelRatio获取屏幕的物理像素与逻辑像素比例
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器尺寸为整个浏览器窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置清除颜色：黑色完全透明(0x000000, 0.0)
				// 这样页面背景可以透过3D场景显示
				renderer.setClearColor(0x000000, 0.0);
				
				// 设置动画循环函数：animate函数将在每一帧被调用
				// 这是Three.js的渲染循环机制
				renderer.setAnimationLoop(animate);
				
				// 附加调试检查器到渲染器
				// 检查器提供场景图查看、性能监控等功能
				renderer.inspector = new Inspector();
				
				// 将渲染器的DOM元素（canvas画布）添加到页面body中
				document.body.appendChild(renderer.domElement);

				// 创建场景对象
				// 场景是所有3D对象的容器，包括网格、灯光、相机等
				scene = new THREE.Scene();

				// 创建透视相机(PerspectiveCamera)
				// 参数说明：
				// 40 - 视野角度(FOV)，单位是度，垂直方向的角度
				// window.innerWidth / window.innerHeight - 宽高比
				// 1 - 近裁剪面：距离相机多近开始渲染
				// 1000 - 远裁剪面：距离相机多远停止渲染
				camera = new THREE.PerspectiveCamera(40, window.innerWidth / window.innerHeight, 1, 1000);
				
				// 设置相机初始位置：(x, y, z)坐标系
				// x: -40（左侧），y: 0（水平面），z: 60（前方）
				camera.position.set(-40, 0, 60);

				// 创建轨道控制器(OrbitControls)
				// 将相机和渲染器的DOM元素关联，实现鼠标交互
				controls = new OrbitControls(camera, renderer.domElement);
				
				// 设置相机控制限制：
				controls.minDistance = 10;  // 最小缩放距离：防止相机穿入对象内部
				controls.maxDistance = 500; // 最大缩放距离：防止相机过远

				// 创建交点可视化球体
				// SphereGeometry参数：半径0.25，宽度分段数8，高度分段数4
				// 分段数较低是为了性能优化，因为球体只是视觉辅助
				const sphereGeometry = new THREE.SphereGeometry(0.25, 8, 4);
				
				// 实际交点球体材质（红色）
				const sphereInterMaterial = new THREE.MeshBasicMaterial({
					color: 0xff0000,   // 红色：表示光线与线条的实际交点
					depthTest: false   // 禁用深度测试：始终显示在最前面
				});
				
				// 线上最近点球体材质（绿色）
				const sphereOnLineMaterial = new THREE.MeshBasicMaterial({
					color: 0x00ff00,   // 绿色：表示线条上的最近点
					depthTest: false   // 禁用深度测试
				});

				// 创建两个球体网格对象
				sphereInter = new THREE.Mesh(sphereGeometry, sphereInterMaterial);
				sphereOnLine = new THREE.Mesh(sphereGeometry, sphereOnLineMaterial);
				
				// 初始时隐藏球体：只有在检测到交点时才显示
				sphereInter.visible = false;
				sphereOnLine.visible = false;
				
				// 设置渲染顺序：较高的值会在后期渲染，显示在其他对象上面
				sphereInter.renderOrder = 10;
				sphereOnLine.renderOrder = 10;
				
				// 将球体添加到场景中
				scene.add(sphereInter);
				scene.add(sphereOnLine);

				// ============== 创建螺旋线条数据 ==============
				// 生成用于创建螺旋线条的几何数据
				const positions = [];  // 顶点位置数组：[x1, y1, z1, x2, y2, z2, ...]
				const colors = [];     // 顶点颜色数组：[r1, g1, b1, r2, g2, b2, ...]
				const points = [];     // 控制点数组，用于定义样条曲线

				// 生成螺旋线的控制点
				// 使用参数方程：x = t*sin(2t), y = t, z = t*cos(2t)
				// 这产生了一个在xz平面旋转的螺旋线，同时沿y轴上升
				for (let i = -50; i < 50; i++) {
					const t = i / 3;  // 参数t控制螺旋线的密度
					// 创建三维向量点并添加到数组
					points.push(new THREE.Vector3(
						t * Math.sin(2 * t),  // x坐标：正弦函数产生旋转
						t,                    // y坐标：线性增长产生上升
						t * Math.cos(2 * t)   // z坐标：余弦函数产生旋转
					));
				}

				// 创建Catmull-Rom样条曲线
				// Catmull-Rom曲线经过所有控制点，产生平滑的曲线
				// 比直接连接点更平滑，比贝塞尔曲线更容易控制
				const spline = new THREE.CatmullRomCurve3(points);
				
				// 计算曲线上的采样点数量：控制点数的3倍，确保曲线足够平滑
				const divisions = Math.round(3 * points.length);
				
				// 临时变量重用，避免频繁创建对象（性能优化）
				const point = new THREE.Vector3();  // 用于存储从曲线上获取的点
				const color = new THREE.Color();    // 用于临时颜色计算

				// 沿着样条曲线采样，生成密集的顶点数据
				for (let i = 0, l = divisions; i < l; i++) {
					// 计算参数t：从0到1的归一化值
					const t = i / l;
					
					// 从样条曲线上获取点位置
					spline.getPoint(t, point);
					
					// 将点坐标添加到位置数组
					positions.push(point.x, point.y, point.z);
					
					// 基于参数t计算颜色：使用HSL色彩空间
					// HSL色彩空间更容易创建渐变效果：
					// H（色调）：t * 360°，产生彩虹色渐变
					// S（饱和度）：1.0，完全饱和
					// L（亮度）：0.5，中等亮度
					color.setHSL(t, 1.0, 0.5, THREE.SRGBColorSpace);
					
					// 将颜色添加到颜色数组（RGB格式）
					colors.push(color.r, color.g, color.b);
				}

				// ============== 创建线条几何体 ==============
				// 创建连续线条几何体（LineGeometry）
				// LineGeometry用于绘制连续的、平滑连接的线条
				const lineGeometry = new LineGeometry();
				lineGeometry.setPositions(positions);  // 设置顶点位置数据
				lineGeometry.setColors(colors);        // 设置顶点颜色数据

				// 创建线段集合几何体（LineSegmentsGeometry）
				// LineSegmentsGeometry用于绘制独立的线段集合
				// 与LineGeometry不同，线段之间不保证平滑连接
				const segmentsGeometry = new LineSegmentsGeometry();
				segmentsGeometry.setPositions(positions);
				segmentsGeometry.setColors(colors);

				// ============== 创建线条对象并添加到场景 ==============
				// 创建线段集合对象（LineSegments2）
				// LineSegments2是WebGPU优化的线段渲染器
				segments = new LineSegments2(segmentsGeometry, matLine);
				// 计算线段距离：用于后续的渐变效果或动画
				segments.computeLineDistances();
				// 设置缩放：1,1,1表示原始大小
				segments.scale.set(1, 1, 1);
				// 将对象添加到场景
				scene.add(segments);

				// 创建阈值线段集合：用于可视化检测范围
				thresholdSegments = new LineSegments2(segmentsGeometry, matThresholdLine);
				thresholdSegments.computeLineDistances();
				thresholdSegments.scale.set(1, 1, 1);
				scene.add(thresholdSegments);

				// 创建连续线条对象（Line2）
				// Line2是WebGPU优化的连续线条渲染器
				line = new Line2(lineGeometry, matLine);
				line.computeLineDistances();
				line.scale.set(1, 1, 1);
				scene.add(line);

				// 创建阈值连续线条：用于可视化检测范围
				thresholdLine = new Line2(lineGeometry, matThresholdLine);
				thresholdLine.computeLineDistances();
				thresholdLine.scale.set(1, 1, 1);
				scene.add(thresholdLine);

				// ============== 额外几何体创建（备用） ==============
				// 创建标准的BufferGeometry（Three.js通用几何体格式）
				// 这里只是演示如何创建，实际未使用
				const geo = new THREE.BufferGeometry();
				// 设置位置属性：3个值表示一个顶点(x, y, z)
				geo.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
				// 设置颜色属性：3个值表示一个颜色(r, g, b)
				geo.setAttribute('color', new THREE.Float32BufferAttribute(colors, 3));

				// ============== 初始设置 ==============
				// 根据初始参数设置显示哪种线条类型
				switchLine(params['线条类型']);

				// ============== 事件监听器设置 ==============
				// 监听鼠标/指针移动事件
				// pointermove比mousemove更通用，支持触摸设备
				document.addEventListener('pointermove', onPointerMove);
				
				// 监听窗口大小变化事件
				window.addEventListener('resize', onWindowResize);
				
				// 立即调用一次，确保初始尺寸正确
				onWindowResize();

				// 初始化GUI控制面板
				initGui();
			}

			/**
			 * 窗口大小变化处理函数
			 * 当浏览器窗口大小改变时，调整渲染器和相机设置
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				// 宽高比 = 窗口宽度 / 窗口高度
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 当相机参数改变后，必须调用此方法更新内部矩阵
				camera.updateProjectionMatrix();

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

			/**
			 * 指针移动事件处理函数
			 * 将屏幕坐标转换为Three.js使用的标准化设备坐标(NDC)
			 * @param {PointerEvent} event - 指针事件对象
			 */
			function onPointerMove(event) {
				// 将鼠标X坐标转换为NDC：
				// 1. event.clientX / window.innerWidth：得到0到1的比值
				// 2. * 2：扩展到0到2
				// 3. - 1：转换到-1到1的范围
				// 屏幕左边缘对应-1，右边缘对应1
				pointer.x = (event.clientX / window.innerWidth) * 2 - 1;
				
				// 将鼠标Y坐标转换为NDC：
				// 1. 乘以-1：因为屏幕坐标原点在左上角，而NDC原点在中心
				// 2. 屏幕顶部对应1，底部对应-1
				pointer.y = -(event.clientY / window.innerHeight) * 2 + 1;
			}

			/**
			 * 动画循环函数（每帧调用）
			 * 这是Three.js应用的核心循环，负责：
			 * 1. 更新动画状态
			 * 2. 执行光线投射检测
			 * 3. 渲染场景
			 */
			async function animate() {
				// 获取时间增量：上一帧到当前帧的时间（秒）
				// 用于时间相关的动画，确保动画速度与帧率无关
				const delta = clock.getDelta();

				// 确定当前哪个线条对象是可见的，用于光线投射检测
				// 如果连续线条可见，则检测连续线条；否则检测线段集合
				const obj = line.visible ? line : segments;
				
				// 同步阈值线条的位置和旋转，确保它们与主要线条完全一致
				// 这样阈值可视化才能准确反映实际检测范围
				thresholdLine.position.copy(line.position);
				thresholdLine.quaternion.copy(line.quaternion);
				thresholdSegments.position.copy(segments.position);
				thresholdSegments.quaternion.copy(segments.quaternion);

				// 如果启用了动画，旋转线条对象
				// delta * 0.1：控制旋转速度，每秒钟旋转0.1弧度（约5.7度）
				if (params.animate) {
					line.rotation.y += delta * 0.1;  // 绕Y轴旋转
					segments.rotation.y = line.rotation.y;  // 同步线段集合的旋转
				}

				// ============== 光线投射检测 ==============
				// 从相机位置和鼠标位置创建光线
				// 这条光线从相机出发，穿过鼠标在3D空间中的对应点
				raycaster.setFromCamera(pointer, camera);

				// 检测光线与当前可见线条对象的交点
				// intersectObject返回一个数组，包含所有交点信息
				const intersects = raycaster.intersectObject(obj);

				// 如果有交点
				if (intersects.length > 0) {
					// 显示两个球体：一个用于实际交点，一个用于线上最近点
					sphereInter.visible = true;
					sphereOnLine.visible = true;

					// 更新球体位置
					// point: 光线与线条的实际交点（可能在线条宽度范围内）
					sphereInter.position.copy(intersects[0].point);
					// pointOnLine: 线条几何体上的最近点（实际线条中心）
					sphereOnLine.position.copy(intersects[0].pointOnLine);

					// 获取交点处的颜色信息
					// faceIndex: 交点的面索引，用于查找对应的颜色
					const index = intersects[0].faceIndex;
					
					// 从几何体中获取颜色属性
					// 'instanceColorStart'是粗线条材质使用的颜色属性名称
					const colors = obj.geometry.getAttribute('instanceColorStart');
					
					// 从颜色缓冲区中读取指定索引的颜色
					color.fromBufferAttribute(colors, index);

					// 设置球体颜色，基于交点颜色进行偏移
					// offsetHSL: 调整HSL值产生不同的颜色变体
					// 红色球体：色调增加0.3（变暖色调）
					sphereInter.material.color.copy(color).offsetHSL(0.3, 0, 0);
					// 绿色球体：色调增加0.7（变冷色调）
					sphereOnLine.material.color.copy(color).offsetHSL(0.7, 0, 0);

					// 更改鼠标指针样式为十字准星，表示当前在交互状态
					renderer.domElement.style.cursor = 'crosshair';
				} else {
					// 如果没有交点，隐藏球体并恢复默认指针
					sphereInter.visible = false;
					sphereOnLine.visible = false;
					renderer.domElement.style.cursor = '';
				}

				// 渲染场景：将3D场景绘制到画布上
				// 这是WebGPU管线的执行入口
				renderer.render(scene, camera);
			}

			/**
			 * 切换线条类型函数
			 * 控制显示连续线条还是线段集合
			 * @param {number} val - 线条类型：0=连续线条，1=线段集合
			 */
			function switchLine(val) {
				switch (val) {
					case 0:  // 显示连续线条，隐藏线段集合
						line.visible = true;
						thresholdLine.visible = true;

						segments.visible = false;
						thresholdSegments.visible = false;
						break;

					case 1:  // 显示线段集合，隐藏连续线条
						line.visible = false;
						thresholdLine.visible = false;

						segments.visible = true;
						thresholdSegments.visible = true;
						break;
				}
			}

			/**
			 * 初始化GUI控制面板
			 * 创建交互式控制面板，允许用户调整各种参数
			 */
			function initGui() {
				// 使用检查器创建参数面板，标题为"设置"
				gui = renderer.inspector.createParameters('设置');

				// 添加线条类型选择控件
				// 使用下拉菜单选择连续线条或线段集合
				gui.add(params, '线条类型', {
					'连续线条': 0,
					'线段集合': 1
				}).onChange(function(val) {
					// 当值改变时，切换显示的线条类型
					switchLine(val);
				});

				// 添加世界单位切换控件
				// 控制线条宽度使用世界单位还是像素单位
				gui.add(params, '使用世界单位').onChange(function(val) {
					// 更新主线条材质的单位设置
					matLine.worldUnits = val;
					// 标记材质需要更新（Three.js优化机制）
					matLine.needsUpdate = true;

					// 同时更新阈值线条材质的单位设置
					matThresholdLine.worldUnits = val;
					matThresholdLine.needsUpdate = true;
				});

				// 添加阈值可视化切换控件
				// 显示或隐藏表示检测范围的半透明线条
				gui.add(params, '显示检测阈值').onChange(function(val) {
					matThresholdLine.visible = val;
				});

				// 添加线条宽度控件
				// 范围从1到10，调整线条的视觉粗细
				gui.add(params, '线条宽度', 1, 10).onChange(function(val) {
					// 更新主线条宽度
					matLine.linewidth = val;
					// 更新阈值线条宽度：主线条宽度 + 检测阈值
					// 这样阈值可视化能准确显示检测范围
					matThresholdLine.linewidth = matLine.linewidth + raycaster.params.Line2.threshold;
				});

				// 添加Alpha抗锯齿切换控件
				// 控制是否使用alpha-to-coverage技术改善线条边缘
				gui.add(params, '启用Alpha抗锯齿').onChange(function(val) {
					matLine.alphaToCoverage = val;
				});

				// 添加检测阈值控件
				// 范围从0到10，控制光线检测的灵敏度
				gui.add(params, '检测阈值', 0, 10).onChange(function(val) {
					// 更新光线投射器的检测阈值
					raycaster.params.Line2.threshold = val;
					// 更新阈值线条的宽度以匹配新的检测范围
					matThresholdLine.linewidth = matLine.linewidth + raycaster.params.Line2.threshold;
				});

				// 添加线条平移控件
				// 范围从0到10，沿X轴移动所有线条
				gui.add(params, '线条平移', 0, 10).onChange(function(val) {
					// 同时移动两种类型的线条，保持位置同步
					line.position.x = val;
					segments.position.x = val;
				});

				// 添加动画开关控件
				// 开启或关闭线条的自动旋转动画
				gui.add(params, '启用动画');
			}
		</script>
	</body>
</html>