<!-- Three.js WebGL裁剪平面演示 - 详细功能说明
🎯 项目概述
这是一个基于Three.js的WebGL 3D图形演示，专门展示3D裁剪平面技术的实现与应用。项目通过一个旋转的圆环结几何体，直观展示如何利用数学平面切割3D对象，并支持实时交互调整各种参数。

📊 主要功能模块
1. 3D场景构建
相机系统：透视相机模拟人眼视角，可自由旋转、缩放、平移

灯光系统：多光源配置（环境光 + 聚光灯 + 方向光），产生逼真阴影

几何体：圆环结（Torus Knot）作为演示主体，具有复杂曲面

地面：接收阴影的平面，提供空间参照

2. 裁剪平面技术核心
2.1 本地裁剪
作用对象：仅影响特定材质（圆环结）

实现方式：通过材质属性 clippingPlanes 设置

视觉效果：物体被平面切割，显示内部结构

阴影支持：阴影也遵循相同的裁剪规则

2.2 全局裁剪
作用对象：影响场景中的所有物体（包括地面和物体）

实现方式：通过渲染器属性 clippingPlanes 设置

视觉效果：整个3D场景被统一平面切割

3. 交互控制系统
3.1 相机控制
旋转：鼠标左键拖动 - 环绕目标点旋转

平移：鼠标右键拖动 - 移动观察位置

缩放：鼠标滚轮 - 拉近或推远视角

3.2 参数调整（右侧GUI面板）
本地裁剪面板：

启用/禁用本地裁剪

控制阴影是否裁剪

调整本地裁剪平面高度（0.3-1.25范围）

全局裁剪面板：

启用/禁用全局裁剪

调整全局裁剪平面位置（-0.4-3.0范围）

图形质量：

多重采样抗锯齿开关

4. 动态效果
自动旋转：圆环结在X轴和Y轴上持续缓慢旋转

呼吸动画：物体大小随时间周期性变化（0.75-1.0倍缩放）

实时更新：所有参数调整立即反映在视觉效果上

🔧 核心技术要点
1. 裁剪平面数学原理
javascript
// 平面定义：法向量(normal) + 常数(constant)
const plane = new THREE.Plane(new THREE.Vector3(0, -1, 0), 0.8);
// 对应平面方程：0*x + (-1)*y + 0*z + 0.8 = 0
// 简化：-y + 0.8 = 0 → y = 0.8
// 效果：裁剪掉y < 0.8的部分
2. 阴影系统集成
阴影生成：灯光设置 castShadow = true

阴影接收：地面设置 receiveShadow = true

阴影裁剪：材质设置 clipShadows = true

性能优化：通过阴影贴图（1024x1024分辨率）预计算

3. 抗锯齿技术
alphaToCoverage：利用多重采样实现高质量边缘平滑

硬件抗锯齿：WebGL原生抗锯齿支持

像素比适配：window.devicePixelRatio 适配高DPI屏幕

4. 渲染优化策略
裁剪面优化：及早剔除不可见片段，减少片段着色器计算

阴影映射：避免实时光线追踪，使用预计算阴影贴图

响应式设计：窗口大小变化时自动调整渲染尺寸和相机参数

5. 模块化架构
javascript
// ES6模块导入
import * as THREE from 'three';                    // 核心库
import Stats from 'three/addons/libs/stats.module.js';  // 性能监控
import { GUI } from 'three/addons/libs/lil-gui.module.min.js';  // GUI控制
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';  // 相机控制
🎨 视觉效果层次
第一层：基础3D渲染
圆环结几何体的真实感渲染

Phong光照模型下的高光反射

双面材质使得内外表面都可见

第二层：阴影效果
多光源产生的复合阴影

地面上的柔和投影

物体自阴影效果

第三层：裁剪效果
清晰的切割边界

内部结构的展示

阴影与主体的同步裁剪

第四层：动画效果
平滑的旋转运动

呼吸式的缩放动画

实时交互反馈

📱 技术兼容性
支持的浏览器
Chrome 60+（推荐）

Firefox 55+

Safari 11+

Edge 79+

硬件要求
GPU：支持WebGL 1.0或2.0

内存：建议4GB以上

分辨率：适应各种屏幕尺寸

🎓 教育价值
适合学习的内容
Three.js基础：场景、相机、渲染器的配置

光照与阴影：多光源系统的构建

高级材质：Phong材质属性和参数调整

几何体操作：复杂几何体的创建和变换

交互开发：GUI系统与用户输入处理

性能优化：渲染循环和资源管理

实际应用场景
医学可视化：器官剖面展示

地质勘探：地层剖面分析

工业设计：零件内部结构检查

建筑可视化：建筑剖面展示

游戏开发：特殊视觉效果

🔄 代码执行流程
text
初始化 → 创建3D组件 → 设置裁剪系统 → 启动渲染循环
    ↓         ↓            ↓             ↓
相机/场景   灯光/几何体   本地/全局裁剪   动画更新
    ↓         ↓            ↓             ↓
用户交互 → GUI控制 → 实时参数更新 → 重新渲染 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js 3D图形库的WebGL裁剪平面示例 -->
		<title>Three.js WebGL - 裁剪平面技术演示</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">
	</head>
	<body>
		<!-- 信息展示区域：显示页面说明和操作指引 -->
		<div id="info">
			<h1>Three.js WebGL - 3D裁剪平面演示</h1>
		</div>

		<!-- 导入映射表（Import Map）：现代JavaScript模块导入配置 -->
		<!-- 作用：告诉浏览器如何解析模块导入语句中的路径 -->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 主JavaScript模块：使用type="module"支持ES6模块化 -->
		<script type="module">
			// ==================== 模块导入区域 ====================
			// 导入Three.js核心库 - 使用命名空间导入所有导出
			import * as THREE from 'three';

			// 导入性能监控模块 - 显示FPS、渲染时间等性能指标
			import Stats from 'three/addons/libs/stats.module.js';
			
			// 导入GUI库 - 创建用户界面控件，用于实时调整参数
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// 导入轨道控制器 - 提供鼠标/触摸控制相机功能
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ==================== 全局变量声明 ====================
			// 这些变量在整个应用中使用，存储Three.js的核心对象
			let camera;      // 相机：定义观察3D场景的视角
			let scene;       // 场景：所有3D对象的容器
			let renderer;    // 渲染器：负责将3D场景绘制到2D画布
			let startTime;   // 开始时间：用于计算动画时间
			let object;      // 主要3D对象：圆环结几何体
			let stats;       // 性能统计对象：显示帧率等性能数据

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

			/**
			 * 初始化函数 - Three.js应用的启动点
			 * 职责：创建和配置所有Three.js核心组件
			 * 执行顺序：相机 → 场景 → 灯光 → 几何体 → 材质 → 渲染器 → GUI
			 */
			function init() {
				// ========== 1. 相机系统初始化 ==========
				// 创建透视相机（模拟人眼视角）
				// 参数说明：
				// 36 - 视野角度(FOV)：垂直方向的视角范围，单位度
				// window.innerWidth / window.innerHeight - 宽高比：根据窗口尺寸动态计算
				// 0.25 - 近裁剪面：距离相机多近开始渲染，防止太近的物体变形
				// 16 - 远裁剪面：距离相机多远停止渲染，优化性能
				camera = new THREE.PerspectiveCamera(36, window.innerWidth / window.innerHeight, 0.25, 16);
				
				// 设置相机初始位置
				// X轴：0（中心）Y轴：1.3（略高于地面）Z轴：3（从前方观察）
				camera.position.set(0, 1.3, 3);

				// ========== 2. 场景创建 ==========
				// 场景对象是3D世界的容器，所有物体、灯光、相机都添加到场景中
				scene = new THREE.Scene();

				// ========== 3. 灯光系统配置 ==========
				// 3.1 环境光 - 提供基础均匀照明，无方向性，不产生阴影
				// 参数：0xcccccc - RGB颜色值（浅灰色）
				scene.add(new THREE.AmbientLight(0xcccccc));

				// 3.2 聚光灯 - 模拟锥形光线，产生清晰阴影
				const spotLight = new THREE.SpotLight(0xffffff, 60);
				spotLight.angle = Math.PI / 5;            // 光束角度：π/5弧度（36度）
				spotLight.penumbra = 0.2;                 // 半影系数：光束边缘的模糊程度（0-1）
				spotLight.position.set(2, 3, 3);          // 灯光位置：右上后方
				spotLight.castShadow = true;              // 启用阴影投射
				spotLight.shadow.camera.near = 3;         // 阴影相机近平面
				spotLight.shadow.camera.far = 10;         // 阴影相机远平面
				spotLight.shadow.mapSize.width = 1024;    // 阴影贴图宽度（分辨率影响阴影质量）
				spotLight.shadow.mapSize.height = 1024;   // 阴影贴图高度
				scene.add(spotLight);

				// 3.3 方向光 - 模拟太阳光，平行光线，产生柔和阴影
				const dirLight = new THREE.DirectionalLight(0x55505a, 3);
				dirLight.position.set(0, 3, 0);           // 正上方照射
				dirLight.castShadow = true;
				dirLight.shadow.camera.near = 1;
				dirLight.shadow.camera.far = 10;
				// 设置正交相机的视锥体范围（形成一个长方体观察区域）
				dirLight.shadow.camera.right = 1;     // 右边界
				dirLight.shadow.camera.left = -1;     // 左边界
				dirLight.shadow.camera.top = 1;       // 上边界
				dirLight.shadow.camera.bottom = -1;   // 下边界
				dirLight.shadow.mapSize.width = 1024;
				dirLight.shadow.mapSize.height = 1024;
				scene.add(dirLight);

				// ========== 4. 裁剪平面技术实现 ==========
				// 4.1 本地裁剪平面 - 只影响应用了该平面的特定材质
				// 平面定义：new THREE.Plane(法向量, 常数)
				// 法向量(0, -1, 0)表示平面朝向负Y轴（向下）
				// 常数0.8表示平面距离原点的距离（沿法向量方向）
				const localPlane = new THREE.Plane(new THREE.Vector3(0, -1, 0), 0.8);
				
				// 4.2 全局裁剪平面 - 影响场景中的所有物体
				// 法向量(-1, 0, 0)表示平面朝向负X轴（向左）
				const globalPlane = new THREE.Plane(new THREE.Vector3(-1, 0, 0), 0.1);

				// ========== 5. 几何体与材质创建 ==========
				// 5.1 创建Phong材质（具有高光反射的材质类型）
				const material = new THREE.MeshPhongMaterial({
					color: 0x80ee10,          // 材质主颜色：青绿色
					shininess: 100,           // 高光强度：0-128，值越大高光点越小越亮
					side: THREE.DoubleSide,   // 渲染面：双面渲染（正反面都可见）

					// 裁剪相关属性（材质级别）
					clippingPlanes: [localPlane], // 应用本地裁剪平面数组
					clipShadows: true,            // 阴影是否也受裁剪影响

					// 图形质量增强
					alphaToCoverage: true,        // 多重采样抗锯齿，特别适用于带透明度的边缘
				});

				// 5.2 创建圆环结几何体（复杂的数学曲面）
				// 参数说明：
				// 0.4 - 主要半径：环的中心到管中心的距离
				// 0.08 - 管半径：环的粗细
				// 95 - 管分段数：围绕管的细分程度（影响平滑度）
				// 20 - 径向分段数：环绕的分段数
				const geometry = new THREE.TorusKnotGeometry(0.4, 0.08, 95, 20);

				// 5.3 创建网格对象（几何体 + 材质 = 可渲染的3D对象）
				object = new THREE.Mesh(geometry, material);
				object.castShadow = true;        // 此物体投射阴影到其他表面
				scene.add(object);               // 将物体添加到场景

				// ========== 6. 地面创建 ==========
				// 6.1 创建地面几何体（9x9的平面，分成1x1个网格）
				const ground = new THREE.Mesh(
					new THREE.PlaneGeometry(9, 9, 1, 1),
					new THREE.MeshPhongMaterial({
						color: 0xa0adaf,      // 地面颜色：浅灰蓝色
						shininess: 150,       // 较高高光值，产生反光效果
						alphaToCoverage: true // 地面也启用多重采样抗锯齿
					})
				);

				// 6.2 地面变换设置
				// PlaneGeometry默认创建在XY平面，需要旋转到XZ平面（Three.js中Y轴是向上的）
				ground.rotation.x = -Math.PI / 2; // 绕X轴旋转-90度
				ground.receiveShadow = true;      // 地面接收其他物体投射的阴影
				scene.add(ground);                // 将地面添加到场景

				// ========== 7. WebGL渲染器配置 ==========
				// 7.1 创建WebGL渲染器实例
				// { antialias: true } 启用硬件抗锯齿
				renderer = new THREE.WebGLRenderer({ antialias: true });
				
				// 7.2 渲染器参数设置
				renderer.setPixelRatio(window.devicePixelRatio);  // 适配高DPI屏幕
				renderer.setSize(window.innerWidth, window.innerHeight); // 全屏尺寸
				renderer.setAnimationLoop(animate);               // 设置渲染循环回调
				renderer.shadowMap.enabled = true;                // 启用阴影映射系统
				
				// 7.3 将渲染器的canvas元素添加到DOM
				document.body.appendChild(renderer.domElement);

				// 7.4 窗口大小变化事件监听器
				window.addEventListener('resize', onWindowResize);

				// ========== 8. 渲染器级别的裁剪设置 ==========
				// 8.1 定义全局裁剪平面数组
				const globalPlanes = [globalPlane];
				
				// 8.2 创建空数组并冻结（防止意外修改）
				// Object.freeze()使数组不可变，确保渲染器状态稳定
				const Empty = Object.freeze([]);
				
				// 8.3 初始渲染器裁剪配置
				renderer.clippingPlanes = Empty;      // 初始不启用全局裁剪
				renderer.localClippingEnabled = true; // 启用本地裁剪功能

				// ========== 9. 性能监控初始化 ==========
				// Stats.js提供FPS（帧率）、MS（渲染时间）、MB（内存）显示
				stats = new Stats();
				document.body.appendChild(stats.dom);

				// ========== 10. 用户交互控制 ==========
				// 轨道控制器：实现鼠标/触摸控制相机运动
				const controls = new OrbitControls(camera, renderer.domElement);
				controls.target.set(0, 1, 0); // 设置相机的观察目标点
				controls.update();            // 强制更新控制器状态

				// ========== 11. GUI用户界面创建 ==========
				// 11.1 创建GUI主实例
				const gui = new GUI();
				
				// 11.2 定义通用属性对象
				const props = {
					alphaToCoverage: true, // 多重采样抗锯齿开关
				};

				// 11.3 创建本地裁剪控制面板
				const folderLocal = gui.addFolder('本地裁剪设置');
				
				// 本地裁剪属性配置（使用getter/setter实现数据绑定）
				const propsLocal = {
					// 本地裁剪开关
					get '启用'() {
						return renderer.localClippingEnabled;
					},
					set '启用'(v) {
						renderer.localClippingEnabled = v;
					},

					// 阴影裁剪开关
					get '阴影裁剪'() {
						return material.clipShadows;
					},
					set '阴影裁剪'(v) {
						material.clipShadows = v;
					},

					// 裁剪平面位置
					get '平面位置'() {
						return localPlane.constant;
					},
					set '平面位置'(v) {
						localPlane.constant = v; // 修改平面常数，调整裁剪位置
					}
				};

				// 11.4 创建全局裁剪控制面板
				const folderGlobal = gui.addFolder('全局裁剪设置');
				
				// 全局裁剪属性配置
				const propsGlobal = {
					// 全局裁剪开关
					get '启用'() {
						// 通过检查clippingPlanes是否为空数组来判断是否启用
						return renderer.clippingPlanes !== Empty;
					},
					set '启用'(v) {
						// 启用时传入globalPlanes数组，禁用时传入Empty空数组
						renderer.clippingPlanes = v ? globalPlanes : Empty;
					},

					// 全局裁剪平面位置
					get '平面位置'() {
						return globalPlane.constant;
					},
					set '平面位置'(v) {
						globalPlane.constant = v;
					}
				};

				// 11.5 添加GUI控制器
				// alphaToCoverage控制器
				gui.add(props, 'alphaToCoverage')
				   .name('多重采样抗锯齿')
				   .onChange(function (value) {
						// 更新地面材质
						ground.material.alphaToCoverage = value;
						ground.material.needsUpdate = true; // 标记材质需要更新

						// 更新物体材质
						material.alphaToCoverage = value;
						material.needsUpdate = true;
					});

				// 本地裁剪控制器
				folderLocal.add(propsLocal, '启用').name('启用本地裁剪');
				folderLocal.add(propsLocal, '阴影裁剪').name('启用阴影裁剪');
				folderLocal.add(propsLocal, '平面位置', 0.3, 1.25)
				           .name('裁剪平面高度')
				           .step(0.01); // 设置滑块步长

				// 全局裁剪控制器
				folderGlobal.add(propsGlobal, '启用').name('启用全局裁剪');
				folderGlobal.add(propsGlobal, '平面位置', -0.4, 3)
				            .name('全局裁剪位置')
				            .step(0.01);

				// 11.6 展开GUI面板（默认展开状态）
				folderLocal.open();
				folderGlobal.open();

				// ========== 12. 应用启动 ==========
				// 记录应用启动时间，用于计算动画时间
				startTime = Date.now();
			}

			/**
			 * 窗口大小变化处理函数
			 * 响应浏览器窗口尺寸变化，保持正确的渲染比例
			 */
			function onWindowResize() {
				// 更新相机宽高比（防止图像拉伸）
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵（必须调用，否则渲染会出错）
				camera.updateProjectionMatrix();
				
				// 更新渲染器尺寸为新的窗口尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 动画循环函数 - Three.js的核心渲染循环
			 * 每帧调用一次（通常60次/秒）
			 * 执行顺序：更新动画 → 性能统计开始 → 渲染场景 → 性能统计结束
			 */
			function animate() {
				// 计算应用运行时间（转换为秒）
				const currentTime = Date.now();
				const time = (currentTime - startTime) / 1000;

				// ========== 物体动画更新 ==========
				// 1. 设置物体位置（保持固定高度）
				object.position.y = 0.8;
				
				// 2. 设置物体旋转（随时间连续旋转）
				object.rotation.x = time * 0.5;  // X轴旋转速度：0.5弧度/秒
				object.rotation.y = time * 0.2;  // Y轴旋转速度：0.2弧度/秒
				
				// 3. 设置物体缩放（呼吸动画效果）
				// Math.cos(time)：余弦函数产生-1到1的波动
				// * 0.125：振幅（缩放变化幅度）
				// + 0.875：基准值（平均缩放大小）
				// 最终效果：缩放值在0.75到1.0之间平滑变化
				object.scale.setScalar(Math.cos(time) * 0.125 + 0.875);

				// ========== 渲染流程 ==========
				// 开始性能统计计时
				stats.begin();
				
				// 核心渲染调用：将3D场景通过相机视角渲染到2D画布
				renderer.render(scene, camera);
				
				// 结束性能统计计时
				stats.end();
			}
		</script>
	</body>
</html>