@chocozhang/three-model-render 1.0.3 → 1.0.4

package/dist/index.d.ts

@@ -3,6 +3,17 @@ import { OutlinePass } from 'three/examples/jsm/postprocessing/OutlinePass';
 import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
 
+/**
+ * @file labelManager.ts
+ * @description
+ * Manages HTML labels attached to 3D objects. Efficiently updates label positions based on camera movement.
+ *
+ * @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.
+ */
+
 interface LabelOptions$1 {
     fontSize?: string;
     color?: string;
@@ -19,23 +30,34 @@ interface LabelManager$1 {
     isRunning: () => boolean;
 }
 /**
- * 给子模型添加头顶标签（支持 Mesh 和 Group）- 优化版
- *
- * ✨ 性能优化：
- * - 缓存包围盒，避免每帧重复计算
- * - 支持暂停/恢复更新
- * - 可配置更新间隔，降低 CPU 占用
- * - 只在可见时更新，隐藏时自动暂停
- *
- * @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 的管理接口
+ * 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 - 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
  */
 declare function addChildModelLabels(camera: THREE.Camera, renderer: THREE.WebGLRenderer, parentModel: THREE.Object3D, modelLabelsMap: Record<string, string>, options?: LabelOptions$1): LabelManager$1;
 
+/**
+ * @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.
+ */
+
 type HoverBreathOptions = {
     camera: THREE.Camera;
     scene: THREE.Scene;
@@ -48,13 +70,13 @@ type HoverBreathOptions = {
     throttleDelay?: number;
 };
 /**
- * 创建单例高亮器 —— 推荐在 mounted 时创建一次
- * 返回 { updateHighlightNames, dispose, getHoveredName } 接口
+ * 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
  */
 declare function enableHoverBreath(opts: HoverBreathOptions): {
     updateHighlightNames: (names: string[] | null) => void;
@@ -64,7 +86,18 @@ declare function enableHoverBreath(opts: HoverBreathOptions): {
 };
 
 /**
- * 后期处理配置选项
+ * @file postProcessing.ts
+ * @description
+ * Manages the post-processing chain, specifically for Outline effects and Gamma correction.
+ *
+ * @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.
+ */
+
+/**
+ * Post-processing configuration options
  */
 interface PostProcessingOptions {
     edgeStrength?: number;
@@ -75,7 +108,7 @@ interface PostProcessingOptions {
     resolutionScale?: number;
 }
 /**
- * 后期处理管理接口
+ * Post-processing management interface
  */
 interface PostProcessingManager {
     composer: EffectComposer;
@@ -84,23 +117,34 @@ interface PostProcessingManager {
     dispose: () => void;
 }
 /**
- * 初始化描边相关信息（包含 OutlinePass）- 优化版
+ * Initialize outline-related information (contains OutlinePass)
  *
- * ✨ 功能增强：
- * - 支持窗口 resize 自动更新
- * - 可配置分辨率缩放提升性能
- * - 完善的资源释放管理
+ * 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
  */
 declare function initPostProcessing(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, options?: PostProcessingOptions): PostProcessingManager;
 
 /**
- * 点击处理器配置选项
+ * @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.
+ */
+
+/**
+ * Click Handler Options
  */
 interface ClickHandlerOptions {
     clickThreshold?: number;
@@ -115,21 +159,21 @@ interface ClickHandlerOptions {
     maxThickness?: number;
 }
 /**
- * 创建模型点击高亮工具（OutlinePass 版）- 优化版
- *
- * ✨ 功能增强：
- * - 使用 AbortController 统一管理事件生命周期
- * - 支持防抖处理避免频繁触发
- * - 可自定义 Raycaster 参数
- * - 根据相机距离动态调整描边厚度
- *
- * @param camera 相机
- * @param scene 场景
- * @param renderer 渲染器
- * @param outlinePass 已初始化的 OutlinePass
- * @param onClick 点击回调
- * @param options 可选配置
- * @returns dispose 函数，用于清理事件和资源
+ * Create Model Click Highlight Tool (OutlinePass Version) - Optimized
+ *
+ * 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 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
  */
 declare function createModelClickHandler(camera: THREE.Camera, scene: THREE.Scene, renderer: THREE.WebGLRenderer, outlinePass: OutlinePass, onClick: (object: THREE.Object3D | null, info?: {
     name?: string;
@@ -137,17 +181,28 @@ declare function createModelClickHandler(camera: THREE.Camera, scene: THREE.Scen
     uuid?: string;
 }) => void, options?: ClickHandlerOptions): () => void;
 
+/**
+ * @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.
+ */
+
 type FilterFn = (obj: THREE.Object3D) => boolean;
 /**
- * ArrowGuide - 优化版
- * 箭头引导效果工具，支持高亮模型并淡化其他对象
- *
- * ✨ 优化内容：
- * - 使用 WeakMap 自动回收材质，避免内存泄漏
- * - 使用 AbortController 管理事件生命周期
- * - 添加材质复用机制，减少重复创建
- * - 改进 dispose 逻辑，确保完全释放资源
- * - 添加错误处理和边界检查
+ * ArrowGuide - Optimized Version
+ * Arrow guide effect tool, supports highlighting models and fading other objects.
+ *
+ * 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
  */
 declare class ArrowGuide {
     private renderer;
@@ -176,44 +231,55 @@ declare class ArrowGuide {
     private makeFadedClone;
     private createFadedMaterialFrom;
     /**
-     * 设置箭头 Mesh
+     * Set Arrow Mesh
      */
     setArrowMesh(mesh: THREE.Mesh): void;
     /**
-     * 高亮指定模型
+     * Highlight specified models
      */
     highlight(models: THREE.Object3D[]): void;
     private applyHighlight;
     restore(): void;
     /**
-     * 动画更新（每帧调用）
+     * Animation update (called every frame)
      */
     animate(): void;
     /**
-     * 初始化事件监听器
+     * Initialize event listeners
      */
     private initEvents;
     /**
-     * 释放所有资源
+     * Dispose all resources
      */
     dispose(): void;
 }
 
+/**
+ * @file liquidFiller.ts
+ * @description
+ * Liquid filling effect for single or multiple models using local clipping planes.
+ *
+ * @best-practice
+ * - Use `fillTo` to animate liquid level.
+ * - Supports multiple independent liquid levels.
+ * - Call `dispose` to clean up resources and event listeners.
+ */
+
 interface LiquidFillerOptions {
     color?: number;
     opacity?: number;
     speed?: number;
 }
 /**
- * LiquidFillerGroup - 优化版
- * 支持单模型或多模型液位动画、独立颜色控制
- *
- * ✨ 优化内容：
- * - 使用 renderer.domElement 替代 window 事件
- * - 使用 AbortController 管理事件生命周期
- * - 添加错误处理和边界检查
- * - 优化动画管理，避免内存泄漏
- * - 完善资源释放逻辑
+ * 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
  */
 declare class LiquidFillerGroup {
     private items;
@@ -225,35 +291,47 @@ declare class LiquidFillerGroup {
     private clickThreshold;
     private abortController;
     /**
-     * 构造函数
-     * @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: THREE.Object3D | THREE.Object3D[], scene: THREE.Scene, camera: THREE.Camera, renderer: THREE.WebGLRenderer, defaultOptions?: LiquidFillerOptions, clickThreshold?: number);
-    /** pointerdown 记录位置 */
+    /** pointerdown record position */
     private handlePointerDown;
-    /** pointerup 判断点击空白，恢复原始材质 */
+    /** pointerup check click blank, restore original material */
     private handlePointerUp;
     /**
-   * 设置液位
-   * @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: THREE.Object3D | THREE.Object3D[], percent: number): void;
-    /** 设置多个模型液位，percentList 与 items 顺序对应 */
+    /** Set multiple model levels, percentList corresponds to items order */
     fillToAll(percentList: number[]): void;
-    /** 恢复单个模型原始材质并移除液体 */
+    /** Restore single model original material and remove liquid */
     restore(model: THREE.Object3D): void;
-    /** 恢复所有模型 */
+    /** Restore all models */
     restoreAll(): void;
-    /** 销毁方法，释放事件和资源 */
+    /** Dispose method, release events and resources */
     dispose(): void;
 }
 
+/**
+ * @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.
+ */
+
 interface FollowOptions {
     duration?: number;
     padding?: number;
@@ -269,72 +347,83 @@ interface FollowOptions {
     onProgress?: (progress: number) => void;
 }
 /**
- * 推荐角度枚举，便于快速选取常见视角
+ * Recommended camera angles for quick selection of common views
  */
 declare const FOLLOW_ANGLES: {
-    /** 等距斜视（默认视角）- 适合建筑、机械设备展示 */
+    /** Isometric view (default) - suitable for architecture, mechanical equipment */
     readonly ISOMETRIC: {
         readonly azimuth: number;
         readonly elevation: number;
     };
-    /** 正前视角 - 适合正面展示、UI 对齐 */
+    /** Front view - suitable for frontal display, UI alignment */
     readonly FRONT: {
         readonly azimuth: 0;
         readonly elevation: 0;
     };
-    /** 右侧视角 - 适合机械剖面、侧视检查 */
+    /** Right view - suitable for mechanical sections, side inspection */
     readonly RIGHT: {
         readonly azimuth: number;
         readonly elevation: 0;
     };
-    /** 左侧视角 */
+    /** Left view */
     readonly LEFT: {
         readonly azimuth: number;
         readonly elevation: 0;
     };
-    /** 后视角 */
+    /** Back view */
     readonly BACK: {
         readonly azimuth: number;
         readonly elevation: 0;
     };
-    /** 顶视图 - 适合地图、平面布局展示 */
+    /** Top view - suitable for maps, layout display */
     readonly TOP: {
         readonly azimuth: 0;
         readonly elevation: number;
     };
-    /** 低角度俯视 - 适合车辆、人物等近地物体 */
+    /** Low angle view - suitable for vehicles, characters near the ground */
     readonly LOW_ANGLE: {
         readonly azimuth: number;
         readonly elevation: number;
     };
-    /** 高角度俯视 - 适合鸟瞰、全景浏览 */
+    /** High angle view - suitable for bird's eye view, panoramic browsing */
     readonly HIGH_ANGLE: {
         readonly azimuth: number;
         readonly elevation: number;
     };
 };
 /**
- * 自动将相机移到目标的斜上角位置，并保证目标在可视范围内（平滑过渡）- 优化版
- *
- * ✨ 优化内容：
- * - 支持多种缓动函数
- * - 添加进度回调
- * - 支持取消动画
- * - WeakMap 跟踪防止泄漏
- * - 完善错误处理
+ * Automatically moves the camera to a diagonal position relative to the target,
+ * ensuring the target is within the field of view (smooth transition).
+ *
+ * Features:
+ * - Supports multiple easing functions
+ * - Adds progress callback
+ * - Supports animation cancellation
+ * - Uses WeakMap to track and prevent memory leaks
+ * - Robust error handling
  */
 declare function followModels(camera: THREE.Camera, targets: THREE.Object3D | THREE.Object3D[] | null | undefined, options?: FollowOptions): Promise<void>;
 /**
- * ✨ 取消相机的跟随动画
+ * Cancel the camera follow animation
  */
 declare function cancelFollow(camera: THREE.Camera): void;
 
 /**
- * 视角类型
+ * @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.
+ */
+
+/**
+ * View types
  */
 type ViewPosition = 'front' | 'back' | 'left' | 'right' | 'top' | 'bottom' | 'iso';
 /**
- * 视角配置选项
+ * View configuration options
  */
 interface SetViewOptions {
     distanceFactor?: number;
@@ -343,46 +432,57 @@ interface SetViewOptions {
     onProgress?: (progress: number) => void;
 }
 /**
- * 平滑切换相机到模型的最佳视角 - 优化版
- *
- * ✨ 优化内容：
- * - 复用 followModels 逻辑，避免代码重复
- * - 支持更多视角
- * - 配置选项增强
- * - 返回 Promise 支持链式调用
- * - 支持取消动画
- *
- * @param camera       THREE.PerspectiveCamera 相机实例
- * @param controls     OrbitControls 控制器实例
- * @param targetObj    THREE.Object3D 模型对象
- * @param position     视角位置
- * @param options      配置选项
+ * Smoothly switches the camera to the optimal angle for the model.
+ *
+ * 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 instance
+ * @param controls     OrbitControls instance
+ * @param targetObj    THREE.Object3D model object
+ * @param position     View position
+ * @param options      Configuration options
  * @returns Promise<void>
  */
 declare function setView(camera: THREE.PerspectiveCamera, controls: OrbitControls, targetObj: THREE.Object3D, position?: ViewPosition, options?: SetViewOptions): Promise<void>;
 /**
- * ✨ 取消视角切换动画
+ * Cancel view switch animation
  */
 declare function cancelSetView(camera: THREE.PerspectiveCamera): void;
 /**
- * ✨ 预设视角快捷方法
+ * Preset view shortcut methods
  */
 declare const ViewPresets: {
     /**
-     * 前视图
+     * Front View
      */
     front: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
     /**
-     * 等距视图
+     * Isometric View
      */
     isometric: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
     /**
-     * 顶视图
+     * Top View
      */
     top: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
 };
 
-/** 加载参数：现在有默认值 */
+/**
+ * @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.
+ */
+
+/** Loading Options: Now has default values */
 interface LoadOptions {
     manager?: THREE.LoadingManager;
     dracoDecoderPath?: string | null;
@@ -394,21 +494,32 @@ interface LoadOptions {
     skipSkinned?: boolean;
 }
 declare function loadModelByUrl(url: string, options?: LoadOptions): Promise<THREE.Object3D>;
-/** 彻底释放对象：几何体，材质和其贴图（危险：共享资源会被释放） */
+/** Completely dispose object: geometry, material and its textures (Danger: shared resources will be disposed) */
 declare function disposeObject(obj: THREE.Object3D | null): void;
-/** 释放材质及其贴图 */
+/** Dispose material and its textures */
 declare function disposeMaterial(mat: any): void;
 
 /**
- * Skybox 加载工具
+ * @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.
+ */
+
+/**
+ * Skybox Loader Utility
  *
- * 支持：
- *  - 立方体贴图：paths: [px, nx, py, ny, pz, nz]
- *  - 等距 / HDR 全景：url: 'path/to/scene.hdr' 或 jpg
+ * Supports:
+ *  - Cube Texture: paths: [px, nx, py, ny, pz, nz]
+ *  - Equirectangular / HDR Panorama: url: 'path/to/scene.hdr' or jpg
  *
- * 返回一个 SkyboxHandle，包含对 scene 的修改记录和 dispose() 方法。
+ * Returns a SkyboxHandle containing modification records for the scene and a dispose() method.
  */
-/** 统一返回句柄 */
+/** Unified Return Handle */
 type SkyboxHandle = {
     key: string;
     backgroundTexture: THREE.Texture | null;
@@ -416,10 +527,10 @@ type SkyboxHandle = {
     pmremGenerator: THREE.PMREMGenerator | null;
     setAsBackground: boolean;
     setAsEnvironment: boolean;
-    /** 卸载并释放资源（如果是缓存共享，需要 refCount 逻辑） */
+    /** Unload and release resources (if cached/shared, refCount logic is needed) */
     dispose: () => void;
 };
-/** 加载选项与默认值 */
+/** Loading Options & Defaults */
 interface SkyboxOptions {
     setAsBackground?: boolean;
     setAsEnvironment?: boolean;
@@ -428,15 +539,15 @@ interface SkyboxOptions {
     cache?: boolean;
 }
 /**
- * 加载立方体贴图（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
  */
 declare function loadCubeSkybox(renderer: THREE.WebGLRenderer, scene: THREE.Scene, paths: string[], opts?: SkyboxOptions): Promise<SkyboxHandle>;
 /**
- * 加载等距/单图（支持 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
@@ -451,15 +562,26 @@ type LoadSkyboxParams = {
     url: string;
 };
 declare function loadSkybox(renderer: THREE.WebGLRenderer, scene: THREE.Scene, params: LoadSkyboxParams, opts?: SkyboxOptions): Promise<SkyboxHandle>;
-/** 释放一个缓存的 skybox（会减少 refCount，refCount=0 时才真正 dispose） */
+/** Release a cached skybox (decrements refCount, only truly disposes when refCount=0) */
 declare function releaseSkybox(handle: SkyboxHandle): void;
 
 /**
- * 加载进度回调类型
+ * @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.
+ */
+
+/**
+ * Load progress callback type
  */
 type LoadProgressCallback = (progress: number) => void;
 /**
- * 加载选项
+ * Load options
  */
 interface LoadSkyOptions {
     background?: boolean;
@@ -468,91 +590,102 @@ interface LoadSkyOptions {
     onError?: (error: any) => void;
 }
 /**
- * BlueSkyManager - 优化版
+ * BlueSkyManager - Optimized
  * ---------------------------------------------------------
- * 一个全局单例管理器，用于加载和管理基于 HDR/EXR 的蓝天白云环境贴图。
- *
- * ✨ 优化内容：
- * - 添加加载进度回调
- * - 支持加载取消
- * - 完善错误处理
- * - 返回 Promise 支持异步
- * - 添加加载状态管理
+ * A global singleton manager for loading and managing HDR/EXR based blue sky environment maps.
+ *
+ * Features:
+ * - Adds load progress callback
+ * - Supports load cancellation
+ * - Improved error handling
+ * - Returns Promise for async operation
+ * - Adds loading state management
  */
 declare class BlueSkyManager {
-    /** three.js 渲染器实例 */
+    /** three.js renderer instance */
     private renderer;
-    /** three.js 场景实例 */
+    /** three.js scene instance */
     private scene;
-    /** PMREM 生成器，用于将 HDR/EXR 转换为高效的反射贴图 */
+    /** PMREM generator, used to convert HDR/EXR to efficient reflection maps */
     private pmremGen;
-    /** 当前环境贴图的 RenderTarget，用于后续释放 */
+    /** RenderTarget for current environment map, used for subsequent disposal */
     private skyRT;
-    /** 是否已经初始化 */
+    /** Whether already initialized */
     private isInitialized;
-    /** ✨ 当前加载器，用于取消加载 */
+    /** Current loader, used for cancelling load */
     private currentLoader;
-    /** ✨ 加载状态 */
+    /** Loading state */
     private loadingState;
     /**
-     * 初始化
+     * 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: THREE.WebGLRenderer, scene: THREE.Scene, exposure?: number): void;
     /**
-     * ✨ 加载蓝天 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: string, options?: LoadSkyOptions): Promise<void>;
     /**
-     * 加载蓝天 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: string, background?: boolean): void;
     /**
-     * ✨ 取消当前加载
+     * Cancel current load
      */
     cancelLoad(): void;
     /**
-     * ✨ 获取加载状态
+     * Get loading state
      */
     getLoadingState(): 'idle' | 'loading' | 'loaded' | 'error';
     /**
-     * ✨ 是否正在加载
+     * Is loading
      */
     isLoading(): boolean;
     /**
-     * 释放当前的天空贴图资源
+     * 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(): void;
     /**
-     * 完全销毁 BlueSkyManager
+     * Completely destroy BlueSkyManager
      * ---------------------------------------------------------
-     * 包括 PMREMGenerator 的销毁
-     * 通常在场景彻底销毁或应用退出时调用
+     * Includes destruction of PMREMGenerator
+     * Usually called when the scene is completely destroyed or the application exits
      */
     destroy(): void;
 }
 /**
- * 🌐 全局单例
+ * Global Singleton
  * ---------------------------------------------------------
- * 直接导出一个全局唯一的 BlueSkyManager 实例，
- * 保证整个应用中只用一个 PMREMGenerator，性能最佳。
+ * Directly export a globally unique BlueSkyManager instance,
+ * Ensuring only one PMREMGenerator is used throughout the application for best performance.
  */
 declare const BlueSky: 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.
+ */
+
 interface LabelOptions {
     fontSize?: string;
     color?: string;
@@ -575,153 +708,48 @@ interface LabelManager {
     dispose: () => void;
 }
 /**
- * 创建模型标签（带连线和脉冲圆点）- 优化版
- *
- * ✨ 优化内容：
- * - 支持暂停/恢复更新
- * - 可配置更新间隔
- * - 淡入淡出效果
- * - 缓存包围盒计算
- * - RAF 管理优化
+ * Create Model Labels (with connecting lines and pulsing dots) - Optimized
+ *
+ * Features:
+ * - Supports pause/resume
+ * - Configurable update interval
+ * - Fade in/out effects
+ * - Cached bounding box calculation
+ * - RAF management optimization
  */
 declare function createModelsLabel(camera: THREE.Camera, renderer: THREE.WebGLRenderer, parentModel: THREE.Object3D, modelLabelsMap: Record<string, string>, options?: LabelOptions): LabelManager;
 
 /**
- * GroupExploder - 基于 Three.js 的模型爆炸效果工具（支持 Vue3 + TS）
- * ----------------------------------------------------------------------
- * 该工具用于对指定 Mesh 的集合进行“爆炸 / 还原”动画：
- *  - 仅初始化一次（onMounted）
- *  - 支持动态切换模型并自动还原上一个模型的爆炸状态
- *  - 支持多种排列模式（ring / spiral / grid / radial）
- *  - 支持非爆炸对象自动透明化（dimOthers）
- *  - 支持摄像机自动前置定位到最佳观察点
- *  - 所有动画均采用原生 requestAnimationFrame 实现
- *
- * ----------------------------------------------------------------------
- * 🔧 构造参数
- * ----------------------------------------------------------------------
- * @param scene      Three.js 场景实例
- * @param camera     Three.js 相机（一般为 PerspectiveCamera）
- * @param controls   OrbitControls 控件实例（必须绑定 camera）
- *
+ * @file exploder.ts
+ * @description
+ * GroupExploder - Three.js based model explosion effect tool (Vue3 + TS Support)
  * ----------------------------------------------------------------------
- * 🔥 爆炸参数 ExplodeOptions
- * ----------------------------------------------------------------------
- * 所有参数均可在 explode() 调用时指定，也可设置默认值。
- *
- * type ArrangeMode = 'ring' | 'spiral' | 'grid' | 'radial'
- *
- * @param mode?: ArrangeMode
- *        爆炸排列方式：
- *        - 'ring'   环形排列（默认）
- *        - 'spiral' 螺旋上升排列
- *        - 'grid'   平面网格排列（规则整齐）
- *        - 'radial' 从中心点向外扩散
- *
- * @param spacing?: number
- *        相邻爆炸对象之间的间距（默认：2.5）
- *
- * @param duration?: number
- *        爆炸动画时长（ms），原生 rAF 完成（默认：1000）
- *
- * @param lift?: number
- *        爆炸对象整体抬升的高度因子，用于让爆炸看起来更立体（默认：0.6）
- *
- * @param cameraPadding?: number
- *        摄像机贴合爆炸后包围球时的额外安全距离（默认：1.2）
- *
- * @param autoRestorePrev?: boolean
- *        当切换模型时，是否自动 restore 上一个模型的爆炸元素（默认：true）
- *
- * @param dimOthers?: { enabled: boolean; opacity?: number }
- *        非爆炸对象透明化配置：
- *        - enabled: true   开启
- *        - opacity: number 指定非爆炸对象透明度（默认：0.15）
- *
- * @param debug?: boolean
- *        是否开启调试日志，输出所有内部状态（默认 false）
- *
- *
- * ----------------------------------------------------------------------
- * 📌 方法说明
- * ----------------------------------------------------------------------
- *
- * ◆ setMeshes(meshSet: Set<Mesh>, contextId?: string)
- *    设置当前模型的爆炸 Mesh 集合：
- *      - 会记录 Mesh 的初始 transform
- *      - 根据 autoRestorePrev 自动还原上次爆炸
- *      - 第二个参数 contextId 可选，用于区分业务场景
- *
- *
- * ◆ explode(options?: ExplodeOptions)
- *    对当前 meshSet 执行爆炸动画：
- *      - 根据 mode 生成爆炸布局
- *      - 相机先自动飞向最佳观察点
- *      - 执行 mesh 位移动画
- *      - 按需将非爆炸模型透明化
- *
- *
- * ◆ restore(duration?: number)
- *    还原所有爆炸 Mesh 到爆炸前的 transform：
- *      - 支持平滑动画
- *      - 自动取消透明化
- *
- *
- * ◆ dispose()
- *    移除事件监听、取消动画、清理引用（在组件销毁时调用）
- *
- *
- * ----------------------------------------------------------------------
- * 🎨 排列模式说明
- * ----------------------------------------------------------------------
- *
- * 1. Ring（环形）
- *    - 按圆均匀分布
- *    - spacing 控制半径
- *    - lift 控制整体抬起高度
- *
- * 2. Spiral（螺旋）
- *    - 在环形基础上添加高度递增（y++)
- *    - 数量大时视觉效果最强
- *
- * 3. Grid（网格）
- *    - 类似棋盘布局
- *    - spacing 控制网格大小
- *    - z 不变或小幅度变化
- *
- * 4. Radial（径向扩散）
- *    - 从中心向外 “爆炸式” 发散
- *    - 对于大型组件分解展示非常适合
- *
- *
- * ----------------------------------------------------------------------
- * 📌 使用示例（业务层 Vue）
- * ----------------------------------------------------------------------
- *
- * const exploder = new GroupExploder(scene, camera, controls);
- *
- * onMounted(() => {
- *   exploder.setMeshes(new Set([meshA, meshB, meshC]));
- * });
- *
- * const triggerExplode = () => {
- *   exploder.explode({
- *     mode: 'ring',
- *     spacing: 3,
- *     duration: 1200,
- *     lift: 0.8,
- *     cameraPadding: 1.3,
- *     dimOthers: { enabled: true, opacity: 0.2 },
- *   });
- * };
- *
- * const triggerRestore = () => {
- *   exploder.restore(600);
- * };
- *
+ * 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.
  */
 
 type ArrangeMode = 'ring' | 'spiral' | 'grid' | 'radial';
+/**
+ * Explosion Parameters
+ * @param mode Explosion arrangement mode: 'ring' | 'spiral' | 'grid' | 'radial'
+ * @param spacing Spacing between adjacent exploded objects (default: 2.5)
+ * @param duration Animation duration in ms (default: 1000)
+ * @param lift Lift factor for exploded objects (default: 0.6)
+ * @param cameraPadding Extra safety distance for camera framing (default: 1.2)
+ * @param autoRestorePrev Whether to automatically restore the previous model's explosion when switching models (default: true)
+ * @param dimOthers Configuration for dimming non-exploded objects
+ * @param debug Enable debug logs (default: false)
+ */
 type ExplodeOptions = {
     mode?: ArrangeMode;
     spacing?: number;
@@ -751,6 +779,12 @@ declare class GroupExploder {
     private isExploded;
     private isInitialized;
     onLog?: (s: string) => void;
+    /**
+     * 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: THREE.Scene, camera: THREE.PerspectiveCamera | THREE.Camera, controls?: {
         target?: THREE.Vector3;
         update?: () => void;
@@ -758,10 +792,12 @@ declare class GroupExploder {
     private log;
     init(): void;
     /**
-     * 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: Set<THREE.Mesh> | null, options?: {
         autoRestorePrev?: boolean;
@@ -777,6 +813,11 @@ declare class GroupExploder {
      * animate camera to that targetBound, then animate meshes to targets.
      */
     explode(opts?: ExplodeOptions): Promise<void>;
+    /**
+     * Restore all exploded meshes to their original transform:
+     * - Supports smooth animation
+     * - Automatically cancels transparency
+     */
     restore(duration?: number): Promise<void>;
     /**
      * restoreSet: reparent and restore transforms using provided stateMap.
@@ -791,29 +832,44 @@ declare class GroupExploder {
     private computeBoundingSphereForPositionsAndMeshes;
     private computeTargetsByMode;
     private animateCameraToFit;
-    private getCameraLookAtPoint;
+    /**
+     * Cancel all running animations
+     */
     private cancelAnimations;
-    dispose(restoreBefore?: boolean): Promise<void>;
+    /**
+     * Dispose: remove listener, cancel animation, clear references
+     */
+    dispose(): void;
 }
 
+/**
+ * @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.
+ */
+
 interface AutoSetupOptions {
-    /** 相机在包围球基础上的额外填充倍数（>1 扩大可视范围） */
+    /** Extra padding multiplier based on bounding sphere (>1 expands view range) */
     padding?: number;
-    /** 相机仰角偏移（弧度），默认小俯视（0.2 rad ≈ 11°） */
+    /** Camera elevation offset (radians), default slight top-down (0.2 rad ≈ 11°) */
     elevation?: number;
-    /** 是否启用阴影（shadow） - 性能开销大，默认 false */
+    /** Whether to enable shadows - high performance cost, default false */
     enableShadows?: boolean;
-    /** 阴影贴图尺寸，越高越清晰越耗性能，默认 1024 */
+    /** Shadow map size, higher is clearer but more expensive, default 1024 */
     shadowMapSize?: number;
-    /** DirectionalLights 的数量（均匀分布在四面） */
+    /** Number of DirectionalLights (evenly distributed around) */
     directionalCount?: number;
-    /** 是否自动把 mesh.castShadow / mesh.receiveShadow 设置为 true（默认 true） */
+    /** Whether to automatically set mesh.castShadow / mesh.receiveShadow to true (default true) */
     setMeshShadowProps?: boolean;
-    /** 如果传入 renderer，则工具会自动启用 renderer.shadowMap（如果 enableShadows 为 true） */
+    /** If renderer is passed, the tool will automatically enable renderer.shadowMap (if enableShadows is true) */
     renderer?: THREE.WebGLRenderer | null;
 }
 /**
- * 返回值句柄，包含 created lights group、computed center/radius、以及 dispose 方法
+ * Return handle, containing created lights group, computed center/radius, and dispose method
  */
 type AutoSetupHandle = {
     lightsGroup: THREE.Group;
@@ -823,19 +879,19 @@ type AutoSetupHandle = {
     updateLightIntensity: (factor: number) => void;
 };
 /**
- * 自动设置相机与基础灯光 - 优化版
+ * 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
  */
 declare function autoSetupCameraAndLight(camera: THREE.PerspectiveCamera, scene: THREE.Scene, model: THREE.Object3D, options?: AutoSetupOptions): AutoSetupHandle;