@chocozhang/three-model-render 1.0.1

package/dist/core/index.mjs

@@ -0,0 +1,432 @@
+import * as THREE from 'three';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer';
+import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass';
+import { OutlinePass } from 'three/examples/jsm/postprocessing/OutlinePass';
+import { GammaCorrectionShader } from 'three/examples/jsm/shaders/GammaCorrectionShader';
+import { ShaderPass } from 'three/examples/jsm/postprocessing/ShaderPass';
+
+/**
+ * 给子模型添加头顶标签（支持 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 的管理接口
+ */
+function addChildModelLabels(camera, renderer, parentModel, modelLabelsMap, options) {
+    // 防御性检查：确保 parentModel 已加载
+    if (!parentModel || typeof parentModel.traverse !== 'function') {
+        console.error('parentModel 无效，请确保 FBX 模型已加载完成');
+        return {
+            pause: () => { },
+            resume: () => { },
+            dispose: () => { },
+            isRunning: () => false
+        };
+    }
+    // 配置项
+    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 中
+    const container = document.createElement('div');
+    container.style.position = 'absolute';
+    container.style.top = '0';
+    container.style.left = '0';
+    container.style.pointerEvents = 'none'; // 避免阻挡鼠标事件
+    container.style.zIndex = '1000';
+    document.body.appendChild(container);
+    const labels = [];
+    // 状态管理
+    let rafId = null;
+    let isPaused = false;
+    let lastUpdateTime = 0;
+    // 遍历所有子模型
+    parentModel.traverse((child) => {
+        var _a;
+        // 只处理 Mesh 或 Group
+        if ((child.isMesh || child.type === 'Group')) {
+            // 动态匹配 name，防止 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 标签
+            const el = document.createElement('div');
+            el.innerText = labelText;
+            // 样式直接在 JS 中定义，可通过 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.whiteSpace = 'nowrap';
+            el.style.pointerEvents = 'none';
+            el.style.transition = 'opacity 0.2s ease';
+            // 加入容器
+            container.appendChild(el);
+            // 初始化缓存
+            const cachedBox = new THREE.Box3().setFromObject(child);
+            const center = new THREE.Vector3();
+            cachedBox.getCenter(center);
+            const cachedTopPos = new THREE.Vector3(center.x, cachedBox.max.y, center.z);
+            labels.push({
+                object: child,
+                el,
+                cachedBox,
+                cachedTopPos,
+                needsUpdate: true
+            });
+        }
+    });
+    /**
+     * 更新缓存的包围盒（仅在模型变换时调用）
+     */
+    const updateCache = (labelData) => {
+        labelData.cachedBox.setFromObject(labelData.object);
+        const center = new THREE.Vector3();
+        labelData.cachedBox.getCenter(center);
+        labelData.cachedTopPos.set(center.x, labelData.cachedBox.max.y, center.z);
+        labelData.needsUpdate = false;
+    };
+    /**
+     * 获取对象顶部世界坐标（使用缓存）
+     */
+    const getObjectTopPosition = (labelData) => {
+        if (enableCache) {
+            // 检查对象是否发生变换
+            if (labelData.needsUpdate || labelData.object.matrixWorldNeedsUpdate) {
+                updateCache(labelData);
+            }
+            return labelData.cachedTopPos;
+        }
+        else {
+            // 不使用缓存，每次都重新计算
+            const box = new THREE.Box3().setFromObject(labelData.object);
+            const center = new THREE.Vector3();
+            box.getCenter(center);
+            return new THREE.Vector3(center.x, box.max.y, center.z);
+        }
+    };
+    /**
+     * 更新标签位置函数
+     */
+    function updateLabels(timestamp = 0) {
+        // 检查是否暂停
+        if (isPaused) {
+            rafId = null;
+            return;
+        }
+        // 检查更新间隔
+        if (updateInterval > 0 && timestamp - lastUpdateTime < updateInterval) {
+            rafId = requestAnimationFrame(updateLabels);
+            return;
+        }
+        lastUpdateTime = timestamp;
+        const width = renderer.domElement.clientWidth;
+        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 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)`; // 屏幕位置
+        });
+        rafId = requestAnimationFrame(updateLabels); // 循环更新
+    }
+    // 启动更新
+    updateLabels();
+    /**
+     * 暂停更新
+     */
+    const pause = () => {
+        isPaused = true;
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+    };
+    /**
+     * 恢复更新
+     */
+    const resume = () => {
+        if (!isPaused)
+            return;
+        isPaused = false;
+        updateLabels();
+    };
+    /**
+     * 检查是否正在运行
+     */
+    const isRunning = () => !isPaused;
+    /**
+     * 清理函数：卸载所有 DOM 标签，取消动画，避免内存泄漏
+     */
+    const dispose = () => {
+        pause();
+        labels.forEach(({ el }) => {
+            if (container.contains(el)) {
+                container.removeChild(el);
+            }
+        });
+        if (document.body.contains(container)) {
+            document.body.removeChild(container);
+        }
+        labels.length = 0;
+    };
+    return {
+        pause,
+        resume,
+        dispose,
+        isRunning
+    };
+}
+
+// src/utils/hoverBreathEffectByNameSingleton.ts
+/**
+ * 创建单例高亮器 —— 推荐在 mounted 时创建一次
+ * 返回 { updateHighlightNames, dispose, getHoveredName } 接口
+ *
+ * ✨ 性能优化：
+ * - 无 hover 对象时自动暂停动画
+ * - mousemove 节流处理，避免过度计算
+ * - 使用 passive 事件监听器提升滚动性能
+ */
+function enableHoverBreath(opts) {
+    const { camera, scene, renderer, outlinePass, highlightNames = null, minStrength = 2, maxStrength = 5, speed = 4, throttleDelay = 16, // 默认约 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
+    let highlightSet = highlightNames === null ? null : new Set(highlightNames);
+    // 节流相关
+    let lastMoveTime = 0;
+    let rafPending = false;
+    function setHighlightNames(names) {
+        highlightSet = names === null ? null : new Set(names);
+        // 如果当前 hovered 不在新名单中，及时清理 selection
+        if (hovered && highlightSet && !highlightSet.has(hovered.name)) {
+            hovered = null;
+            outlinePass.selectedObjects = [];
+            // 暂停动画
+            if (animationId !== null) {
+                cancelAnimationFrame(animationId);
+                animationId = null;
+            }
+        }
+    }
+    /**
+     * 节流版本的 mousemove 处理
+     */
+    function onMouseMove(ev) {
+        const now = performance.now();
+        // 节流：如果距上次处理时间小于阈值，跳过
+        if (now - lastMoveTime < throttleDelay) {
+            // 使用 RAF 延迟处理，避免丢失最后一次事件
+            if (!rafPending) {
+                rafPending = true;
+                requestAnimationFrame(() => {
+                    rafPending = false;
+                    processMouseMove(ev);
+                });
+            }
+            return;
+        }
+        lastMoveTime = now;
+        processMouseMove(ev);
+    }
+    /**
+     * 实际的 mousemove 逻辑
+     */
+    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）
+        const intersects = raycaster.intersectObjects(scene.children, true);
+        if (intersects.length > 0) {
+            const obj = intersects[0].object;
+            // 判断是否允许被高亮
+            const allowed = highlightSet === null ? true : highlightSet.has(obj.name);
+            if (allowed) {
+                if (hovered !== obj) {
+                    hovered = obj;
+                    outlinePass.selectedObjects = [obj];
+                    // 启动动画（如果未运行）
+                    if (animationId === null) {
+                        animate();
+                    }
+                }
+            }
+            else {
+                if (hovered !== null) {
+                    hovered = null;
+                    outlinePass.selectedObjects = [];
+                    // 停止动画
+                    if (animationId !== null) {
+                        cancelAnimationFrame(animationId);
+                        animationId = null;
+                    }
+                }
+            }
+        }
+        else {
+            if (hovered !== null) {
+                hovered = null;
+                outlinePass.selectedObjects = [];
+                // 停止动画
+                if (animationId !== null) {
+                    cancelAnimationFrame(animationId);
+                    animationId = null;
+                }
+            }
+        }
+    }
+    /**
+     * 动画循环 - 只在有 hovered 对象时运行
+     */
+    function animate() {
+        // 如果没有 hovered 对象，停止动画
+        if (!hovered) {
+            animationId = null;
+            return;
+        }
+        animationId = requestAnimationFrame(animate);
+        time += speed * 0.02;
+        const strength = minStrength + ((Math.sin(time) + 1) / 2) * (maxStrength - minStrength);
+        outlinePass.edgeStrength = strength;
+    }
+    // 启动（只调用一次）
+    // 使用 passive 提升滚动性能
+    renderer.domElement.addEventListener('mousemove', onMouseMove, { passive: true });
+    // 注意：不在这里启动 animate，等有 hover 对象时再启动
+    // refresh: 如果你在某些情况下需要强制清理 selectedObjects
+    function refreshSelection() {
+        if (hovered && highlightSet && !highlightSet.has(hovered.name)) {
+            hovered = null;
+            outlinePass.selectedObjects = [];
+            if (animationId !== null) {
+                cancelAnimationFrame(animationId);
+                animationId = null;
+            }
+        }
+    }
+    function getHoveredName() {
+        return hovered ? hovered.name : null;
+    }
+    function dispose() {
+        renderer.domElement.removeEventListener('mousemove', onMouseMove);
+        if (animationId) {
+            cancelAnimationFrame(animationId);
+            animationId = null;
+        }
+        outlinePass.selectedObjects = [];
+        // 清空引用
+        hovered = null;
+        highlightSet = null;
+    }
+    return {
+        updateHighlightNames: setHighlightNames,
+        dispose,
+        refreshSelection,
+        getHoveredName,
+    };
+}
+
+/**
+ * 初始化描边相关信息（包含 OutlinePass）- 优化版
+ *
+ * ✨ 功能增强：
+ * - 支持窗口 resize 自动更新
+ * - 可配置分辨率缩放提升性能
+ * - 完善的资源释放管理
+ *
+ * @param renderer THREE.WebGLRenderer
+ * @param scene THREE.Scene
+ * @param camera THREE.Camera
+ * @param options PostProcessingOptions - 可选配置
+ * @returns PostProcessingManager - 包含 composer/outlinePass/resize/dispose 的管理接口
+ */
+function initPostProcessing(renderer, scene, camera, options = {}) {
+    // 默认配置
+    const { edgeStrength = 4, edgeGlow = 1, edgeThickness = 2, visibleEdgeColor = '#ffee00', hiddenEdgeColor = '#000000', resolutionScale = 1.0 } = options;
+    // 获取渲染器实际尺寸
+    const getSize = () => {
+        const width = renderer.domElement.clientWidth;
+        const height = renderer.domElement.clientHeight;
+        return {
+            width: Math.floor(width * resolutionScale),
+            height: Math.floor(height * resolutionScale)
+        };
+    };
+    const size = getSize();
+    // 创建 EffectComposer
+    const composer = new EffectComposer(renderer);
+    // 基础 RenderPass
+    const renderPass = new RenderPass(scene, camera);
+    composer.addPass(renderPass);
+    // OutlinePass 用于模型描边
+    const outlinePass = new OutlinePass(new THREE.Vector2(size.width, size.height), scene, camera);
+    outlinePass.edgeStrength = edgeStrength;
+    outlinePass.edgeGlow = edgeGlow;
+    outlinePass.edgeThickness = edgeThickness;
+    outlinePass.visibleEdgeColor.set(visibleEdgeColor);
+    outlinePass.hiddenEdgeColor.set(hiddenEdgeColor);
+    composer.addPass(outlinePass);
+    // Gamma 校正
+    const gammaPass = new ShaderPass(GammaCorrectionShader);
+    composer.addPass(gammaPass);
+    /**
+     * resize 处理函数
+     * @param width 可选宽度，不传则使用 renderer.domElement 的实际宽度
+     * @param height 可选高度，不传则使用 renderer.domElement 的实际高度
+     */
+    const resize = (width, height) => {
+        const actualSize = width !== undefined && height !== undefined
+            ? { width: Math.floor(width * resolutionScale), height: Math.floor(height * resolutionScale) }
+            : getSize();
+        // 更新 composer 尺寸
+        composer.setSize(actualSize.width, actualSize.height);
+        // 更新 outlinePass 分辨率
+        outlinePass.resolution.set(actualSize.width, actualSize.height);
+    };
+    /**
+     * 释放资源
+     */
+    const dispose = () => {
+        // 释放所有 passes
+        composer.passes.forEach(pass => {
+            if (pass.dispose) {
+                pass.dispose();
+            }
+        });
+        // 清空 passes 数组
+        composer.passes.length = 0;
+    };
+    return {
+        composer,
+        outlinePass,
+        resize,
+        dispose
+    };
+}
+
+export { addChildModelLabels, enableHoverBreath, initPostProcessing };
+//# sourceMappingURL=index.mjs.map

package/dist/core/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":["../../src/core/labelManager.ts","../../src/core/hoverEffect.ts","../../src/core/postProcessing.ts"],"sourcesContent":[null,null,null],"names":[],"mappings":"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"}

package/dist/effect/index.d.ts

@@ -0,0 +1,214 @@
+import * as THREE from 'three';
+
+/**
+ * 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）
+ *
+ * ----------------------------------------------------------------------
+ * 🔥 爆炸参数 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);
+ * };
+ *
+ */
+
+type ArrangeMode = 'ring' | 'spiral' | 'grid' | 'radial';
+type ExplodeOptions = {
+    mode?: ArrangeMode;
+    spacing?: number;
+    duration?: number;
+    lift?: number;
+    cameraPadding?: number;
+    autoRestorePrev?: boolean;
+    dimOthers?: {
+        enabled: boolean;
+        opacity?: number;
+    };
+    debug?: boolean;
+};
+declare class GroupExploder {
+    private scene;
+    private camera;
+    private controls?;
+    private currentSet;
+    private stateMap;
+    private prevSet;
+    private prevStateMap;
+    private materialContexts;
+    private materialSnaps;
+    private contextMaterials;
+    private animId;
+    private cameraAnimId;
+    private isExploded;
+    private isInitialized;
+    onLog?: (s: string) => void;
+    constructor(scene: THREE.Scene, camera: THREE.PerspectiveCamera | THREE.Camera, controls?: {
+        target?: THREE.Vector3;
+        update?: () => void;
+    });
+    private log;
+    init(): void;
+    /**
+     * setMeshes(newSet):
+     * - 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*.
+     */
+    setMeshes(newSet: Set<THREE.Mesh> | null, options?: {
+        autoRestorePrev?: boolean;
+        restoreDuration?: number;
+    }): Promise<void>;
+    /**
+     * ensureSnapshotsForSet: for each mesh in set, ensure stateMap has an entry.
+     * If missing, record current matrixWorld as originalMatrixWorld (best-effort).
+     */
+    private ensureSnapshotsForSet;
+    /**
+     * explode: compute targets first, compute targetBound using targets + mesh radii,
+     * animate camera to that targetBound, then animate meshes to targets.
+     */
+    explode(opts?: ExplodeOptions): Promise<void>;
+    restore(duration?: number): Promise<void>;
+    /**
+     * restoreSet: reparent and restore transforms using provided stateMap.
+     * If missing stateMap entry for a mesh, use fallbacks:
+     *  1) mesh.userData.__originalMatrixWorld (if present)
+     *  2) mesh.matrixWorld (current) -> smooth lerp to itself (no-op visually)
+     */
+    private restoreSet;
+    private applyDimToOthers;
+    private cleanContextsForMeshes;
+    private computeBoundingSphereForMeshes;
+    private computeBoundingSphereForPositionsAndMeshes;
+    private computeTargetsByMode;
+    private animateCameraToFit;
+    private getCameraLookAtPoint;
+    private cancelAnimations;
+    dispose(restoreBefore?: boolean): Promise<void>;
+}
+
+export { GroupExploder };
+export type { ExplodeOptions };