<!-- Three.js 3D编辑器 - 功能描述与技术详解
🎯 核心功能概述
这是一个基于WebGL的交互式3D对象编辑器，允许用户在浏览器中直接操作3D模型。系统模拟了专业3D软件（如Blender、Maya）的核心变换功能，提供了直观的交互体验。

主要功能模块
1. 3D对象变换系统
平移（Translation）：沿X/Y/Z轴移动物体

旋转（Rotation）：绕各坐标轴旋转物体

缩放（Scale）：在三个维度上缩放物体

变换控制器可视化：彩色坐标轴手柄（红=X，绿=Y，蓝=Z）

2. 双相机视角系统
透视相机：模拟人眼真实视角，有近大远小的透视效果

正交相机：CAD/工程图风格，无透视变形，保持物体比例

一键切换：两种视角模式可随时切换

3. 高级控制功能
坐标系切换：世界坐标系 vs 局部坐标系

吸附功能：精确对齐到网格（移动、旋转、缩放）

轴锁定：独立启用/禁用各坐标轴控制

控制器调节：动态调整控制手柄大小

4. 交互操作
鼠标交互：

拖拽：对象变换/相机控制

滚轮：视图缩放

右键/中键：相机控制

键盘快捷键：20+个快捷键覆盖所有操作

实时渲染：所有操作即时反馈

🛠️ 核心技术要点
1. Three.js架构应用
javascript
// 核心架构组件
场景树(Scene Graph)        // 层次化组织3D对象
相机系统(Camera System)    // 多相机管理
渲染管线(Render Pipeline)  // WebGL渲染优化
控制器架构(Control System) // 输入事件处理
2. 渲染引擎优化
技术点	实现方式	作用
抗锯齿	WebGLRenderer({ antialias: true })	消除3D边缘锯齿
纹理优化	anisotropy设置	提高倾斜表面纹理质量
色彩管理	sRGB颜色空间	准确的颜色渲染
像素匹配	setPixelRatio()	适配高DPI屏幕
3. 相机系统设计
javascript
// 透视相机 - 真实感渲染
new THREE.PerspectiveCamera(fov, aspect, near, far)

// 正交相机 - 精确测量
new THREE.OrthographicCamera(left, right, top, bottom, near, far)

// 双相机切换逻辑
currentCamera = currentCamera.isPerspectiveCamera ? cameraOrtho : cameraPersp;
4. 控制器集成策略
javascript
// 控制器协同工作流程
用户输入 → TransformControls → 变换对象 → 触发渲染
用户输入 → OrbitControls → 变换相机 → 触发渲染

// 冲突避免机制
control.addEventListener('dragging-changed', (event) => {
    orbit.enabled = !event.value; // 变换时禁用相机控制
});
5. 输入事件处理系统
javascript
// 三层事件处理架构
1. 鼠标事件 → OrbitControls（相机控制）
2. 键盘事件 → TransformControls（对象变换）
3. 窗口事件 → 响应式布局调整
🔧 关键技术实现细节
1. 变换控制器深度集成
javascript
// 控制器绑定到对象
control.attach(mesh);

// 获取可视化辅助线（Gizmo）
const gizmo = control.getHelper();
scene.add(gizmo); // Gizmo本身也是3D对象

// 控制器状态管理
control.setMode('translate'); // 切换模式
control.setSpace('world');    // 切换坐标系
control.showX = false;        // 隐藏X轴
2. 精确的吸附系统
javascript
// 按下Shift时启用
control.setTranslationSnap(1);                    // 移动：1单位吸附
control.setRotationSnap(THREE.MathUtils.degToRad(15)); // 旋转：15度吸附
control.setScaleSnap(0.25);                       // 缩放：0.25倍吸附

// 松开Shift时禁用（设置为null）
control.setTranslationSnap(null);
3. 响应式布局实现
javascript
function onWindowResize() {
    const aspect = window.innerWidth / window.innerHeight;
    
    // 透视相机更新
    cameraPersp.aspect = aspect;
    cameraPersp.updateProjectionMatrix();
    
    // 正交相机更新（保持比例）
    cameraOrtho.left = cameraOrtho.bottom * aspect;
    cameraOrtho.right = cameraOrtho.top * aspect;
    cameraOrtho.updateProjectionMatrix();
    
    // 渲染器尺寸更新
    renderer.setSize(window.innerWidth, window.innerHeight);
}
4. 资源加载与优化
javascript
// 异步纹理加载
const texture = new THREE.TextureLoader().load('textures/crate.gif', render);
// 回调函数确保纹理加载完成后渲染

// 性能优化设置
texture.anisotropy = renderer.capabilities.getMaxAnisotropy();
// 使用GPU支持的最大各向异性过滤 -->


<!DOCTYPE html>
<html lang="zh-CN">
<!-- 设置页面语言为中文，有助于浏览器和辅助工具识别页面语言 -->
<head>
    <!-- 页面标题：描述页面主要内容 -->
    <title>Three.js WebGL 3D编辑器 - 变换控制器演示</title>
    <!-- 字符编码声明：指定文档使用UTF-8字符编码，确保中文字符正确显示 -->
    <meta charset="utf-8">
    <!-- 视口设置：控制移动设备上的显示和行为 -->
    <!-- width=device-width: 宽度等于设备宽度 -->
    <!-- user-scalable=no: 禁止用户手动缩放页面 -->
    <!-- minimum-scale=1.0, 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>
    <!-- 操作说明面板：显示所有可用的键盘快捷键和操作说明 -->
    <div id="info">
        <strong>3D对象变换控制演示</strong><br>
        “W”旋转 | “E”平移 | “R”缩放 | “+/-”调整大小<br>
		“Q”键切换世界空间/局部空间 | “Shift”键对齐网格<br>
		“X”切换键 X | “Y”切换键 Y | “Z”切换键 Z | “空格键”开启/关闭状态切换<br>
		“Esc”键可重置当前变换状态<br>
		“C”键切换摄像头 | “V”键实现随机缩放
        中键拖拽：平移相机视角
    </div>

    <!-- 模块导入映射配置（Import Maps）：现代浏览器模块导入路径映射 -->
    <!-- 作用：定义JavaScript模块的导入路径，简化模块导入语句 -->
    <script type="importmap">
        {
            "imports": {
                "three": "../build/three.module.js",
                "three/addons/": "./jsm/"
            }
        }
    </script>

    <!-- 主JavaScript模块：包含所有3D场景的创建和交互逻辑 -->
    <!-- type="module"：声明这是一个ES6模块，支持模块化导入导出 -->
    <script type="module">
        // ==================== 模块导入区域 ====================
        // 导入Three.js核心库的所有功能并命名为THREE
        // THREE对象包含所有Three.js的核心类和方法
        import * as THREE from 'three';
        
        // 从Three.js附加组件中导入轨道控制器
        // OrbitControls：用于控制相机围绕目标点旋转、平移和缩放
        import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
        
        // 从Three.js附加组件中导入变换控制器
        // TransformControls：用于交互式地平移、旋转和缩放3D对象
        import { TransformControls } from 'three/addons/controls/TransformControls.js';

        // ==================== 全局变量声明 ====================
        // 相机相关变量
        let cameraPersp;      // 透视相机：模拟人眼视角，有近大远小的透视效果
        let cameraOrtho;      // 正交相机：无透视效果，所有对象大小不变
        let currentCamera;    // 当前活动相机（指向cameraPersp或cameraOrtho）
        
        // 场景和控制器变量
        let scene;      // Three.js场景容器，包含所有3D对象、灯光等
        let renderer;   // WebGL渲染器：负责将3D场景渲染到2D画布上
        let control;    // 变换控制器实例：控制对象的变换操作
        let orbit;      // 轨道控制器实例：控制相机的视角

        // ==================== 初始化入口 ====================
        // 调用初始化函数，设置场景、相机、灯光等所有必要组件
        init();
        // 调用渲染函数，开始渲染循环
        render();

        /**
         * 初始化函数：创建整个3D场景的所有组件
         * 包括：渲染器、相机、场景、灯光、几何体、控制器、事件监听器
         * 这是整个应用的起点，所有3D资源都在这里创建和配置
         */
        function init() {
            // ---------- 1. 创建WebGL渲染器 ----------
            // 创建WebGL渲染器实例，开启抗锯齿以获得更平滑的边缘
            renderer = new THREE.WebGLRenderer({ antialias: true });
            // 设置设备像素比：匹配显示器的物理像素和CSS像素比例
            // 这在高分辨率屏幕上可以防止模糊
            renderer.setPixelRatio(window.devicePixelRatio);
            // 设置渲染器的输出尺寸为整个浏览器窗口大小
            renderer.setSize(window.innerWidth, window.innerHeight);
            // 将渲染器的DOM元素（canvas画布）添加到网页body中
            document.body.appendChild(renderer.domElement);

            // 计算窗口的宽高比（宽度/高度）
            // 这个值对于设置相机投影参数非常重要
            const aspect = window.innerWidth / window.innerHeight;

            // ---------- 2. 创建相机 ----------
            // 正交相机的视锥体大小，控制可见范围
            const frustumSize = 5;

            // 创建透视相机（模拟人眼视角）
            // 参数说明：
            // - 50：视野角度（FOV），单位度，越大看到的范围越广
            // - aspect：宽高比，确保图像不变形
            // - 0.1：近裁剪面，比这个距离近的对象不渲染
            // - 100：远裁剪面，比这个距离远的对象不渲染
            cameraPersp = new THREE.PerspectiveCamera(50, aspect, 0.1, 100);
            
            // 创建正交相机（无透视效果，常用于CAD、工程图）
            // 参数说明（左右上下）：
            // - left: -frustumSize * aspect
            // - right: frustumSize * aspect
            // - top: frustumSize
            // - bottom: -frustumSize
            cameraOrtho = new THREE.OrthographicCamera(
                -frustumSize * aspect, frustumSize * aspect, // 左右边界
                frustumSize, -frustumSize,                    // 上下边界
                0.1, 100                                      // 近远裁剪面
            );
            
            // 设置当前使用的相机为透视相机
            currentCamera = cameraPersp;
            // 设置相机初始位置：X=5, Y=2.5, Z=5
            // 这样相机在场景的右上后方，可以俯视场景中心
            currentCamera.position.set(5, 2.5, 5);

            // ---------- 3. 创建场景和基础元素 ----------
            // 创建Three.js场景，所有3D对象都添加到这个场景中
            scene = new THREE.Scene();
            
            // 添加网格辅助线：帮助判断对象的位置和大小
            // 参数说明：
            // - 5：网格尺寸（5x5单位）
            // - 10：网格细分数量（10x10个小格子）
            // - 0x888888：主网格线颜色（灰色）
            // - 0x444444：次网格线颜色（深灰色）
            scene.add(new THREE.GridHelper(5, 10, 0x888888, 0x444444));

            // ---------- 4. 创建灯光系统 ----------
            // 创建环境光：均匀照亮整个场景，没有方向，模拟间接光照
            // 0xffffff：白色光，强度默认1.0
            const ambientLight = new THREE.AmbientLight(0xffffff);
            scene.add(ambientLight);

            // 创建平行光：有方向的光源，模拟太阳光
            // 参数说明：
            // - 0xffffff：白色光
            // - 4：光照强度，值越大越亮
            const light = new THREE.DirectionalLight(0xffffff, 4);
            light.position.set(1, 1, 1); // 设置光源方向向量（从光源指向原点）
            scene.add(light);

            // ---------- 5. 加载纹理和创建3D对象 ----------
            // 使用纹理加载器加载箱子纹理图片
            // 'textures/crate.gif'：纹理文件路径
            // render：加载完成后的回调函数，这里直接调用渲染函数
            const texture = new THREE.TextureLoader().load('textures/crate.gif', render);
            
            // 设置纹理颜色空间为sRGB：确保颜色正确显示，符合人眼感知
            texture.colorSpace = THREE.SRGBColorSpace;
            
            // 设置纹理的各向异性过滤级别：提高纹理在倾斜角度下的显示质量
            // getMaxAnisotropy()：获取GPU支持的最大各向异性值
            texture.anisotropy = renderer.capabilities.getMaxAnisotropy();

            // 创建立方体几何体：默认是1x1x1单位的立方体
            const geometry = new THREE.BoxGeometry();
            
            // 创建材质：使用Lambert材质（模拟漫反射表面）
            // Lambert材质会对光线做出反应，但不会产生镜面高光
            const material = new THREE.MeshLambertMaterial({ 
                map: texture  // 使用加载的纹理作为材质贴图
            });

            // ---------- 6. 创建控制器 ----------
            // 创建轨道控制器：允许用户通过鼠标控制相机视角
            // 参数说明：
            // - currentCamera：要控制的相机对象
            // - renderer.domElement：事件监听的DOM元素（canvas画布）
            orbit = new OrbitControls(currentCamera, renderer.domElement);
            orbit.update(); // 初始化控制器，更新内部状态
            
            // 监听轨道控制器的变化事件：当用户操作相机时触发渲染
            // 确保每次操作后场景都能及时更新显示
            orbit.addEventListener('change', render);

            // 创建变换控制器：用于交互式控制3D对象的变换
            // 参数说明（同上）：
            // - currentCamera：控制器渲染和交互依赖的相机
            // - renderer.domElement：事件监听的DOM元素
            control = new TransformControls(currentCamera, renderer.domElement);
            
            // 监听变换控制器的变化事件：当对象被变换时触发渲染
            control.addEventListener('change', render);
            
            // 监听拖拽状态变化事件：当开始或结束拖拽时触发
            // 这个事件确保变换控制器和轨道控制器不会同时响应输入
            control.addEventListener('dragging-changed', function (event) {
                // event.value：布尔值，true表示正在拖拽，false表示拖拽结束
                // 当变换控制器正在拖拽对象时，禁用轨道控制器
                // 当拖拽结束时，重新启用轨道控制器
                orbit.enabled = !event.value;
            });

            // ---------- 7. 创建立方体对象并设置控制器 ----------
            // 创建立方体网格：组合几何体和材质
            const mesh = new THREE.Mesh(geometry, material);
            scene.add(mesh); // 将立方体添加到场景中

            // 将变换控制器附加到立方体上
            // 现在控制器可以控制这个特定的立方体对象
            control.attach(mesh);

            // 获取变换控制器的可视化辅助线（Gizmo）
            // Gizmo是控制器在3D空间中的可视化表示（坐标轴手柄）
            const gizmo = control.getHelper();
            scene.add(gizmo); // 将辅助线添加到场景中，以便渲染

            // ---------- 8. 设置窗口事件监听 ----------
            // 监听窗口大小变化事件：当浏览器窗口改变大小时调整渲染
            window.addEventListener('resize', onWindowResize);

            // ---------- 9. 键盘事件监听器（按下） ----------
            /**
             * 键盘按下事件处理函数
             * 处理所有用于控制3D场景的快捷键
             * event.key：获取按下的键值（标准化，不区分大小写）
             */
            window.addEventListener('keydown', function (event) {
                // 使用switch语句根据按下的键执行不同操作
                switch (event.key.toLowerCase()) { // 转换为小写，不区分大小写
                    case 'q': // 切换变换控制器的坐标系
                        // control.space：当前坐标系模式（'local'或'world'）
                        // 局部坐标系：相对于对象自身的坐标轴
                        // 世界坐标系：相对于场景全局的坐标轴
                        control.setSpace(control.space === 'local' ? 'world' : 'local');
                        break;

                    case 'shift': // 启用变换吸附功能（按住时生效）
                        // 设置平移吸附：每移动1个单位吸附一次
                        control.setTranslationSnap(1);
                        // 设置旋转吸附：每15度吸附一次（需要将度转换为弧度）
                        control.setRotationSnap(THREE.MathUtils.degToRad(15));
                        // 设置缩放吸附：每0.25倍吸附一次
                        control.setScaleSnap(0.25);
                        break;

                    case 'w': // 切换到平移（移动）模式
                        control.setMode('translate');
                        break;

                    case 'e': // 切换到旋转模式
                        control.setMode('rotate');
                        break;

                    case 'r': // 切换到缩放模式
                        control.setMode('scale');
                        break;

                    case 'c': // 切换相机类型（透视↔正交）
                        // 保存当前相机的位置（克隆，避免引用问题）
                        const position = currentCamera.position.clone();
                        
                        // 判断当前相机类型并切换
                        // isPerspectiveCamera：透视相机的特有属性
                        currentCamera = currentCamera.isPerspectiveCamera ? cameraOrtho : cameraPersp;
                        
                        // 将新相机移动到原相机的位置
                        currentCamera.position.copy(position);
                        
                        // 更新控制器使用的相机引用
                        orbit.object = currentCamera;  // 更新轨道控制器的目标相机
                        control.camera = currentCamera; // 更新变换控制器的观察相机
                        
                        // 让新相机看向轨道控制器的当前目标点
                        // orbit.target：轨道控制器正在观察的3D点
                        currentCamera.lookAt(orbit.target.x, orbit.target.y, orbit.target.z);
                        
                        // 调用窗口大小变化处理函数，更新相机的投影矩阵
                        onWindowResize();
                        break;

                    case 'v': // 随机设置相机视野和缩放（创造随机视角）
                        // 生成0.1到1.1之间的随机数（+0.1确保不为0）
                        const randomFoV = Math.random() + 0.1;
                        const randomZoom = Math.random() + 0.1;

                        // 随机设置透视相机的视野角度
                        cameraPersp.fov = randomFoV * 160; // 0.1*160到1.1*160度
                        
                        // 随机设置正交相机的视锥范围
                        // 同时设置上下边界，保持对称
                        cameraOrtho.bottom = -randomFoV * 500;
                        cameraOrtho.top = randomFoV * 500;

                        // 随机设置两种相机的缩放级别
                        cameraPersp.zoom = randomZoom * 5;  // 0.1*5到1.1*5倍
                        cameraOrtho.zoom = randomZoom * 5;
                        
                        // 更新相机的投影矩阵以应用新设置
                        onWindowResize();
                        break;

                    case '+': // 增大变换控制器的手柄尺寸
                    case '=': // 同时支持加号和等号键（多数键盘上两者是同一个键）
                        control.setSize(control.size + 0.1); // 每次增加0.1个单位
                        break;

                    case '-': // 减小变换控制器的手柄尺寸
                    case '_': // 同时支持减号和下划线键
                        // Math.max确保尺寸不小于0.1，避免过小或负值
                        control.setSize(Math.max(control.size - 0.1, 0.1));
                        break;

                    case 'x': // 切换X轴控制手柄的显示/隐藏
                        control.showX = !control.showX; // 取反当前状态
                        break;

                    case 'y': // 切换Y轴控制手柄的显示/隐藏
                        control.showY = !control.showY;
                        break;

                    case 'z': // 切换Z轴控制手柄的显示/隐藏
                        control.showZ = !control.showZ;
                        break;

                    case ' ': // 空格键：切换变换控制器的启用状态
                        control.enabled = !control.enabled; // 切换启用/禁用
                        break;

                    case 'escape': // ESC键：重置当前变换操作
                        control.reset(); // 将控制器的变换状态重置为初始状态
                        break;
                }
            });

            // ---------- 10. 键盘事件监听器（释放） ----------
            /**
             * 键盘释放事件处理函数
             * 主要用于处理需要按住生效的功能
             */
            window.addEventListener('keyup', function (event) {
                switch (event.key.toLowerCase()) {
                    case 'shift': // 释放Shift键时关闭吸附功能
                        // 将吸附值设为null即可关闭吸附功能
                        control.setTranslationSnap(null); // 关闭平移吸附
                        control.setRotationSnap(null);    // 关闭旋转吸附
                        control.setScaleSnap(null);       // 关闭缩放吸附
                        break;
                }
            });
        }

        /**
         * 窗口大小变化处理函数
         * 当浏览器窗口大小改变时调用，确保3D场景正确适应新尺寸
         * 主要任务：
         * 1. 更新相机的宽高比和投影矩阵
         * 2. 更新渲染器的输出尺寸
         * 3. 重新渲染场景
         */
        function onWindowResize() {
            // 重新计算窗口的宽高比
            const aspect = window.innerWidth / window.innerHeight;

            // ---------- 更新透视相机 ----------
            // 更新透视相机的宽高比属性
            cameraPersp.aspect = aspect;
            // 更新透视相机的投影矩阵
            // 注意：修改相机参数后必须调用此方法，否则参数不生效
            cameraPersp.updateProjectionMatrix();

            // ---------- 更新正交相机 ----------
            // 正交相机的左右边界需要根据宽高比重新计算
            // 公式：左边界 = 下边界 × 宽高比，右边界 = 上边界 × 宽高比
            // 这样可以保持场景不变形（拉伸或压缩）
            cameraOrtho.left = cameraOrtho.bottom * aspect;
            cameraOrtho.right = cameraOrtho.top * aspect;
            // 更新正交相机的投影矩阵
            cameraOrtho.updateProjectionMatrix();

            // ---------- 更新渲染器 ----------
            // 将渲染器的输出尺寸设置为新的窗口尺寸
            renderer.setSize(window.innerWidth, window.innerHeight);

            // ---------- 重新渲染 ----------
            // 调用渲染函数，使用新设置重新绘制场景
            render();
        }

        /**
         * 渲染函数
         * 将3D场景渲染到2D画布上的核心函数
         * 工作原理：
         * 1. renderer.render()方法将场景（scene）从相机视角（currentCamera）渲染
         * 2. 结果被绘制到WebGL画布上（renderer.domElement）
         * 3. 这个函数在所有需要更新显示时被调用（用户交互、窗口变化等）
         */
        function render() {
            // 执行渲染操作
            // 参数说明：
            // - scene：要渲染的3D场景（包含所有对象、灯光等）
            // - currentCamera：用于观察场景的相机
            renderer.render(scene, currentCamera);
        }
    </script>
</body>
</html>