@chocozhang/three-model-render 1.0.3 → 1.0.4

package/dist/interaction/index.d.ts

@@ -2,7 +2,18 @@ import * as THREE from 'three';
 import { OutlinePass } from 'three/examples/jsm/postprocessing/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.
+ */
+
+/**
+ * Click Handler Options
  */
 interface ClickHandlerOptions {
     clickThreshold?: number;
@@ -17,21 +28,21 @@ interface ClickHandlerOptions {
     maxThickness?: number;
 }
 /**
- * 创建模型点击高亮工具（OutlinePass 版）- 优化版
+ * 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
  */
 declare function createModelClickHandler(camera: THREE.Camera, scene: THREE.Scene, renderer: THREE.WebGLRenderer, outlinePass: OutlinePass, onClick: (object: THREE.Object3D | null, info?: {
     name?: string;
@@ -39,17 +50,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 - 优化版
- * 箭头引导效果工具，支持高亮模型并淡化其他对象
+ * 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
  */
 declare class ArrowGuide {
     private renderer;
@@ -78,44 +100,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 - 优化版
- * 支持单模型或多模型液位动画、独立颜色控制
+ * LiquidFillerGroup - Optimized
+ * Supports single or multi-model liquid level animation with independent color control.
  *
- * ✨ 优化内容：
- * - 使用 renderer.domElement 替代 window 事件
- * - 使用 AbortController 管理事件生命周期
- * - 添加错误处理和边界检查
- * - 优化动画管理，避免内存泄漏
- * - 完善资源释放逻辑
+ * 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;
@@ -127,32 +160,32 @@ 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;
 }