<!-- Three.js WebGL高级裁剪平面示例 - 功能与技术详解
一、核心功能概述
1. 双重裁剪系统
本地裁剪（Local Clipping）：基于材质的裁剪，每个红色立方体都被一个动态变换的四面体形状裁剪体积所裁剪

全局裁剪（Global Clipping）：基于渲染器的裁剪，整个场景被圆柱形排列的平面裁剪

独立控制：两种裁剪方式可以独立启用/禁用，互不影响

2. 动态动画效果
旋转动画：立方体群围绕自身中心持续旋转

弹性缩放：使用余弦函数实现平滑的周期性缩放效果

同步变换：裁剪体积与立方体群同步变换，保持相对位置

3. 可视化系统
裁剪体积可视化：用半透明彩色平面显示四面体裁剪体积

智能裁剪：可视化平面之间互相裁剪，避免重叠显示问题

实时同步：可视化与裁剪体积实时同步变换

4. 交互控制系统
相机控制：鼠标拖拽旋转、平移、滚轮缩放

GUI面板：实时调整各种参数的交互式控制面板

状态反馈：控制面板实时反映当前状态

二、主要技术点详解
1. 裁剪平面技术
javascript
// 关键技术实现：
clippingPlanes: createPlanes(Planes.length), // 本地裁剪
clipShadows: true,                          // 阴影裁剪
renderer.clippingPlanes = globalClippingPlanes, // 全局裁剪
平面数学表示：使用THREE.Plane类表示无限延伸的平面

局部坐标系变换：通过矩阵变换动态更新平面位置和方向

阴影支持：启用clipShadows使阴影也被正确裁剪

2. 高效渲染技术
javascript
// 实例化网格：一次绘制调用渲染125个立方体
object = new THREE.InstancedMesh(geometry, clipMaterial, count);
object.setMatrixAt(i, matrix); // 为每个实例设置独立变换
InstancedMesh：显著减少WebGL绘制调用次数

矩阵复用：重用矩阵对象减少内存分配

批量更新：一次性设置所有实例的变换矩阵

3. 几何变换数学
javascript
// 关键变换算法：
assignTransformedPlanes(planesOut, planesIn, matrix);
planeToMatrix(plane); // 平面到矩阵的转换
setObjectWorldMatrix(object, matrix); // 设置对象世界矩阵
矩阵运算：使用4×4矩阵表示旋转、平移、缩放

平面变换：通过applyMatrix4()方法变换平面

坐标系转换：局部坐标与世界坐标之间的转换

4. 可视化技术
javascript
// 可视化平面设置：
clippingPlanes: clipMaterial.clippingPlanes.filter(_, j) => j !== i
opacity: 0.2, transparent: true
相互裁剪：每个可视化平面被其他平面裁剪，形成闭合体积

透明度混合：半透明材质叠加显示

颜色编码：不同平面使用不同颜色（HSL彩虹色）

5. 光照与阴影系统
javascript
// 多重光源设置：
new THREE.AmbientLight(0xffffff);           // 环境光
new THREE.SpotLight(0xffffff, 60);          // 聚光灯
new THREE.DirectionalLight(0xffffff, 1.5);  // 方向光
三种光源组合：环境光提供基础照明，聚光灯和方向光提供方向性照明

阴影映射：启用阴影贴图，支持软阴影

阴影相机配置：为不同光源类型配置合适的阴影观察范围

6. 性能优化技术
javascript
// 性能优化措施：
renderer.setPixelRatio(window.devicePixelRatio); // DPI适配
stats = new Stats();                           // 性能监控
matrixAutoUpdate = false;                      // 手动矩阵更新
设备像素比适配：适应高DPI屏幕

性能监控：实时显示帧率、内存等指标

手动更新控制：禁用自动矩阵更新，按需更新提高性能

7. 用户交互系统
javascript
// 交互控制实现：
new OrbitControls(camera, renderer.domElement); // 相机控制器
const gui = new GUI();                         // 控制面板
window.addEventListener('resize', onWindowResize); // 响应式设计
轨道控制器：支持完整的3D场景导航

响应式布局：自动适应窗口大小变化

GUI控制面板：友好的参数调整界面

三、算法与数学原理
1. 四面体裁剪体积生成
javascript
// 基于凸多面体的裁剪：
planesFromMesh(vertices, indices); // 从网格生成平面
setFromCoplanarPoints(a, b, c);    // 三点确定平面
凸多面体表示：四面体是最简单的凸多面体

平面提取算法：从三角形网格提取边界平面

共面点计算：三个点确定一个平面方程

2. 圆柱形裁剪平面生成
javascript
// 均匀分布的垂直平面：
plane.normal.set(Math.cos(angle), 0, Math.sin(angle));
plane.constant = innerRadius;
极坐标转换：角度转换为法线方向

垂直平面阵列：所有平面法线的y分量为0

半径控制：plane.constant控制圆柱半径

3. 正交基构建算法
javascript
// Hughes & Moeller '99算法：
if (Math.abs(zAxis.x) > Math.abs(zAxis.z)) {
    yAxis.set(-zAxis.y, zAxis.x, 0);
} else {
    yAxis.set(0, -zAxis.z, zAxis.y);
}
xAxis.crossVectors(yAxis.normalize(), zAxis);
稳定正交化：避免数值不稳定情况

右手坐标系：确保叉乘顺序正确

矩阵构造：从正交基构建变换矩阵

4. 动态变换系统
javascript
// 复合变换：
transform.copy(object.matrix);                    // 基础变换
transform.multiply(tmpMatrix.makeScale(bouncy)); // 缩放变换
assignTransformedPlanes(planesOut, planesIn, transform); // 平面变换
矩阵组合：按正确顺序组合变换矩阵

周期性动画：使用三角函数创建平滑动画

同步更新：确保所有相关元素同步变换

四、应用场景与扩展
1. 应用场景
3D建模工具：交互式裁剪和切割功能

科学可视化：显示特定区域的数据

游戏开发：特殊视觉效果实现

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

2. 技术扩展方向
多裁剪体积：支持多个独立裁剪体积

布尔运算：基于裁剪实现并集、交集、差集

动态生成：根据用户输入实时生成裁剪体积

GPU加速：使用自定义着色器实现更复杂的裁剪效果

五、总结
这个示例展示了Three.js中高级裁剪功能的完整实现，涵盖了从基础数学原理到高级渲染技术的各个方面。它不仅是一个功能演示，更是一个优秀的学习资源，展示了如何：

组合使用多种Three.js特性：实例化渲染、多重光照、阴影系统、裁剪平面

实现复杂的几何变换：矩阵运算、坐标转换、动态更新

创建交互式3D应用：用户控制、实时反馈、响应式设计

优化WebGL渲染性能：减少绘制调用、内存复用、按需更新 -->


<!DOCTYPE html>
<html lang="en">
<head>
    <!-- 页面标题：Three.js WebGL高级裁剪平面示例 -->
    <title>Three.js WebGL - 高级裁剪平面示例</title>
    <!-- 字符编码 -->
    <meta charset="utf-8">
    <!-- 移动端视口设置：禁止用户缩放，设置最小和最大缩放比例 -->
    <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
    <!-- 外部样式表 -->
    <link type="text/css" rel="stylesheet" href="main.css">
</head>
<body>
    <!-- 信息面板：显示示例说明和操作指南 -->
    <div id="info">
        <h1>Three.js高级裁剪平面示例</h1>
        <p>
            <strong>示例说明：</strong>本示例演示了Three.js中高级裁剪平面的使用，包括本地裁剪和全局裁剪两种方式。
            红色立方体群被一个动态变换的四面体形状的裁剪体积所裁剪，同时还可以启用圆柱形的全局裁剪平面。
        </p>
        <p>
            <strong>本地裁剪：</strong>每个立方体的材质都有自己的一组裁剪平面，形成一个四面体形状的裁剪体积。
            这个体积会随着时间动态旋转和缩放，形成动画效果。
        </p>
        <p>
            <strong>全局裁剪：</strong>渲染器级别的裁剪平面，影响场景中的所有物体，形成圆柱形的裁剪区域。
        </p>
    </div>

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

    <script type="module">
        // ============================ 模块导入区域 ============================
        // 导入Three.js核心库
        import * as THREE from 'three';

        // 导入性能监控器，用于显示帧率等性能指标
        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';

        // ============================ 工具函数定义 ============================

        /**
         * 从三角形网格生成裁剪平面数组
         * 此函数将凸面三角形网格转换为一系列平面，这些平面构成一个裁剪体积
         * 
         * @param {THREE.Vector3[]} vertices - 网格的顶点数组，包含所有顶点的位置
         * @param {number[]} indices - 网格的索引数组，指定如何连接顶点形成三角形
         * @returns {THREE.Plane[]} 返回由网格面定义的平面数组
         * 
         * 工作原理：
         * 1. 遍历每个三角形（每3个索引组成一个三角形）
         * 2. 根据三角形的三个顶点计算平面方程
         * 3. 使用setFromCoplanarPoints方法创建平面
         */
        function planesFromMesh(vertices, indices) {
            // 计算三角形数量：每个三角形有3个索引
            const n = indices.length / 3;
            // 创建结果数组，每个三角形对应一个平面
            const result = new Array(n);

            // 遍历所有三角形
            // i: 三角形索引，j: 在indices数组中的起始位置
            for (let i = 0, j = 0; i < n; ++i, j += 3) {
                // 获取三角形的三个顶点
                const a = vertices[indices[j]];
                const b = vertices[indices[j + 1]];
                const c = vertices[indices[j + 2]];

                // 创建平面并设置为通过这三个点
                // 注意：这三个点必须是共面的（在同一平面上）
                result[i] = new THREE.Plane().setFromCoplanarPoints(a, b, c);
            }

            return result;
        }

        /**
         * 创建指定数量的未初始化平面对象
         * 这些平面将在后续被赋予实际的值
         * 
         * @param {number} n - 需要创建的平面数量
         * @returns {THREE.Plane[]} 返回包含n个空平面的数组
         */
        function createPlanes(n) {
            const result = new Array(n);
            for (let i = 0; i !== n; ++i)
                result[i] = new THREE.Plane(); // 创建新的平面对象
            return result;
        }

        /**
         * 将输入的平面数组应用变换矩阵后赋值给输出平面数组
         * 这个函数用于动态更新裁剪平面的位置和方向
         * 
         * @param {THREE.Plane[]} planesOut - 输出平面数组，将接收变换后的平面
         * @param {THREE.Plane[]} planesIn - 输入平面数组，原始的平面定义
         * @param {THREE.Matrix4} matrix - 4x4变换矩阵，定义旋转、平移和缩放
         * 
         * 变换过程：
         * 1. 复制输入平面
         * 2. 应用变换矩阵
         * 3. 将结果存储到输出平面
         */
        function assignTransformedPlanes(planesOut, planesIn, matrix) {
            // 遍历所有平面
            for (let i = 0, n = planesIn.length; i !== n; ++i) {
                // copy()：复制平面属性
                // applyMatrix4()：应用变换矩阵到平面
                planesOut[i].copy(planesIn[i]).applyMatrix4(matrix);
            }
        }

        /**
         * 创建圆柱形排列的平面数组
         * 这些平面围绕Y轴均匀分布，形成一个圆柱形的裁剪体积
         * 
         * @param {number} n - 平面数量，决定圆柱的"面数"
         * @param {number} innerRadius - 内半径，平面到Y轴的距离
         * @returns {THREE.Plane[]} 返回圆柱形排列的平面数组
         * 
         * 几何解释：
         * 每个平面都是垂直的（法线的y分量为0）
         * 平面围绕Y轴等角度分布，法线方向指向圆柱外部
         */
        function cylindricalPlanes(n, innerRadius) {
            // 创建指定数量的空平面
            const result = createPlanes(n);

            for (let i = 0; i !== n; ++i) {
                const plane = result[i];
                // 计算当前平面的角度（弧度制）
                // 2π / n 是相邻平面之间的角度间隔
                const angle = i * Math.PI * 2 / n;

                // 设置平面法线方向：
                // x = cos(angle), z = sin(angle), y = 0（保持垂直）
                plane.normal.set(Math.cos(angle), 0, Math.sin(angle));
                
                // 设置平面常数：平面到原点的距离
                plane.constant = innerRadius;
            }

            return result;
        }

        /**
         * 将平面转换为矩阵的工厂函数
         * 创建一个将局部坐标系对齐到给定平面的变换矩阵
         * 
         * 返回的函数执行以下操作：
         * 1. 以平面法线作为新坐标系的Z轴
         * 2. 计算正交的X轴和Y轴
         * 3. 将平面上的一个点作为平移分量
         * 
         * 使用Hughes & Moeller '99算法构建正交基
         */
        const planeToMatrix = (function () {
            // 临时变量，用于计算过程中的中间值
            const xAxis = new THREE.Vector3(); // X轴向量
            const yAxis = new THREE.Vector3(); // Y轴向量
            const trans = new THREE.Vector3(); // 平移向量

            /**
             * 将平面转换为对齐矩阵
             * @param {THREE.Plane} plane - 输入平面
             * @returns {THREE.Matrix4} 4x4变换矩阵
             */
            return function planeToMatrix(plane) {
                const zAxis = plane.normal; // 平面法线作为新坐标系的Z轴
                const matrix = new THREE.Matrix4(); // 创建结果矩阵

                // Hughes & Moeller '99算法：从单位向量构建正交基
                // 这是一种稳定的方法来创建正交坐标系
                if (Math.abs(zAxis.x) > Math.abs(zAxis.z)) {
                    // 如果法线的x分量大于z分量，使用这个分支确保数值稳定性
                    yAxis.set(-zAxis.y, zAxis.x, 0);
                } else {
                    yAxis.set(0, -zAxis.z, zAxis.y);
                }

                // 归一化Y轴，然后与Z轴叉乘得到X轴
                // 叉乘的顺序确保得到右手坐标系
                xAxis.crossVectors(yAxis.normalize(), zAxis);

                // 获取平面上的一个点作为坐标原点
                plane.coplanarPoint(trans);
                
                // 构建变换矩阵
                // 矩阵的前三列是X、Y、Z轴的方向
                // 第四列是平移分量
                return matrix.set(
                    xAxis.x, yAxis.x, zAxis.x, trans.x,
                    xAxis.y, yAxis.y, zAxis.y, trans.y,
                    xAxis.z, yAxis.z, zAxis.z, trans.z,
                    0,      0,      0,      1
                );
            };
        }());

        // ============================ 裁剪体积定义 ============================

        // 定义正四面体的顶点（用于本地裁剪体积）
        // 四面体是一个有4个顶点和4个面的简单凸多面体
        const Vertices = [
            new THREE.Vector3(+1, 0, +Math.SQRT1_2),  // 顶点0：右前方
            new THREE.Vector3(-1, 0, +Math.SQRT1_2),  // 顶点1：左前方
            new THREE.Vector3(0, +1, -Math.SQRT1_2),  // 顶点2：上方后方
            new THREE.Vector3(0, -1, -Math.SQRT1_2)   // 顶点3：下方后方
        ];

        // 定义四面体的三角形面索引
        // 每3个数字定义一个三角形，4个面共12个索引
        const Indices = [
            0, 1, 2,  // 前面
            0, 2, 3,  // 右面
            0, 3, 1,  // 底面
            1, 3, 2   // 左面
        ];

        // 从四面体网格生成裁剪平面
        // 这4个平面将形成一个四面体形状的裁剪体积
        const Planes = planesFromMesh(Vertices, Indices);
        
        // 为每个平面预计算变换矩阵
        // 这些矩阵用于将平面可视化网格正确定位
        const PlaneMatrices = Planes.map(planeToMatrix);

        // 创建全局裁剪平面：5个平面形成圆柱形
        // 这5个垂直平面围绕Y轴均匀分布，半径为2.5
        const GlobalClippingPlanes = cylindricalPlanes(5, 2.5);

        // 空数组常量，用于表示"无裁剪平面"
        // Object.freeze确保数组不可修改
        const Empty = Object.freeze([]);

        // ============================ 全局变量声明 ============================
        let camera, scene, renderer, startTime, stats;  // 核心Three.js对象
        let object, clipMaterial, volumeVisualization, globalClippingPlanes; // 场景对象

        /**
         * 初始化函数：创建并设置整个Three.js场景
         * 这是程序的入口点，设置所有必要的组件
         */
        function init() {
            // ========== 相机设置 ==========
            // 创建透视相机，模拟人眼视角
            camera = new THREE.PerspectiveCamera(
                36, // 视野角度(FOV)：垂直视角为36度，较小的角度减少透视变形
                window.innerWidth / window.innerHeight, // 宽高比：匹配窗口比例
                0.25, // 近裁剪面：距离相机0.25单位以内的物体不显示
                16    // 远裁剪面：距离相机16单位以外的物体不显示
            );
            // 设置相机初始位置：x=0, y=1.5(人眼高度), z=3(向后3个单位)
            camera.position.set(0, 1.5, 3);

            // ========== 场景创建 ==========
            scene = new THREE.Scene(); // 创建主场景对象

            // ========== 灯光系统设置 ==========
            
            // 环境光：提供基础照明，没有方向，均匀照亮所有面
            scene.add(new THREE.AmbientLight(0xffffff));

            // 聚光灯：提供主要的方向性照明和阴影
            const spotLight = new THREE.SpotLight(0xffffff, 60); // 白色光，强度60
            spotLight.angle = Math.PI / 5; // 照射角度：36度（π/5弧度）
            spotLight.penumbra = 0.2; // 半影：阴影边缘的模糊程度
            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);

            // 方向光：模拟太阳光，平行光线
            const dirLight = new THREE.DirectionalLight(0xffffff, 1.5); // 白色光，强度1.5
            dirLight.position.set(0, 2, 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);

            // ========== 主要几何体和材质 ==========
            
            // 创建裁剪材质：用于所有立方体实例
            clipMaterial = new THREE.MeshPhongMaterial({
                color: 0xee0a10, // 鲜艳的红色
                shininess: 100, // 高光亮度：0-100，值越大高光点越小越亮
                side: THREE.DoubleSide, // 双面渲染：内外表面都渲染
                
                // 裁剪相关设置：
                clippingPlanes: createPlanes(Planes.length), // 创建本地裁剪平面数组
                clipShadows: true // 启用阴影裁剪：阴影也会被裁剪平面影响
            });

            // 创建立方体实例化网格：高效渲染大量相同几何体
            const count = 5 * 5 * 5; // 5x5x5网格，共125个立方体
            const geometry = new THREE.BoxGeometry(0.18, 0.18, 0.18); // 每个立方体尺寸
            object = new THREE.InstancedMesh(geometry, clipMaterial, count);
            object.castShadow = true; // 立方体投射阴影

            // 设置每个立方体实例的位置
            let i = 0; // 实例索引
            const matrix = new THREE.Matrix4(); // 重用矩阵对象提高性能
            
            // 三重循环创建5x5x5的立方体阵列
            for (let z = -2; z <= 2; ++z)          // z轴：从-2到2
                for (let y = -2; y <= 2; ++y)      // y轴：从-2到2
                    for (let x = -2; x <= 2; ++x) { // x轴：从-2到2
                        // 设置位置：将坐标缩放到[-0.4, 0.4]范围
                        matrix.setPosition(x / 5, y / 5, z / 5);
                        // 为当前实例设置变换矩阵
                        object.setMatrixAt(i++, matrix);
                    }

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

            // ========== 裁剪体积可视化 ==========
            
            // 创建平面几何体，用于可视化裁剪平面
            const planeGeometry = new THREE.PlaneGeometry(3, 3, 1, 1);
            const color = new THREE.Color(); // 颜色对象，用于动态生成颜色

            volumeVisualization = new THREE.Group(); // 创建组来包含所有可视化平面
            volumeVisualization.visible = false; // 默认隐藏可视化

            // 为每个裁剪平面创建可视化网格
            for (let i = 0, n = Planes.length; i !== n; ++i) {
                // 使用HSL颜色模型生成彩虹色：色相根据平面索引变化
                const material = new THREE.MeshBasicMaterial({
                    color: color.setHSL(i / n, 0.5, 0.5).getHex(), // HSL转十六进制
                    side: THREE.DoubleSide, // 双面显示
                    opacity: 0.2, // 透明度：20%不透明
                    transparent: true, // 启用透明度
                    
                    // 裁剪设置：排除当前平面本身，避免自身裁剪造成显示问题
                    // 这样每个平面只被其他平面裁剪，形成完整的体积可视化
                    clippingPlanes: clipMaterial.clippingPlanes.filter(function(_, j) {
                        return j !== i; // 过滤掉当前平面
                    })
                    // 注意：可视化平面不需要阴影裁剪，因为它们不投射阴影
                });

                const mesh = new THREE.Mesh(planeGeometry, material);
                mesh.matrixAutoUpdate = false; // 禁用自动矩阵更新，我们将手动控制
                volumeVisualization.add(mesh); // 添加到可视化组
            }
            scene.add(volumeVisualization); // 将可视化组添加到场景

            // ========== 地面 ==========
            
            const ground = new THREE.Mesh(
                planeGeometry, // 重用平面几何体
                new THREE.MeshPhongMaterial({
                    color: 0xa0adaf, // 浅灰色
                    shininess: 10 // 较低的高光，模拟粗糙表面
                })
            );
            ground.rotation.x = -Math.PI / 2; // 旋转90度，使平面水平
            ground.scale.multiplyScalar(3); // 放大3倍
            ground.receiveShadow = true; // 地面接收阴影
            scene.add(ground);

            // ========== 渲染器设置 ==========
            
            const container = document.body; // 使用body作为容器

            renderer = new THREE.WebGLRenderer(); // 创建WebGL渲染器
            renderer.setPixelRatio(window.devicePixelRatio); // 设置设备像素比，适应高DPI屏幕
            renderer.setSize(window.innerWidth, window.innerHeight); // 设置渲染尺寸
            renderer.setAnimationLoop(animate); // 设置动画循环回调函数
            
            // 阴影和裁剪设置
            renderer.shadowMap.enabled = true; // 启用阴影贴图
            container.appendChild(renderer.domElement); // 将canvas添加到页面
            
            // 全局裁剪平面设置
            globalClippingPlanes = createPlanes(GlobalClippingPlanes.length); // 创建全局裁剪平面数组
            renderer.clippingPlanes = Empty; // 初始禁用全局裁剪（使用空数组）
            renderer.localClippingEnabled = true; // 启用本地裁剪（材质级别的裁剪）

            // ========== 窗口大小调整处理 ==========
            
            window.addEventListener('resize', onWindowResize);

            // ========== 性能监控 ==========
            
            stats = new Stats(); // 创建性能监控器
            container.appendChild(stats.dom); // 将监控器UI添加到页面

            // ========== 相机控制器 ==========
            
            const controls = new OrbitControls(camera, renderer.domElement);
            controls.minDistance = 1; // 最小缩放距离：相机不能比1更近
            controls.maxDistance = 8; // 最大缩放距离：相机不能比8更远
            controls.target.set(0, 1, 0); // 控制焦点：相机围绕此点旋转
            controls.update(); // 立即应用控制设置

            // ========== GUI控制面板 ==========
            
            const gui = new GUI(); // 创建GUI实例

            // 本地裁剪控制文件夹
            const folder = gui.addFolder('本地裁剪设置');
            
            // 定义GUI控制属性对象
            // 使用getter/setter确保GUI和实际值同步
            const props = {
                // 启用/禁用本地裁剪
                get '启用裁剪'() {
                    return renderer.localClippingEnabled;
                },
                set '启用裁剪'(v) {
                    renderer.localClippingEnabled = v;
                    // 如果禁用裁剪，同时隐藏可视化
                    if (!v) volumeVisualization.visible = false;
                },

                // 启用/禁用阴影裁剪
                get '启用阴影裁剪'() {
                    return clipMaterial.clipShadows;
                },
                set '启用阴影裁剪'(v) {
                    clipMaterial.clipShadows = v;
                },

                // 显示/隐藏裁剪体积可视化
                get '显示可视化'() {
                    return volumeVisualization.visible;
                },
                set '显示可视化'(v) {
                    // 只有在启用裁剪时才允许显示可视化
                    if (renderer.localClippingEnabled)
                        volumeVisualization.visible = v;
                }
            };

            // 向GUI添加控制项
            folder.add(props, '启用裁剪'); // 复选框：启用/禁用裁剪
            folder.add(props, '启用阴影裁剪'); // 复选框：启用/禁用阴影裁剪
            folder.add(props, '显示可视化').listen(); // 复选框：显示可视化，listen()确保GUI响应外部变化

            // 全局裁剪控制文件夹
            const globalFolder = gui.addFolder('全局裁剪设置');
            globalFolder.add({
                get '启用全局裁剪'() {
                    // 检查是否启用全局裁剪：渲染器的裁剪平面是否不为空数组
                    return renderer.clippingPlanes !== Empty;
                },
                set '启用全局裁剪'(v) {
                    // 切换全局裁剪：启用时使用全局裁剪平面，禁用时使用空数组
                    renderer.clippingPlanes = v ? globalClippingPlanes : Empty;
                }
            }, '启用全局裁剪'); // 复选框：启用/禁用全局裁剪

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

        /**
         * 窗口大小调整事件处理函数
         * 当浏览器窗口大小改变时，调整相机和渲染器以适应新尺寸
         */
        function onWindowResize() {
            // 更新相机宽高比
            camera.aspect = window.innerWidth / window.innerHeight;
            // 必须调用此方法使新的宽高比生效
            camera.updateProjectionMatrix();
            
            // 更新渲染器尺寸
            renderer.setSize(window.innerWidth, window.innerHeight);
        }

        /**
         * 设置对象的世界矩阵
         * 这个函数用于将对象定位到指定的世界空间位置
         * 
         * @param {THREE.Object3D} object - 要设置的对象
         * @param {THREE.Matrix4} matrix - 目标世界矩阵
         * 
         * 工作原理：
         * 1. 获取对象的父级世界矩阵的逆矩阵
         * 2. 将目标世界矩阵转换到对象的局部空间
         * 3. 应用转换后的矩阵到对象
         */
        function setObjectWorldMatrix(object, matrix) {
            const parent = object.parent; // 获取父对象
            scene.updateMatrixWorld(); // 更新整个场景的世界矩阵
            
            // 计算局部矩阵：从父级世界空间转换到目标世界空间
            object.matrix.copy(parent.matrixWorld).invert(); // 父级世界矩阵的逆
            object.applyMatrix4(matrix); // 应用目标矩阵
        }

        // 临时矩阵变量，用于动画循环中的计算
        const transform = new THREE.Matrix4(); // 主变换矩阵
        const tmpMatrix = new THREE.Matrix4(); // 临时计算矩阵

        /**
         * 动画循环函数
         * 每帧调用，更新动画状态并渲染场景
         */
        function animate() {
            // 计算从程序启动到当前的时间（秒）
            const currentTime = Date.now();
            const time = (currentTime - startTime) / 1000;

            // ========== 更新主对象动画 ==========
            
            // 设置对象基础位置和旋转
            object.position.y = 1; // 固定Y轴位置
            object.rotation.x = time * 0.5; // X轴旋转：每秒0.5弧度
            object.rotation.y = time * 0.2; // Y轴旋转：每秒0.2弧度
            object.updateMatrix(); // 更新对象的变换矩阵
            
            // 复制对象矩阵作为基础变换
            transform.copy(object.matrix);

            // 添加弹跳缩放效果
            // 使用余弦函数创建平滑的周期性变化
            // Math.cos(time * 0.5) 产生[-1, 1]的振荡
            // *0.5 + 0.7 将范围调整到[0.2, 1.2]
            const bouncy = Math.cos(time * 0.5) * 0.5 + 0.7;
            
            // 创建缩放矩阵并应用到主变换
            transform.multiply(tmpMatrix.makeScale(bouncy, bouncy, bouncy));

            // ========== 更新本地裁剪平面 ==========
            
            // 将基础变换应用到四面体平面
            assignTransformedPlanes(
                clipMaterial.clippingPlanes, // 目标：材质裁剪平面
                Planes, // 源：四面体平面定义
                transform // 变换：包含旋转、平移和缩放
            );

            // ========== 更新可视化平面 ==========
            
            const planeMeshes = volumeVisualization.children; // 获取所有可视化平面
            for (let i = 0, n = planeMeshes.length; i !== n; ++i) {
                // 计算每个可视化平面的世界矩阵：
                // 基础变换 × 平面对齐矩阵
                tmpMatrix.multiplyMatrices(transform, PlaneMatrices[i]);
                
                // 设置可视化平面的世界矩阵
                setObjectWorldMatrix(planeMeshes[i], tmpMatrix);
            }

            // ========== 更新全局裁剪平面 ==========
            
            // 为全局裁剪平面创建旋转动画
            transform.makeRotationY(time * 0.1); // Y轴旋转：每秒0.1弧度
            
            // 应用旋转到全局裁剪平面
            assignTransformedPlanes(
                globalClippingPlanes, // 目标：渲染器裁剪平面
                GlobalClippingPlanes, // 源：圆柱形平面定义
                transform // 变换：仅包含旋转
            );

            // ========== 渲染场景 ==========
            
            stats.begin(); // 开始性能统计采样
            renderer.render(scene, camera); // 渲染场景
            stats.end(); // 结束性能统计采样
        }

        // ========== 程序启动 ==========
        init(); // 调用初始化函数，启动程序
    </script>

    <!-- 内联样式：设置信息面板的样式 -->
    <style>
        #info {
            position: absolute; /* 绝对定位，覆盖在3D场景上方 */
            top: 10px; /* 距离顶部10像素 */
            left: 10px; /* 距离左侧10像素 */
            width: 300px; /* 固定宽度 */
            max-height: 80vh; /* 最大高度为视口的80% */
            overflow-y: auto; /* 内容过多时显示滚动条 */
            background-color: rgba(0, 0, 0, 0.7); /* 半透明黑色背景 */
            color: white; /* 白色文字 */
            padding: 15px; /* 内边距 */
            border-radius: 10px; /* 圆角 */
            font-family: Arial, sans-serif; /* 字体 */
            font-size: 14px; /* 字体大小 */
            line-height: 1.5; /* 行高 */
            z-index: 100; /* 确保显示在最上层 */
        }
        
        #info h1 {
            margin-top: 0; /* 移除标题上边距 */
            color: #4CAF50; /* 绿色标题 */
            font-size: 18px; /* 标题字体大小 */
            border-bottom: 1px solid #4CAF50; /* 标题下划线 */
            padding-bottom: 8px; /* 标题下内边距 */
        }
        
        #info strong {
            color: #FF9800; /* 橙色强调文字 */
        }
        
        #info p {
            margin: 10px 0; /* 段落间距 */
        }
    </style>
</body>
</html>