<!-- Three.js光线投射纹理交互演示代码功能详解
一、整体功能概述
这是一个基于Three.js的交互式3D纹理演示应用，主要展示以下核心功能：

1. 核心交互功能
实时鼠标交互：通过鼠标在3D物体表面移动，可以实时检测交点并显示对应的UV坐标位置

动态纹理更新：在纹理上绘制黄色十字标记，直观展示鼠标当前位置的纹理坐标

多物体对比：同时展示立方体、平面和圆形三种不同几何体的纹理映射效果

2. 可视化教学功能
UV坐标可视化：将抽象的UV坐标系统通过十字标记具体化

纹理变换演示：实时展示纹理偏移、重复、旋转和包裹模式的效果

不同几何体对比：展示相同纹理在不同类型几何体表面的映射差异

3. 参数控制功能
实时调节：通过GUI控制面板可以实时调整纹理的各种参数

效果即时反馈：参数调整立即在3D场景中反映，无需重新加载

二、主要技术点详解
1. Three.js核心架构
javascript
// 三大核心组件
const camera = new THREE.PerspectiveCamera(...);  // 透视相机 - 模拟人眼视角
const scene = new THREE.Scene();                  // 场景容器 - 所有3D物体的集合
const renderer = new THREE.WebGLRenderer();       // WebGL渲染器 - 硬件加速渲染
2. 光线投射(Raycaster)系统
javascript
// 核心流程：
// 1. 鼠标屏幕坐标 → 2. 标准化设备坐标 → 3. 光线投射 → 4. 交点计算
const raycaster = new THREE.Raycaster();
raycaster.setFromCamera(mouse, camera);           // 从相机发射光线
const intersects = raycaster.intersectObjects(objects); // 计算交点
坐标转换流程：
屏幕坐标 (clientX, clientY) → 像素位置

归一化坐标 (0-1范围) → 相对于容器的位置

标准化设备坐标 (-1到1) → Three.js需要的坐标系统

3D世界坐标 → 实际3D空间位置

UV纹理坐标 (0-1) → 纹理上的对应位置

3. 动态纹理生成系统
javascript
// CanvasTexture类：将HTML Canvas作为纹理源
function CanvasTexture(parentTexture) {
    this._canvas = document.createElement('canvas');   // 创建Canvas
    this._context2D = this._canvas.getContext('2d');  // 获取2D上下文
    // ... 绘制纹理内容
}

// 纹理更新机制
canvas.setCrossPosition(uv.x, uv.y);  // 设置标记位置
texture.needsUpdate = true;           // 标记纹理需要更新
纹理绘制流程：
加载背景图片 → UV测试网格纹理

清空画布 → 清除上一帧内容

绘制背景 → 基础的纹理图案

绘制十字标记 → 交互反馈指示器

标记纹理更新 → 通知Three.js更新GPU纹理

4. 纹理变换系统
javascript
// 四种基本纹理变换
circleTexture.offset.x = params.offsetX;   // 偏移：移动纹理位置
circleTexture.repeat.x = params.repeatX;   // 重复：缩放纹理显示
circleTexture.rotation = params.rotation;  // 旋转：旋转纹理角度
circleTexture.wrapS = params.wrapS;        // 包裹：处理超出边界的纹理
包裹模式类型：
RepeatWrapping：重复模式 - 纹理无限重复

ClampToEdgeWrapping：边缘拉伸 - 拉伸边缘像素

MirroredRepeatWrapping：镜像重复 - 镜像翻转重复

5. UV坐标系统定制
javascript
// 自定义UV映射示例
for (let i = 0; i < uvs.length; i++) {
    // 立方体：放大纹理效果
    uvs[i] *= 2;
    
    // 圆形：偏移并缩放纹理
    uvs[i] = (uvs[i] - 0.25) * 2;
}
6. GUI参数控制系统
javascript
const gui = new GUI();
// 创建各种控制项
gui.add(params, 'wrapS', WRAPPING).onChange(setwrapS);    // 下拉选择
gui.add(params, 'offsetX', 0, 5);                         // 滑块控制
gui.add(params, 'rotation', 0, 2 * Math.PI);              // 旋转角度
7. 响应式布局系统
javascript
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight; // 更新宽高比
    camera.updateProjectionMatrix();                       // 更新投影矩阵
    renderer.setSize(window.innerWidth, window.innerHeight); // 更新渲染尺寸
}
三、关键技术亮点
1. 单纹理多对象共享
javascript
// 一个CanvasTexture实例服务于多个Three.js纹理对象
canvas.addParent(cubeTexture);    // 立方体使用
canvas.addParent(planeTexture);   // 平面使用
canvas.addParent(circleTexture);  // 圆形使用
优势：节省内存，统一管理

效果：所有物体上的纹理同步更新

2. 实时UV坐标变换
javascript
// 应用所有纹理变换到UV坐标
intersects[0].object.material.map.transformUv(uv);
功能：考虑所有纹理变换参数（偏移、重复、旋转）

结果：准确的十字标记位置，反映实际纹理状态

3. 性能优化策略
javascript
// 只在需要时更新纹理
texture.needsUpdate = true;  // 标志位机制，避免不必要的GPU上传
四、学习价值
1. Three.js学习要点
纹理系统：理解纹理映射、UV坐标、纹理变换

交互系统：掌握光线投射原理和实现

渲染管线：了解从3D场景到2D屏幕的完整流程

2. 图形学概念
坐标系统：屏幕坐标、世界坐标、UV坐标的相互转换

纹理映射：2D纹理如何映射到3D几何体表面

实时渲染：动态更新和交互反馈的实现机制

3. 实际应用场景
3D产品展示：交互式产品查看器

游戏开发：物体选取和交互检测

数据可视化：3D数据点的交互探索

教育演示：图形学概念的可视化教学

五、运行效果
运行该代码将呈现以下效果：

初始界面：三个3D物体（立方体、平面、圆形）显示在场景中

鼠标交互：移动鼠标到物体表面，黄色十字标记跟随显示

参数调节：通过右侧控制面板调整圆形纹理的各种参数

实时反馈：所有调整立即在场景中反映，十字标记位置准确更新 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：显示这是一个Three.js光线投射纹理交互示例 -->
		<title>Three.js光线投射器纹理交互演示</title>
		<!-- 字符编码设置为UTF-8，支持中文字符 -->
		<meta charset="utf-8">
		<!-- 视口设置：适配移动设备，禁止用户缩放 -->
		<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="main.css">
		<!-- 内联CSS样式：设置页面基础样式 -->
		<style>
			/* 设置页面主体背景为白色，文字颜色为深灰色 */
			body {
				background-color: #fff;
				color: #444;
			}
			/* 设置链接颜色为浅蓝色 */
			a {
				color: #08f;
			}
		</style>
	</head>
	<body>
		<!-- 3D渲染容器：Three.js将在此div中渲染3D场景 -->
		<div id="container"></div>
		<!-- 信息展示区域：显示技术信息和版权链接 -->
		<div id="info">
			<!-- 显示项目基于Three.js，并链接到Three.js官网 -->
			基于<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a>的光线投射器纹理交互演示
		</div>

		<!-- 模块导入映射表：配置ES模块的导入路径 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 主程序脚本模块：使用ES模块语法 -->
		<script type="module">
			// 导入Three.js核心库的所有功能
			import * as THREE from 'three';
			// 导入轻量级GUI库，用于创建参数控制面板
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// 纹理包装模式常量映射表：将字符串映射到Three.js的包装模式常量
			const WRAPPING = {
				'RepeatWrapping': THREE.RepeatWrapping,          // 重复包裹模式：纹理在UV坐标超出1时重复显示
				'ClampToEdgeWrapping': THREE.ClampToEdgeWrapping, // 边缘拉伸模式：UV坐标超出1时拉伸边缘像素
				'MirroredRepeatWrapping': THREE.MirroredRepeatWrapping // 镜像重复模式：纹理以镜像方式重复
			};

			// GUI控制面板参数对象：存储纹理的各种变换参数
			const params = {
				wrapS: THREE.RepeatWrapping,     // S方向（水平方向）的纹理包裹模式
				wrapT: THREE.RepeatWrapping,     // T方向（垂直方向）的纹理包裹模式
				offsetX: 0,      // 纹理在X轴（水平方向）的偏移量（0-5范围）
				offsetY: 0,      // 纹理在Y轴（垂直方向）的偏移量（0-5范围）
				repeatX: 1,      // 纹理在X轴（水平方向）的重复次数（0-5范围）
				repeatY: 1,      // 纹理在Y轴（垂直方向）的重复次数（0-5范围）
				rotation: 0,     // 纹理旋转角度，以弧度为单位（0-2π范围）
			};

			/**
			 * CanvasTexture类 - 创建动态可交互纹理的核心类
			 * 功能：在HTML Canvas上绘制纹理，支持动态更新纹理内容
			 * 特别功能：在鼠标与3D物体交互时，在纹理对应位置绘制十字标记
			 * 
			 * @param {THREE.Texture} parentTexture - 可选的父纹理对象
			 *                             如果提供，该纹理将使用此canvas作为图像源
			 */
			function CanvasTexture( parentTexture ) {
				// 创建Canvas元素作为纹理的绘图表面
				this._canvas = document.createElement( 'canvas' );
				// 设置Canvas初始尺寸为1024x1024像素
				this._canvas.width = this._canvas.height = 1024;
				// 获取Canvas的2D绘图上下文，用于绘制纹理内容
				this._context2D = this._canvas.getContext( '2d' );

				// 初始化父纹理数组：用于跟踪所有使用此Canvas作为图像源的纹理对象
				this._parentTexture = [];

				// 如果提供了父纹理参数，将其添加到父纹理数组并建立关联
				if ( parentTexture ) {
					this._parentTexture.push( parentTexture );
					// 将Canvas设置为父纹理的图像源
					parentTexture.image = this._canvas;
				}

				// 保存当前对象的引用，用于事件回调函数中访问
				const that = this;
				
				// 创建Image对象用于加载背景纹理图片
				this._background = document.createElement( 'img' );
				
				// 设置图片加载完成后的回调函数
				this._background.addEventListener( 'load', function () {
					// 图片加载完成后，将Canvas尺寸调整为图片的实际尺寸
					that._canvas.width = that._background.naturalWidth;
					that._canvas.height = that._background.naturalHeight;

					// 计算十字标记的各种尺寸参数：
					// 十字标记的基础半径，取画布宽度和高度的1/30中的较小值
					that._crossRadius = Math.ceil( Math.min( that._canvas.width, that._canvas.height / 30 ) );
					// 十字标记的最大长度：半径乘以√2/2（约0.707），即从中心到角落的对角线长度
					that._crossMax = Math.ceil( 0.70710678 * that._crossRadius );
					// 十字标记的最小长度：最大长度的1/10
					that._crossMin = Math.ceil( that._crossMax / 10 );
					// 十字标记的线条厚度：最大长度的1/10
					that._crossThickness = Math.ceil( that._crossMax / 10 );

					// 调用绘制方法，在Canvas上绘制纹理内容
					that._draw();
				} );
				
				// 设置图片的跨域属性为空字符串，允许加载跨域图片
				this._background.crossOrigin = '';
				// 设置图片源路径：使用Three.js示例中的UV网格测试纹理
				this._background.src = 'textures/uv_grid_opengl.jpg';

				// 初始绘制纹理内容
				this._draw();
			}

			// 定义CanvasTexture类的原型对象，包含类的方法
			CanvasTexture.prototype = {
				// 构造函数指向CanvasTexture，确保正确的原型链
				constructor: CanvasTexture,

				// 类属性定义
				_canvas: null,        // HTML Canvas元素引用
				_context2D: null,     // Canvas 2D绘图上下文引用
				_xCross: 0,           // 十字标记中心点的X坐标（像素单位）
				_yCross: 0,           // 十字标记中心点的Y坐标（像素单位）

				// 十字标记的尺寸属性（初始值，将在图片加载后重新计算）
				_crossRadius: 57,     // 十字标记的半径
				_crossMax: 40,        // 十字标记的最大长度（对角线方向）
				_crossMin: 4,         // 十字标记的最小长度
				_crossThickness: 4,   // 十字标记线条的厚度

				_parentTexture: [],   // 关联的父纹理对象数组

				/**
				 * 添加父纹理方法
				 * 功能：将一个新的纹理对象关联到此CanvasTexture
				 *       使该纹理使用此Canvas作为图像源
				 * 
				 * @param {THREE.Texture} parentTexture - 要关联的Three.js纹理对象
				 */
				addParent: function ( parentTexture ) {
					// 检查该纹理是否已存在于父纹理数组中（避免重复添加）
					if ( this._parentTexture.indexOf( parentTexture ) === -1 ) {
						// 将纹理添加到父纹理数组
						this._parentTexture.push( parentTexture );
						// 将此Canvas设置为纹理的图像源
						parentTexture.image = this._canvas;
					}
				},

				/**
				 * 设置十字标记位置方法
				 * 功能：根据归一化的UV坐标（0-1范围）设置十字标记在纹理上的位置
				 *       然后重新绘制Canvas内容
				 * 
				 * @param {number} x - 归一化的X坐标（0-1范围）
				 * @param {number} y - 归一化的Y坐标（0-1范围）
				 */
				setCrossPosition: function ( x, y ) {
					// 将归一化坐标转换为Canvas上的像素坐标
					this._xCross = x * this._canvas.width;    // X方向像素坐标
					this._yCross = y * this._canvas.height;   // Y方向像素坐标
					
					// 调用私有绘制方法更新Canvas内容
					this._draw();
				},

				/**
				 * 私有绘制方法
				 * 功能：绘制完整的纹理内容，包括背景图片和十字标记
				 *       该方法不对外公开，仅在内部调用
				 */
				_draw: function () {
					// 安全检查：确保Canvas上下文已初始化
					if ( ! this._context2D ) return;

					// 第一步：清空Canvas，擦除之前绘制的内容
					this._context2D.clearRect( 0, 0, this._canvas.width, this._canvas.height );

					// 第二步：绘制背景图片
					// 将加载的UV网格图片绘制到Canvas上，作为纹理的底图
					this._context2D.drawImage( this._background, 0, 0 );

					// 第三步：绘制黄色十字标记
					// 设置十字标记的线条样式
					this._context2D.lineWidth = this._crossThickness * 3; // 线条宽度为厚度的3倍
					this._context2D.strokeStyle = '#FFFF00';              // 设置线条颜色为黄色

					// 开始绘制路径
					this._context2D.beginPath();
					
					// 绘制左上角线段：从左上角外部指向中心
					// 起点：中心点向左上角偏移(crossMax+2)像素
					this._context2D.moveTo( this._xCross - this._crossMax - 2, this._yCross - this._crossMax - 2 );
					// 终点：中心点向左上角偏移crossMin像素
					this._context2D.lineTo( this._xCross - this._crossMin, this._yCross - this._crossMin );
					
					// 绘制右下角线段：从中心指向右下角外部
					// 起点：中心点向右下角偏移crossMin像素
					this._context2D.moveTo( this._xCross + this._crossMin, this._yCross + this._crossMin );
					// 终点：中心点向右下角偏移(crossMax+2)像素
					this._context2D.lineTo( this._xCross + this._crossMax + 2, this._yCross + this._crossMax + 2 );
					
					// 绘制左下角线段：从左下角外部指向中心
					// 起点：中心点向左下角偏移(crossMax+2)像素
					this._context2D.moveTo( this._xCross - this._crossMax - 2, this._yCross + this._crossMax + 2 );
					// 终点：中心点向左下角偏移crossMin像素
					this._context2D.lineTo( this._xCross - this._crossMin, this._yCross + this._crossMin );
					
					// 绘制右上角线段：从中心指向右上角外部
					// 起点：中心点向右上角偏移crossMin像素
					this._context2D.moveTo( this._xCross + this._crossMin, this._yCross - this._crossMin );
					// 终点：中心点向右上角偏移(crossMax+2)像素
					this._context2D.lineTo( this._xCross + this._crossMax + 2, this._yCross - this._crossMax - 2 );
					
					// 描边路径，将设置的线条样式应用到路径上
					this._context2D.stroke();

					// 第四步：更新所有关联的父纹理
					// 遍历父纹理数组，将每个纹理标记为需要更新
					for ( let i = 0; i < this._parentTexture.length; i ++ ) {
						// 设置needsUpdate为true，告诉Three.js在下一帧重新上传纹理到GPU
						this._parentTexture[ i ].needsUpdate = true;
					}
				}
			};

			// 获取浏览器窗口的宽度和高度，用于设置渲染器尺寸和相机比例
			const width = window.innerWidth;
			const height = window.innerHeight;

			// 全局变量声明
			let canvas; // CanvasTexture类的实例
			let planeTexture, cubeTexture, circleTexture; // 三个3D物体对应的纹理对象
			let container; // 存放3D场景的DOM容器元素

			// Three.js核心对象
			let camera, scene, renderer; // 相机、场景、渲染器

			// 光线投射相关对象
			const raycaster = new THREE.Raycaster();      // 光线投射器：用于检测鼠标与3D物体的交点
			const mouse = new THREE.Vector2();            // 2D向量：存储标准化设备坐标（-1到1范围）
			const onClickPosition = new THREE.Vector2();  // 2D向量：存储点击位置的归一化坐标（0-1范围）

			// 程序入口：调用初始化函数
			init();

			/**
			 * 初始化函数
			 * 功能：初始化整个3D场景，包括创建场景、相机、渲染器、3D物体和事件监听
			 * 这是整个程序的起点，负责所有初始化工作
			 */
			function init() {
				// 第一步：获取DOM容器元素
				// 这个div将包含Three.js渲染的3D场景
				container = document.getElementById( 'container' );

				// 第二步：创建Three.js场景对象
				// 场景是所有3D对象的容器，类似于一个虚拟的3D世界
				scene = new THREE.Scene();
				// 设置场景背景颜色为浅灰色（十六进制颜色值0xeeeeee）
				scene.background = new THREE.Color( 0xeeeeee );

				// 第三步：创建透视相机
				// 透视相机模拟人眼的视觉效果，近大远小
				// 参数：45度视野角，窗口宽高比，近裁剪面1单位，远裁剪面1000单位
				camera = new THREE.PerspectiveCamera( 45, width / height, 1, 1000 );
				// 设置相机在3D空间中的位置
				camera.position.x = -30; // 向左偏移30单位
				camera.position.y = 40;  // 向上偏移40单位
				camera.position.z = 50;  // 向后偏移50单位
				// 让相机看向场景的中心点(0,0,0)
				camera.lookAt( scene.position );

				// 第四步：创建WebGL渲染器
				// 渲染器负责将3D场景渲染到2D Canvas上
				renderer = new THREE.WebGLRenderer();
				// 设置设备像素比，确保在高DPI屏幕上清晰显示
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器的输出尺寸为浏览器窗口尺寸
				renderer.setSize( width, height );
				// 设置动画循环回调函数，每一帧都会调用animate函数
				renderer.setAnimationLoop( animate );
				// 将渲染器的Canvas元素添加到DOM容器中
				container.appendChild( renderer.domElement );

				// 第五步：创建立方体（位于场景中间）
				// 创建纹理对象：使用动态Canvas纹理，设置映射方式和包裹模式
				cubeTexture = new THREE.Texture( undefined, THREE.UVMapping, THREE.RepeatWrapping, THREE.RepeatWrapping );
				// 设置纹理颜色空间为sRGB，确保颜色显示正确
				cubeTexture.colorSpace = THREE.SRGBColorSpace;
				// 创建CanvasTexture实例，并将立方体纹理作为父纹理传入
				canvas = new CanvasTexture( cubeTexture );
				// 创建基础材质，使用刚刚创建的纹理作为贴图
				const cubeMaterial = new THREE.MeshBasicMaterial( { map: cubeTexture } );
				// 创建立方体几何体，尺寸为20x20x20单位
				const cubeGeometry = new THREE.BoxGeometry( 20, 20, 20 );
				// 获取立方体的UV坐标数组
				// UV坐标定义了纹理如何映射到几何体表面
				let uvs = cubeGeometry.attributes.uv.array;
				
				// 修改UV坐标：将所有UV坐标值乘以2
				// 效果：纹理在立方体表面上只显示一半，看起来像是纹理被放大了
				for ( let i = 0; i < uvs.length; i ++ ) {
					uvs[ i ] *= 2;
				}

				// 创建网格对象：将几何体和材质组合成一个可渲染的3D物体
				const cube = new THREE.Mesh( cubeGeometry, cubeMaterial );
				// 设置立方体在场景中的位置
				cube.position.x = 4;   // 向右偏移4单位
				cube.position.y = -5;  // 向下偏移5单位
				cube.position.z = 0;   // 深度位置为0
				// 将立方体添加到场景中
				scene.add( cube );

				// 第六步：创建平面（位于场景左侧）
				// 创建平面纹理：使用镜像重复包裹模式
				planeTexture = new THREE.Texture( undefined, THREE.UVMapping, THREE.MirroredRepeatWrapping, THREE.MirroredRepeatWrapping );
				planeTexture.colorSpace = THREE.SRGBColorSpace;
				// 将平面纹理添加到CanvasTexture的父纹理列表中
				// 这样平面纹理也会使用同一个Canvas作为图像源
				canvas.addParent( planeTexture );
				// 创建平面材质
				const planeMaterial = new THREE.MeshBasicMaterial( { map: planeTexture } );
				// 创建平面几何体，尺寸为25x25单位
				const planeGeometry = new THREE.PlaneGeometry( 25, 25, 1, 1 );
				// 获取平面的UV坐标数组
				uvs = planeGeometry.attributes.uv.array;
				
				// 修改平面的UV坐标：同样乘以2
				for ( let i = 0; i < uvs.length; i ++ ) {
					uvs[ i ] *= 2;
				}

				// 创建平面网格对象
				const plane = new THREE.Mesh( planeGeometry, planeMaterial );
				// 设置平面在场景中的位置（左侧）
				plane.position.x = -16; // 向左偏移16单位
				plane.position.y = -5;  // 向下偏移5单位
				plane.position.z = 0;   // 深度位置为0
				// 将平面添加到场景中
				scene.add( plane );

				// 第七步：创建圆形（位于场景右侧）
				// 创建圆形纹理：使用重复包裹模式
				circleTexture = new THREE.Texture( undefined, THREE.UVMapping, THREE.RepeatWrapping, THREE.RepeatWrapping );
				circleTexture.colorSpace = THREE.SRGBColorSpace;
				// 将圆形纹理添加到CanvasTexture的父纹理列表中
				canvas.addParent( circleTexture );
				// 创建圆形材质
				const circleMaterial = new THREE.MeshBasicMaterial( { map: circleTexture } );
				// 创建圆形几何体：半径25单位，40个分段，完整圆形（0到2π弧度）
				const circleGeometry = new THREE.CircleGeometry( 25, 40, 0, Math.PI * 2 );
				// 获取圆形的UV坐标数组
				uvs = circleGeometry.attributes.uv.array;
				
				// 修改圆形的UV坐标：进行偏移和缩放变换
				// (uv - 0.25) * 2 的效果：将UV坐标中心移动到纹理的左上角区域
				for ( let i = 0; i < uvs.length; i ++ ) {
					uvs[ i ] = ( uvs[ i ] - 0.25 ) * 2;
				}

				// 创建圆形网格对象
				const circle = new THREE.Mesh( circleGeometry, circleMaterial );
				// 设置圆形在场景中的位置（右侧）
				circle.position.x = 24;  // 向右偏移24单位
				circle.position.y = -5;  // 向下偏移5单位
				circle.position.z = 0;   // 深度位置为0
				// 将圆形添加到场景中
				scene.add( circle );

				// 第八步：设置事件监听器
				// 监听窗口大小改变事件，当浏览器窗口尺寸变化时调整渲染
				window.addEventListener( 'resize', onWindowResize );
				// 监听容器内的鼠标移动事件，用于实现交互功能
				container.addEventListener( 'mousemove', onMouseMove );

				// 第九步：创建GUI控制面板
				// 实例化GUI对象，用于创建参数控制界面
				const gui = new GUI();
				// 设置控制面板的标题
				gui.title( '圆形纹理设置' );

				// 添加GUI控制项：
				// 1. S方向包裹模式选择器，选项来自WRAPPING映射表
				gui.add( params, 'wrapS', WRAPPING ).onChange( setwrapS );
				// 2. T方向包裹模式选择器
				gui.add( params, 'wrapT', WRAPPING ).onChange( setwrapT );
				// 3. X轴偏移滑块，范围0-5，步长默认
				gui.add( params, 'offsetX', 0, 5 );
				// 4. Y轴偏移滑块，范围0-5
				gui.add( params, 'offsetY', 0, 5 );
				// 5. X轴重复次数滑块，范围0-5
				gui.add( params, 'repeatX', 0, 5 );
				// 6. Y轴重复次数滑块，范围0-5
				gui.add( params, 'repeatY', 0, 5 );
				// 7. 旋转角度滑块，范围0到2π弧度（0-360度）
				gui.add( params, 'rotation', 0, 2 * Math.PI );
				// 默认打开GUI控制面板
				gui.open();
			}

			/**
			 * 窗口大小调整事件处理函数
			 * 功能：当浏览器窗口大小改变时，调整相机和渲染器的设置
			 *       确保3D场景始终正确适配窗口尺寸
			 */
			function onWindowResize() {
				// 更新相机的宽高比：使用新的窗口宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵：必须调用此方法使宽高比更改生效
				camera.updateProjectionMatrix();
				
				// 更新渲染器的输出尺寸：匹配新的窗口尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			/**
			 * 鼠标移动事件处理函数
			 * 功能：处理鼠标在3D场景容器内的移动
			 *       计算鼠标与3D物体的交点，并更新纹理上的十字标记位置
			 * 
			 * @param {MouseEvent} evt - 鼠标事件对象，包含鼠标位置等信息
			 */
			function onMouseMove( evt ) {
				// 阻止事件的默认行为（如文本选择等）
				evt.preventDefault();

				// 第一步：获取鼠标在容器内的归一化坐标
				// 调用getMousePosition函数，将鼠标的客户端坐标转换为0-1范围的归一化坐标
				const array = getMousePosition( container, evt.clientX, evt.clientY );
				// 将数组转换为THREE.Vector2向量对象
				onClickPosition.fromArray( array );

				// 第二步：执行光线投射检测
				// 调用getIntersects函数，检测从鼠标位置发射的光线与场景中所有物体的交点
				const intersects = getIntersects( onClickPosition, scene.children );

				// 第三步：处理检测结果
				// 如果检测到交点且交点包含UV坐标信息
				if ( intersects.length > 0 && intersects[ 0 ].uv ) {
					// 获取第一个交点的UV坐标
					// UV坐标表示交点在物体纹理上的位置（0-1范围）
					const uv = intersects[ 0 ].uv;
					// 对UV坐标应用纹理变换（偏移、重复、旋转等）
					// 确保十字标记位置考虑了纹理的所有变换参数
					intersects[ 0 ].object.material.map.transformUv( uv );
					// 调用CanvasTexture的setCrossPosition方法
					// 在纹理的对应位置绘制十字标记
					canvas.setCrossPosition( uv.x, uv.y );
				}
			}

			/**
			 * 获取鼠标在容器内的归一化坐标
			 * 功能：将鼠标的全局客户端坐标转换为相对于指定容器的归一化坐标（0-1范围）
			 * 
			 * @param {HTMLElement} dom - DOM容器元素，通常是渲染3D场景的div
			 * @param {number} x - 鼠标事件的clientX属性（全局X坐标）
			 * @param {number} y - 鼠标事件的clientY属性（全局Y坐标）
			 * @returns {Array} 包含两个元素的数组：[归一化X坐标, 归一化Y坐标]
			 */
			function getMousePosition( dom, x, y ) {
				// 获取容器元素在视口中的位置和尺寸信息
				const rect = dom.getBoundingClientRect();
				// 返回归一化坐标：
				// X坐标 = (鼠标X - 容器左边界) / 容器宽度
				// Y坐标 = (鼠标Y - 容器上边界) / 容器高度
				return [ 
					( x - rect.left ) / rect.width,   // 归一化X坐标（0-1范围）
					( y - rect.top ) / rect.height    // 归一化Y坐标（0-1范围）
				];
			}

			/**
			 * 执行光线投射检测
			 * 功能：从相机位置向鼠标指向的3D空间发射一条光线
			 *       检测光线与场景中指定物体的交点
			 * 
			 * @param {Object} point - 包含x和y属性的对象，表示归一化坐标（0-1范围）
			 * @param {Array} objects - Three.js物体数组，要检测交点的物体集合
			 * @returns {Array} 交点数组，每个交点对象包含交点位置、法线、UV等信息
			 */
			function getIntersects( point, objects ) {
				// 第一步：将归一化坐标转换为标准化设备坐标
				// Three.js的Raycaster需要标准化设备坐标，范围是：
				// X: -1（左）到 1（右）
				// Y: -1（下）到 1（上）
				// 计算方式：
				// X: (point.x * 2) - 1  将0-1映射到-1到1
				// Y: -(point.y * 2) + 1 将0-1映射到1到-1（反转Y轴，因为屏幕坐标Y轴向下）
				mouse.set( ( point.x * 2 ) - 1, - ( point.y * 2 ) + 1 );

				// 第二步：设置光线投射器的起点和方向
				// 从相机位置向鼠标指向的3D空间位置发射光线
				raycaster.setFromCamera( mouse, camera );

				// 第三步：检测光线与物体的交点
				// intersectObjects方法返回所有交点，按距离从近到远排序
				// 参数1: 要检测的物体数组
				// 参数2: false表示不检测子物体（只检测直接子级）
				return raycaster.intersectObjects( objects, false );
			}

			/**
			 * 动画循环函数
			 * 功能：Three.js的渲染循环，每一帧都会调用此函数
			 *       更新场景状态并重新渲染
			 */
			function animate() {
				// 第一步：根据GUI控制面板的参数更新圆形纹理的属性
				// 这些属性会影响纹理在圆形物体上的显示方式
				circleTexture.offset.x = params.offsetX;   // 设置纹理在X轴的偏移量
				circleTexture.offset.y = params.offsetY;   // 设置纹理在Y轴的偏移量
				circleTexture.repeat.x = params.repeatX;   // 设置纹理在X轴的重复次数
				circleTexture.repeat.y = params.repeatY;   // 设置纹理在Y轴的重复次数
				circleTexture.rotation = params.rotation;  // 设置纹理的旋转角度（弧度）

				// 第二步：渲染场景
				// 调用渲染器的render方法，将3D场景从相机视角渲染到Canvas上
				renderer.render( scene, camera );
			}

			/**
			 * 设置纹理S方向包裹模式的回调函数
			 * 功能：当GUI中S方向包裹模式参数改变时调用
			 *       更新圆形纹理的S方向包裹模式
			 * 
			 * @param {THREE.Wrapping} value - 新的包裹模式值
			 */
			function setwrapS( value ) {
				// 更新圆形纹理的S方向包裹模式
				circleTexture.wrapS = value;
				// 标记纹理需要更新，告诉Three.js在下一帧重新上传纹理数据到GPU
				circleTexture.needsUpdate = true;
			}

			/**
			 * 设置纹理T方向包裹模式的回调函数
			 * 功能：当GUI中T方向包裹模式参数改变时调用
			 *       更新圆形纹理的T方向包裹模式
			 * 
			 * @param {THREE.Wrapping} value - 新的包裹模式值
			 */
			function setwrapT( value ) {
				// 更新圆形纹理的T方向包裹模式
				circleTexture.wrapT = value;
				// 标记纹理需要更新
				circleTexture.needsUpdate = true;
			}
		</script>
	</body>
</html>