@chocozhang/three-model-render 1.0.2 → 1.0.4

package/dist/effect/index.d.ts

@@ -1,141 +1,36 @@
 import * as THREE from 'three';
 
 /**
- * GroupExploder - 基于 Three.js 的模型爆炸效果工具（支持 Vue3 + TS）
+ * @file exploder.ts
+ * @description
+ * GroupExploder - Three.js based model explosion effect tool (Vue3 + TS Support)
  * ----------------------------------------------------------------------
- * 该工具用于对指定 Mesh 的集合进行“爆炸 / 还原”动画：
- *  - 仅初始化一次（onMounted）
- *  - 支持动态切换模型并自动还原上一个模型的爆炸状态
- *  - 支持多种排列模式（ring / spiral / grid / radial）
- *  - 支持非爆炸对象自动透明化（dimOthers）
- *  - 支持摄像机自动前置定位到最佳观察点
- *  - 所有动画均采用原生 requestAnimationFrame 实现
- *
- * ----------------------------------------------------------------------
- * 🔧 构造参数
- * ----------------------------------------------------------------------
- * @param scene      Three.js 场景实例
- * @param camera     Three.js 相机（一般为 PerspectiveCamera）
- * @param controls   OrbitControls 控件实例（必须绑定 camera）
- *
- * ----------------------------------------------------------------------
- * 🔥 爆炸参数 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;
@@ -165,6 +60,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;
@@ -172,10 +73,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;
@@ -191,6 +94,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.
@@ -205,9 +113,14 @@ 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;
 }
 
 export { GroupExploder };

package/dist/effect/index.js

@@ -53,10 +53,34 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * @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;
@@ -88,10 +112,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* () {
@@ -293,6 +319,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');
@@ -649,99 +680,112 @@ 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__namespace.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__namespace.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__namespace.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__namespace.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');
     }
 }