<!-- 代码功能概述
这是一个基于 Three.js 的交互式 犹他茶壶 3D 可视化应用。犹他茶壶是计算机图形学中的经典测试模型，由 Martin Newell 于 1975 年在犹他大学创建，已成为 3D 图形领域的标志性测试对象。

核心功能：
3D 茶壶可视化：展示经典的犹他茶壶模型

交互式控制：用户可以通过 GUI 实时调整茶壶的各种参数

多材质渲染：支持 6 种不同的着色和渲染模式

相机控制：用户可以用鼠标旋转、缩放和平移视图

响应式设计：自动适应不同屏幕尺寸

主要技术点详解
1. Three.js 核心架构
场景图(Scene Graph)：使用 THREE.Scene 作为容器管理所有 3D 对象

相机系统：透视相机(PerspectiveCamera)模拟人眼视角

渲染器：WebGL 渲染器利用 GPU 加速 3D 渲染

几何体：使用专门的 TeapotGeometry 生成器创建茶壶模型

2. 几何体与细分技术
javascript
// 茶壶几何体参数
const geometry = new TeapotGeometry(
  teapotSize,     // 尺寸
  tess,           // 细分级别 (2-50)
  showBottom,     // 是否显示底部
  showLid,        // 是否显示盖子
  showBody,       // 是否显示壶体
  fitLid,         // 盖子是否贴合
  useBlinnScale   // 是否使用Blinn调整比例
);
参数化几何体：茶壶由多个贝塞尔曲面片构成

细分控制：通过 tess 参数控制曲面细分级别，影响模型精度和性能

组件可选：可以单独显示/隐藏壶体、盖子、底部

3. 材质与着色系统
支持 6 种不同的材质类型，展示不同的渲染技术：

材质类型	技术特点	适用场景
线框(Wireframe)	只显示网格边线	查看模型拓扑结构
平面着色(Flat)	每个面单一颜色，无平滑	低多边形风格
平滑着色(Smooth)	Lambert 着色，漫反射	无光泽表面
光泽(Glossy)	Phong 着色，包含高光	塑料/金属质感
纹理(Textured)	UV 纹理映射	真实感表面
反射(Reflective)	环境贴图反射	镜面/金属表面
4. 光照系统
javascript
// 双光源设置
ambientLight = new THREE.AmbientLight(0x7c7c7c, 2.0);  // 环境光
light = new THREE.DirectionalLight(0xFFFFFF, 2.0);     // 方向光
环境光：均匀照亮整个场景，无方向性

方向光：模拟太阳光，有明确方向，产生明暗对比

Phong 光照模型：计算环境光、漫反射、镜面反射分量

5. 纹理与贴图技术
2D 纹理映射：使用 UV 网格纹理检查纹理坐标

立方体贴图：6 张图片构成的环境贴图，用于反射效果

纹理参数：设置包裹模式、各向异性过滤、颜色空间

6. 用户交互系统
GUI 控制面板（lil-gui 库）：
细分级别：从 2 到 50 的多级细分控制

显示部件：独立控制壶体、盖子、底部的可见性

比例选项：在原始比例和 Blinn 调整比例之间切换

着色模式：6 种材质的实时切换

相机控制（OrbitControls）：
旋转：左键拖动旋转视角

缩放：滚轮缩放

平移：右键拖动平移视图

7. 性能优化技术
按需渲染：只在参数变化或用户交互时重新渲染

资源管理：正确释放不再使用的几何体内存

响应式设计：自动适应窗口大小变化

抗锯齿：启用 WebGL 抗锯齿提升视觉质量

8. 现代 JavaScript 特性
ES6 模块：使用 import/export 语法

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

事件驱动：基于事件监听器实现响应式更新

9. 茶壶特有的计算机图形学知识点
贝塞尔曲面：原始茶壶由 28 个三次贝塞尔曲面片构成

Blinn 调整：Jim Blinn 对原始茶壶比例的修正，使其更美观

计算机图形学历史：茶壶作为标准测试模型的起源和意义

技术架构图
text
用户交互层
    ├── GUI 控制面板 (lil-gui)
    └── 3D 视图控制 (OrbitControls)
        │
应用逻辑层
    ├── 参数状态管理 (effectController)
    ├── 渲染调度 (render())
    └── 几何体重建 (createNewTeapot())
        │
Three.js 核心层
    ├── 场景管理 (Scene)
    ├── 相机系统 (Camera)
    ├── 渲染管道 (Renderer)
    ├── 几何体系统 (Geometry)
    ├── 材质系统 (Material)
    └── 光照系统 (Lights)
        │
WebGL/GPU 层
    ├── 顶点着色器
    ├── 片段着色器
    └── GPU 硬件加速
教育价值
这个示例完整展示了：

Three.js 基本工作流程：从初始化到渲染的完整流程

3D 图形学基础概念：几何体、材质、光照、纹理

交互式 3D 应用开发：GUI 集成和用户输入处理

性能最佳实践：资源管理和按需渲染

经典图形学知识：犹他茶壶的历史和技术细节 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面基本元数据设置 -->
		<title>Three.js WebGL - 犹他茶壶缓冲区几何体</title>
		<!-- 字符编码设置为UTF-8，支持中文显示 -->
		<meta charset="utf-8">
		<!-- 
			视口(viewport)设置：
			width=device-width: 宽度等于设备宽度
			user-scalable=no: 禁止用户缩放
			minimum-scale=1.0: 最小缩放比例为1
			maximum-scale=1.0: 最大缩放比例为1
			这确保了页面在移动设备上的正确显示
		-->
		<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">
	</head>
	<body>
		<!-- 
			信息展示区域：
			id="info" 用于CSS样式选择或JavaScript操作
			包含项目信息和来源说明
		-->
		<div id="info">
			<!-- 
				Three.js官方链接：
				target="_blank": 在新标签页打开
				rel="noopener": 安全设置，防止新页面访问原页面的window.opener
			-->
			<a href="https://three.js.org" target="_blank" rel="noopener">Three.js</a> - 犹他茶壶三维模型<br />
			<!-- 课程来源链接 -->
			示例来自 <a href="https://www.udacity.com/course/interactive-3d-graphics--cs291" target="_blank" rel="noopener">Udacity交互式3D图形课程</a>
		</div>

		<!-- 
			导入映射表(Import Map):
			现代浏览器支持的模块解析机制
			允许定义模块的导入路径别名
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module" 表示这是ES6模块
			模块具有自己的作用域，支持静态导入
		-->
		<script type="module">
			// ============== 模块导入区域 ==============
			
			// 导入Three.js核心库的所有功能
			// * as THREE 表示将整个模块作为THREE对象导入
			import * as THREE from 'three';

			// 导入轻量级GUI库，用于创建用户交互控制面板
			// lil-gui是一个小型、无依赖的GUI库
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// 导入轨道控制器，允许用户用鼠标控制相机（旋转、缩放、平移）
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入茶壶几何体生成器，用于创建经典的"犹他茶壶"3D模型
			// 犹他茶壶是计算机图形学中的经典测试模型
			import { TeapotGeometry } from 'three/addons/geometries/TeapotGeometry.js';

			// ============== 全局变量声明区域 ==============
			
			// Three.js核心对象
			let camera;        // 相机：决定观察3D场景的视角
			let scene;         // 场景：包含所有3D对象的容器
			let renderer;      // 渲染器：负责将3D场景渲染到2D画布上
			
			let cameraControls; // 相机控制器：处理用户输入，控制相机移动
			let effectController; // GUI控制器对象：存储和控制所有可调节参数
			
			const teapotSize = 300; // 茶壶的基础尺寸（单位：Three.js单位）
			
			// 光源对象
			let ambientLight; // 环境光：均匀照亮整个场景，没有方向
			let light;        // 方向光：来自特定方向的光源，产生阴影效果
			
			// 茶壶参数状态变量（初始值设为-1以强制首次渲染时更新）
			let tess = -1;     // Tessellation细分级别：控制模型的多边形数量
			let bBottom;       // 是否显示茶壶底部
			let bLid;          // 是否显示茶壶盖子
			let bBody;         // 是否显示茶壶主体
			let bFitLid;       // 盖子是否与壶体紧密贴合
			let bNonBlinn;     // 是否使用原始比例（非Blinn比例）
			let shading;       // 当前使用的着色/渲染模式
			
			// 茶壶和纹理相关变量
			let teapot;        // 茶壶网格对象：包含几何体和材质的3D对象
			let textureCube;   // 立方体贴图：用于环境反射的6面纹理
			
			// 材质字典：存储不同类型的材质，按键名访问
			const materials = {};

			// ============== 主程序入口 ==============
			
			// 执行初始化函数，设置所有Three.js组件
			init();
			
			// 执行首次渲染，将3D场景绘制到屏幕上
			render();

			// ============== 函数定义区域 ==============
			
			/**
			 * 初始化函数
			 * 职责：创建和配置所有Three.js组件
			 * 包括相机、场景、灯光、渲染器、控制器、纹理、材质等
			 * 不包含业务逻辑，只进行初始化设置
			 */
			function init() {
				// ----- 创建DOM容器 -----
				// 创建一个div元素作为Three.js渲染器的容器
				const container = document.createElement('div');
				// 将容器添加到body中
				document.body.appendChild(container);

				// 获取当前浏览器窗口的尺寸
				const canvasWidth = window.innerWidth;
				const canvasHeight = window.innerHeight;

				// ----- 相机设置 -----
				/**
				 * 创建透视相机(PerspectiveCamera)
				 * 参数说明：
				 * 1. 45 - 视野角度(FOV)，单位度，越大看到范围越广
				 * 2. window.innerWidth / window.innerHeight - 宽高比，避免图像拉伸
				 * 3. 1 - 近裁剪面，比此距离近的物体不显示
				 * 4. 80000 - 远裁剪面，比此距离远的物体不显示
				 */
				camera = new THREE.PerspectiveCamera(
					45, 
					window.innerWidth / window.innerHeight, 
					1, 
					80000
				);
				
				// 设置相机初始位置 (x, y, z坐标)
				// 这里的位置经过调整，以获得茶壶的良好视角
				camera.position.set(-600, 550, 1300);

				// ----- 灯光设置 -----
				/**
				 * 创建环境光(AmbientLight)
				 * 参数说明：
				 * 1. 0x7c7c7c - 光的颜色，十六进制RGB
				 * 2. 2.0 - 光的强度，值越大越亮
				 * 环境光均匀照射所有物体，没有方向性，不产生阴影
				 */
				ambientLight = new THREE.AmbientLight(0x7c7c7c, 2.0);

				/**
				 * 创建方向光(DirectionalLight)
				 * 参数说明：
				 * 1. 0xFFFFFF - 白色光
				 * 2. 2.0 - 光的强度
				 * 方向光模拟太阳光，有明确方向，会产生阴影
				 */
				light = new THREE.DirectionalLight(0xFFFFFF, 2.0);
				
				// 设置方向光的方向向量 (x, y, z)
				// 这个向量会被归一化，重要的是方向而不是长度
				light.position.set(0.32, 0.39, 0.7);

				// ----- 渲染器设置 -----
				/**
				 * 创建WebGL渲染器
				 * 配置选项：
				 * antialias: true - 开启抗锯齿，使边缘更平滑
				 */
				renderer = new THREE.WebGLRenderer({ antialias: true });
				
				/**
				 * 设置设备像素比
				 * 作用：适配高清屏幕(Retina屏等)
				 * window.devicePixelRatio获取设备的物理像素与CSS像素的比值
				 */
				renderer.setPixelRatio(window.devicePixelRatio);
				
				// 设置渲染器输出的画布尺寸为整个窗口大小
				renderer.setSize(canvasWidth, canvasHeight);
				
				// 将渲染器的canvas元素添加到之前创建的容器中
				// renderer.domElement是WebGL渲染器创建的<canvas>元素
				container.appendChild(renderer.domElement);

				// ----- 事件监听器 -----
				/**
				 * 监听窗口大小改变事件
				 * 当用户调整浏览器窗口大小时，重新调整渲染器和相机
				 */
				window.addEventListener('resize', onWindowResize);

				// ----- 相机控制器设置 -----
				/**
				 * 创建轨道控制器(OrbitControls)
				 * 参数：
				 * 1. camera - 要控制的相机
				 * 2. renderer.domElement - 监听事件的DOM元素
				 * 功能：允许用户用鼠标拖拽旋转、滚轮缩放、右键平移
				 */
				cameraControls = new OrbitControls(camera, renderer.domElement);
				
				/**
				 * 监听控制器变化事件
				 * 当用户操作控制器时，触发渲染更新
				 */
				cameraControls.addEventListener('change', render);

				// ----- 纹理加载 -----
				/**
				 * 加载UV网格纹理
				 * 这是一个棋盘格纹理，用于检查纹理映射是否正确
				 */
				const textureMap = new THREE.TextureLoader().load('textures/uv_grid_opengl.jpg');
				
				// 设置纹理的包裹方式：在UV坐标超出[0,1]时重复纹理
				textureMap.wrapS = THREE.RepeatWrapping;  // U方向（水平）
				textureMap.wrapT = THREE.RepeatWrapping;  // V方向（垂直）
				
				/**
				 * 设置各向异性过滤(Anisotropy)
				 * 作用：提高纹理在倾斜角度下的质量
				 * 16是最大值，但实际受硬件限制
				 */
				textureMap.anisotropy = 16;
				
				// 设置纹理颜色空间为sRGB，确保颜色正确显示
				textureMap.colorSpace = THREE.SRGBColorSpace;

				// ----- 立方体贴图加载（用于环境反射） -----
				// 立方体贴图由6个图片组成，模拟环境反射
				const path = 'textures/cube/pisa/';  // 贴图文件所在目录
				
				// 立方体贴图6个面的文件名（顺序重要）：
				// px: 正X面（右）, nx: 负X面（左）
				// py: 正Y面（上）, ny: 负Y面（下）
				// pz: 正Z面（前）, nz: 负Z面（后）
				const urls = ['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png'];
				
				// 加载立方体贴图
				textureCube = new THREE.CubeTextureLoader().setPath(path).load(urls);

				// ----- 材质创建 -----
				/**
				 * 线框材质(Wireframe)
				 * 只显示模型的网格线，不填充面
				 * 用于查看模型的结构和拓扑
				 */
				materials['wireframe'] = new THREE.MeshBasicMaterial({
					wireframe: true  // 启用线框模式
				});

				/**
				 * 平面着色材质(Flat Shading)
				 * 每个面使用单一颜色，没有平滑渐变
				 * 参数：
				 * specular: 0x000000 - 无高光（黑色）
				 * flatShading: true - 启用平面着色
				 * side: THREE.DoubleSide - 双面渲染，内外都可见
				 */
				materials['flat'] = new THREE.MeshPhongMaterial({
					specular: 0x000000,
					flatShading: true,
					side: THREE.DoubleSide
				});

				/**
				 * 平滑着色材质(Smooth Shading)
				 * 使用Lambert着色模型，计算漫反射，无高光
				 * 产生平滑的颜色过渡效果
				 */
				materials['smooth'] = new THREE.MeshLambertMaterial({
					side: THREE.DoubleSide
				});

				/**
				 * 光泽材质(Glossy)
				 * 使用Phong着色模型，包含漫反射和高光
				 * 参数：
				 * color: 0xc0c0c0 - 银色（材质基础色）
				 * specular: 0x404040 - 高光颜色（深灰色）
				 * shininess: 300 - 光泽度，值越大高光点越小
				 */
				materials['glossy'] = new THREE.MeshPhongMaterial({
					color: 0xc0c0c0,
					specular: 0x404040,
					shininess: 300,
					side: THREE.DoubleSide
				});

				/**
				 * 纹理材质(Textured)
				 * 使用之前加载的UV网格纹理
				 * map: textureMap - 将纹理应用到材质
				 */
				materials['textured'] = new THREE.MeshPhongMaterial({
					map: textureMap,
					side: THREE.DoubleSide
				});

				/**
				 * 反射材质(Reflective)
				 * 使用立方体贴图作为环境贴图，模拟反射效果
				 * envMap: textureCube - 环境贴图
				 */
				materials['reflective'] = new THREE.MeshPhongMaterial({
					envMap: textureCube,
					side: THREE.DoubleSide
				});

				// ----- 场景设置 -----
				// 创建主场景对象，所有3D对象都将添加到场景中
				scene = new THREE.Scene();
				
				// 设置场景背景色为浅灰色（十六进制颜色）
				scene.background = new THREE.Color(0xAAAAAA);
				
				// 将创建的光源添加到场景中
				scene.add(ambientLight);
				scene.add(light);

				// ----- 图形用户界面(GUI)设置 -----
				setupGui();
			}

			/**
			 * 窗口大小改变事件处理函数
			 * 职责：当浏览器窗口大小改变时，重新调整渲染器和相机
			 * 确保3D场景始终正确填充窗口
			 */
			function onWindowResize() {
				// 获取新的窗口尺寸
				const canvasWidth = window.innerWidth;
				const canvasHeight = window.innerHeight;

				// 更新渲染器尺寸，使其匹配新的窗口大小
				renderer.setSize(canvasWidth, canvasHeight);

				/**
				 * 更新相机的宽高比
				 * 如果不更新，图像会被拉伸或压缩
				 */
				camera.aspect = canvasWidth / canvasHeight;
				
				/**
				 * 更新相机的投影矩阵
				 * 在Three.js中，修改相机参数后必须调用此方法
				 * 使更改生效
				 */
				camera.updateProjectionMatrix();

				// 重新渲染场景，显示调整后的效果
				render();
			}

			/**
			 * 设置图形用户界面(GUI)
			 * 职责：创建用户交互控制面板
			 * 使用lil-gui库创建可调节参数的控件
			 */
			function setupGui() {
				/**
				 * effectController对象
				 * 存储所有可以通过GUI调节的参数
				 * 这些参数控制茶壶的显示方式和外观
				 */
				effectController = {
					newTess: 15,      // 默认细分级别：15（中等细节）
					bottom: true,     // 默认显示茶壶底部
					lid: true,        // 默认显示茶壶盖子
					body: true,       // 默认显示茶壶主体
					fitLid: false,    // 默认盖子不紧密贴合
					nonblinn: false,  // 默认使用Blinn比例（调整后的比例）
					newShading: 'glossy'  // 默认使用光泽材质
				};

				// 创建GUI实例
				const gui = new GUI();
				
				/**
				 * 添加细分级别控制器
				 * 参数：
				 * 1. effectController - 目标对象
				 * 2. 'newTess' - 要控制的属性名
				 * 3. [2, 3, 4, 5, 6, 8, 10, 15, 20, 30, 40, 50] - 可选值数组
				 * 方法：
				 * .name('细分级别') - 设置显示名称
				 * .onChange(render) - 值改变时调用render函数
				 */
				gui.add(effectController, 'newTess', [2, 3, 4, 5, 6, 8, 10, 15, 20, 30, 40, 50])
				   .name('细分级别')
				   .onChange(render);
				
				// 添加盖子显示/隐藏控制器（复选框）
				gui.add(effectController, 'lid')
				   .name('显示盖子')
				   .onChange(render);
				
				// 添加壶体显示/隐藏控制器
				gui.add(effectController, 'body')
				   .name('显示壶体')
				   .onChange(render);
				
				// 添加底部显示/隐藏控制器
				gui.add(effectController, 'bottom')
				   .name('显示底部')
				   .onChange(render);
				
				// 添加盖子贴合控制器
				// fitLid控制盖子是否与壶体紧密贴合
				gui.add(effectController, 'fitLid')
				   .name('贴合盖子')
				   .onChange(render);
				
				// 添加原始比例控制器
				// nonblinn为true时使用原始茶壶比例，false时使用Blinn调整后的比例
				gui.add(effectController, 'nonblinn')
				   .name('原始比例')
				   .onChange(render);
				
				// 添加着色模式控制器（下拉选择框）
				gui.add(effectController, 'newShading', 
					['wireframe', 'flat', 'smooth', 'glossy', 'textured', 'reflective']
				).name('着色模式').onChange(render);
			}

			/**
			 * 渲染函数
			 * 职责：根据当前参数状态更新并渲染3D场景
			 * 这是Three.js应用的核心循环（虽然不是真正的循环，由事件触发）
			 */
			function render() {
				/**
				 * 检查是否有参数发生变化
				 * 比较effectController中的当前值与存储的旧值
				 * 如果任何参数改变，需要重新创建茶壶
				 */
				if (effectController.newTess !== tess ||
					effectController.bottom !== bBottom ||
					effectController.lid !== bLid ||
					effectController.body !== bBody ||
					effectController.fitLid !== bFitLid ||
					effectController.nonblinn !== bNonBlinn ||
					effectController.newShading !== shading) {

					// 更新存储的旧值，为下次比较做准备
					tess = effectController.newTess;
					bBottom = effectController.bottom;
					bLid = effectController.lid;
					bBody = effectController.body;
					bFitLid = effectController.fitLid;
					bNonBlinn = effectController.nonblinn;
					shading = effectController.newShading;

					// 创建新的茶壶（参数改变时）
					createNewTeapot();
				}

				/**
				 * 根据着色模式设置场景背景
				 * 特殊处理：反射模式需要使用立方体贴图作为背景
				 * 这样反射效果才会正确显示环境
				 */
				if (shading === 'reflective') {
					// 反射模式下，设置场景背景为立方体贴图
					scene.background = textureCube;
				} else {
					// 其他模式下，清除背景（使用纯色背景）
					scene.background = null;
				}

				/**
				 * 执行实际渲染
				 * 参数：
				 * 1. scene - 要渲染的场景
				 * 2. camera - 从哪个视角渲染
				 * 渲染器将3D场景通过相机的视角转换为2D图像，绘制到canvas上
				 */
				renderer.render(scene, camera);
			}

			/**
			 * 创建新茶壶函数
			 * 职责：根据当前GUI参数生成新的茶壶几何体并添加到场景
			 * 每次参数改变时调用，替换旧的茶壶
			 */
			function createNewTeapot() {
				/**
				 * 清理旧的茶壶（如果存在）
				 * 重要：在Three.js中，手动创建的几何体和材质需要手动释放内存
				 */
				if (teapot !== undefined) {
					// 释放几何体占用的GPU内存
					teapot.geometry.dispose();
					
					// 从场景中移除茶壶对象
					scene.remove(teapot);
				}

				/**
				 * 创建新的茶壶几何体
				 * TeapotGeometry参数说明：
				 * 1. teapotSize (300) - 茶壶的尺寸
				 * 2. tess - 细分级别，控制多边形数量，值越高模型越平滑
				 * 3. effectController.bottom - 是否生成底部几何体
				 * 4. effectController.lid - 是否生成盖子几何体
				 * 5. effectController.body - 是否生成壶体几何体
				 * 6. effectController.fitLid - 盖子是否紧密贴合壶体
				 * 7. !effectController.nonblinn - 是否应用Blinn比例
				 *    (Blinn对原始茶壶比例进行了调整，使其更美观)
				 */
				const geometry = new TeapotGeometry(
					teapotSize,           // 尺寸
					tess,                 // 细分级别
					effectController.bottom, // 是否显示底部
					effectController.lid,   // 是否显示盖子
					effectController.body,  // 是否显示壶体
					effectController.fitLid, // 盖子是否贴合
					!effectController.nonblinn // 是否使用Blinn比例
				);

				/**
				 * 创建网格(Mesh)对象
				 * Mesh是Three.js中的基本3D对象，包含：
				 * - geometry: 形状定义（顶点、面等）
				 * - material: 外观定义（颜色、纹理、光照反应等）
				 * 从materials字典中根据当前着色模式选择材质
				 */
				teapot = new THREE.Mesh(geometry, materials[shading]);

				// 将新创建的茶壶添加到场景中
				scene.add(teapot);
			}
		</script>
	</body>
</html>