@chocozhang/three-model-render 1.0.3 → 1.0.4

package/dist/index.mjs

@@ -8,25 +8,35 @@ import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUti
 import { EXRLoader } from 'three/examples/jsm/loaders/EXRLoader.js';
 
 /**
- * 给子模型添加头顶标签（支持 Mesh 和 Group）- 优化版
+ * @file labelManager.ts
+ * @description
+ * Manages HTML labels attached to 3D objects. Efficiently updates label positions based on camera movement.
  *
- * ✨ 性能优化：
- * - 缓存包围盒，避免每帧重复计算
- * - 支持暂停/恢复更新
- * - 可配置更新间隔，降低 CPU 占用
- * - 只在可见时更新，隐藏时自动暂停
+ * @best-practice
+ * - Use `addChildModelLabels` to label parts of a loaded model.
+ * - Labels are HTML elements overlaid on the canvas.
+ * - Supports performance optimization via caching and visibility culling.
+ */
+/**
+ * Add overhead labels to child models (supports Mesh and Group)
+ *
+ * Features:
+ * - Caches bounding boxes to avoid repetitive calculation every frame
+ * - Supports pause/resume
+ * - Configurable update interval to reduce CPU usage
+ * - Automatically pauses when hidden
  *
- * @param camera THREE.Camera - 场景摄像机
- * @param renderer THREE.WebGLRenderer - 渲染器，用于屏幕尺寸
- * @param parentModel THREE.Object3D - FBX 根节点或 Group
- * @param modelLabelsMap Record<string,string> - 模型 name → 标签文字 映射表
- * @param options LabelOptions - 可选标签样式配置
- * @returns LabelManager - 包含 pause/resume/dispose 的管理接口
+ * @param camera THREE.Camera - Scene camera
+ * @param renderer THREE.WebGLRenderer - Renderer, used for screen size
+ * @param parentModel THREE.Object3D - FBX root node or Group
+ * @param modelLabelsMap Record<string,string> - Map of model name to label text
+ * @param options LabelOptions - Optional label style configuration
+ * @returns LabelManager - Management interface containing pause/resume/dispose
  */
 function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, options) {
-    // 防御性检查：确保 parentModel 已加载
+    // Defensive check: ensure parentModel is loaded
     if (!parentModel || typeof parentModel.traverse !== 'function') {
-        console.error('parentModel 无效，请确保 FBX 模型已加载完成');
+        console.error('parentModel invalid, please ensure the FBX model is loaded');
         return {
             pause: () => { },
             resume: () => { },
@@ -34,48 +44,48 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
             isRunning: () => false
         };
     }
-    // 配置项
+    // Configuration
     const enableCache = (options === null || options === void 0 ? void 0 : options.enableCache) !== false;
     const updateInterval = (options === null || options === void 0 ? void 0 : options.updateInterval) || 0;
-    // 创建标签容器，绝对定位，放在 body 中
+    // Create label container, absolute positioning, attached to body
     const container = document.createElement('div');
     container.style.position = 'absolute';
     container.style.top = '0';
     container.style.left = '0';
-    container.style.pointerEvents = 'none'; // 避免阻挡鼠标事件
+    container.style.pointerEvents = 'none'; // Avoid blocking mouse events
     container.style.zIndex = '1000';
     document.body.appendChild(container);
     const labels = [];
-    // 状态管理
+    // State management
     let rafId = null;
     let isPaused = false;
     let lastUpdateTime = 0;
-    // 遍历所有子模型
+    // Traverse all child models
     parentModel.traverse((child) => {
         var _a;
-        // 只处理 Mesh 或 Group
+        // Only process Mesh or Group
         if ((child.isMesh || child.type === 'Group')) {
-            // 动态匹配 name，防止 undefined
+            // Dynamic matching of name to prevent undefined
             const labelText = (_a = Object.entries(modelLabelsMap).find(([key]) => child.name.includes(key))) === null || _a === void 0 ? void 0 : _a[1];
             if (!labelText)
-                return; // 没有匹配标签则跳过
-            // 创建 DOM 标签
+                return; // Skip if no matching label
+            // Create DOM label
             const el = document.createElement('div');
             el.innerText = labelText;
-            // 样式直接在 JS 中定义，可通过 options 覆盖
+            // Styles defined in JS, can be overridden via options
             el.style.position = 'absolute';
             el.style.color = (options === null || options === void 0 ? void 0 : options.color) || '#fff';
             el.style.background = (options === null || options === void 0 ? void 0 : options.background) || 'rgba(0,0,0,0.6)';
             el.style.padding = (options === null || options === void 0 ? void 0 : options.padding) || '4px 8px';
             el.style.borderRadius = (options === null || options === void 0 ? void 0 : options.borderRadius) || '4px';
             el.style.fontSize = (options === null || options === void 0 ? void 0 : options.fontSize) || '14px';
-            el.style.transform = 'translate(-50%, -100%)'; // 让标签在模型正上方
+            el.style.transform = 'translate(-50%, -100%)'; // Position label directly above the model
             el.style.whiteSpace = 'nowrap';
             el.style.pointerEvents = 'none';
             el.style.transition = 'opacity 0.2s ease';
-            // 加入容器
+            // Append to container
             container.appendChild(el);
-            // 初始化缓存
+            // Initialize cache
             const cachedBox = new THREE.Box3().setFromObject(child);
             const center = new THREE.Vector3();
             cachedBox.getCenter(center);
@@ -90,7 +100,7 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         }
     });
     /**
-     * 更新缓存的包围盒（仅在模型变换时调用）
+     * Update cached bounding box (called only when model transforms)
      */
     const updateCache = (labelData) => {
         labelData.cachedBox.setFromObject(labelData.object);
@@ -100,18 +110,18 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         labelData.needsUpdate = false;
     };
     /**
-     * 获取对象顶部世界坐标（使用缓存）
+     * Get object top world coordinates (using cache)
      */
     const getObjectTopPosition = (labelData) => {
         if (enableCache) {
-            // 检查对象是否发生变换
+            // Check if object has transformed
             if (labelData.needsUpdate || labelData.object.matrixWorldNeedsUpdate) {
                 updateCache(labelData);
             }
             return labelData.cachedTopPos;
         }
         else {
-            // 不使用缓存，每次都重新计算
+            // Do not use cache, recalculate every time
             const box = new THREE.Box3().setFromObject(labelData.object);
             const center = new THREE.Vector3();
             box.getCenter(center);
@@ -119,15 +129,15 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         }
     };
     /**
-     * 更新标签位置函数
+     * Update label positions function
      */
     function updateLabels(timestamp = 0) {
-        // 检查是否暂停
+        // Check pause state
         if (isPaused) {
             rafId = null;
             return;
         }
-        // 检查更新间隔
+        // Check update interval
         if (updateInterval > 0 && timestamp - lastUpdateTime < updateInterval) {
             rafId = requestAnimationFrame(updateLabels);
             return;
@@ -137,22 +147,22 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         const height = renderer.domElement.clientHeight;
         labels.forEach((labelData) => {
             const { el } = labelData;
-            const pos = getObjectTopPosition(labelData); // 使用缓存的顶部坐标
-            pos.project(camera); // 转到屏幕坐标
-            const x = (pos.x * 0.5 + 0.5) * width; // 屏幕 X
-            const y = (-(pos.y * 0.5) + 0.5) * height; // 屏幕 Y
-            // 控制标签显示/隐藏（摄像机后方隐藏）
+            const pos = getObjectTopPosition(labelData); // Use cached top position
+            pos.project(camera); // Convert to screen coordinates
+            const x = (pos.x * 0.5 + 0.5) * width; // Screen X
+            const y = (-(pos.y * 0.5) + 0.5) * height; // Screen Y
+            // Control label visibility (hidden when behind camera)
             const isVisible = pos.z < 1;
             el.style.opacity = isVisible ? '1' : '0';
             el.style.display = isVisible ? 'block' : 'none';
-            el.style.transform = `translate(-50%, -100%) translate(${x}px, ${y}px)`; // 屏幕位置
+            el.style.transform = `translate(-50%, -100%) translate(${x}px, ${y}px)`; // Screen position
         });
-        rafId = requestAnimationFrame(updateLabels); // 循环更新
+        rafId = requestAnimationFrame(updateLabels); // Loop update
     }
-    // 启动更新
+    // Start update
     updateLabels();
     /**
-     * 暂停更新
+     * Pause updates
      */
     const pause = () => {
         isPaused = true;
@@ -162,7 +172,7 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         }
     };
     /**
-     * 恢复更新
+     * Resume updates
      */
     const resume = () => {
         if (!isPaused)
@@ -171,11 +181,11 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
         updateLabels();
     };
     /**
-     * 检查是否正在运行
+     * Check if running
      */
     const isRunning = () => !isPaused;
     /**
-     * 清理函数：卸载所有 DOM 标签，取消动画，避免内存泄漏
+     * Cleanup function: Remove all DOM labels, cancel animation, avoid memory leaks
      */
     const dispose = () => {
         pause();
@@ -197,36 +207,45 @@ function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, opti
     };
 }
 
-// src/utils/hoverBreathEffectByNameSingleton.ts
 /**
- * 创建单例高亮器 —— 推荐在 mounted 时创建一次
- * 返回 { updateHighlightNames, dispose, getHoveredName } 接口
+ * @file hoverEffect.ts
+ * @description
+ * Singleton highlight effect manager. Uses OutlinePass to create a breathing highlight effect on hovered objects.
+ *
+ * @best-practice
+ * - Initialize once in your setup/mounted hook.
+ * - Call `updateHighlightNames` to filter which objects are interactive.
+ * - Automatically handles mousemove throttling and cleanup on dispose.
+ */
+/**
+ * Create a singleton highlighter - Recommended to create once on mount
+ * Returns { updateHighlightNames, dispose, getHoveredName } interface
  *
- * ✨ 性能优化：
- * - 无 hover 对象时自动暂停动画
- * - mousemove 节流处理，避免过度计算
- * - 使用 passive 事件监听器提升滚动性能
+ * Features:
+ * - Automatically pauses animation when no object is hovered
+ * - Throttles mousemove events to avoid excessive calculation
+ * - Uses passive event listeners to improve scrolling performance
  */
 function enableHoverBreath(opts) {
-    const { camera, scene, renderer, outlinePass, highlightNames = null, minStrength = 2, maxStrength = 5, speed = 4, throttleDelay = 16, // 默认约 60fps
+    const { camera, scene, renderer, outlinePass, highlightNames = null, minStrength = 2, maxStrength = 5, speed = 4, throttleDelay = 16, // Default ~60fps
      } = opts;
     const raycaster = new THREE.Raycaster();
     const mouse = new THREE.Vector2();
     let hovered = null;
     let time = 0;
     let animationId = null;
-    // highlightSet: null 表示 all; empty Set 表示 none
+    // highlightSet: null means all; empty Set means none
     let highlightSet = highlightNames === null ? null : new Set(highlightNames);
-    // 节流相关
+    // Throttling related
     let lastMoveTime = 0;
     let rafPending = false;
     function setHighlightNames(names) {
         highlightSet = names === null ? null : new Set(names);
-        // 如果当前 hovered 不在新名单中，及时清理 selection
+        // If current hovered object is not in the new list, clean up selection immediately
         if (hovered && highlightSet && !highlightSet.has(hovered.name)) {
             hovered = null;
             outlinePass.selectedObjects = [];
-            // 暂停动画
+            // Pause animation
             if (animationId !== null) {
                 cancelAnimationFrame(animationId);
                 animationId = null;
@@ -234,13 +253,13 @@ function enableHoverBreath(opts) {
         }
     }
     /**
-     * 节流版本的 mousemove 处理
+     * Throttled mousemove handler
      */
     function onMouseMove(ev) {
         const now = performance.now();
-        // 节流：如果距上次处理时间小于阈值，跳过
+        // Throttle: if time since last process is less than threshold, skip
         if (now - lastMoveTime < throttleDelay) {
-            // 使用 RAF 延迟处理，避免丢失最后一次事件
+            // Use RAF to process the latest event later, ensuring the last event isn't lost
             if (!rafPending) {
                 rafPending = true;
                 requestAnimationFrame(() => {
@@ -254,24 +273,24 @@ function enableHoverBreath(opts) {
         processMouseMove(ev);
     }
     /**
-     * 实际的 mousemove 逻辑
+     * Actual mousemove logic
      */
     function processMouseMove(ev) {
         const rect = renderer.domElement.getBoundingClientRect();
         mouse.x = ((ev.clientX - rect.left) / rect.width) * 2 - 1;
         mouse.y = -((ev.clientY - rect.top) / rect.height) * 2 + 1;
         raycaster.setFromCamera(mouse, camera);
-        // 深度检测 scene 的所有子对象（true）
+        // Deep detect all children of the scene (true)
         const intersects = raycaster.intersectObjects(scene.children, true);
         if (intersects.length > 0) {
             const obj = intersects[0].object;
-            // 判断是否允许被高亮
+            // Determine if it is allowed to be highlighted
             const allowed = highlightSet === null ? true : highlightSet.has(obj.name);
             if (allowed) {
                 if (hovered !== obj) {
                     hovered = obj;
                     outlinePass.selectedObjects = [obj];
-                    // 启动动画（如果未运行）
+                    // Start animation (if not running)
                     if (animationId === null) {
                         animate();
                     }
@@ -281,7 +300,7 @@ function enableHoverBreath(opts) {
                 if (hovered !== null) {
                     hovered = null;
                     outlinePass.selectedObjects = [];
-                    // 停止动画
+                    // Stop animation
                     if (animationId !== null) {
                         cancelAnimationFrame(animationId);
                         animationId = null;
@@ -293,7 +312,7 @@ function enableHoverBreath(opts) {
             if (hovered !== null) {
                 hovered = null;
                 outlinePass.selectedObjects = [];
-                // 停止动画
+                // Stop animation
                 if (animationId !== null) {
                     cancelAnimationFrame(animationId);
                     animationId = null;
@@ -302,10 +321,10 @@ function enableHoverBreath(opts) {
         }
     }
     /**
-     * 动画循环 - 只在有 hovered 对象时运行
+     * Animation loop - only runs when there is a hovered object
      */
     function animate() {
-        // 如果没有 hovered 对象，停止动画
+        // If no hovered object, stop animation
         if (!hovered) {
             animationId = null;
             return;
@@ -315,11 +334,11 @@ function enableHoverBreath(opts) {
         const strength = minStrength + ((Math.sin(time) + 1) / 2) * (maxStrength - minStrength);
         outlinePass.edgeStrength = strength;
     }
-    // 启动（只调用一次）
-    // 使用 passive 提升滚动性能
+    // Start (called only once)
+    // Use passive to improve scrolling performance
     renderer.domElement.addEventListener('mousemove', onMouseMove, { passive: true });
-    // 注意：不在这里启动 animate，等有 hover 对象时再启动
-    // refresh: 如果你在某些情况下需要强制清理 selectedObjects
+    // Note: Do not start animate here, wait until there is a hover object
+    // refresh: Forcibly clean up selectedObjects if needed
     function refreshSelection() {
         if (hovered && highlightSet && !highlightSet.has(hovered.name)) {
             hovered = null;
@@ -340,7 +359,7 @@ function enableHoverBreath(opts) {
             animationId = null;
         }
         outlinePass.selectedObjects = [];
-        // 清空引用
+        // Clear references
         hovered = null;
         highlightSet = null;
     }
@@ -353,23 +372,33 @@ function enableHoverBreath(opts) {
 }
 
 /**
- * 初始化描边相关信息（包含 OutlinePass）- 优化版
+ * @file postProcessing.ts
+ * @description
+ * Manages the post-processing chain, specifically for Outline effects and Gamma correction.
  *
- * ✨ 功能增强：
- * - 支持窗口 resize 自动更新
- * - 可配置分辨率缩放提升性能
- * - 完善的资源释放管理
+ * @best-practice
+ * - call `initPostProcessing` after creating your renderer and scene.
+ * - Use the returned `composer` in your render loop instead of `renderer.render`.
+ * - Handles resizing automatically via the `resize` method.
+ */
+/**
+ * Initialize outline-related information (contains OutlinePass)
+ *
+ * Capabilities:
+ * - Supports automatic update on window resize
+ * - Configurable resolution scale for performance improvement
+ * - Comprehensive resource disposal management
  *
  * @param renderer THREE.WebGLRenderer
  * @param scene THREE.Scene
  * @param camera THREE.Camera
- * @param options PostProcessingOptions - 可选配置
- * @returns PostProcessingManager - 包含 composer/outlinePass/resize/dispose 的管理接口
+ * @param options PostProcessingOptions - Optional configuration
+ * @returns PostProcessingManager - Management interface containing composer/outlinePass/resize/dispose
  */
 function initPostProcessing(renderer, scene, camera, options = {}) {
-    // 默认配置
+    // Default configuration
     const { edgeStrength = 4, edgeGlow = 1, edgeThickness = 2, visibleEdgeColor = '#ffee00', hiddenEdgeColor = '#000000', resolutionScale = 1.0 } = options;
-    // 获取渲染器实际尺寸
+    // Get renderer actual size
     const getSize = () => {
         const width = renderer.domElement.clientWidth;
         const height = renderer.domElement.clientHeight;
@@ -379,12 +408,12 @@ function initPostProcessing(renderer, scene, camera, options = {}) {
         };
     };
     const size = getSize();
-    // 创建 EffectComposer
+    // Create EffectComposer
     const composer = new EffectComposer(renderer);
-    // 基础 RenderPass
+    // Basic RenderPass
     const renderPass = new RenderPass(scene, camera);
     composer.addPass(renderPass);
-    // OutlinePass 用于模型描边
+    // OutlinePass for model outlining
     const outlinePass = new OutlinePass(new THREE.Vector2(size.width, size.height), scene, camera);
     outlinePass.edgeStrength = edgeStrength;
     outlinePass.edgeGlow = edgeGlow;
@@ -392,34 +421,34 @@ function initPostProcessing(renderer, scene, camera, options = {}) {
     outlinePass.visibleEdgeColor.set(visibleEdgeColor);
     outlinePass.hiddenEdgeColor.set(hiddenEdgeColor);
     composer.addPass(outlinePass);
-    // Gamma 校正
+    // Gamma correction
     const gammaPass = new ShaderPass(GammaCorrectionShader);
     composer.addPass(gammaPass);
     /**
-     * resize 处理函数
-     * @param width 可选宽度，不传则使用 renderer.domElement 的实际宽度
-     * @param height 可选高度，不传则使用 renderer.domElement 的实际高度
+     * Handle resize
+     * @param width Optional width, uses renderer.domElement actual width if not provided
+     * @param height Optional height, uses renderer.domElement actual height if not provided
      */
     const resize = (width, height) => {
         const actualSize = width !== undefined && height !== undefined
             ? { width: Math.floor(width * resolutionScale), height: Math.floor(height * resolutionScale) }
             : getSize();
-        // 更新 composer 尺寸
+        // Update composer size
         composer.setSize(actualSize.width, actualSize.height);
-        // 更新 outlinePass 分辨率
+        // Update outlinePass resolution
         outlinePass.resolution.set(actualSize.width, actualSize.height);
     };
     /**
-     * 释放资源
+     * Dispose resources
      */
     const dispose = () => {
-        // 释放所有 passes
+        // Dipose all passes
         composer.passes.forEach(pass => {
             if (pass.dispose) {
                 pass.dispose();
             }
         });
-        // 清空 passes 数组
+        // Clear passes array
         composer.passes.length = 0;
     };
     return {
@@ -431,28 +460,38 @@ function initPostProcessing(renderer, scene, camera, options = {}) {
 }
 
 /**
- * 创建模型点击高亮工具（OutlinePass 版）- 优化版
+ * @file clickHandler.ts
+ * @description
+ * Tool for handling model clicks and highlighting (OutlinePass version).
+ *
+ * @best-practice
+ * - Use `createModelClickHandler` to setup interaction.
+ * - Handles debouncing and click threshold automatically.
+ * - Cleanup using the returned dispose function.
+ */
+/**
+ * Create Model Click Highlight Tool (OutlinePass Version) - Optimized
  *
- * ✨ 功能增强：
- * - 使用 AbortController 统一管理事件生命周期
- * - 支持防抖处理避免频繁触发
- * - 可自定义 Raycaster 参数
- * - 根据相机距离动态调整描边厚度
+ * Features:
+ * - Uses AbortController to unify event lifecycle management
+ * - Supports debounce to avoid frequent triggering
+ * - Customizable Raycaster parameters
+ * - Dynamically adjusts outline thickness based on camera distance
  *
- * @param camera 相机
- * @param scene 场景
- * @param renderer 渲染器
- * @param outlinePass 已初始化的 OutlinePass
- * @param onClick 点击回调
- * @param options 可选配置
- * @returns dispose 函数，用于清理事件和资源
+ * @param camera Camera
+ * @param scene Scene
+ * @param renderer Renderer
+ * @param outlinePass Initialized OutlinePass
+ * @param onClick Click callback
+ * @param options Optional configuration
+ * @returns Dispose function, used to clean up events and resources
  */
 function createModelClickHandler(camera, scene, renderer, outlinePass, onClick, options = {}) {
-    // 配置项
+    // Configuration
     const { clickThreshold = 3, debounceDelay = 0, raycasterParams = {}, enableDynamicThickness = true, minThickness = 1, maxThickness = 10 } = options;
     const raycaster = new THREE.Raycaster();
     const mouse = new THREE.Vector2();
-    // 应用 raycaster 自定义参数
+    // Apply Raycaster custom parameters
     if (raycasterParams.near !== undefined)
         raycaster.near = raycasterParams.near;
     if (raycasterParams.far !== undefined)
@@ -469,25 +508,25 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
     let startY = 0;
     let selectedObject = null;
     let debounceTimer = null;
-    // 使用 AbortController 统一管理事件
+    // Use AbortController to manage events uniformly
     const abortController = new AbortController();
     const signal = abortController.signal;
-    /** 恢复对象高亮（清空 OutlinePass.selectedObjects） */
+    /** Restore object highlight (Clear OutlinePass.selectedObjects) */
     function restoreObject() {
         outlinePass.selectedObjects = [];
     }
-    /** 鼠标按下记录位置 */
+    /** Record mouse down position */
     function handleMouseDown(event) {
         startX = event.clientX;
         startY = event.clientY;
     }
-    /** 鼠标抬起判定点击或拖动（带防抖） */
+    /** Mouse up determines click or drag (with debounce) */
     function handleMouseUp(event) {
         const dx = Math.abs(event.clientX - startX);
         const dy = Math.abs(event.clientY - startY);
         if (dx > clickThreshold || dy > clickThreshold)
-            return; // 拖动不触发点击
-        // 防抖处理
+            return; // Drag does not trigger click
+        // Debounce processing
         if (debounceDelay > 0) {
             if (debounceTimer !== null) {
                 clearTimeout(debounceTimer);
@@ -501,7 +540,7 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
             processClick(event);
         }
     }
-    /** 实际的点击处理逻辑 */
+    /** Actual click processing logic */
     function processClick(event) {
         const rect = renderer.domElement.getBoundingClientRect();
         mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
@@ -510,55 +549,64 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
         const intersects = raycaster.intersectObjects(scene.children, true);
         if (intersects.length > 0) {
             let object = intersects[0].object;
-            // 点击不同模型，先清除之前高亮
+            // Click different model, clear previous highlight first
             if (selectedObject && selectedObject !== object)
                 restoreObject();
             selectedObject = object;
-            // highlightObject(selectedObject); // 可选：是否自动高亮
+            // highlightObject(selectedObject); // Optional: whether to auto highlight
             onClick(selectedObject, {
-                name: selectedObject.name || '未命名模型',
+                name: selectedObject.name || 'Unnamed Model',
                 position: selectedObject.getWorldPosition(new THREE.Vector3()),
                 uuid: selectedObject.uuid
             });
         }
         else {
-            // 点击空白 → 清除高亮
+            // Click blank -> Clear highlight
             if (selectedObject)
                 restoreObject();
             selectedObject = null;
             onClick(null);
         }
     }
-    // 使用 AbortController 的 signal 注册事件
+    // Register events using signal from AbortController
     renderer.domElement.addEventListener('mousedown', handleMouseDown, { signal });
     renderer.domElement.addEventListener('mouseup', handleMouseUp, { signal });
-    /** 销毁函数：解绑事件并清除高亮 */
+    /** Dispose function: Unbind events and clear highlight */
     return () => {
-        // 清理防抖定时器
+        // Clear debounce timer
         if (debounceTimer !== null) {
             clearTimeout(debounceTimer);
             debounceTimer = null;
         }
-        // 一次性解绑所有事件
+        // Unbind all events at once
         abortController.abort();
-        // 清除高亮
+        // Clear highlight
         restoreObject();
-        // 清空引用
+        // Clear reference
         selectedObject = null;
     };
 }
 
-// src/utils/ArrowGuide.ts
 /**
- * ArrowGuide - 优化版
- * 箭头引导效果工具，支持高亮模型并淡化其他对象
+ * @file arrowGuide.ts
+ * @description
+ * Arrow guide effect tool, supports highlighting models and fading other objects.
+ *
+ * @best-practice
+ * - Use `highlight` to focus on specific models.
+ * - Automatically manages materials and memory using WeakMap.
+ * - Call `dispose` when component unmounts.
+ */
+/**
+ * ArrowGuide - Optimized Version
+ * Arrow guide effect tool, supports highlighting models and fading other objects.
  *
- * ✨ 优化内容：
- * - 使用 WeakMap 自动回收材质，避免内存泄漏
- * - 使用 AbortController 管理事件生命周期
- * - 添加材质复用机制，减少重复创建
- * - 改进 dispose 逻辑，确保完全释放资源
- * - 添加错误处理和边界检查
+ * Features:
+ * - Uses WeakMap for automatic material recycling, preventing memory leaks
+ * - Uses AbortController to manage event lifecycle
+ * - Adds material reuse mechanism to reuse materials
+ * - Improved dispose logic ensuring complete resource release
+ * - Adds error handling and boundary checks
  */
 class ArrowGuide {
     constructor(renderer, camera, scene, options) {
@@ -573,12 +621,12 @@ class ArrowGuide {
         this.clickThreshold = 10;
         this.raycaster = new THREE.Raycaster();
         this.mouse = new THREE.Vector2();
-        // ✨ 使用 WeakMap 自动回收材质（GC 友好）
+        // Use WeakMap for automatic material recycling (GC friendly)
         this.originalMaterials = new WeakMap();
         this.fadedMaterials = new WeakMap();
-        // ✨ AbortController 用于事件管理
+        // AbortController for event management
         this.abortController = null;
-        // 配置：非高亮透明度和亮度
+        // Config: Non-highlight opacity and brightness
         this.fadeOpacity = 0.5;
         this.fadeBrightness = 0.1;
         this.clickThreshold = (_a = options === null || options === void 0 ? void 0 : options.clickThreshold) !== null && _a !== void 0 ? _a : 10;
@@ -588,30 +636,30 @@ class ArrowGuide {
         this.abortController = new AbortController();
         this.initEvents();
     }
-    // —— 工具：缓存原材质（仅首次）
+    // Tool: Cache original material (first time only)
     cacheOriginalMaterial(mesh) {
         if (!this.originalMaterials.has(mesh)) {
             this.originalMaterials.set(mesh, mesh.material);
         }
     }
-    // —— 工具：为某个材质克隆一个"半透明版本"，保留所有贴图与参数
+    // Tool: Clone a "translucent version" for a material, preserving all maps and parameters
     makeFadedClone(mat) {
         const clone = mat.clone();
         const c = clone;
-        // 只改透明相关参数，不改 map / normalMap / roughnessMap 等细节
+        // Only modify transparency parameters, do not modify detail maps like map / normalMap / roughnessMap
         c.transparent = true;
         if (typeof c.opacity === 'number')
             c.opacity = this.fadeOpacity;
         if (c.color && c.color.isColor) {
-            c.color.multiplyScalar(this.fadeBrightness); // 颜色整体变暗
+            c.color.multiplyScalar(this.fadeBrightness); // Darken color overall
         }
-        // 为了让箭头在透明建筑后也能顺畅显示，常用策略：不写深度，仅测试深度
+        // Common strategy for fluid display behind transparent objects: do not write depth, only test depth
         clone.depthWrite = false;
         clone.depthTest = true;
         clone.needsUpdate = true;
         return clone;
     }
-    // —— 工具：为 mesh.material（可能是数组）批量克隆"半透明版本"
+    // Tool: Batch clone "translucent version" for mesh.material (could be array)
     createFadedMaterialFrom(mesh) {
         const orig = mesh.material;
         if (Array.isArray(orig)) {
@@ -620,7 +668,7 @@ class ArrowGuide {
         return this.makeFadedClone(orig);
     }
     /**
-     * 设置箭头 Mesh
+     * Set Arrow Mesh
      */
     setArrowMesh(mesh) {
         this.lxMesh = mesh;
@@ -636,15 +684,15 @@ class ArrowGuide {
             mesh.visible = false;
         }
         catch (error) {
-            console.error('ArrowGuide: 设置箭头材质失败', error);
+            console.error('ArrowGuide: Failed to set arrow material', error);
         }
     }
     /**
-     * 高亮指定模型
+     * Highlight specified models
      */
     highlight(models) {
         if (!models || models.length === 0) {
-            console.warn('ArrowGuide: 高亮模型列表为空');
+            console.warn('ArrowGuide: Highlight model list is empty');
             return;
         }
         this.modelBrightArr = models;
@@ -653,9 +701,9 @@ class ArrowGuide {
             this.lxMesh.visible = true;
         this.applyHighlight();
     }
-    // ✅ 应用高亮效果：非高亮模型保留细节 → 使用"克隆后的半透明材质"
+    // Apply highlight effect: Non-highlighted models preserve details -> use "cloned translucent material"
     applyHighlight() {
-        // ✨ 使用 Set 提升查找性能
+        // Use Set to improve lookup performance
         const keepMeshes = new Set();
         this.modelBrightArr.forEach(obj => {
             obj.traverse(child => {
@@ -667,21 +715,21 @@ class ArrowGuide {
             this.scene.traverse(obj => {
                 if (obj.isMesh) {
                     const mesh = obj;
-                    // 缓存原材质（用于恢复）
+                    // Cache original material (for restoration)
                     this.cacheOriginalMaterial(mesh);
                     if (!keepMeshes.has(mesh)) {
-                        // 非高亮：如果还没给它生成过"半透明克隆材质"，就创建一次
+                        // Non-highlighted: if no "translucent clone material" generated yet, create one
                         if (!this.fadedMaterials.has(mesh)) {
                             const faded = this.createFadedMaterialFrom(mesh);
                             this.fadedMaterials.set(mesh, faded);
                         }
-                        // 替换为克隆材质（保留所有贴图/法线等细节）
+                        // Replace with clone material (preserve all maps/normals details)
                         const fadedMat = this.fadedMaterials.get(mesh);
                         if (fadedMat)
                             mesh.material = fadedMat;
                     }
                     else {
-                        // 高亮对象：确保回到原材质（避免上一次高亮后遗留）
+                        // Highlighted object: ensure return to original material (avoid leftover from previous highlight)
                         const orig = this.originalMaterials.get(mesh);
                         if (orig && mesh.material !== orig) {
                             mesh.material = orig;
@@ -692,16 +740,16 @@ class ArrowGuide {
             });
         }
         catch (error) {
-            console.error('ArrowGuide: 应用高亮失败', error);
+            console.error('ArrowGuide: Failed to apply highlight', error);
         }
     }
-    // ✅ 恢复为原材质 & 释放克隆材质
+    // Restore to original material & dispose clone material
     restore() {
         this.flowActive = false;
         if (this.lxMesh)
             this.lxMesh.visible = false;
         try {
-            // ✨ 收集所有需要释放的材质
+            // Collect all materials to dispose
             const materialsToDispose = [];
             this.scene.traverse(obj => {
                 if (obj.isMesh) {
@@ -711,7 +759,7 @@ class ArrowGuide {
                         mesh.material = orig;
                         mesh.material.needsUpdate = true;
                     }
-                    // ✨ 收集待释放的淡化材质
+                    // Collect faded materials to dispose
                     const faded = this.fadedMaterials.get(mesh);
                     if (faded) {
                         if (Array.isArray(faded)) {
@@ -723,24 +771,24 @@ class ArrowGuide {
                     }
                 }
             });
-            // ✨ 批量释放材质（不触碰贴图资源）
+            // Batch dispose materials (do not touch texture resources)
             materialsToDispose.forEach(mat => {
                 try {
                     mat.dispose();
                 }
                 catch (error) {
-                    console.error('ArrowGuide: 释放材质失败', error);
+                    console.error('ArrowGuide: Failed to dispose material', error);
                 }
             });
-            // ✨ 创建新的 WeakMap（相当于清空）
+            // Create new WeakMap (equivalent to clearing)
             this.fadedMaterials = new WeakMap();
         }
         catch (error) {
-            console.error('ArrowGuide: 恢复材质失败', error);
+            console.error('ArrowGuide: Failed to restore material', error);
         }
     }
     /**
-     * 动画更新（每帧调用）
+     * Animation update (called every frame)
      */
     animate() {
         if (!this.flowActive || !this.lxMesh)
@@ -754,16 +802,16 @@ class ArrowGuide {
             }
         }
         catch (error) {
-            console.error('ArrowGuide: 动画更新失败', error);
+            console.error('ArrowGuide: Animation update failed', error);
         }
     }
     /**
-     * 初始化事件监听器
+     * Initialize event listeners
      */
     initEvents() {
         const dom = this.renderer.domElement;
         const signal = this.abortController.signal;
-        // ✨ 使用 AbortController signal 自动管理事件生命周期
+        // Use AbortController signal to automatically manage event lifecycle
         dom.addEventListener('pointerdown', (e) => {
             this.pointerDownPos.set(e.clientX, e.clientY);
         }, { signal });
@@ -771,7 +819,7 @@ class ArrowGuide {
             const dx = Math.abs(e.clientX - this.pointerDownPos.x);
             const dy = Math.abs(e.clientY - this.pointerDownPos.y);
             if (dx > this.clickThreshold || dy > this.clickThreshold)
-                return; // 拖拽
+                return; // Dragging
             const rect = dom.getBoundingClientRect();
             this.mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1;
             this.mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1;
@@ -785,21 +833,21 @@ class ArrowGuide {
                 return true;
             });
             if (filtered.length === 0)
-                this.restore(); // 点击空白恢复
+                this.restore(); // Click blank space to restore
         }, { signal });
     }
     /**
-     * 释放所有资源
+     * Dispose all resources
      */
     dispose() {
-        // ✨ 先恢复材质
+        // Restore materials first
         this.restore();
-        // ✨ 使用 AbortController 一次性解绑所有事件
+        // Unbind all events at once using AbortController
         if (this.abortController) {
             this.abortController.abort();
             this.abortController = null;
         }
-        // ✨ 清空引用
+        // Clear references
         this.modelBrightArr = [];
         this.lxMesh = null;
         this.fadedMaterials = new WeakMap();
@@ -808,50 +856,59 @@ class ArrowGuide {
     }
 }
 
-// utils/LiquidFillerGroup.ts
 /**
- * LiquidFillerGroup - 优化版
- * 支持单模型或多模型液位动画、独立颜色控制
+ * @file liquidFiller.ts
+ * @description
+ * Liquid filling effect for single or multiple models using local clipping planes.
  *
- * ✨ 优化内容：
- * - 使用 renderer.domElement 替代 window 事件
- * - 使用 AbortController 管理事件生命周期
- * - 添加错误处理和边界检查
- * - 优化动画管理，避免内存泄漏
- * - 完善资源释放逻辑
+ * @best-practice
+ * - Use `fillTo` to animate liquid level.
+ * - Supports multiple independent liquid levels.
+ * - Call `dispose` to clean up resources and event listeners.
+ */
+/**
+ * LiquidFillerGroup - Optimized
+ * Supports single or multi-model liquid level animation with independent color control.
+ *
+ * Features:
+ * - Uses renderer.domElement instead of window events
+ * - Uses AbortController to manage event lifecycle
+ * - Adds error handling and boundary checks
+ * - Optimized animation management to prevent memory leaks
+ * - Comprehensive resource disposal logic
  */
 class LiquidFillerGroup {
     /**
-     * 构造函数
-     * @param models 单个或多个 THREE.Object3D
-     * @param scene 场景
-     * @param camera 相机
-     * @param renderer 渲染器
-     * @param defaultOptions 默认液体选项
-     * @param clickThreshold 点击阈值，单位像素
+     * Constructor
+     * @param models Single or multiple THREE.Object3D
+     * @param scene Scene
+     * @param camera Camera
+     * @param renderer Renderer
+     * @param defaultOptions Default liquid options
+     * @param clickThreshold Click threshold in pixels
      */
     constructor(models, scene, camera, renderer, defaultOptions, clickThreshold = 10) {
         this.items = [];
         this.raycaster = new THREE.Raycaster();
         this.pointerDownPos = new THREE.Vector2();
         this.clickThreshold = 10;
-        this.abortController = null; // ✨ 事件管理器
-        /** pointerdown 记录位置 */
+        this.abortController = null; // Event manager
+        /** pointerdown record position */
         this.handlePointerDown = (event) => {
             this.pointerDownPos.set(event.clientX, event.clientY);
         };
-        /** pointerup 判断点击空白，恢复原始材质 */
+        /** pointerup check click blank, restore original material */
         this.handlePointerUp = (event) => {
             const dx = event.clientX - this.pointerDownPos.x;
             const dy = event.clientY - this.pointerDownPos.y;
             const distance = Math.sqrt(dx * dx + dy * dy);
             if (distance > this.clickThreshold)
-                return; // 拖拽不触发
-            // ✨ 使用 renderer.domElement 的实际尺寸
+                return; // Do not trigger on drag
+            // Use renderer.domElement actual size
             const rect = this.renderer.domElement.getBoundingClientRect();
             const pointerNDC = new THREE.Vector2(((event.clientX - rect.left) / rect.width) * 2 - 1, -((event.clientY - rect.top) / rect.height) * 2 + 1);
             this.raycaster.setFromCamera(pointerNDC, this.camera);
-            // 点击空白 -> 所有模型恢复
+            // Click blank -> Restore all models
             const intersectsAny = this.items.some(item => this.raycaster.intersectObject(item.model, true).length > 0);
             if (!intersectsAny) {
                 this.restoreAll();
@@ -861,7 +918,7 @@ class LiquidFillerGroup {
         this.camera = camera;
         this.renderer = renderer;
         this.clickThreshold = clickThreshold;
-        // ✨ 创建 AbortController 用于事件管理
+        // Create AbortController for event management
         this.abortController = new AbortController();
         const modelArray = Array.isArray(models) ? models : [models];
         modelArray.forEach(model => {
@@ -872,7 +929,7 @@ class LiquidFillerGroup {
                     opacity: (_b = defaultOptions === null || defaultOptions === void 0 ? void 0 : defaultOptions.opacity) !== null && _b !== void 0 ? _b : 0.6,
                     speed: (_c = defaultOptions === null || defaultOptions === void 0 ? void 0 : defaultOptions.speed) !== null && _c !== void 0 ? _c : 0.05,
                 };
-                // 保存原始材质
+                // Save original materials
                 const originalMaterials = new Map();
                 model.traverse(obj => {
                     if (obj.isMesh) {
@@ -880,12 +937,12 @@ class LiquidFillerGroup {
                         originalMaterials.set(mesh, mesh.material);
                     }
                 });
-                // ✨ 边界检查：确保有材质可以保存
+                // Boundary check: ensure there are materials to save
                 if (originalMaterials.size === 0) {
-                    console.warn('LiquidFillerGroup: 模型没有 Mesh 对象', model);
+                    console.warn('LiquidFillerGroup: Model has no Mesh objects', model);
                     return;
                 }
-                // 应用淡线框材质
+                // Apply faded wireframe material
                 model.traverse(obj => {
                     if (obj.isMesh) {
                         const mesh = obj;
@@ -897,7 +954,7 @@ class LiquidFillerGroup {
                         });
                     }
                 });
-                // 创建液体 Mesh
+                // Create liquid Mesh
                 const geometries = [];
                 model.traverse(obj => {
                     if (obj.isMesh) {
@@ -908,12 +965,12 @@ class LiquidFillerGroup {
                     }
                 });
                 if (geometries.length === 0) {
-                    console.warn('LiquidFillerGroup: 模型没有几何体', model);
+                    console.warn('LiquidFillerGroup: Model has no geometries', model);
                     return;
                 }
                 const mergedGeometry = BufferGeometryUtils.mergeGeometries(geometries, false);
                 if (!mergedGeometry) {
-                    console.error('LiquidFillerGroup: 几何体合并失败', model);
+                    console.error('LiquidFillerGroup: Failed to merge geometries', model);
                     return;
                 }
                 const material = new THREE.MeshPhongMaterial({
@@ -924,7 +981,7 @@ class LiquidFillerGroup {
                 });
                 const liquidMesh = new THREE.Mesh(mergedGeometry, material);
                 this.scene.add(liquidMesh);
-                // 设置 clippingPlane
+                // Set clippingPlane
                 const clipPlane = new THREE.Plane(new THREE.Vector3(0, -1, 0), 0);
                 const mat = liquidMesh.material;
                 mat.clippingPlanes = [clipPlane];
@@ -935,41 +992,41 @@ class LiquidFillerGroup {
                     clipPlane,
                     originalMaterials,
                     options,
-                    animationId: null // ✨ 初始化动画 ID
+                    animationId: null // Initialize animation ID
                 });
             }
             catch (error) {
-                console.error('LiquidFillerGroup: 初始化模型失败', model, error);
+                console.error('LiquidFillerGroup: Failed to initialize model', model, error);
             }
         });
-        // ✨ 使用 renderer.domElement 替代 window，使用 AbortController signal
+        // Use renderer.domElement instead of window, use AbortController signal
         const signal = this.abortController.signal;
         this.renderer.domElement.addEventListener('pointerdown', this.handlePointerDown, { signal });
         this.renderer.domElement.addEventListener('pointerup', this.handlePointerUp, { signal });
     }
     /**
-   * 设置液位
-   * @param models 单个模型或模型数组
-   * @param percent 液位百分比 0~1
-   */
+     * Set liquid level
+     * @param models Single model or array of models
+     * @param percent Liquid level percentage 0~1
+     */
     fillTo(models, percent) {
-        // ✨ 边界检查
+        // Boundary check
         if (percent < 0 || percent > 1) {
-            console.warn('LiquidFillerGroup: percent 必须在 0~1 之间', percent);
+            console.warn('LiquidFillerGroup: percent must be between 0 and 1', percent);
             percent = Math.max(0, Math.min(1, percent));
         }
         const modelArray = Array.isArray(models) ? models : [models];
         modelArray.forEach(model => {
             const item = this.items.find(i => i.model === model);
             if (!item) {
-                console.warn('LiquidFillerGroup: 未找到模型', model);
+                console.warn('LiquidFillerGroup: Model not found', model);
                 return;
             }
             if (!item.liquidMesh) {
-                console.warn('LiquidFillerGroup: liquidMesh 已被释放', model);
+                console.warn('LiquidFillerGroup: liquidMesh already disposed', model);
                 return;
             }
-            // ✨ 取消之前的动画
+            // Cancel previous animation
             if (item.animationId !== null) {
                 cancelAnimationFrame(item.animationId);
                 item.animationId = null;
@@ -997,14 +1054,14 @@ class LiquidFillerGroup {
                 animate();
             }
             catch (error) {
-                console.error('LiquidFillerGroup: fillTo 执行失败', model, error);
+                console.error('LiquidFillerGroup: fillTo execution failed', model, error);
             }
         });
     }
-    /** 设置多个模型液位，percentList 与 items 顺序对应 */
+    /** Set multiple model levels, percentList corresponds to items order */
     fillToAll(percentList) {
         if (percentList.length !== this.items.length) {
-            console.warn(`LiquidFillerGroup: percentList 长度 (${percentList.length}) 与 items 长度 (${this.items.length}) 不匹配`);
+            console.warn(`LiquidFillerGroup: percentList length (${percentList.length}) does not match items length (${this.items.length})`);
         }
         percentList.forEach((p, idx) => {
             if (idx < this.items.length) {
@@ -1012,17 +1069,17 @@ class LiquidFillerGroup {
             }
         });
     }
-    /** 恢复单个模型原始材质并移除液体 */
+    /** Restore single model original material and remove liquid */
     restore(model) {
         const item = this.items.find(i => i.model === model);
         if (!item)
             return;
-        // ✨ 取消动画
+        // Cancel animation
         if (item.animationId !== null) {
             cancelAnimationFrame(item.animationId);
             item.animationId = null;
         }
-        // 恢复原始材质
+        // Restore original material
         item.model.traverse(obj => {
             if (obj.isMesh) {
                 const mesh = obj;
@@ -1031,7 +1088,7 @@ class LiquidFillerGroup {
                     mesh.material = original;
             }
         });
-        // 释放液体 Mesh
+        // Dispose liquid Mesh
         if (item.liquidMesh) {
             this.scene.remove(item.liquidMesh);
             item.liquidMesh.geometry.dispose();
@@ -1044,50 +1101,60 @@ class LiquidFillerGroup {
             item.liquidMesh = null;
         }
     }
-    /** 恢复所有模型 */
+    /** Restore all models */
     restoreAll() {
         this.items.forEach(item => this.restore(item.model));
     }
-    /** 销毁方法，释放事件和资源 */
+    /** Dispose method, release events and resources */
     dispose() {
-        // ✨ 先恢复所有模型
+        // Restore all models first
         this.restoreAll();
-        // ✨ 使用 AbortController 一次性解绑所有事件
+        // Unbind all events at once using AbortController
         if (this.abortController) {
             this.abortController.abort();
             this.abortController = null;
         }
-        // ✨ 清空 items
+        // Clear items
         this.items.length = 0;
     }
 }
 
-// src/utils/followModels.ts - 优化版
-// ✨ 使用 WeakMap 跟踪动画，支持取消
+/**
+ * @file followModels.ts
+ * @description
+ * Camera utility to automatically follow and focus on 3D models.
+ * It smoothly moves the camera to an optimal viewing position relative to the target object(s).
+ *
+ * @best-practice
+ * - Use `followModels` to focus on a newly selected object.
+ * - Call `cancelFollow` before starting a new manual camera interaction if needed.
+ * - Adjust `padding` to control how tight the camera framing is.
+ */
+// Use WeakMap to track animations, allowing for cancellation
 const _animationMap = new WeakMap();
 /**
- * 推荐角度枚举，便于快速选取常见视角
+ * Recommended camera angles for quick selection of common views
  */
 const FOLLOW_ANGLES = {
-    /** 等距斜视（默认视角）- 适合建筑、机械设备展示 */
+    /** Isometric view (default) - suitable for architecture, mechanical equipment */
     ISOMETRIC: { azimuth: Math.PI / 4, elevation: Math.PI / 4 },
-    /** 正前视角 - 适合正面展示、UI 对齐 */
+    /** Front view - suitable for frontal display, UI alignment */
     FRONT: { azimuth: 0, elevation: 0 },
-    /** 右侧视角 - 适合机械剖面、侧视检查 */
+    /** Right view - suitable for mechanical sections, side inspection */
     RIGHT: { azimuth: Math.PI / 2, elevation: 0 },
-    /** 左侧视角 */
+    /** Left view */
     LEFT: { azimuth: -Math.PI / 2, elevation: 0 },
-    /** 后视角 */
+    /** Back view */
     BACK: { azimuth: Math.PI, elevation: 0 },
-    /** 顶视图 - 适合地图、平面布局展示 */
+    /** Top view - suitable for maps, layout display */
     TOP: { azimuth: 0, elevation: Math.PI / 2 },
-    /** 低角度俯视 - 适合车辆、人物等近地物体 */
+    /** Low angle view - suitable for vehicles, characters near the ground */
     LOW_ANGLE: { azimuth: Math.PI / 4, elevation: Math.PI / 6 },
-    /** 高角度俯视 - 适合鸟瞰、全景浏览 */
+    /** High angle view - suitable for bird's eye view, panoramic browsing */
     HIGH_ANGLE: { azimuth: Math.PI / 4, elevation: Math.PI / 3 }
 };
 /**
- * 缓动函数集合
+ * Collection of easing functions
  */
 const EASING_FUNCTIONS = {
     linear: (t) => t,
@@ -1096,20 +1163,21 @@ const EASING_FUNCTIONS = {
     easeIn: (t) => t * t * t
 };
 /**
- * 自动将相机移到目标的斜上角位置，并保证目标在可视范围内（平滑过渡）- 优化版
+ * Automatically moves the camera to a diagonal position relative to the target,
+ * ensuring the target is within the field of view (smooth transition).
  *
- * ✨ 优化内容：
- * - 支持多种缓动函数
- * - 添加进度回调
- * - 支持取消动画
- * - WeakMap 跟踪防止泄漏
- * - 完善错误处理
+ * Features:
+ * - Supports multiple easing functions
+ * - Adds progress callback
+ * - Supports animation cancellation
+ * - Uses WeakMap to track and prevent memory leaks
+ * - Robust error handling
  */
 function followModels(camera, targets, options = {}) {
     var _a, _b, _c, _d, _e, _f;
-    // ✨ 取消之前的动画
+    // Cancel previous animation
     cancelFollow(camera);
-    // ✨ 边界检查
+    // Boundary check
     const arr = [];
     if (!targets)
         return Promise.resolve();
@@ -1118,15 +1186,15 @@ function followModels(camera, targets, options = {}) {
     else
         arr.push(targets);
     if (arr.length === 0) {
-        console.warn('followModels: 目标对象为空');
+        console.warn('followModels: Target object is empty');
         return Promise.resolve();
     }
     try {
         const box = new THREE.Box3();
         arr.forEach((o) => box.expandByObject(o));
-        // ✨ 检查包围盒有效性
+        // Check bounding box validity
         if (!isFinite(box.min.x) || !isFinite(box.max.x)) {
-            console.warn('followModels: 包围盒计算失败');
+            console.warn('followModels: Failed to calculate bounding box');
             return Promise.resolve();
         }
         const sphere = new THREE.Sphere();
@@ -1142,7 +1210,7 @@ function followModels(camera, targets, options = {}) {
         const elevation = (_e = options.elevation) !== null && _e !== void 0 ? _e : Math.PI / 4;
         const easing = (_f = options.easing) !== null && _f !== void 0 ? _f : 'easeOut';
         const onProgress = options.onProgress;
-        // ✨ 获取缓动函数
+        // Get easing function
         const easingFn = EASING_FUNCTIONS[easing] || EASING_FUNCTIONS.easeOut;
         let distance = 10;
         if (camera.isPerspectiveCamera) {
@@ -1162,7 +1230,7 @@ function followModels(camera, targets, options = {}) {
         else {
             distance = camera.position.distanceTo(center);
         }
-        // 根据 azimuth / elevation 计算方向
+        // Calculate direction based on azimuth / elevation
         const hx = Math.sin(azimuth);
         const hz = Math.cos(azimuth);
         const dir = new THREE.Vector3(hx * Math.cos(elevation), Math.sin(elevation), hz * Math.cos(elevation)).normalize();
@@ -1175,7 +1243,6 @@ function followModels(camera, targets, options = {}) {
         const startTime = performance.now();
         return new Promise((resolve) => {
             const step = (now) => {
-                var _a;
                 const elapsed = now - startTime;
                 const t = Math.min(1, duration > 0 ? elapsed / duration : 1);
                 const k = easingFn(t);
@@ -1189,14 +1256,16 @@ function followModels(camera, targets, options = {}) {
                 else {
                     camera.lookAt(endTarget);
                 }
-                (_a = camera.updateProjectionMatrix) === null || _a === void 0 ? void 0 : _a.call(camera);
-                // ✨ 调用进度回调
+                if (camera.updateProjectionMatrix) {
+                    camera.updateProjectionMatrix();
+                }
+                // Call progress callback
                 if (onProgress) {
                     try {
                         onProgress(t);
                     }
                     catch (error) {
-                        console.error('followModels: 进度回调错误', error);
+                        console.error('followModels: Progress callback error', error);
                     }
                 }
                 if (t < 1) {
@@ -1222,12 +1291,12 @@ function followModels(camera, targets, options = {}) {
         });
     }
     catch (error) {
-        console.error('followModels: 执行失败', error);
+        console.error('followModels: Execution failed', error);
         return Promise.reject(error);
     }
 }
 /**
- * ✨ 取消相机的跟随动画
+ * Cancel the camera follow animation
  */
 function cancelFollow(camera) {
     const rafId = _animationMap.get(camera);
@@ -1237,42 +1306,50 @@ function cancelFollow(camera) {
     }
 }
 
-// src/utils/setView.ts - 优化版
 /**
- * 平滑切换相机到模型的最佳视角 - 优化版
+ * @file setView.ts
+ * @description
+ * Utility to smoothly transition the camera to preset views (Front, Back, Top, Isometric, etc.).
+ *
+ * @best-practice
+ * - Use `setView` for UI buttons that switch camera angles.
+ * - Leverage `ViewPresets` for readable code when using standard views.
+ */
+/**
+ * Smoothly switches the camera to the optimal angle for the model.
  *
- * ✨ 优化内容：
- * - 复用 followModels 逻辑，避免代码重复
- * - 支持更多视角
- * - 配置选项增强
- * - 返回 Promise 支持链式调用
- * - 支持取消动画
+ * Features:
+ * - Reuses followModels logic to avoid code duplication
+ * - Supports more angles
+ * - Enhanced configuration options
+ * - Returns Promise to support chaining
+ * - Supports animation cancellation
  *
- * @param camera       THREE.PerspectiveCamera 相机实例
- * @param controls     OrbitControls 控制器实例
- * @param targetObj    THREE.Object3D 模型对象
- * @param position     视角位置
- * @param options      配置选项
+ * @param camera       THREE.PerspectiveCamera instance
+ * @param controls     OrbitControls instance
+ * @param targetObj    THREE.Object3D model object
+ * @param position     View position
+ * @param options      Configuration options
  * @returns Promise<void>
  */
 function setView(camera, controls, targetObj, position = 'front', options = {}) {
     const { distanceFactor = 0.8, duration = 1000, easing = 'easeInOut', onProgress } = options;
-    // ✨ 边界检查
+    // Boundary check
     if (!targetObj) {
-        console.warn('setView: 目标对象为空');
+        console.warn('setView: Target object is empty');
         return Promise.reject(new Error('Target object is required'));
     }
     try {
-        // 计算包围盒
+        // Calculate bounding box
         const box = new THREE.Box3().setFromObject(targetObj);
         if (!isFinite(box.min.x)) {
-            console.warn('setView: 包围盒计算失败');
+            console.warn('setView: Failed to calculate bounding box');
             return Promise.reject(new Error('Invalid bounding box'));
         }
         const center = box.getCenter(new THREE.Vector3());
         const size = box.getSize(new THREE.Vector3());
         const maxSize = Math.max(size.x, size.y, size.z);
-        // ✨ 使用映射表简化视角计算
+        // Use mapping table for creating view angles
         const viewAngles = {
             'front': { azimuth: 0, elevation: 0 },
             'back': { azimuth: Math.PI, elevation: 0 },
@@ -1283,7 +1360,7 @@ function setView(camera, controls, targetObj, position = 'front', options = {})
             'iso': { azimuth: Math.PI / 4, elevation: Math.PI / 4 }
         };
         const angle = viewAngles[position] || viewAngles.front;
-        // ✨ 复用 followModels，避免代码重复
+        // Reuse followModels to avoid code duplication
         return followModels(camera, targetObj, {
             duration,
             padding: distanceFactor,
@@ -1295,30 +1372,30 @@ function setView(camera, controls, targetObj, position = 'front', options = {})
         });
     }
     catch (error) {
-        console.error('setView: 执行失败', error);
+        console.error('setView: Execution failed', error);
         return Promise.reject(error);
     }
 }
 /**
- * ✨ 取消视角切换动画
+ * Cancel view switch animation
  */
 function cancelSetView(camera) {
     cancelFollow(camera);
 }
 /**
- * ✨ 预设视角快捷方法
+ * Preset view shortcut methods
  */
 const ViewPresets = {
     /**
-     * 前视图
+     * Front View
      */
     front: (camera, controls, target, options) => setView(camera, controls, target, 'front', options),
     /**
-     * 等距视图
+     * Isometric View
      */
     isometric: (camera, controls, target, options) => setView(camera, controls, target, 'iso', options),
     /**
-     * 顶视图
+     * Top View
      */
     top: (camera, controls, target, options) => setView(camera, controls, target, 'top', options)
 };
@@ -1355,6 +1432,16 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * @file modelLoader.ts
+ * @description
+ * Utility to load 3D models (GLTF, FBX, OBJ, PLY, STL) from URLs.
+ *
+ * @best-practice
+ * - Use `loadModelByUrl` for a unified loading interface.
+ * - Supports Draco compression and KTX2 textures for GLTF.
+ * - Includes optimization options like geometry merging and texture downscaling.
+ */
 const DEFAULT_OPTIONS$1 = {
     useKTX2: false,
     mergeGeometries: false,
@@ -1362,12 +1449,12 @@ const DEFAULT_OPTIONS$1 = {
     useSimpleMaterials: false,
     skipSkinned: true,
 };
-/** 自动根据扩展名决定启用哪些选项（智能判断） */
+/** Automatically determine which options to enable based on extension (smart judgment) */
 function normalizeOptions(url, opts) {
     const ext = (url.split('.').pop() || '').toLowerCase();
     const merged = Object.assign(Object.assign({}, DEFAULT_OPTIONS$1), opts);
     if (ext === 'gltf' || ext === 'glb') {
-        // gltf/glb 默认尝试 draco/ktx2，如果用户没填
+        // gltf/glb defaults to trying draco/ktx2 if user didn't specify
         if (merged.dracoDecoderPath === undefined)
             merged.dracoDecoderPath = '/draco/';
         if (merged.useKTX2 === undefined)
@@ -1376,7 +1463,7 @@ function normalizeOptions(url, opts) {
             merged.ktx2TranscoderPath = '/basis/';
     }
     else {
-        // fbx/obj/ply/stl 等不需要 draco/ktx2
+        // fbx/obj/ply/stl etc. do not need draco/ktx2
         merged.dracoDecoderPath = null;
         merged.ktx2TranscoderPath = null;
         merged.useKTX2 = false;
@@ -1432,8 +1519,8 @@ function loadModelByUrl(url_1) {
                 var _a;
                 if (ext === 'gltf' || ext === 'glb') {
                     const sceneObj = res.scene || res;
-                    // --- 关键：把 animations 暴露到 scene.userData（或 scene.animations）上 ---
-                    // 这样调用方只要拿到 sceneObj，就能通过 sceneObj.userData.animations 读取到 clips
+                    // --- Critical: Expose animations to scene.userData (or scene.animations) ---
+                    // So the caller can access clips simply by getting sceneObj.userData.animations
                     sceneObj.userData = (sceneObj === null || sceneObj === void 0 ? void 0 : sceneObj.userData) || {};
                     sceneObj.userData.animations = (_a = res.animations) !== null && _a !== void 0 ? _a : [];
                     resolve(sceneObj);
@@ -1443,7 +1530,7 @@ function loadModelByUrl(url_1) {
                 }
             }, undefined, (err) => reject(err));
         });
-        // 优化
+        // Optimize
         object.traverse((child) => {
             var _a, _b, _c;
             const mesh = child;
@@ -1478,7 +1565,7 @@ function loadModelByUrl(url_1) {
         return object;
     });
 }
-/** 运行时下采样网格中的贴图到 maxSize（canvas drawImage）以节省 GPU 内存 */
+/** Runtime downscale textures in mesh to maxSize (canvas drawImage) to save GPU memory */
 function downscaleTexturesInObject(obj, maxSize) {
     obj.traverse((ch) => {
         if (!ch.isMesh)
@@ -1521,10 +1608,10 @@ function downscaleTexturesInObject(obj, maxSize) {
     });
 }
 /**
- * 尝试合并 object 中的几何体（只合并：非透明、非 SkinnedMesh、attribute 集合兼容的 BufferGeometry）
- * - 合并前会把每个 mesh 的几何体应用 world matrix（so merged geometry in world space）
- * - 合并会按材质 UUID 分组（不同材质不能合并）
- * - 合并函数会兼容 BufferGeometryUtils 的常见导出名
+ * Try to merge geometries in object (Only merge: non-transparent, non-SkinnedMesh, attribute compatible BufferGeometry)
+ * - Before merging, apply world matrix to each mesh's geometry (so merged geometry is in world space)
+ * - Merging will group by material UUID (different materials cannot be merged)
+ * - Merge function is compatible with common export names of BufferGeometryUtils
  */
 function tryMergeGeometries(root, opts) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -1604,9 +1691,9 @@ function tryMergeGeometries(root, opts) {
     });
 }
 /* ---------------------
-   释放工具
+   Dispose Utils
    --------------------- */
-/** 彻底释放对象：几何体，材质和其贴图（危险：共享资源会被释放） */
+/** Completely dispose object: geometry, material and its textures (Danger: shared resources will be disposed) */
 function disposeObject(obj) {
     if (!obj)
         return;
@@ -1629,7 +1716,7 @@ function disposeObject(obj) {
         }
     });
 }
-/** 释放材质及其贴图 */
+/** Dispose material and its textures */
 function disposeMaterial(mat) {
     if (!mat)
         return;
@@ -1648,25 +1735,45 @@ function disposeMaterial(mat) {
     }
     catch (_a) { }
 }
+// Helper to convert to simple material (stub)
+function toSimpleMaterial(mat) {
+    // Basic implementation, preserve color/map
+    const m = new THREE.MeshBasicMaterial();
+    if (mat.color)
+        m.color.copy(mat.color);
+    if (mat.map)
+        m.map = mat.map;
+    return m;
+}
 
-/** 默认值 */
+/**
+ * @file skyboxLoader.ts
+ * @description
+ * Utility for loading skyboxes (CubeTexture or Equirectangular/HDR).
+ *
+ * @best-practice
+ * - Use `loadSkybox` for a unified interface.
+ * - Supports internal caching to avoid reloading the same skybox.
+ * - Can set background and environment map independently.
+ */
+/** Default Values */
 const DEFAULT_OPTIONS = {
     setAsBackground: true,
     setAsEnvironment: true,
     useSRGBEncoding: true,
     cache: true
 };
-/** 内部缓存：key -> { handle, refCount } */
+/** Internal Cache: key -> { handle, refCount } */
 const cubeCache = new Map();
 const equirectCache = new Map();
 /* -------------------------------------------
-   公共函数：加载 skybox（自动选 cube 或 equirect）
+   Public Function: Load skybox (Automatically choose cube or equirect)
    ------------------------------------------- */
 /**
- * 加载立方体贴图（6张）
- * @param renderer THREE.WebGLRenderer - 用于 PMREM 生成环境贴图
+ * Load Cube Texture (6 images)
+ * @param renderer THREE.WebGLRenderer - Used for PMREM generating environment map
  * @param scene THREE.Scene
- * @param paths string[] 6 张图片地址，顺序：[px, nx, py, ny, pz, nz]
+ * @param paths string[] 6 image paths, order: [px, nx, py, ny, pz, nz]
  * @param opts SkyboxOptions
  */
 function loadCubeSkybox(renderer_1, scene_1, paths_1) {
@@ -1676,7 +1783,7 @@ function loadCubeSkybox(renderer_1, scene_1, paths_1) {
         if (!Array.isArray(paths) || paths.length !== 6)
             throw new Error('cube skybox requires 6 image paths');
         const key = paths.join('|');
-        // 缓存处理
+        // Cache handling
         if (options.cache && cubeCache.has(key)) {
             const rec = cubeCache.get(key);
             rec.refCount += 1;
@@ -1687,12 +1794,12 @@ function loadCubeSkybox(renderer_1, scene_1, paths_1) {
                 scene.environment = rec.handle.envRenderTarget.texture;
             return rec.handle;
         }
-        // 加载立方体贴图
+        // Load cube texture
         const loader = new THREE.CubeTextureLoader();
         const texture = yield new Promise((resolve, reject) => {
             loader.load(paths, (tex) => resolve(tex), undefined, (err) => reject(err));
         });
-        // 设置编码与映射
+        // Set encoding and mapping
         if (options.useSRGBEncoding)
             texture.encoding = THREE.sRGBEncoding;
         texture.mapping = THREE.CubeReflectionMapping;
@@ -1765,7 +1872,7 @@ function loadCubeSkybox(renderer_1, scene_1, paths_1) {
     });
 }
 /**
- * 加载等距/单图（支持 HDR via RGBELoader）
+ * Load Equirectangular/Single Image (Supports HDR via RGBELoader)
  * @param renderer THREE.WebGLRenderer
  * @param scene THREE.Scene
  * @param url string - *.hdr, *.exr, *.jpg, *.png
@@ -1785,7 +1892,7 @@ function loadEquirectSkybox(renderer_1, scene_1, url_1) {
                 scene.environment = rec.handle.envRenderTarget.texture;
             return rec.handle;
         }
-        // 动态导入 RGBELoader（用于 .hdr/.exr），如果加载的是普通 jpg/png 可直接用 TextureLoader
+        // Dynamically import RGBELoader (for .hdr/.exr), if loading normal jpg/png directly use TextureLoader
         const isHDR = /\.hdr$|\.exr$/i.test(url);
         let hdrTexture;
         if (isHDR) {
@@ -1862,9 +1969,9 @@ function loadSkybox(renderer_1, scene_1, params_1) {
     });
 }
 /* -------------------------
-   缓存/引用计数 辅助方法
+   Cache / Reference Counting Helper Methods
    ------------------------- */
-/** 释放一个缓存的 skybox（会减少 refCount，refCount=0 时才真正 dispose） */
+/** Release a cached skybox (decrements refCount, only truly disposes when refCount=0) */
 function releaseSkybox(handle) {
     // check cube cache
     if (cubeCache.has(handle.key)) {
@@ -1889,85 +1996,94 @@ function releaseSkybox(handle) {
     // handle.dispose()
 }
 
-// utils/BlueSkyManager.ts - 优化版
 /**
- * BlueSkyManager - 优化版
+ * @file blueSkyManager.ts
+ * @description
+ * Global singleton manager for loading and managing HDR/EXR blue sky environment maps.
+ *
+ * @best-practice
+ * - Call `init` once before use.
+ * - Use `loadAsync` to load skyboxes with progress tracking.
+ * - Automatically handles PMREM generation for realistic lighting.
+ */
+/**
+ * BlueSkyManager - Optimized
  * ---------------------------------------------------------
- * 一个全局单例管理器，用于加载和管理基于 HDR/EXR 的蓝天白云环境贴图。
+ * A global singleton manager for loading and managing HDR/EXR based blue sky environment maps.
  *
- * ✨ 优化内容：
- * - 添加加载进度回调
- * - 支持加载取消
- * - 完善错误处理
- * - 返回 Promise 支持异步
- * - 添加加载状态管理
+ * Features:
+ * - Adds load progress callback
+ * - Supports load cancellation
+ * - Improved error handling
+ * - Returns Promise for async operation
+ * - Adds loading state management
  */
 class BlueSkyManager {
     constructor() {
-        /** 当前环境贴图的 RenderTarget，用于后续释放 */
+        /** RenderTarget for current environment map, used for subsequent disposal */
         this.skyRT = null;
-        /** 是否已经初始化 */
+        /** Whether already initialized */
         this.isInitialized = false;
-        /** ✨ 当前加载器，用于取消加载 */
+        /** Current loader, used for cancelling load */
         this.currentLoader = null;
-        /** ✨ 加载状态 */
+        /** Loading state */
         this.loadingState = 'idle';
     }
     /**
-     * 初始化
+     * Initialize
      * ---------------------------------------------------------
-     * 必须在使用 BlueSkyManager 之前调用一次。
-     * @param renderer WebGLRenderer 实例
-     * @param scene Three.js 场景
-     * @param exposure 曝光度 (默认 1.0)
+     * Must be called once before using BlueSkyManager.
+     * @param renderer WebGLRenderer instance
+     * @param scene Three.js Scene
+     * @param exposure Exposure (default 1.0)
      */
     init(renderer, scene, exposure = 1.0) {
         if (this.isInitialized) {
-            console.warn('BlueSkyManager: 已经初始化，跳过重复初始化');
+            console.warn('BlueSkyManager: Already initialized, skipping duplicate initialization');
             return;
         }
         this.renderer = renderer;
         this.scene = scene;
-        // 使用 ACESFilmicToneMapping，效果更接近真实
+        // Use ACESFilmicToneMapping, effect is closer to reality
         this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
         this.renderer.toneMappingExposure = exposure;
-        // 初始化 PMREM 生成器（全局只需一个）
+        // Initialize PMREM generator (only one needed globally)
         this.pmremGen = new THREE.PMREMGenerator(renderer);
         this.pmremGen.compileEquirectangularShader();
         this.isInitialized = true;
     }
     /**
-     * ✨ 加载蓝天 HDR/EXR 贴图并应用到场景（Promise 版本）
+     * Load blue sky HDR/EXR map and apply to scene (Promise version)
      * ---------------------------------------------------------
-     * @param exrPath HDR/EXR 文件路径
-     * @param options 加载选项
+     * @param exrPath HDR/EXR file path
+     * @param options Load options
      * @returns Promise<void>
      */
     loadAsync(exrPath, options = {}) {
         if (!this.isInitialized) {
             return Promise.reject(new Error('BlueSkyManager not initialized!'));
         }
-        // ✨ 取消之前的加载
+        // Cancel previous load
         this.cancelLoad();
         const { background = true, onProgress, onComplete, onError } = options;
         this.loadingState = 'loading';
         this.currentLoader = new EXRLoader();
         return new Promise((resolve, reject) => {
             this.currentLoader.load(exrPath, 
-            // 成功回调
+            // Success callback
             (texture) => {
                 try {
-                    // 设置贴图为球面反射映射
+                    // Set texture mapping to EquirectangularReflectionMapping
                     texture.mapping = THREE.EquirectangularReflectionMapping;
-                    // 清理旧的环境贴图
+                    // Clear old environment map
                     this.dispose();
-                    // 用 PMREM 生成高效的环境贴图
+                    // Generate efficient environment map using PMREM
                     this.skyRT = this.pmremGen.fromEquirectangular(texture);
-                    // 应用到场景：环境光照 & 背景
+                    // Apply to scene: Environment Lighting & Background
                     this.scene.environment = this.skyRT.texture;
                     if (background)
                         this.scene.background = this.skyRT.texture;
-                    // 原始 HDR/EXR 贴图用完即销毁，节省内存
+                    // Dispose original HDR/EXR texture immediately to save memory
                     texture.dispose();
                     this.loadingState = 'loaded';
                     this.currentLoader = null;
@@ -1985,14 +2101,14 @@ class BlueSkyManager {
                     reject(error);
                 }
             }, 
-            // 进度回调
+            // Progress callback
             (xhr) => {
                 if (onProgress && xhr.lengthComputable) {
                     const progress = xhr.loaded / xhr.total;
                     onProgress(progress);
                 }
             }, 
-            // 错误回调
+            // Error callback
             (err) => {
                 this.loadingState = 'error';
                 this.currentLoader = null;
@@ -2004,10 +2120,10 @@ class BlueSkyManager {
         });
     }
     /**
-     * 加载蓝天 HDR/EXR 贴图并应用到场景（同步 API，保持向后兼容）
+     * Load blue sky HDR/EXR map and apply to scene (Sync API, for backward compatibility)
      * ---------------------------------------------------------
-     * @param exrPath HDR/EXR 文件路径
-     * @param background 是否应用为场景背景 (默认 true)
+     * @param exrPath HDR/EXR file path
+     * @param background Whether to apply as scene background (default true)
      */
     load(exrPath, background = true) {
         this.loadAsync(exrPath, { background }).catch((error) => {
@@ -2015,32 +2131,32 @@ class BlueSkyManager {
         });
     }
     /**
-     * ✨ 取消当前加载
+     * Cancel current load
      */
     cancelLoad() {
         if (this.currentLoader) {
-            // EXRLoader 本身没有 abort 方法，但我们可以清空引用
+            // EXRLoader itself does not have abort method, but we can clear the reference
             this.currentLoader = null;
             this.loadingState = 'idle';
         }
     }
     /**
-     * ✨ 获取加载状态
+     * Get loading state
      */
     getLoadingState() {
         return this.loadingState;
     }
     /**
-     * ✨ 是否正在加载
+     * Is loading
      */
     isLoading() {
         return this.loadingState === 'loading';
     }
     /**
-     * 释放当前的天空贴图资源
+     * Release current sky texture resources
      * ---------------------------------------------------------
-     * 仅清理 skyRT，不销毁 PMREM
-     * 适用于切换 HDR/EXR 文件时调用
+     * Only cleans up skyRT, does not destroy PMREM
+     * Suitable for calling when switching HDR/EXR files
      */
     dispose() {
         if (this.skyRT) {
@@ -2054,10 +2170,10 @@ class BlueSkyManager {
             this.scene.environment = null;
     }
     /**
-     * 完全销毁 BlueSkyManager
+     * Completely destroy BlueSkyManager
      * ---------------------------------------------------------
-     * 包括 PMREMGenerator 的销毁
-     * 通常在场景彻底销毁或应用退出时调用
+     * Includes destruction of PMREMGenerator
+     * Usually called when the scene is completely destroyed or the application exits
      */
     destroy() {
         var _a;
@@ -2069,22 +2185,32 @@ class BlueSkyManager {
     }
 }
 /**
- * 🌐 全局单例
+ * Global Singleton
  * ---------------------------------------------------------
- * 直接导出一个全局唯一的 BlueSkyManager 实例，
- * 保证整个应用中只用一个 PMREMGenerator，性能最佳。
+ * Directly export a globally unique BlueSkyManager instance,
+ * Ensuring only one PMREMGenerator is used throughout the application for best performance.
  */
 const BlueSky = new BlueSkyManager();
 
 /**
- * 创建模型标签（带连线和脉冲圆点）- 优化版
+ * @file modelsLabel.ts
+ * @description
+ * Creates interactive 2D labels (DOM elements) attached to 3D objects with connecting lines.
+ *
+ * @best-practice
+ * - Use `createModelsLabel` to annotate parts of a model.
+ * - Supports fading endpoints, pulsing dots, and custom styling.
+ * - Performance optimized with caching and RAF throttling.
+ */
+/**
+ * Create Model Labels (with connecting lines and pulsing dots) - Optimized
  *
- * ✨ 优化内容：
- * - 支持暂停/恢复更新
- * - 可配置更新间隔
- * - 淡入淡出效果
- * - 缓存包围盒计算
- * - RAF 管理优化
+ * Features:
+ * - Supports pause/resume
+ * - Configurable update interval
+ * - Fade in/out effects
+ * - Cached bounding box calculation
+ * - RAF management optimization
  */
 function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, options) {
     var _a, _b, _c, _d, _e, _f;
@@ -2099,8 +2225,8 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
         dotSpacing: (_c = options === null || options === void 0 ? void 0 : options.dotSpacing) !== null && _c !== void 0 ? _c : 2,
         lineColor: (options === null || options === void 0 ? void 0 : options.lineColor) || 'rgba(200,200,200,0.7)',
         lineWidth: (_d = options === null || options === void 0 ? void 0 : options.lineWidth) !== null && _d !== void 0 ? _d : 1,
-        updateInterval: (_e = options === null || options === void 0 ? void 0 : options.updateInterval) !== null && _e !== void 0 ? _e : 0, // ✨ 默认每帧更新
-        fadeInDuration: (_f = options === null || options === void 0 ? void 0 : options.fadeInDuration) !== null && _f !== void 0 ? _f : 300, // ✨ 淡入时长
+        updateInterval: (_e = options === null || options === void 0 ? void 0 : options.updateInterval) !== null && _e !== void 0 ? _e : 0, // Default update every frame
+        fadeInDuration: (_f = options === null || options === void 0 ? void 0 : options.fadeInDuration) !== null && _f !== void 0 ? _f : 300, // Fade-in duration
     };
     const container = document.createElement('div');
     container.style.position = 'absolute';
@@ -2126,10 +2252,10 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
     let currentLabelsMap = Object.assign({}, modelLabelsMap);
     let labels = [];
     let isActive = true;
-    let isPaused = false; // ✨ 暂停状态
-    let rafId = null; // ✨ RAF ID
-    let lastUpdateTime = 0; // ✨ 上次更新时间
-    // ✨ 注入样式（带淡入动画）
+    let isPaused = false;
+    let rafId = null;
+    let lastUpdateTime = 0;
+    // Inject styles (with fade-in animation)
     const styleId = 'three-model-label-styles';
     if (!document.getElementById(styleId)) {
         const style = document.createElement('style');
@@ -2168,14 +2294,14 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
     `;
         document.head.appendChild(style);
     }
-    // ✨ 获取或更新缓存的顶部位置
+    // Get or update cached top position
     const getObjectTopPosition = (labelData) => {
         const obj = labelData.object;
-        // 如果有缓存且对象没有变换，直接返回
+        // If cached and object hasn't transformed, return cached
         if (labelData.cachedTopPos && !obj.matrixWorldNeedsUpdate) {
             return labelData.cachedTopPos.clone();
         }
-        // 重新计算
+        // Recalculate
         const box = new THREE.Box3().setFromObject(obj);
         labelData.cachedBox = box;
         if (!box.isEmpty()) {
@@ -2253,20 +2379,20 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
                     wrapper,
                     dot,
                     line,
-                    cachedBox: null, // ✨ 初始化缓存
+                    cachedBox: null, // Initialize cache
                     cachedTopPos: null
                 });
             }
         });
     };
     rebuildLabels();
-    // ✨ 优化的更新函数
+    // Optimized update function
     const updateLabels = (timestamp) => {
         if (!isActive || isPaused) {
             rafId = null;
             return;
         }
-        // ✨ 节流处理
+        // Throttle
         if (cfg.updateInterval > 0 && timestamp - lastUpdateTime < cfg.updateInterval) {
             rafId = requestAnimationFrame(updateLabels);
             return;
@@ -2279,7 +2405,7 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
         svg.setAttribute('height', `${height}`);
         labels.forEach((labelData) => {
             const { el, wrapper, dot, line } = labelData;
-            const topWorld = getObjectTopPosition(labelData); // ✨ 使用缓存
+            const topWorld = getObjectTopPosition(labelData); // Use cache
             const topNDC = topWorld.clone().project(camera);
             const modelX = (topNDC.x * 0.5 + 0.5) * width + rect.left;
             const modelY = (-(topNDC.y * 0.5) + 0.5) * height + rect.top;
@@ -2314,7 +2440,7 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
             currentLabelsMap = Object.assign({}, newMap);
             rebuildLabels();
         },
-        // ✨ 暂停更新
+        // Pause update
         pause() {
             isPaused = true;
             if (rafId !== null) {
@@ -2322,7 +2448,7 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
                 rafId = null;
             }
         },
-        // ✨ 恢复更新
+        // Resume update
         resume() {
             if (!isPaused)
                 return;
@@ -2343,10 +2469,34 @@ function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, option
     };
 }
 
+/**
+ * @file exploder.ts
+ * @description
+ * GroupExploder - Three.js based model explosion effect tool (Vue3 + TS Support)
+ * ----------------------------------------------------------------------
+ * This tool is used to perform "explode / restore" animations on a set of specified Meshes:
+ *  - Initialize only once (onMounted)
+ *  - Supports dynamic switching of models and automatically restores the explosion state of the previous model
+ *  - Supports multiple arrangement modes (ring / spiral / grid / radial)
+ *  - Supports automatic transparency for non-exploded objects (dimOthers)
+ *  - Supports automatic camera positioning to the best observation point
+ *  - All animations use native requestAnimationFrame
+ *
+ * @best-practice
+ * - Initialize in `onMounted`.
+ * - Use `setMeshes` to update the active set of meshes to explode.
+ * - Call `explode()` to trigger the effect and `restore()` to reset.
+ */
 function easeInOutQuad(t) {
     return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
 }
 class GroupExploder {
+    /**
+     * Constructor
+     * @param scene Three.js Scene instance
+     * @param camera Three.js Camera (usually PerspectiveCamera)
+     * @param controls OrbitControls instance (must be bound to camera)
+     */
     constructor(scene, camera, controls) {
         // sets and snapshots
         this.currentSet = null;
@@ -2378,10 +2528,12 @@ class GroupExploder {
         this.log('init() called');
     }
     /**
-     * setMeshes(newSet):
+     * Set the current set of meshes for explosion.
      * - Detects content-level changes even if same Set reference is used.
      * - Preserves prevSet/stateMap to allow async restore when needed.
      * - Ensures stateMap contains snapshots for *all meshes in the new set*.
+     * @param newSet The new set of meshes
+     * @param contextId Optional context ID to distinguish business scenarios
      */
     setMeshes(newSet, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -2583,6 +2735,11 @@ class GroupExploder {
             return;
         });
     }
+    /**
+     * Restore all exploded meshes to their original transform:
+     * - Supports smooth animation
+     * - Automatically cancels transparency
+     */
     restore(duration = 400) {
         if (!this.currentSet || this.currentSet.size === 0) {
             this.log('restore: no currentSet to restore');
@@ -2939,120 +3096,142 @@ class GroupExploder {
         return targets;
     }
     animateCameraToFit(targetCenter, targetRadius, opts) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const duration = (_a = opts === null || opts === void 0 ? void 0 : opts.duration) !== null && _a !== void 0 ? _a : 600;
         const padding = (_b = opts === null || opts === void 0 ? void 0 : opts.padding) !== null && _b !== void 0 ? _b : 1.5;
         if (!(this.camera instanceof THREE.PerspectiveCamera)) {
             if (this.controls && this.controls.target) {
-                this.controls.target.copy(targetCenter);
-                if (typeof this.controls.update === 'function')
-                    this.controls.update();
+                // Fallback for non-PerspectiveCamera
+                const startTarget = this.controls.target.clone();
+                const startPos = this.camera.position.clone();
+                const endTarget = targetCenter.clone();
+                const dir = startPos.clone().sub(startTarget).normalize();
+                const dist = startPos.distanceTo(startTarget);
+                const endPos = endTarget.clone().add(dir.multiplyScalar(dist));
+                const startTime = performance.now();
+                const tick = (now) => {
+                    var _a;
+                    const t = Math.min(1, (now - startTime) / duration);
+                    const k = easeInOutQuad(t);
+                    if (this.controls && this.controls.target) {
+                        this.controls.target.lerpVectors(startTarget, endTarget, k);
+                    }
+                    this.camera.position.lerpVectors(startPos, endPos, k);
+                    if ((_a = this.controls) === null || _a === void 0 ? void 0 : _a.update)
+                        this.controls.update();
+                    if (t < 1) {
+                        this.cameraAnimId = requestAnimationFrame(tick);
+                    }
+                    else {
+                        this.cameraAnimId = null;
+                    }
+                };
+                this.cameraAnimId = requestAnimationFrame(tick);
             }
             return Promise.resolve();
         }
-        const cam = this.camera;
-        const fov = (cam.fov * Math.PI) / 180;
-        const safeRadius = isFinite(targetRadius) && targetRadius > 0 ? targetRadius : 1;
-        const desiredDistance = Math.min(1e6, (safeRadius * ((_c = opts === null || opts === void 0 ? void 0 : opts.padding) !== null && _c !== void 0 ? _c : padding)) / Math.sin(fov / 2));
-        const camPos = cam.position.clone();
-        const dir = camPos.clone().sub(targetCenter);
-        if (dir.length() === 0)
+        // PerspectiveCamera logic
+        const fov = THREE.MathUtils.degToRad(this.camera.fov);
+        const aspect = this.camera.aspect;
+        // Calculate distance needed to fit the sphere
+        // tan(fov/2) = radius / distance  => distance = radius / tan(fov/2)
+        // We also consider aspect ratio for horizontal fit
+        const distV = targetRadius / Math.sin(fov / 2);
+        const distH = targetRadius / Math.sin(Math.min(fov, fov * aspect) / 2); // approximate
+        const dist = Math.max(distV, distH) * padding;
+        const startPos = this.camera.position.clone();
+        const startTarget = ((_c = this.controls) === null || _c === void 0 ? void 0 : _c.target) ? this.controls.target.clone() : new THREE.Vector3(); // assumption
+        if (!((_d = this.controls) === null || _d === void 0 ? void 0 : _d.target)) {
+            this.camera.getWorldDirection(startTarget);
+            startTarget.add(startPos);
+        }
+        // Determine end position: keep current viewing direction relative to center
+        const dir = startPos.clone().sub(startTarget).normalize();
+        if (dir.lengthSq() < 0.001)
             dir.set(0, 0, 1);
-        else
-            dir.normalize();
-        const newCamPos = targetCenter.clone().add(dir.multiplyScalar(desiredDistance));
-        const startPos = cam.position.clone();
-        const startTarget = (this.controls && this.controls.target) ? (this.controls.target.clone()) : this.getCameraLookAtPoint();
         const endTarget = targetCenter.clone();
-        const startTime = performance.now();
+        const endPos = endTarget.clone().add(dir.multiplyScalar(dist));
         return new Promise((resolve) => {
+            const startTime = performance.now();
             const tick = (now) => {
-                const t = Math.min(1, (now - startTime) / Math.max(1, duration));
-                const eased = easeInOutQuad(t);
-                cam.position.lerpVectors(startPos, newCamPos, eased);
-                if (this.controls && this.controls.target)
-                    this.controls.target.lerpVectors(startTarget, endTarget, eased);
-                cam.updateProjectionMatrix();
-                if (this.controls && typeof this.controls.update === 'function')
-                    this.controls.update();
-                if (t < 1)
+                var _a, _b;
+                const t = Math.min(1, (now - startTime) / duration);
+                const k = easeInOutQuad(t);
+                this.camera.position.lerpVectors(startPos, endPos, k);
+                if (this.controls && this.controls.target) {
+                    this.controls.target.lerpVectors(startTarget, endTarget, k);
+                    (_b = (_a = this.controls).update) === null || _b === void 0 ? void 0 : _b.call(_a);
+                }
+                else {
+                    this.camera.lookAt(endTarget); // simple lookAt if no controls
+                }
+                if (t < 1) {
                     this.cameraAnimId = requestAnimationFrame(tick);
+                }
                 else {
                     this.cameraAnimId = null;
-                    this.log(`animateCameraToFit: done. center=${targetCenter.toArray().map((n) => n.toFixed(2))}, radius=${targetRadius.toFixed(2)}`);
                     resolve();
                 }
             };
             this.cameraAnimId = requestAnimationFrame(tick);
         });
     }
-    getCameraLookAtPoint() {
-        const dir = new THREE.Vector3();
-        this.camera.getWorldDirection(dir);
-        return this.camera.position.clone().add(dir.multiplyScalar(10));
-    }
+    /**
+     * Cancel all running animations
+     */
     cancelAnimations() {
-        if (this.animId) {
+        if (this.animId !== null) {
             cancelAnimationFrame(this.animId);
             this.animId = null;
         }
-        if (this.cameraAnimId) {
+        if (this.cameraAnimId !== null) {
             cancelAnimationFrame(this.cameraAnimId);
             this.cameraAnimId = null;
         }
     }
+    /**
+     * Dispose: remove listener, cancel animation, clear references
+     */
     dispose() {
-        return __awaiter(this, arguments, void 0, function* (restoreBefore = true) {
-            this.cancelAnimations();
-            if (restoreBefore && this.isExploded) {
-                try {
-                    yield this.restore(200);
-                }
-                catch (_a) { }
-            }
-            // force restore of materials
-            for (const [mat, ctxs] of Array.from(this.materialContexts.entries())) {
-                const snap = this.materialSnaps.get(mat);
-                if (snap) {
-                    mat.transparent = snap.transparent;
-                    mat.opacity = snap.opacity;
-                    if (typeof snap.depthWrite !== 'undefined')
-                        mat.depthWrite = snap.depthWrite;
-                    mat.needsUpdate = true;
-                }
-                this.materialContexts.delete(mat);
-                this.materialSnaps.delete(mat);
-            }
-            this.contextMaterials.clear();
-            this.stateMap.clear();
-            this.prevStateMap.clear();
-            this.currentSet = null;
-            this.prevSet = null;
-            this.isInitialized = false;
-            this.isExploded = false;
-            this.log('dispose: cleaned up');
-        });
+        this.cancelAnimations();
+        this.currentSet = null;
+        this.prevSet = null;
+        this.stateMap.clear();
+        this.prevStateMap.clear();
+        this.materialContexts.clear();
+        this.materialSnaps.clear();
+        this.contextMaterials.clear();
+        this.log('dispose() called, resources cleaned up');
     }
 }
 
 /**
- * 自动设置相机与基础灯光 - 优化版
+ * @file autoSetup.ts
+ * @description
+ * Automatically sets up the camera and basic lighting scene based on the model's bounding box.
+ *
+ * @best-practice
+ * - Call `autoSetupCameraAndLight` after loading a model to get a quick "good looking" scene.
+ * - Returns a handle to dispose lights or update intensity later.
+ */
+/**
+ * Automatically setup camera and basic lighting - Optimized
  *
- * ✨ 优化内容：
- * - 添加灯光强度调整方法
- * - 完善错误处理
- * - 优化dispose逻辑
+ * Features:
+ * - Adds light intensity adjustment method
+ * - Improved error handling
+ * - Optimized dispose logic
  *
- * - camera: THREE.PerspectiveCamera（会被移动并指向模型中心）
- * - scene: THREE.Scene（会把新创建的 light group 加入 scene）
- * - model: THREE.Object3D 已加载的模型（任意 transform/坐标）
- * - options: 可选配置（见 AutoSetupOptions）
+ * - camera: THREE.PerspectiveCamera (will be moved and pointed at model center)
+ * - scene: THREE.Scene (newly created light group will be added to the scene)
+ * - model: THREE.Object3D loaded model (arbitrary transform/coordinates)
+ * - options: Optional configuration (see AutoSetupOptions)
  *
- * 返回 AutoSetupHandle，调用方在组件卸载/切换时请调用 handle.dispose()
+ * Returns AutoSetupHandle, caller should call handle.dispose() when component unmounts/switches
  */
 function autoSetupCameraAndLight(camera, scene, model, options = {}) {
     var _a, _b, _c, _d, _e, _f, _g;
-    // ✨ 边界检查
+    // Boundary check
     if (!camera || !scene || !model) {
         throw new Error('autoSetupCameraAndLight: camera, scene, model are required');
     }
@@ -3066,9 +3245,9 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
         renderer: (_g = options.renderer) !== null && _g !== void 0 ? _g : null,
     };
     try {
-        // --- 1) 计算包围数据
+        // --- 1) Calculate bounding data
         const box = new THREE.Box3().setFromObject(model);
-        // ✨ 检查包围盒有效性
+        // Check bounding box validity
         if (!isFinite(box.min.x)) {
             throw new Error('autoSetupCameraAndLight: Invalid bounding box');
         }
@@ -3076,7 +3255,7 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
         box.getBoundingSphere(sphere);
         const center = sphere.center.clone();
         const radius = Math.max(0.001, sphere.radius);
-        // --- 2) 计算相机位置
+        // --- 2) Calculate camera position
         const fov = (camera.fov * Math.PI) / 180;
         const halfFov = fov / 2;
         const sinHalfFov = Math.max(Math.sin(halfFov), 0.001);
@@ -3088,17 +3267,17 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
         camera.near = Math.max(0.001, radius / 1000);
         camera.far = Math.max(1000, radius * 50);
         camera.updateProjectionMatrix();
-        // --- 3) 启用阴影
+        // --- 3) Enable Shadows
         if (opts.renderer && opts.enableShadows) {
             opts.renderer.shadowMap.enabled = true;
             opts.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
         }
-        // --- 4) 创建灯光组
+        // --- 4) Create Lights Group
         const lightsGroup = new THREE.Group();
         lightsGroup.name = 'autoSetupLightsGroup';
         lightsGroup.position.copy(center);
         scene.add(lightsGroup);
-        // 4.1 基础光
+        // 4.1 Basic Light
         const hemi = new THREE.HemisphereLight(0xffffff, 0x444444, 0.6);
         hemi.name = 'auto_hemi';
         hemi.position.set(0, radius * 2.0, 0);
@@ -3106,7 +3285,7 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
         const ambient = new THREE.AmbientLight(0xffffff, 0.25);
         ambient.name = 'auto_ambient';
         lightsGroup.add(ambient);
-        // 4.2 方向光
+        // 4.2 Directional Lights
         const dirCount = Math.max(1, Math.floor(opts.directionalCount));
         const directionalLights = [];
         const dirs = [];
@@ -3141,7 +3320,7 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
             }
             directionalLights.push(light);
         }
-        // 4.3 点光补光
+        // 4.3 Point Light Fill
         const fill1 = new THREE.PointLight(0xffffff, 0.5, radius * 4);
         fill1.position.copy(center).add(new THREE.Vector3(radius * 0.5, 0.2 * radius, 0));
         fill1.name = 'auto_fill1';
@@ -3150,7 +3329,7 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
         fill2.position.copy(center).add(new THREE.Vector3(-radius * 0.5, -0.2 * radius, 0));
         fill2.name = 'auto_fill2';
         lightsGroup.add(fill2);
-        // --- 5) 设置 Mesh 阴影属性
+        // --- 5) Set Mesh Shadow Props
         if (opts.setMeshShadowProps) {
             model.traverse((ch) => {
                 if (ch.isMesh) {
@@ -3161,12 +3340,12 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
                 }
             });
         }
-        // --- 6) 返回 handle ---
+        // --- 6) Return handle ---
         const handle = {
             lightsGroup,
             center,
             radius,
-            // ✨ 新增灯光强度调整
+            // Update light intensity
             updateLightIntensity(factor) {
                 lightsGroup.traverse((node) => {
                     if (node.isLight) {
@@ -3178,10 +3357,10 @@ function autoSetupCameraAndLight(camera, scene, model, options = {}) {
             },
             dispose: () => {
                 try {
-                    // 移除灯光组
+                    // Remove lights group
                     if (lightsGroup.parent)
                         lightsGroup.parent.remove(lightsGroup);
-                    // 清理阴影资源
+                    // Dispose shadow resources
                     lightsGroup.traverse((node) => {
                         if (node.isLight) {
                             const l = node;