@chocozhang/three-model-render 1.0.1

package/dist/index.js

@@ -0,0 +1,3268 @@
+'use strict';
+
+var THREE = require('three');
+var EffectComposer = require('three/examples/jsm/postprocessing/EffectComposer');
+var RenderPass = require('three/examples/jsm/postprocessing/RenderPass');
+var OutlinePass = require('three/examples/jsm/postprocessing/OutlinePass');
+var GammaCorrectionShader = require('three/examples/jsm/shaders/GammaCorrectionShader');
+var ShaderPass = require('three/examples/jsm/postprocessing/ShaderPass');
+var BufferGeometryUtils = require('three/examples/jsm/utils/BufferGeometryUtils.js');
+var EXRLoader_js = require('three/examples/jsm/loaders/EXRLoader.js');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var THREE__namespace = /*#__PURE__*/_interopNamespaceDefault(THREE);
+var BufferGeometryUtils__namespace = /*#__PURE__*/_interopNamespaceDefault(BufferGeometryUtils);
+
+/**
+ * 给子模型添加头顶标签（支持 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__namespace.Box3().setFromObject(child);
+            const center = new THREE__namespace.Vector3();
+            cachedBox.getCenter(center);
+            const cachedTopPos = new THREE__namespace.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__namespace.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__namespace.Box3().setFromObject(labelData.object);
+            const center = new THREE__namespace.Vector3();
+            box.getCenter(center);
+            return new THREE__namespace.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__namespace.Raycaster();
+    const mouse = new THREE__namespace.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.EffectComposer(renderer);
+    // 基础 RenderPass
+    const renderPass = new RenderPass.RenderPass(scene, camera);
+    composer.addPass(renderPass);
+    // OutlinePass 用于模型描边
+    const outlinePass = new OutlinePass.OutlinePass(new THREE__namespace.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.ShaderPass(GammaCorrectionShader.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
+    };
+}
+
+/**
+ * 创建模型点击高亮工具（OutlinePass 版）- 优化版
+ *
+ * ✨ 功能增强：
+ * - 使用 AbortController 统一管理事件生命周期
+ * - 支持防抖处理避免频繁触发
+ * - 可自定义 Raycaster 参数
+ * - 根据相机距离动态调整描边厚度
+ *
+ * @param camera 相机
+ * @param scene 场景
+ * @param renderer 渲染器
+ * @param outlinePass 已初始化的 OutlinePass
+ * @param onClick 点击回调
+ * @param options 可选配置
+ * @returns dispose 函数，用于清理事件和资源
+ */
+function createModelClickHandler(camera, scene, renderer, outlinePass, onClick, options = {}) {
+    // 配置项
+    const { clickThreshold = 3, debounceDelay = 0, raycasterParams = {}, enableDynamicThickness = true, minThickness = 1, maxThickness = 10 } = options;
+    const raycaster = new THREE__namespace.Raycaster();
+    const mouse = new THREE__namespace.Vector2();
+    // 应用 raycaster 自定义参数
+    if (raycasterParams.near !== undefined)
+        raycaster.near = raycasterParams.near;
+    if (raycasterParams.far !== undefined)
+        raycaster.far = raycasterParams.far;
+    if (raycasterParams.pointsPrecision !== undefined) {
+        if (!raycaster.params.Points) {
+            raycaster.params.Points = { threshold: raycasterParams.pointsPrecision };
+        }
+        else {
+            raycaster.params.Points.threshold = raycasterParams.pointsPrecision;
+        }
+    }
+    let startX = 0;
+    let startY = 0;
+    let selectedObject = null;
+    let debounceTimer = null;
+    // 使用 AbortController 统一管理事件
+    const abortController = new AbortController();
+    const signal = abortController.signal;
+    /** 恢复对象高亮（清空 OutlinePass.selectedObjects） */
+    function restoreObject() {
+        outlinePass.selectedObjects = [];
+    }
+    /** 鼠标按下记录位置 */
+    function handleMouseDown(event) {
+        startX = event.clientX;
+        startY = event.clientY;
+    }
+    /** 鼠标抬起判定点击或拖动（带防抖） */
+    function handleMouseUp(event) {
+        const dx = Math.abs(event.clientX - startX);
+        const dy = Math.abs(event.clientY - startY);
+        if (dx > clickThreshold || dy > clickThreshold)
+            return; // 拖动不触发点击
+        // 防抖处理
+        if (debounceDelay > 0) {
+            if (debounceTimer !== null) {
+                clearTimeout(debounceTimer);
+            }
+            debounceTimer = window.setTimeout(() => {
+                processClick(event);
+                debounceTimer = null;
+            }, debounceDelay);
+        }
+        else {
+            processClick(event);
+        }
+    }
+    /** 实际的点击处理逻辑 */
+    function processClick(event) {
+        const rect = renderer.domElement.getBoundingClientRect();
+        mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+        mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+        raycaster.setFromCamera(mouse, camera);
+        const intersects = raycaster.intersectObjects(scene.children, true);
+        if (intersects.length > 0) {
+            let object = intersects[0].object;
+            // 点击不同模型，先清除之前高亮
+            if (selectedObject && selectedObject !== object)
+                restoreObject();
+            selectedObject = object;
+            // highlightObject(selectedObject); // 可选：是否自动高亮
+            onClick(selectedObject, {
+                name: selectedObject.name || '未命名模型',
+                position: selectedObject.getWorldPosition(new THREE__namespace.Vector3()),
+                uuid: selectedObject.uuid
+            });
+        }
+        else {
+            // 点击空白 → 清除高亮
+            if (selectedObject)
+                restoreObject();
+            selectedObject = null;
+            onClick(null);
+        }
+    }
+    // 使用 AbortController 的 signal 注册事件
+    renderer.domElement.addEventListener('mousedown', handleMouseDown, { signal });
+    renderer.domElement.addEventListener('mouseup', handleMouseUp, { signal });
+    /** 销毁函数：解绑事件并清除高亮 */
+    return () => {
+        // 清理防抖定时器
+        if (debounceTimer !== null) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+        // 一次性解绑所有事件
+        abortController.abort();
+        // 清除高亮
+        restoreObject();
+        // 清空引用
+        selectedObject = null;
+    };
+}
+
+// src/utils/ArrowGuide.ts
+/**
+ * ArrowGuide - 优化版
+ * 箭头引导效果工具，支持高亮模型并淡化其他对象
+ *
+ * ✨ 优化内容：
+ * - 使用 WeakMap 自动回收材质，避免内存泄漏
+ * - 使用 AbortController 管理事件生命周期
+ * - 添加材质复用机制，减少重复创建
+ * - 改进 dispose 逻辑，确保完全释放资源
+ * - 添加错误处理和边界检查
+ */
+class ArrowGuide {
+    constructor(renderer, camera, scene, options) {
+        var _a, _b, _c;
+        this.renderer = renderer;
+        this.camera = camera;
+        this.scene = scene;
+        this.lxMesh = null;
+        this.flowActive = false;
+        this.modelBrightArr = [];
+        this.pointerDownPos = new THREE__namespace.Vector2();
+        this.clickThreshold = 10;
+        this.raycaster = new THREE__namespace.Raycaster();
+        this.mouse = new THREE__namespace.Vector2();
+        // ✨ 使用 WeakMap 自动回收材质（GC 友好）
+        this.originalMaterials = new WeakMap();
+        this.fadedMaterials = new WeakMap();
+        // ✨ AbortController 用于事件管理
+        this.abortController = null;
+        // 配置：非高亮透明度和亮度
+        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;
+        this.ignoreRaycastNames = new Set((options === null || options === void 0 ? void 0 : options.ignoreRaycastNames) || []);
+        this.fadeOpacity = (_b = options === null || options === void 0 ? void 0 : options.fadeOpacity) !== null && _b !== void 0 ? _b : 0.5;
+        this.fadeBrightness = (_c = options === null || options === void 0 ? void 0 : options.fadeBrightness) !== null && _c !== void 0 ? _c : 0.1;
+        this.abortController = new AbortController();
+        this.initEvents();
+    }
+    // —— 工具：缓存原材质（仅首次）
+    cacheOriginalMaterial(mesh) {
+        if (!this.originalMaterials.has(mesh)) {
+            this.originalMaterials.set(mesh, mesh.material);
+        }
+    }
+    // —— 工具：为某个材质克隆一个"半透明版本"，保留所有贴图与参数
+    makeFadedClone(mat) {
+        const clone = mat.clone();
+        const c = clone;
+        // 只改透明相关参数，不改 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); // 颜色整体变暗
+        }
+        // 为了让箭头在透明建筑后也能顺畅显示，常用策略：不写深度，仅测试深度
+        clone.depthWrite = false;
+        clone.depthTest = true;
+        clone.needsUpdate = true;
+        return clone;
+    }
+    // —— 工具：为 mesh.material（可能是数组）批量克隆"半透明版本"
+    createFadedMaterialFrom(mesh) {
+        const orig = mesh.material;
+        if (Array.isArray(orig)) {
+            return orig.map(m => this.makeFadedClone(m));
+        }
+        return this.makeFadedClone(orig);
+    }
+    /**
+     * 设置箭头 Mesh
+     */
+    setArrowMesh(mesh) {
+        this.lxMesh = mesh;
+        this.cacheOriginalMaterial(mesh);
+        try {
+            const mat = mesh.material;
+            if (mat && mat.map) {
+                const map = mat.map;
+                map.wrapS = THREE__namespace.RepeatWrapping;
+                map.wrapT = THREE__namespace.RepeatWrapping;
+                map.needsUpdate = true;
+            }
+            mesh.visible = false;
+        }
+        catch (error) {
+            console.error('ArrowGuide: 设置箭头材质失败', error);
+        }
+    }
+    /**
+     * 高亮指定模型
+     */
+    highlight(models) {
+        if (!models || models.length === 0) {
+            console.warn('ArrowGuide: 高亮模型列表为空');
+            return;
+        }
+        this.modelBrightArr = models;
+        this.flowActive = true;
+        if (this.lxMesh)
+            this.lxMesh.visible = true;
+        this.applyHighlight();
+    }
+    // ✅ 应用高亮效果：非高亮模型保留细节 → 使用"克隆后的半透明材质"
+    applyHighlight() {
+        // ✨ 使用 Set 提升查找性能
+        const keepMeshes = new Set();
+        this.modelBrightArr.forEach(obj => {
+            obj.traverse(child => {
+                if (child.isMesh)
+                    keepMeshes.add(child);
+            });
+        });
+        try {
+            this.scene.traverse(obj => {
+                if (obj.isMesh) {
+                    const mesh = obj;
+                    // 缓存原材质（用于恢复）
+                    this.cacheOriginalMaterial(mesh);
+                    if (!keepMeshes.has(mesh)) {
+                        // 非高亮：如果还没给它生成过"半透明克隆材质"，就创建一次
+                        if (!this.fadedMaterials.has(mesh)) {
+                            const faded = this.createFadedMaterialFrom(mesh);
+                            this.fadedMaterials.set(mesh, faded);
+                        }
+                        // 替换为克隆材质（保留所有贴图/法线等细节）
+                        const fadedMat = this.fadedMaterials.get(mesh);
+                        if (fadedMat)
+                            mesh.material = fadedMat;
+                    }
+                    else {
+                        // 高亮对象：确保回到原材质（避免上一次高亮后遗留）
+                        const orig = this.originalMaterials.get(mesh);
+                        if (orig && mesh.material !== orig) {
+                            mesh.material = orig;
+                            mesh.material.needsUpdate = true;
+                        }
+                    }
+                }
+            });
+        }
+        catch (error) {
+            console.error('ArrowGuide: 应用高亮失败', error);
+        }
+    }
+    // ✅ 恢复为原材质 & 释放克隆材质
+    restore() {
+        this.flowActive = false;
+        if (this.lxMesh)
+            this.lxMesh.visible = false;
+        try {
+            // ✨ 收集所有需要释放的材质
+            const materialsToDispose = [];
+            this.scene.traverse(obj => {
+                if (obj.isMesh) {
+                    const mesh = obj;
+                    const orig = this.originalMaterials.get(mesh);
+                    if (orig) {
+                        mesh.material = orig;
+                        mesh.material.needsUpdate = true;
+                    }
+                    // ✨ 收集待释放的淡化材质
+                    const faded = this.fadedMaterials.get(mesh);
+                    if (faded) {
+                        if (Array.isArray(faded)) {
+                            materialsToDispose.push(...faded);
+                        }
+                        else {
+                            materialsToDispose.push(faded);
+                        }
+                    }
+                }
+            });
+            // ✨ 批量释放材质（不触碰贴图资源）
+            materialsToDispose.forEach(mat => {
+                try {
+                    mat.dispose();
+                }
+                catch (error) {
+                    console.error('ArrowGuide: 释放材质失败', error);
+                }
+            });
+            // ✨ 创建新的 WeakMap（相当于清空）
+            this.fadedMaterials = new WeakMap();
+        }
+        catch (error) {
+            console.error('ArrowGuide: 恢复材质失败', error);
+        }
+    }
+    /**
+     * 动画更新（每帧调用）
+     */
+    animate() {
+        if (!this.flowActive || !this.lxMesh)
+            return;
+        try {
+            const mat = this.lxMesh.material;
+            if (mat && mat.map) {
+                const map = mat.map;
+                map.offset.y -= 0.01;
+                map.needsUpdate = true;
+            }
+        }
+        catch (error) {
+            console.error('ArrowGuide: 动画更新失败', error);
+        }
+    }
+    /**
+     * 初始化事件监听器
+     */
+    initEvents() {
+        const dom = this.renderer.domElement;
+        const signal = this.abortController.signal;
+        // ✨ 使用 AbortController signal 自动管理事件生命周期
+        dom.addEventListener('pointerdown', (e) => {
+            this.pointerDownPos.set(e.clientX, e.clientY);
+        }, { signal });
+        dom.addEventListener('pointerup', (e) => {
+            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; // 拖拽
+            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;
+            this.raycaster.setFromCamera(this.mouse, this.camera);
+            const intersects = this.raycaster.intersectObjects(this.scene.children, true);
+            const filtered = intersects.filter(i => {
+                if (!i.object)
+                    return false;
+                if (this.ignoreRaycastNames.has(i.object.name))
+                    return false;
+                return true;
+            });
+            if (filtered.length === 0)
+                this.restore(); // 点击空白恢复
+        }, { signal });
+    }
+    /**
+     * 释放所有资源
+     */
+    dispose() {
+        // ✨ 先恢复材质
+        this.restore();
+        // ✨ 使用 AbortController 一次性解绑所有事件
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+        // ✨ 清空引用
+        this.modelBrightArr = [];
+        this.lxMesh = null;
+        this.fadedMaterials = new WeakMap();
+        this.originalMaterials = new WeakMap();
+        this.ignoreRaycastNames.clear();
+    }
+}
+
+// utils/LiquidFillerGroup.ts
+/**
+ * LiquidFillerGroup - 优化版
+ * 支持单模型或多模型液位动画、独立颜色控制
+ *
+ * ✨ 优化内容：
+ * - 使用 renderer.domElement 替代 window 事件
+ * - 使用 AbortController 管理事件生命周期
+ * - 添加错误处理和边界检查
+ * - 优化动画管理，避免内存泄漏
+ * - 完善资源释放逻辑
+ */
+class LiquidFillerGroup {
+    /**
+     * 构造函数
+     * @param models 单个或多个 THREE.Object3D
+     * @param scene 场景
+     * @param camera 相机
+     * @param renderer 渲染器
+     * @param defaultOptions 默认液体选项
+     * @param clickThreshold 点击阈值，单位像素
+     */
+    constructor(models, scene, camera, renderer, defaultOptions, clickThreshold = 10) {
+        this.items = [];
+        this.raycaster = new THREE__namespace.Raycaster();
+        this.pointerDownPos = new THREE__namespace.Vector2();
+        this.clickThreshold = 10;
+        this.abortController = null; // ✨ 事件管理器
+        /** pointerdown 记录位置 */
+        this.handlePointerDown = (event) => {
+            this.pointerDownPos.set(event.clientX, event.clientY);
+        };
+        /** pointerup 判断点击空白，恢复原始材质 */
+        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 的实际尺寸
+            const rect = this.renderer.domElement.getBoundingClientRect();
+            const pointerNDC = new THREE__namespace.Vector2(((event.clientX - rect.left) / rect.width) * 2 - 1, -((event.clientY - rect.top) / rect.height) * 2 + 1);
+            this.raycaster.setFromCamera(pointerNDC, this.camera);
+            // 点击空白 -> 所有模型恢复
+            const intersectsAny = this.items.some(item => this.raycaster.intersectObject(item.model, true).length > 0);
+            if (!intersectsAny) {
+                this.restoreAll();
+            }
+        };
+        this.scene = scene;
+        this.camera = camera;
+        this.renderer = renderer;
+        this.clickThreshold = clickThreshold;
+        // ✨ 创建 AbortController 用于事件管理
+        this.abortController = new AbortController();
+        const modelArray = Array.isArray(models) ? models : [models];
+        modelArray.forEach(model => {
+            var _a, _b, _c;
+            try {
+                const options = {
+                    color: (_a = defaultOptions === null || defaultOptions === void 0 ? void 0 : defaultOptions.color) !== null && _a !== void 0 ? _a : 0x00ff00,
+                    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,
+                };
+                // 保存原始材质
+                const originalMaterials = new Map();
+                model.traverse(obj => {
+                    if (obj.isMesh) {
+                        const mesh = obj;
+                        originalMaterials.set(mesh, mesh.material);
+                    }
+                });
+                // ✨ 边界检查：确保有材质可以保存
+                if (originalMaterials.size === 0) {
+                    console.warn('LiquidFillerGroup: 模型没有 Mesh 对象', model);
+                    return;
+                }
+                // 应用淡线框材质
+                model.traverse(obj => {
+                    if (obj.isMesh) {
+                        const mesh = obj;
+                        mesh.material = new THREE__namespace.MeshBasicMaterial({
+                            color: 0xffffff,
+                            wireframe: true,
+                            transparent: true,
+                            opacity: 0.2,
+                        });
+                    }
+                });
+                // 创建液体 Mesh
+                const geometries = [];
+                model.traverse(obj => {
+                    if (obj.isMesh) {
+                        const mesh = obj;
+                        const geom = mesh.geometry.clone();
+                        geom.applyMatrix4(mesh.matrixWorld);
+                        geometries.push(geom);
+                    }
+                });
+                if (geometries.length === 0) {
+                    console.warn('LiquidFillerGroup: 模型没有几何体', model);
+                    return;
+                }
+                const mergedGeometry = BufferGeometryUtils__namespace.mergeGeometries(geometries, false);
+                if (!mergedGeometry) {
+                    console.error('LiquidFillerGroup: 几何体合并失败', model);
+                    return;
+                }
+                const material = new THREE__namespace.MeshPhongMaterial({
+                    color: options.color,
+                    transparent: true,
+                    opacity: options.opacity,
+                    side: THREE__namespace.DoubleSide,
+                });
+                const liquidMesh = new THREE__namespace.Mesh(mergedGeometry, material);
+                this.scene.add(liquidMesh);
+                // 设置 clippingPlane
+                const clipPlane = new THREE__namespace.Plane(new THREE__namespace.Vector3(0, -1, 0), 0);
+                const mat = liquidMesh.material;
+                mat.clippingPlanes = [clipPlane];
+                this.renderer.localClippingEnabled = true;
+                this.items.push({
+                    model,
+                    liquidMesh,
+                    clipPlane,
+                    originalMaterials,
+                    options,
+                    animationId: null // ✨ 初始化动画 ID
+                });
+            }
+            catch (error) {
+                console.error('LiquidFillerGroup: 初始化模型失败', model, error);
+            }
+        });
+        // ✨ 使用 renderer.domElement 替代 window，使用 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
+   */
+    fillTo(models, percent) {
+        // ✨ 边界检查
+        if (percent < 0 || percent > 1) {
+            console.warn('LiquidFillerGroup: percent 必须在 0~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);
+                return;
+            }
+            if (!item.liquidMesh) {
+                console.warn('LiquidFillerGroup: liquidMesh 已被释放', model);
+                return;
+            }
+            // ✨ 取消之前的动画
+            if (item.animationId !== null) {
+                cancelAnimationFrame(item.animationId);
+                item.animationId = null;
+            }
+            try {
+                const box = new THREE__namespace.Box3().setFromObject(item.liquidMesh);
+                const min = box.min.y;
+                const max = box.max.y;
+                const targetHeight = min + (max - min) * percent;
+                const animate = () => {
+                    if (!item.liquidMesh) {
+                        item.animationId = null;
+                        return;
+                    }
+                    const diff = targetHeight - item.clipPlane.constant;
+                    if (Math.abs(diff) > 0.01) {
+                        item.clipPlane.constant += diff * item.options.speed;
+                        item.animationId = requestAnimationFrame(animate);
+                    }
+                    else {
+                        item.clipPlane.constant = targetHeight;
+                        item.animationId = null;
+                    }
+                };
+                animate();
+            }
+            catch (error) {
+                console.error('LiquidFillerGroup: fillTo 执行失败', model, error);
+            }
+        });
+    }
+    /** 设置多个模型液位，percentList 与 items 顺序对应 */
+    fillToAll(percentList) {
+        if (percentList.length !== this.items.length) {
+            console.warn(`LiquidFillerGroup: percentList 长度 (${percentList.length}) 与 items 长度 (${this.items.length}) 不匹配`);
+        }
+        percentList.forEach((p, idx) => {
+            if (idx < this.items.length) {
+                this.fillTo(this.items[idx].model, p);
+            }
+        });
+    }
+    /** 恢复单个模型原始材质并移除液体 */
+    restore(model) {
+        const item = this.items.find(i => i.model === model);
+        if (!item)
+            return;
+        // ✨ 取消动画
+        if (item.animationId !== null) {
+            cancelAnimationFrame(item.animationId);
+            item.animationId = null;
+        }
+        // 恢复原始材质
+        item.model.traverse(obj => {
+            if (obj.isMesh) {
+                const mesh = obj;
+                const original = item.originalMaterials.get(mesh);
+                if (original)
+                    mesh.material = original;
+            }
+        });
+        // 释放液体 Mesh
+        if (item.liquidMesh) {
+            this.scene.remove(item.liquidMesh);
+            item.liquidMesh.geometry.dispose();
+            if (Array.isArray(item.liquidMesh.material)) {
+                item.liquidMesh.material.forEach(m => m.dispose());
+            }
+            else {
+                item.liquidMesh.material.dispose();
+            }
+            item.liquidMesh = null;
+        }
+    }
+    /** 恢复所有模型 */
+    restoreAll() {
+        this.items.forEach(item => this.restore(item.model));
+    }
+    /** 销毁方法，释放事件和资源 */
+    dispose() {
+        // ✨ 先恢复所有模型
+        this.restoreAll();
+        // ✨ 使用 AbortController 一次性解绑所有事件
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+        // ✨ 清空 items
+        this.items.length = 0;
+    }
+}
+
+// src/utils/followModels.ts - 优化版
+// ✨ 使用 WeakMap 跟踪动画，支持取消
+const _animationMap = new WeakMap();
+/**
+ * 推荐角度枚举，便于快速选取常见视角
+ */
+const FOLLOW_ANGLES = {
+    /** 等距斜视（默认视角）- 适合建筑、机械设备展示 */
+    ISOMETRIC: { azimuth: Math.PI / 4, elevation: Math.PI / 4 },
+    /** 正前视角 - 适合正面展示、UI 对齐 */
+    FRONT: { azimuth: 0, elevation: 0 },
+    /** 右侧视角 - 适合机械剖面、侧视检查 */
+    RIGHT: { azimuth: Math.PI / 2, elevation: 0 },
+    /** 左侧视角 */
+    LEFT: { azimuth: -Math.PI / 2, elevation: 0 },
+    /** 后视角 */
+    BACK: { azimuth: Math.PI, elevation: 0 },
+    /** 顶视图 - 适合地图、平面布局展示 */
+    TOP: { azimuth: 0, elevation: Math.PI / 2 },
+    /** 低角度俯视 - 适合车辆、人物等近地物体 */
+    LOW_ANGLE: { azimuth: Math.PI / 4, elevation: Math.PI / 6 },
+    /** 高角度俯视 - 适合鸟瞰、全景浏览 */
+    HIGH_ANGLE: { azimuth: Math.PI / 4, elevation: Math.PI / 3 }
+};
+/**
+ * 缓动函数集合
+ */
+const EASING_FUNCTIONS = {
+    linear: (t) => t,
+    easeInOut: (t) => t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2,
+    easeOut: (t) => 1 - Math.pow(1 - t, 3),
+    easeIn: (t) => t * t * t
+};
+/**
+ * 自动将相机移到目标的斜上角位置，并保证目标在可视范围内（平滑过渡）- 优化版
+ *
+ * ✨ 优化内容：
+ * - 支持多种缓动函数
+ * - 添加进度回调
+ * - 支持取消动画
+ * - WeakMap 跟踪防止泄漏
+ * - 完善错误处理
+ */
+function followModels(camera, targets, options = {}) {
+    var _a, _b, _c, _d, _e, _f;
+    // ✨ 取消之前的动画
+    cancelFollow(camera);
+    // ✨ 边界检查
+    const arr = [];
+    if (!targets)
+        return Promise.resolve();
+    if (Array.isArray(targets))
+        arr.push(...targets.filter(Boolean));
+    else
+        arr.push(targets);
+    if (arr.length === 0) {
+        console.warn('followModels: 目标对象为空');
+        return Promise.resolve();
+    }
+    try {
+        const box = new THREE__namespace.Box3();
+        arr.forEach((o) => box.expandByObject(o));
+        // ✨ 检查包围盒有效性
+        if (!isFinite(box.min.x) || !isFinite(box.max.x)) {
+            console.warn('followModels: 包围盒计算失败');
+            return Promise.resolve();
+        }
+        const sphere = new THREE__namespace.Sphere();
+        box.getBoundingSphere(sphere);
+        const center = sphere.center.clone();
+        const radiusBase = Math.max(0.001, sphere.radius);
+        const duration = (_a = options.duration) !== null && _a !== void 0 ? _a : 700;
+        const padding = (_b = options.padding) !== null && _b !== void 0 ? _b : 1.0;
+        const minDistance = options.minDistance;
+        const maxDistance = options.maxDistance;
+        const controls = (_c = options.controls) !== null && _c !== void 0 ? _c : null;
+        const azimuth = (_d = options.azimuth) !== null && _d !== void 0 ? _d : Math.PI / 4;
+        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;
+        // ✨ 获取缓动函数
+        const easingFn = EASING_FUNCTIONS[easing] || EASING_FUNCTIONS.easeOut;
+        let distance = 10;
+        if (camera.isPerspectiveCamera) {
+            const cam = camera;
+            const halfV = THREE__namespace.MathUtils.degToRad(cam.fov * 0.5);
+            const halfH = Math.atan(Math.tan(halfV) * cam.aspect);
+            const halfMin = Math.min(halfV, halfH);
+            distance = (radiusBase * padding) / Math.sin(halfMin);
+            if (minDistance != null)
+                distance = Math.max(distance, minDistance);
+            if (maxDistance != null)
+                distance = Math.min(distance, maxDistance);
+        }
+        else if (camera.isOrthographicCamera) {
+            distance = camera.position.distanceTo(center);
+        }
+        else {
+            distance = camera.position.distanceTo(center);
+        }
+        // 根据 azimuth / elevation 计算方向
+        const hx = Math.sin(azimuth);
+        const hz = Math.cos(azimuth);
+        const dir = new THREE__namespace.Vector3(hx * Math.cos(elevation), Math.sin(elevation), hz * Math.cos(elevation)).normalize();
+        const desiredPos = center.clone().add(dir.multiplyScalar(distance));
+        const startPos = camera.position.clone();
+        const startTarget = controls && controls.target
+            ? controls.target.clone()
+            : camera.position.clone().add(camera.getWorldDirection(new THREE__namespace.Vector3()).multiplyScalar(1));
+        const endTarget = center.clone();
+        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);
+                camera.position.lerpVectors(startPos, desiredPos, k);
+                if (controls && controls.target) {
+                    const newTarget = new THREE__namespace.Vector3().lerpVectors(startTarget, endTarget, k);
+                    controls.target.copy(newTarget);
+                    if (typeof controls.update === 'function')
+                        controls.update();
+                }
+                else {
+                    camera.lookAt(endTarget);
+                }
+                (_a = camera.updateProjectionMatrix) === null || _a === void 0 ? void 0 : _a.call(camera);
+                // ✨ 调用进度回调
+                if (onProgress) {
+                    try {
+                        onProgress(t);
+                    }
+                    catch (error) {
+                        console.error('followModels: 进度回调错误', error);
+                    }
+                }
+                if (t < 1) {
+                    const rafId = requestAnimationFrame(step);
+                    _animationMap.set(camera, rafId);
+                }
+                else {
+                    _animationMap.delete(camera);
+                    camera.position.copy(desiredPos);
+                    if (controls && controls.target) {
+                        controls.target.copy(endTarget);
+                        if (typeof controls.update === 'function')
+                            controls.update();
+                    }
+                    else {
+                        camera.lookAt(endTarget);
+                    }
+                    resolve();
+                }
+            };
+            const rafId = requestAnimationFrame(step);
+            _animationMap.set(camera, rafId);
+        });
+    }
+    catch (error) {
+        console.error('followModels: 执行失败', error);
+        return Promise.reject(error);
+    }
+}
+/**
+ * ✨ 取消相机的跟随动画
+ */
+function cancelFollow(camera) {
+    const rafId = _animationMap.get(camera);
+    if (rafId !== undefined) {
+        cancelAnimationFrame(rafId);
+        _animationMap.delete(camera);
+    }
+}
+
+// src/utils/setView.ts - 优化版
+/**
+ * 平滑切换相机到模型的最佳视角 - 优化版
+ *
+ * ✨ 优化内容：
+ * - 复用 followModels 逻辑，避免代码重复
+ * - 支持更多视角
+ * - 配置选项增强
+ * - 返回 Promise 支持链式调用
+ * - 支持取消动画
+ *
+ * @param camera       THREE.PerspectiveCamera 相机实例
+ * @param controls     OrbitControls 控制器实例
+ * @param targetObj    THREE.Object3D 模型对象
+ * @param position     视角位置
+ * @param options      配置选项
+ * @returns Promise<void>
+ */
+function setView(camera, controls, targetObj, position = 'front', options = {}) {
+    const { distanceFactor = 0.8, duration = 1000, easing = 'easeInOut', onProgress } = options;
+    // ✨ 边界检查
+    if (!targetObj) {
+        console.warn('setView: 目标对象为空');
+        return Promise.reject(new Error('Target object is required'));
+    }
+    try {
+        // 计算包围盒
+        const box = new THREE__namespace.Box3().setFromObject(targetObj);
+        if (!isFinite(box.min.x)) {
+            console.warn('setView: 包围盒计算失败');
+            return Promise.reject(new Error('Invalid bounding box'));
+        }
+        const center = box.getCenter(new THREE__namespace.Vector3());
+        const size = box.getSize(new THREE__namespace.Vector3());
+        const maxSize = Math.max(size.x, size.y, size.z);
+        // ✨ 使用映射表简化视角计算
+        const viewAngles = {
+            'front': { azimuth: 0, elevation: 0 },
+            'back': { azimuth: Math.PI, elevation: 0 },
+            'left': { azimuth: -Math.PI / 2, elevation: 0 },
+            'right': { azimuth: Math.PI / 2, elevation: 0 },
+            'top': { azimuth: 0, elevation: Math.PI / 2 },
+            'bottom': { azimuth: 0, elevation: -Math.PI / 2 },
+            'iso': { azimuth: Math.PI / 4, elevation: Math.PI / 4 }
+        };
+        const angle = viewAngles[position] || viewAngles.front;
+        // ✨ 复用 followModels，避免代码重复
+        return followModels(camera, targetObj, {
+            duration,
+            padding: distanceFactor,
+            controls,
+            azimuth: angle.azimuth,
+            elevation: angle.elevation,
+            easing,
+            onProgress
+        });
+    }
+    catch (error) {
+        console.error('setView: 执行失败', error);
+        return Promise.reject(error);
+    }
+}
+/**
+ * ✨ 取消视角切换动画
+ */
+function cancelSetView(camera) {
+    cancelFollow(camera);
+}
+/**
+ * ✨ 预设视角快捷方法
+ */
+const ViewPresets = {
+    /**
+     * 前视图
+     */
+    front: (camera, controls, target, options) => setView(camera, controls, target, 'front', options),
+    /**
+     * 等距视图
+     */
+    isometric: (camera, controls, target, options) => setView(camera, controls, target, 'iso', options),
+    /**
+     * 顶视图
+     */
+    top: (camera, controls, target, options) => setView(camera, controls, target, 'top', options)
+};
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+const DEFAULT_OPTIONS$1 = {
+    useKTX2: false,
+    mergeGeometries: false,
+    maxTextureSize: null,
+    useSimpleMaterials: false,
+    skipSkinned: true,
+};
+/** 自动根据扩展名决定启用哪些选项（智能判断） */
+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，如果用户没填
+        if (merged.dracoDecoderPath === undefined)
+            merged.dracoDecoderPath = '/draco/';
+        if (merged.useKTX2 === undefined)
+            merged.useKTX2 = true;
+        if (merged.ktx2TranscoderPath === undefined)
+            merged.ktx2TranscoderPath = '/basis/';
+    }
+    else {
+        // fbx/obj/ply/stl 等不需要 draco/ktx2
+        merged.dracoDecoderPath = null;
+        merged.ktx2TranscoderPath = null;
+        merged.useKTX2 = false;
+    }
+    return merged;
+}
+function loadModelByUrl(url_1) {
+    return __awaiter(this, arguments, void 0, function* (url, options = {}) {
+        var _a, _b;
+        if (!url)
+            throw new Error('url required');
+        const ext = (url.split('.').pop() || '').toLowerCase();
+        const opts = normalizeOptions(url, options);
+        const manager = (_a = opts.manager) !== null && _a !== void 0 ? _a : new THREE__namespace.LoadingManager();
+        let loader;
+        if (ext === 'gltf' || ext === 'glb') {
+            const { GLTFLoader } = yield import('three/examples/jsm/loaders/GLTFLoader.js');
+            const gltfLoader = new GLTFLoader(manager);
+            if (opts.dracoDecoderPath) {
+                const { DRACOLoader } = yield import('three/examples/jsm/loaders/DRACOLoader.js');
+                const draco = new DRACOLoader();
+                draco.setDecoderPath(opts.dracoDecoderPath);
+                gltfLoader.setDRACOLoader(draco);
+            }
+            if (opts.useKTX2 && opts.ktx2TranscoderPath) {
+                const { KTX2Loader } = yield import('three/examples/jsm/loaders/KTX2Loader.js');
+                const ktx2Loader = new KTX2Loader().setTranscoderPath(opts.ktx2TranscoderPath);
+                gltfLoader.__ktx2Loader = ktx2Loader;
+            }
+            loader = gltfLoader;
+        }
+        else if (ext === 'fbx') {
+            const { FBXLoader } = yield import('three/examples/jsm/loaders/FBXLoader.js');
+            loader = new FBXLoader(manager);
+        }
+        else if (ext === 'obj') {
+            const { OBJLoader } = yield import('three/examples/jsm/loaders/OBJLoader.js');
+            loader = new OBJLoader(manager);
+        }
+        else if (ext === 'ply') {
+            const { PLYLoader } = yield import('three/examples/jsm/loaders/PLYLoader.js');
+            loader = new PLYLoader(manager);
+        }
+        else if (ext === 'stl') {
+            const { STLLoader } = yield import('three/examples/jsm/loaders/STLLoader.js');
+            loader = new STLLoader(manager);
+        }
+        else {
+            throw new Error(`Unsupported model extension: .${ext}`);
+        }
+        const object = yield new Promise((resolve, reject) => {
+            loader.load(url, (res) => {
+                var _a;
+                if (ext === 'gltf' || ext === 'glb') {
+                    const sceneObj = res.scene || res;
+                    // --- 关键：把 animations 暴露到 scene.userData（或 scene.animations）上 ---
+                    // 这样调用方只要拿到 sceneObj，就能通过 sceneObj.userData.animations 读取到 clips
+                    sceneObj.userData = (sceneObj === null || sceneObj === void 0 ? void 0 : sceneObj.userData) || {};
+                    sceneObj.userData.animations = (_a = res.animations) !== null && _a !== void 0 ? _a : [];
+                    resolve(sceneObj);
+                }
+                else {
+                    resolve(res);
+                }
+            }, undefined, (err) => reject(err));
+        });
+        // 优化
+        object.traverse((child) => {
+            var _a, _b, _c;
+            const mesh = child;
+            if (mesh.isMesh && mesh.geometry && !mesh.geometry.isBufferGeometry) {
+                try {
+                    mesh.geometry = (_c = (_b = (_a = new THREE__namespace.BufferGeometry()).fromGeometry) === null || _b === void 0 ? void 0 : _b.call(_a, mesh.geometry)) !== null && _c !== void 0 ? _c : mesh.geometry;
+                }
+                catch (_d) { }
+            }
+        });
+        if (opts.maxTextureSize && opts.maxTextureSize > 0)
+            downscaleTexturesInObject(object, opts.maxTextureSize);
+        if (opts.useSimpleMaterials) {
+            object.traverse((child) => {
+                const m = child.material;
+                if (!m)
+                    return;
+                if (Array.isArray(m))
+                    child.material = m.map((mat) => toSimpleMaterial(mat));
+                else
+                    child.material = toSimpleMaterial(m);
+            });
+        }
+        if (opts.mergeGeometries) {
+            try {
+                yield tryMergeGeometries(object, { skipSkinned: (_b = opts.skipSkinned) !== null && _b !== void 0 ? _b : true });
+            }
+            catch (e) {
+                console.warn('mergeGeometries failed', e);
+            }
+        }
+        return object;
+    });
+}
+/** 运行时下采样网格中的贴图到 maxSize（canvas drawImage）以节省 GPU 内存 */
+function downscaleTexturesInObject(obj, maxSize) {
+    obj.traverse((ch) => {
+        if (!ch.isMesh)
+            return;
+        const mesh = ch;
+        const mat = mesh.material;
+        if (!mat)
+            return;
+        const props = ['map', 'normalMap', 'roughnessMap', 'metalnessMap', 'aoMap', 'emissiveMap', 'alphaMap'];
+        props.forEach((p) => {
+            const tex = mat[p];
+            if (!tex || !tex.image)
+                return;
+            const image = tex.image;
+            if (!image.width || !image.height)
+                return;
+            const max = maxSize;
+            if (image.width <= max && image.height <= max)
+                return;
+            // downscale using canvas (sync, may be heavy for many textures)
+            try {
+                const scale = Math.min(max / image.width, max / image.height);
+                const canvas = document.createElement('canvas');
+                canvas.width = Math.floor(image.width * scale);
+                canvas.height = Math.floor(image.height * scale);
+                const ctx = canvas.getContext('2d');
+                if (ctx) {
+                    ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
+                    const newTex = new THREE__namespace.Texture(canvas);
+                    newTex.needsUpdate = true;
+                    // copy common settings (encoding etc)
+                    newTex.encoding = tex.encoding;
+                    mat[p] = newTex;
+                }
+            }
+            catch (e) {
+                console.warn('downscale texture failed', e);
+            }
+        });
+    });
+}
+/**
+ * 尝试合并 object 中的几何体（只合并：非透明、非 SkinnedMesh、attribute 集合兼容的 BufferGeometry）
+ * - 合并前会把每个 mesh 的几何体应用 world matrix（so merged geometry in world space）
+ * - 合并会按材质 UUID 分组（不同材质不能合并）
+ * - 合并函数会兼容 BufferGeometryUtils 的常见导出名
+ */
+function tryMergeGeometries(root, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // collect meshes by material uuid
+        const groups = new Map();
+        root.traverse((ch) => {
+            var _a;
+            if (!ch.isMesh)
+                return;
+            const mesh = ch;
+            if (opts.skipSkinned && mesh.isSkinnedMesh)
+                return;
+            const mat = mesh.material;
+            // don't merge transparent or morph-enabled or skinned meshes
+            if (!mesh.geometry || mesh.visible === false)
+                return;
+            if (mat && mat.transparent)
+                return;
+            const geom = mesh.geometry.clone();
+            mesh.updateWorldMatrix(true, false);
+            geom.applyMatrix4(mesh.matrixWorld);
+            // ensure attributes compatible? we'll rely on merge function to return null if incompatible
+            const key = (mat && mat.uuid) || 'default';
+            const bucket = (_a = groups.get(key)) !== null && _a !== void 0 ? _a : { material: mat !== null && mat !== void 0 ? mat : new THREE__namespace.MeshStandardMaterial(), geoms: [] };
+            bucket.geoms.push(geom);
+            groups.set(key, bucket);
+            // mark for removal (we'll remove meshes after)
+            mesh.userData.__toRemoveForMerge = true;
+        });
+        if (groups.size === 0)
+            return;
+        // dynamic import BufferGeometryUtils and find merge function name
+        const bufUtilsMod = yield import('three/examples/jsm/utils/BufferGeometryUtils.js');
+        // use || chain (avoid mixing ?? with || without parentheses)
+        const mergeFn = bufUtilsMod.mergeBufferGeometries ||
+            bufUtilsMod.mergeGeometries ||
+            bufUtilsMod.mergeBufferGeometries || // defensive duplicate
+            bufUtilsMod.mergeGeometries;
+        if (!mergeFn)
+            throw new Error('No merge function found in BufferGeometryUtils');
+        // for each group, try merge
+        for (const [key, { material, geoms }] of groups) {
+            if (geoms.length <= 1) {
+                // nothing to merge
+                continue;
+            }
+            // call merge function - signature typically mergeBufferGeometries(array, useGroups)
+            const merged = mergeFn(geoms, false);
+            if (!merged) {
+                console.warn('merge returned null for group', key);
+                continue;
+            }
+            // create merged mesh at root (world-space geometry already applied)
+            const mergedMesh = new THREE__namespace.Mesh(merged, material);
+            root.add(mergedMesh);
+        }
+        // now remove original meshes flagged for removal
+        const toRemove = [];
+        root.traverse((ch) => {
+            var _a;
+            if ((_a = ch.userData) === null || _a === void 0 ? void 0 : _a.__toRemoveForMerge)
+                toRemove.push(ch);
+        });
+        toRemove.forEach((m) => {
+            if (m.parent)
+                m.parent.remove(m);
+            // free original resources (geometries already cloned/applied), but careful with shared materials
+            if (m.isMesh) {
+                const mm = m;
+                try {
+                    mm.geometry.dispose();
+                }
+                catch (_a) { }
+                // we do NOT dispose material because it may be reused by mergedMesh
+            }
+        });
+    });
+}
+/* ---------------------
+   释放工具
+   --------------------- */
+/** 彻底释放对象：几何体，材质和其贴图（危险：共享资源会被释放） */
+function disposeObject(obj) {
+    if (!obj)
+        return;
+    obj.traverse((ch) => {
+        if (ch.isMesh) {
+            const m = ch;
+            if (m.geometry) {
+                try {
+                    m.geometry.dispose();
+                }
+                catch (_a) { }
+            }
+            const mat = m.material;
+            if (mat) {
+                if (Array.isArray(mat))
+                    mat.forEach((x) => disposeMaterial(x));
+                else
+                    disposeMaterial(mat);
+            }
+        }
+    });
+}
+/** 释放材质及其贴图 */
+function disposeMaterial(mat) {
+    if (!mat)
+        return;
+    const texNames = ['map', 'alphaMap', 'aoMap', 'emissiveMap', 'envMap', 'metalnessMap', 'roughnessMap', 'normalMap', 'bumpMap', 'displacementMap', 'lightMap'];
+    texNames.forEach((k) => {
+        if (mat[k] && typeof mat[k].dispose === 'function') {
+            try {
+                mat[k].dispose();
+            }
+            catch (_a) { }
+        }
+    });
+    try {
+        if (typeof mat.dispose === 'function')
+            mat.dispose();
+    }
+    catch (_a) { }
+}
+
+/** 默认值 */
+const DEFAULT_OPTIONS = {
+    setAsBackground: true,
+    setAsEnvironment: true,
+    useSRGBEncoding: true,
+    cache: true
+};
+/** 内部缓存：key -> { handle, refCount } */
+const cubeCache = new Map();
+const equirectCache = new Map();
+/* -------------------------------------------
+   公共函数：加载 skybox（自动选 cube 或 equirect）
+   ------------------------------------------- */
+/**
+ * 加载立方体贴图（6张）
+ * @param renderer THREE.WebGLRenderer - 用于 PMREM 生成环境贴图
+ * @param scene THREE.Scene
+ * @param paths string[] 6 张图片地址，顺序：[px, nx, py, ny, pz, nz]
+ * @param opts SkyboxOptions
+ */
+function loadCubeSkybox(renderer_1, scene_1, paths_1) {
+    return __awaiter(this, arguments, void 0, function* (renderer, scene, paths, opts = {}) {
+        var _a, _b;
+        const options = Object.assign(Object.assign({}, DEFAULT_OPTIONS), opts);
+        if (!Array.isArray(paths) || paths.length !== 6)
+            throw new Error('cube skybox requires 6 image paths');
+        const key = paths.join('|');
+        // 缓存处理
+        if (options.cache && cubeCache.has(key)) {
+            const rec = cubeCache.get(key);
+            rec.refCount += 1;
+            // reapply to scene (in case it was removed)
+            if (options.setAsBackground)
+                scene.background = rec.handle.backgroundTexture;
+            if (options.setAsEnvironment && rec.handle.envRenderTarget)
+                scene.environment = rec.handle.envRenderTarget.texture;
+            return rec.handle;
+        }
+        // 加载立方体贴图
+        const loader = new THREE__namespace.CubeTextureLoader();
+        const texture = yield new Promise((resolve, reject) => {
+            loader.load(paths, (tex) => resolve(tex), undefined, (err) => reject(err));
+        });
+        // 设置编码与映射
+        if (options.useSRGBEncoding)
+            texture.encoding = THREE__namespace.sRGBEncoding;
+        texture.mapping = THREE__namespace.CubeReflectionMapping;
+        // apply as background if required
+        if (options.setAsBackground)
+            scene.background = texture;
+        // environment: use PMREM to produce a proper prefiltered env map for PBR
+        let pmremGenerator = (_a = options.pmremGenerator) !== null && _a !== void 0 ? _a : new THREE__namespace.PMREMGenerator(renderer);
+        (_b = pmremGenerator.compileCubemapShader) === null || _b === void 0 ? void 0 : _b.call(pmremGenerator);
+        // fromCubemap might be available in your three.js; fallback to fromEquirectangular approach if not
+        let envRenderTarget = null;
+        if (pmremGenerator.fromCubemap) {
+            envRenderTarget = pmremGenerator.fromCubemap(texture);
+        }
+        else {
+            // Fallback: render cube to env map by using generator.fromEquirectangular with a converted equirect if needed.
+            // Simpler fallback: use the cube texture directly as environment (less correct for reflections).
+            envRenderTarget = null;
+        }
+        if (options.setAsEnvironment) {
+            if (envRenderTarget) {
+                scene.environment = envRenderTarget.texture;
+            }
+            else {
+                // fallback: use cube texture directly (works but not prefiltered)
+                scene.environment = texture;
+            }
+        }
+        const handle = {
+            key,
+            backgroundTexture: options.setAsBackground ? texture : null,
+            envRenderTarget: envRenderTarget,
+            pmremGenerator: options.pmremGenerator ? null : pmremGenerator, // only dispose if we created it
+            setAsBackground: !!options.setAsBackground,
+            setAsEnvironment: !!options.setAsEnvironment,
+            dispose() {
+                // remove from scene
+                if (options.setAsBackground && scene.background === texture)
+                    scene.background = null;
+                if (options.setAsEnvironment && scene.environment) {
+                    // only clear if it's the same texture we set
+                    if (envRenderTarget && scene.environment === envRenderTarget.texture)
+                        scene.environment = null;
+                    else if (scene.environment === texture)
+                        scene.environment = null;
+                }
+                // dispose resources only if not cached/shared
+                if (envRenderTarget) {
+                    try {
+                        envRenderTarget.dispose();
+                    }
+                    catch (_a) { }
+                }
+                try {
+                    texture.dispose();
+                }
+                catch (_b) { }
+                // dispose pmremGenerator we created
+                if (!options.pmremGenerator && pmremGenerator) {
+                    try {
+                        pmremGenerator.dispose();
+                    }
+                    catch (_c) { }
+                }
+            }
+        };
+        if (options.cache)
+            cubeCache.set(key, { handle, refCount: 1 });
+        return handle;
+    });
+}
+/**
+ * 加载等距/单图（支持 HDR via RGBELoader）
+ * @param renderer THREE.WebGLRenderer
+ * @param scene THREE.Scene
+ * @param url string - *.hdr, *.exr, *.jpg, *.png
+ * @param opts SkyboxOptions
+ */
+function loadEquirectSkybox(renderer_1, scene_1, url_1) {
+    return __awaiter(this, arguments, void 0, function* (renderer, scene, url, opts = {}) {
+        var _a, _b;
+        const options = Object.assign(Object.assign({}, DEFAULT_OPTIONS), opts);
+        const key = url;
+        if (options.cache && equirectCache.has(key)) {
+            const rec = equirectCache.get(key);
+            rec.refCount += 1;
+            if (options.setAsBackground)
+                scene.background = rec.handle.backgroundTexture;
+            if (options.setAsEnvironment && rec.handle.envRenderTarget)
+                scene.environment = rec.handle.envRenderTarget.texture;
+            return rec.handle;
+        }
+        // 动态导入 RGBELoader（用于 .hdr/.exr），如果加载的是普通 jpg/png 可直接用 TextureLoader
+        const isHDR = /\.hdr$|\.exr$/i.test(url);
+        let hdrTexture;
+        if (isHDR) {
+            const { RGBELoader } = yield import('three/examples/jsm/loaders/RGBELoader.js');
+            hdrTexture = yield new Promise((resolve, reject) => {
+                new RGBELoader().load(url, (tex) => resolve(tex), undefined, (err) => reject(err));
+            });
+            // RGBE textures typically use LinearEncoding
+            hdrTexture.encoding = THREE__namespace.LinearEncoding;
+        }
+        else {
+            // ordinary image - use TextureLoader
+            const loader = new THREE__namespace.TextureLoader();
+            hdrTexture = yield new Promise((resolve, reject) => {
+                loader.load(url, (t) => resolve(t), undefined, (err) => reject(err));
+            });
+            if (options.useSRGBEncoding)
+                hdrTexture.encoding = THREE__namespace.sRGBEncoding;
+        }
+        // PMREMGenerator to convert equirectangular to prefiltered cubemap (good for PBR)
+        const pmremGenerator = (_a = options.pmremGenerator) !== null && _a !== void 0 ? _a : new THREE__namespace.PMREMGenerator(renderer);
+        (_b = pmremGenerator.compileEquirectangularShader) === null || _b === void 0 ? void 0 : _b.call(pmremGenerator);
+        const envRenderTarget = pmremGenerator.fromEquirectangular(hdrTexture);
+        // envTexture to use for scene.environment
+        const envTexture = envRenderTarget.texture;
+        // set background and/or environment
+        if (options.setAsBackground) {
+            // for background it's ok to use the equirect texture directly or the envTexture
+            // envTexture is cubemap-like and usually better for reflections; using it as background creates cube-projected look
+            scene.background = envTexture;
+        }
+        if (options.setAsEnvironment) {
+            scene.environment = envTexture;
+        }
+        // We can dispose the original hdrTexture (the PMREM target contains the needed data)
+        try {
+            hdrTexture.dispose();
+        }
+        catch (_c) { }
+        const handle = {
+            key,
+            backgroundTexture: options.setAsBackground ? envTexture : null,
+            envRenderTarget,
+            pmremGenerator: options.pmremGenerator ? null : pmremGenerator,
+            setAsBackground: !!options.setAsBackground,
+            setAsEnvironment: !!options.setAsEnvironment,
+            dispose() {
+                if (options.setAsBackground && scene.background === envTexture)
+                    scene.background = null;
+                if (options.setAsEnvironment && scene.environment === envTexture)
+                    scene.environment = null;
+                try {
+                    envRenderTarget.dispose();
+                }
+                catch (_a) { }
+                if (!options.pmremGenerator && pmremGenerator) {
+                    try {
+                        pmremGenerator.dispose();
+                    }
+                    catch (_b) { }
+                }
+            }
+        };
+        if (options.cache)
+            equirectCache.set(key, { handle, refCount: 1 });
+        return handle;
+    });
+}
+function loadSkybox(renderer_1, scene_1, params_1) {
+    return __awaiter(this, arguments, void 0, function* (renderer, scene, params, opts = {}) {
+        if (params.type === 'cube')
+            return loadCubeSkybox(renderer, scene, params.paths, opts);
+        return loadEquirectSkybox(renderer, scene, params.url, opts);
+    });
+}
+/* -------------------------
+   缓存/引用计数 辅助方法
+   ------------------------- */
+/** 释放一个缓存的 skybox（会减少 refCount，refCount=0 时才真正 dispose） */
+function releaseSkybox(handle) {
+    // check cube cache
+    if (cubeCache.has(handle.key)) {
+        const rec = cubeCache.get(handle.key);
+        rec.refCount -= 1;
+        if (rec.refCount <= 0) {
+            rec.handle.dispose();
+            cubeCache.delete(handle.key);
+        }
+        return;
+    }
+    if (equirectCache.has(handle.key)) {
+        const rec = equirectCache.get(handle.key);
+        rec.refCount -= 1;
+        if (rec.refCount <= 0) {
+            rec.handle.dispose();
+            equirectCache.delete(handle.key);
+        }
+        return;
+    }
+    // if not cached, just dispose
+    // handle.dispose()
+}
+
+// utils/BlueSkyManager.ts - 优化版
+/**
+ * BlueSkyManager - 优化版
+ * ---------------------------------------------------------
+ * 一个全局单例管理器，用于加载和管理基于 HDR/EXR 的蓝天白云环境贴图。
+ *
+ * ✨ 优化内容：
+ * - 添加加载进度回调
+ * - 支持加载取消
+ * - 完善错误处理
+ * - 返回 Promise 支持异步
+ * - 添加加载状态管理
+ */
+class BlueSkyManager {
+    constructor() {
+        /** 当前环境贴图的 RenderTarget，用于后续释放 */
+        this.skyRT = null;
+        /** 是否已经初始化 */
+        this.isInitialized = false;
+        /** ✨ 当前加载器，用于取消加载 */
+        this.currentLoader = null;
+        /** ✨ 加载状态 */
+        this.loadingState = 'idle';
+    }
+    /**
+     * 初始化
+     * ---------------------------------------------------------
+     * 必须在使用 BlueSkyManager 之前调用一次。
+     * @param renderer WebGLRenderer 实例
+     * @param scene Three.js 场景
+     * @param exposure 曝光度 (默认 1.0)
+     */
+    init(renderer, scene, exposure = 1.0) {
+        if (this.isInitialized) {
+            console.warn('BlueSkyManager: 已经初始化，跳过重复初始化');
+            return;
+        }
+        this.renderer = renderer;
+        this.scene = scene;
+        // 使用 ACESFilmicToneMapping，效果更接近真实
+        this.renderer.toneMapping = THREE__namespace.ACESFilmicToneMapping;
+        this.renderer.toneMappingExposure = exposure;
+        // 初始化 PMREM 生成器（全局只需一个）
+        this.pmremGen = new THREE__namespace.PMREMGenerator(renderer);
+        this.pmremGen.compileEquirectangularShader();
+        this.isInitialized = true;
+    }
+    /**
+     * ✨ 加载蓝天 HDR/EXR 贴图并应用到场景（Promise 版本）
+     * ---------------------------------------------------------
+     * @param exrPath HDR/EXR 文件路径
+     * @param options 加载选项
+     * @returns Promise<void>
+     */
+    loadAsync(exrPath, options = {}) {
+        if (!this.isInitialized) {
+            return Promise.reject(new Error('BlueSkyManager not initialized!'));
+        }
+        // ✨ 取消之前的加载
+        this.cancelLoad();
+        const { background = true, onProgress, onComplete, onError } = options;
+        this.loadingState = 'loading';
+        this.currentLoader = new EXRLoader_js.EXRLoader();
+        return new Promise((resolve, reject) => {
+            this.currentLoader.load(exrPath, 
+            // 成功回调
+            (texture) => {
+                try {
+                    // 设置贴图为球面反射映射
+                    texture.mapping = THREE__namespace.EquirectangularReflectionMapping;
+                    // 清理旧的环境贴图
+                    this.dispose();
+                    // 用 PMREM 生成高效的环境贴图
+                    this.skyRT = this.pmremGen.fromEquirectangular(texture);
+                    // 应用到场景：环境光照 & 背景
+                    this.scene.environment = this.skyRT.texture;
+                    if (background)
+                        this.scene.background = this.skyRT.texture;
+                    // 原始 HDR/EXR 贴图用完即销毁，节省内存
+                    texture.dispose();
+                    this.loadingState = 'loaded';
+                    this.currentLoader = null;
+                    console.log('✅ Blue sky EXR loaded:', exrPath);
+                    if (onComplete)
+                        onComplete();
+                    resolve();
+                }
+                catch (error) {
+                    this.loadingState = 'error';
+                    this.currentLoader = null;
+                    console.error('❌ Processing EXR sky failed:', error);
+                    if (onError)
+                        onError(error);
+                    reject(error);
+                }
+            }, 
+            // 进度回调
+            (xhr) => {
+                if (onProgress && xhr.lengthComputable) {
+                    const progress = xhr.loaded / xhr.total;
+                    onProgress(progress);
+                }
+            }, 
+            // 错误回调
+            (err) => {
+                this.loadingState = 'error';
+                this.currentLoader = null;
+                console.error('❌ Failed to load EXR sky:', err);
+                if (onError)
+                    onError(err);
+                reject(err);
+            });
+        });
+    }
+    /**
+     * 加载蓝天 HDR/EXR 贴图并应用到场景（同步 API，保持向后兼容）
+     * ---------------------------------------------------------
+     * @param exrPath HDR/EXR 文件路径
+     * @param background 是否应用为场景背景 (默认 true)
+     */
+    load(exrPath, background = true) {
+        this.loadAsync(exrPath, { background }).catch((error) => {
+            console.error('BlueSkyManager load error:', error);
+        });
+    }
+    /**
+     * ✨ 取消当前加载
+     */
+    cancelLoad() {
+        if (this.currentLoader) {
+            // EXRLoader 本身没有 abort 方法，但我们可以清空引用
+            this.currentLoader = null;
+            this.loadingState = 'idle';
+        }
+    }
+    /**
+     * ✨ 获取加载状态
+     */
+    getLoadingState() {
+        return this.loadingState;
+    }
+    /**
+     * ✨ 是否正在加载
+     */
+    isLoading() {
+        return this.loadingState === 'loading';
+    }
+    /**
+     * 释放当前的天空贴图资源
+     * ---------------------------------------------------------
+     * 仅清理 skyRT，不销毁 PMREM
+     * 适用于切换 HDR/EXR 文件时调用
+     */
+    dispose() {
+        if (this.skyRT) {
+            this.skyRT.texture.dispose();
+            this.skyRT.dispose();
+            this.skyRT = null;
+        }
+        if (this.scene && this.scene.background)
+            this.scene.background = null;
+        if (this.scene && this.scene.environment)
+            this.scene.environment = null;
+    }
+    /**
+     * 完全销毁 BlueSkyManager
+     * ---------------------------------------------------------
+     * 包括 PMREMGenerator 的销毁
+     * 通常在场景彻底销毁或应用退出时调用
+     */
+    destroy() {
+        var _a;
+        this.cancelLoad();
+        this.dispose();
+        (_a = this.pmremGen) === null || _a === void 0 ? void 0 : _a.dispose();
+        this.isInitialized = false;
+        this.loadingState = 'idle';
+    }
+}
+/**
+ * 🌐 全局单例
+ * ---------------------------------------------------------
+ * 直接导出一个全局唯一的 BlueSkyManager 实例，
+ * 保证整个应用中只用一个 PMREMGenerator，性能最佳。
+ */
+const BlueSky = new BlueSkyManager();
+
+/**
+ * 创建模型标签（带连线和脉冲圆点）- 优化版
+ *
+ * ✨ 优化内容：
+ * - 支持暂停/恢复更新
+ * - 可配置更新间隔
+ * - 淡入淡出效果
+ * - 缓存包围盒计算
+ * - RAF 管理优化
+ */
+function createModelsLabel(camera, renderer, parentModel, modelLabelsMap, options) {
+    var _a, _b, _c, _d, _e, _f;
+    const cfg = {
+        fontSize: (options === null || options === void 0 ? void 0 : options.fontSize) || '12px',
+        color: (options === null || options === void 0 ? void 0 : options.color) || '#ffffff',
+        background: (options === null || options === void 0 ? void 0 : options.background) || '#1890ff',
+        padding: (options === null || options === void 0 ? void 0 : options.padding) || '6px 10px',
+        borderRadius: (options === null || options === void 0 ? void 0 : options.borderRadius) || '6px',
+        lift: (_a = options === null || options === void 0 ? void 0 : options.lift) !== null && _a !== void 0 ? _a : 100,
+        dotSize: (_b = options === null || options === void 0 ? void 0 : options.dotSize) !== null && _b !== void 0 ? _b : 6,
+        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, // ✨ 淡入时长
+    };
+    const container = document.createElement('div');
+    container.style.position = 'absolute';
+    container.style.top = '0';
+    container.style.left = '0';
+    container.style.width = '100%';
+    container.style.height = '100%';
+    container.style.pointerEvents = 'none';
+    container.style.overflow = 'visible';
+    document.body.appendChild(container);
+    const svgNS = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(svgNS, 'svg');
+    svg.setAttribute('width', '100%');
+    svg.setAttribute('height', '100%');
+    svg.style.position = 'absolute';
+    svg.style.top = '0';
+    svg.style.left = '0';
+    svg.style.overflow = 'visible';
+    svg.style.pointerEvents = 'none';
+    svg.style.zIndex = '1';
+    container.appendChild(svg);
+    let currentModel = parentModel;
+    let currentLabelsMap = Object.assign({}, modelLabelsMap);
+    let labels = [];
+    let isActive = true;
+    let isPaused = false; // ✨ 暂停状态
+    let rafId = null; // ✨ RAF ID
+    let lastUpdateTime = 0; // ✨ 上次更新时间
+    // ✨ 注入样式（带淡入动画）
+    const styleId = 'three-model-label-styles';
+    if (!document.getElementById(styleId)) {
+        const style = document.createElement('style');
+        style.id = styleId;
+        style.innerHTML = `
+      @keyframes pulse-dot {
+        0% { transform: scale(1); opacity: 1; }
+        50% { transform: scale(1.6); opacity: 0.45; }
+        100% { transform: scale(1); opacity: 1; }
+      }
+      @keyframes fade-in-label {
+        from { opacity: 0; transform: translateY(10px); }
+        to { opacity: 1; transform: translateY(0); }
+      }
+      .tm-label {
+        pointer-events: none;
+        display: inline-block;
+        line-height: 1;
+        will-change: transform, opacity;
+        transition: opacity 150ms ease;
+      }
+      .tm-label-wrapper {
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        animation: fade-in-label ${cfg.fadeInDuration}ms ease-out;
+      }
+      .tm-label-dot {
+        border-radius: 50%;
+        will-change: transform, opacity;
+        animation: pulse-dot 1.2s infinite ease-in-out;
+      }
+      .tm-label-text {
+        white-space: nowrap;
+      }
+    `;
+        document.head.appendChild(style);
+    }
+    // ✨ 获取或更新缓存的顶部位置
+    const getObjectTopPosition = (labelData) => {
+        const obj = labelData.object;
+        // 如果有缓存且对象没有变换，直接返回
+        if (labelData.cachedTopPos && !obj.matrixWorldNeedsUpdate) {
+            return labelData.cachedTopPos.clone();
+        }
+        // 重新计算
+        const box = new THREE__namespace.Box3().setFromObject(obj);
+        labelData.cachedBox = box;
+        if (!box.isEmpty()) {
+            const center = new THREE__namespace.Vector3();
+            box.getCenter(center);
+            const topPos = new THREE__namespace.Vector3(center.x, box.max.y, center.z);
+            labelData.cachedTopPos = topPos;
+            return topPos.clone();
+        }
+        const p = new THREE__namespace.Vector3();
+        obj.getWorldPosition(p);
+        labelData.cachedTopPos = p;
+        return p.clone();
+    };
+    const clearLabels = () => {
+        labels.forEach(({ el, line, wrapper }) => {
+            el.remove();
+            wrapper.remove();
+            if (line && line.parentNode)
+                line.parentNode.removeChild(line);
+        });
+        labels = [];
+    };
+    const rebuildLabels = () => {
+        clearLabels();
+        if (!currentModel)
+            return;
+        currentModel.traverse((child) => {
+            var _a;
+            if (child.isMesh || child.type === 'Group') {
+                const labelText = (_a = Object.entries(currentLabelsMap).find(([key]) => child.name.includes(key))) === null || _a === void 0 ? void 0 : _a[1];
+                if (!labelText)
+                    return;
+                const wrapper = document.createElement('div');
+                wrapper.className = 'tm-label-wrapper';
+                wrapper.style.position = 'absolute';
+                wrapper.style.pointerEvents = 'none';
+                wrapper.style.transform = 'translate(-50%, -100%)';
+                wrapper.style.zIndex = '1';
+                const el = document.createElement('div');
+                el.className = 'tm-label';
+                el.style.background = cfg.background;
+                el.style.color = cfg.color;
+                el.style.padding = cfg.padding;
+                el.style.borderRadius = cfg.borderRadius;
+                el.style.fontSize = cfg.fontSize;
+                el.style.boxShadow = '0 6px 18px rgba(0,0,0,0.35)';
+                el.style.backdropFilter = 'blur(4px)';
+                el.style.border = '1px solid rgba(255,255,255,0.03)';
+                el.style.display = 'inline-block';
+                const txt = document.createElement('div');
+                txt.className = 'tm-label-text';
+                txt.innerText = labelText;
+                el.appendChild(txt);
+                const dot = document.createElement('div');
+                dot.className = 'tm-label-dot';
+                dot.style.width = `${cfg.dotSize}px`;
+                dot.style.height = `${cfg.dotSize}px`;
+                dot.style.background = 'radial-gradient(circle at 30% 30%, #fff, rgba(255,255,255,0.85) 20%, rgba(255,204,0,0.9) 60%, rgba(255,170,0,0.9) 100%)';
+                dot.style.boxShadow = '0 0 8px rgba(255,170,0,0.9)';
+                dot.style.flex = '0 0 auto';
+                dot.style.marginRight = `${cfg.dotSpacing}px`;
+                wrapper.appendChild(dot);
+                wrapper.appendChild(el);
+                container.appendChild(wrapper);
+                const line = document.createElementNS(svgNS, 'line');
+                line.setAttribute('stroke', cfg.lineColor);
+                line.setAttribute('stroke-width', `${cfg.lineWidth}`);
+                line.setAttribute('stroke-linecap', 'round');
+                line.setAttribute('opacity', '0.85');
+                svg.appendChild(line);
+                labels.push({
+                    object: child,
+                    el,
+                    wrapper,
+                    dot,
+                    line,
+                    cachedBox: null, // ✨ 初始化缓存
+                    cachedTopPos: null
+                });
+            }
+        });
+    };
+    rebuildLabels();
+    // ✨ 优化的更新函数
+    const updateLabels = (timestamp) => {
+        if (!isActive || isPaused) {
+            rafId = null;
+            return;
+        }
+        // ✨ 节流处理
+        if (cfg.updateInterval > 0 && timestamp - lastUpdateTime < cfg.updateInterval) {
+            rafId = requestAnimationFrame(updateLabels);
+            return;
+        }
+        lastUpdateTime = timestamp;
+        const rect = renderer.domElement.getBoundingClientRect();
+        const width = rect.width;
+        const height = rect.height;
+        svg.setAttribute('width', `${width}`);
+        svg.setAttribute('height', `${height}`);
+        labels.forEach((labelData) => {
+            const { el, wrapper, dot, line } = labelData;
+            const topWorld = getObjectTopPosition(labelData); // ✨ 使用缓存
+            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;
+            const labelX = modelX;
+            const labelY = modelY - cfg.lift;
+            wrapper.style.left = `${labelX}px`;
+            wrapper.style.top = `${labelY}px`;
+            const svgModelX = modelX - rect.left;
+            const svgModelY = modelY - rect.top;
+            const svgLabelX = labelX - rect.left;
+            const svgLabelY = labelY - rect.top + (el.getBoundingClientRect().height * 0.5);
+            line.setAttribute('x1', `${svgModelX}`);
+            line.setAttribute('y1', `${svgModelY}`);
+            line.setAttribute('x2', `${svgLabelX}`);
+            line.setAttribute('y2', `${svgLabelY}`);
+            const visible = topNDC.z < 1;
+            wrapper.style.display = visible ? 'flex' : 'none';
+            line.setAttribute('visibility', visible ? 'visible' : 'hidden');
+            dot.style.opacity = visible ? '1' : '0';
+        });
+        rafId = requestAnimationFrame(updateLabels);
+    };
+    rafId = requestAnimationFrame(updateLabels);
+    return {
+        updateModel(newModel) {
+            if (!newModel || newModel === currentModel)
+                return;
+            currentModel = newModel;
+            rebuildLabels();
+        },
+        updateLabelsMap(newMap) {
+            currentLabelsMap = Object.assign({}, newMap);
+            rebuildLabels();
+        },
+        // ✨ 暂停更新
+        pause() {
+            isPaused = true;
+            if (rafId !== null) {
+                cancelAnimationFrame(rafId);
+                rafId = null;
+            }
+        },
+        // ✨ 恢复更新
+        resume() {
+            if (!isPaused)
+                return;
+            isPaused = false;
+            rafId = requestAnimationFrame(updateLabels);
+        },
+        dispose() {
+            isActive = false;
+            isPaused = true;
+            if (rafId !== null) {
+                cancelAnimationFrame(rafId);
+                rafId = null;
+            }
+            clearLabels();
+            svg.remove();
+            container.remove();
+        },
+    };
+}
+
+function easeInOutQuad(t) {
+    return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+}
+class GroupExploder {
+    constructor(scene, camera, controls) {
+        // sets and snapshots
+        this.currentSet = null;
+        this.stateMap = new Map();
+        // prevSet preserved to allow async restore
+        this.prevSet = null;
+        this.prevStateMap = new Map();
+        // material context map: material -> Set<contextId>, and snapshot store material->snap
+        this.materialContexts = new Map();
+        this.materialSnaps = new Map();
+        this.contextMaterials = new Map();
+        this.animId = null;
+        this.cameraAnimId = null;
+        this.isExploded = false;
+        this.isInitialized = false;
+        this.scene = scene;
+        this.camera = camera;
+        this.controls = controls;
+    }
+    log(msg) {
+        console.log('[GroupExploderDebug]', msg);
+        if (this.onLog)
+            this.onLog(msg);
+    }
+    init() {
+        if (this.isInitialized)
+            return;
+        this.isInitialized = true;
+        this.log('init() called');
+    }
+    /**
+     * 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, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const autoRestorePrev = (_a = options === null || options === void 0 ? void 0 : options.autoRestorePrev) !== null && _a !== void 0 ? _a : true;
+            const restoreDuration = (_b = options === null || options === void 0 ? void 0 : options.restoreDuration) !== null && _b !== void 0 ? _b : 300;
+            this.log(`setMeshes called. newSetSize=${newSet ? newSet.size : 0}, autoRestorePrev=${autoRestorePrev}`);
+            // If the newSet is null and currentSet is null -> nothing
+            if (!newSet && !this.currentSet) {
+                this.log('setMeshes: both newSet and currentSet are null, nothing to do');
+                return;
+            }
+            // If both exist and are the same reference, we still must detect content changes.
+            const sameReference = this.currentSet === newSet;
+            // Prepare prevSet snapshot (we copy current to prev)
+            if (this.currentSet) {
+                this.prevSet = this.currentSet;
+                this.prevStateMap = new Map(this.stateMap);
+                this.log(`setMeshes: backed up current->prev prevSetSize=${this.prevSet.size}`);
+            }
+            else {
+                this.prevSet = null;
+                this.prevStateMap = new Map();
+            }
+            // If we used to be exploded and need to restore prevSet, do that first (await)
+            if (this.prevSet && autoRestorePrev && this.isExploded) {
+                this.log('setMeshes: need to restore prevSet before applying newSet');
+                yield this.restoreSet(this.prevSet, this.prevStateMap, restoreDuration, { debug: true });
+                this.log('setMeshes: prevSet restore done');
+                this.prevStateMap.clear();
+                this.prevSet = null;
+            }
+            // Now register newSet: we clear and rebuild stateMap carefully.
+            // But we must handle the case where caller reuses same Set object and just mutated elements.
+            // We will compute additions and removals.
+            const oldSet = this.currentSet;
+            this.currentSet = newSet;
+            // If newSet is null -> simply clear stateMap
+            if (!this.currentSet) {
+                this.stateMap.clear();
+                this.log('setMeshes: newSet is null -> cleared stateMap');
+                this.isExploded = false;
+                return;
+            }
+            // If we have oldSet (could be same reference) then compute diffs
+            if (oldSet) {
+                // If same reference but size or content differs -> handle diffs
+                const wasSameRef = sameReference;
+                let added = [];
+                let removed = [];
+                // Build maps of membership
+                const oldMembers = new Set(Array.from(oldSet));
+                const newMembers = new Set(Array.from(this.currentSet));
+                // find removals
+                oldMembers.forEach((m) => {
+                    if (!newMembers.has(m))
+                        removed.push(m);
+                });
+                // find additions
+                newMembers.forEach((m) => {
+                    if (!oldMembers.has(m))
+                        added.push(m);
+                });
+                if (wasSameRef && added.length === 0 && removed.length === 0) {
+                    // truly identical (no content changes)
+                    this.log('setMeshes: same reference and identical contents -> nothing to update');
+                    return;
+                }
+                this.log(`setMeshes: diff detected -> added=${added.length}, removed=${removed.length}`);
+                // Remove snapshots for removed meshes
+                removed.forEach((m) => {
+                    if (this.stateMap.has(m)) {
+                        this.stateMap.delete(m);
+                    }
+                });
+                // Ensure snapshots exist for current set members (create for newly added meshes)
+                yield this.ensureSnapshotsForSet(this.currentSet);
+                this.log(`setMeshes: after diff handling, stateMap size=${this.stateMap.size}`);
+                this.isExploded = false;
+                return;
+            }
+            else {
+                // no oldSet -> brand new registration
+                this.stateMap.clear();
+                yield this.ensureSnapshotsForSet(this.currentSet);
+                this.log(`setMeshes: recorded stateMap entries for newSet size=${this.stateMap.size}`);
+                this.isExploded = false;
+                return;
+            }
+        });
+    }
+    /**
+     * ensureSnapshotsForSet: for each mesh in set, ensure stateMap has an entry.
+     * If missing, record current matrixWorld as originalMatrixWorld (best-effort).
+     */
+    ensureSnapshotsForSet(set) {
+        return __awaiter(this, void 0, void 0, function* () {
+            set.forEach((m) => {
+                try {
+                    m.updateMatrixWorld(true);
+                }
+                catch (_a) { }
+                if (!this.stateMap.has(m)) {
+                    try {
+                        this.stateMap.set(m, {
+                            originalParent: m.parent || null,
+                            originalMatrixWorld: (m.matrixWorld && m.matrixWorld.clone()) || new THREE__namespace.Matrix4().copy(m.matrix),
+                        });
+                        // Also store in userData for extra resilience
+                        m.userData.__originalMatrixWorld = this.stateMap.get(m).originalMatrixWorld.clone();
+                    }
+                    catch (e) {
+                        this.log(`ensureSnapshotsForSet: failed to snapshot mesh ${m.name || m.id}: ${e.message}`);
+                    }
+                }
+            });
+        });
+    }
+    /**
+     * explode: compute targets first, compute targetBound using targets + mesh radii,
+     * animate camera to that targetBound, then animate meshes to targets.
+     */
+    explode(opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!this.currentSet || this.currentSet.size === 0) {
+                this.log('explode: empty currentSet, nothing to do');
+                return;
+            }
+            const { spacing = 2, duration = 1000, lift = 0.5, cameraPadding = 1.5, mode = 'spiral', dimOthers = { enabled: true, opacity: 0.25 }, debug = false, } = opts || {};
+            this.log(`explode called. setSize=${this.currentSet.size}, mode=${mode}, spacing=${spacing}, duration=${duration}, lift=${lift}, dim=${dimOthers.enabled}`);
+            this.cancelAnimations();
+            const meshes = Array.from(this.currentSet);
+            // ensure snapshots exist for any meshes that may have been added after initial registration
+            yield this.ensureSnapshotsForSet(this.currentSet);
+            // compute center/radius from current meshes (fallback)
+            const initial = this.computeBoundingSphereForMeshes(meshes);
+            const center = initial.center;
+            const baseRadius = Math.max(1, initial.radius);
+            this.log(`explode: initial center=${center.toArray().map((n) => n.toFixed(3))}, baseRadius=${baseRadius.toFixed(3)}`);
+            // compute targets (pure calculation)
+            const targets = this.computeTargetsByMode(meshes, center, baseRadius + spacing, { lift, mode });
+            this.log(`explode: computed ${targets.length} target positions`);
+            // compute target-based bounding sphere (targets + per-mesh radius)
+            const targetBound = this.computeBoundingSphereForPositionsAndMeshes(targets, meshes);
+            this.log(`explode: targetBound center=${targetBound.center.toArray().map((n) => n.toFixed(3))}, radius=${targetBound.radius.toFixed(3)}`);
+            yield this.animateCameraToFit(targetBound.center, targetBound.radius, { duration: Math.min(600, duration), padding: cameraPadding });
+            this.log('explode: camera animation to target bound completed');
+            // apply dim if needed with context id
+            const contextId = (dimOthers === null || dimOthers === void 0 ? void 0 : dimOthers.enabled) ? this.applyDimToOthers(meshes, (_a = dimOthers.opacity) !== null && _a !== void 0 ? _a : 0.25, { debug }) : null;
+            if (contextId)
+                this.log(`explode: applied dim for context ${contextId}`);
+            // capture starts after camera move
+            const starts = meshes.map((m) => {
+                const v = new THREE__namespace.Vector3();
+                try {
+                    m.getWorldPosition(v);
+                }
+                catch (_a) {
+                    // fallback to originalMatrixWorld if available
+                    const st = this.stateMap.get(m);
+                    if (st)
+                        v.setFromMatrixPosition(st.originalMatrixWorld);
+                }
+                return v;
+            });
+            const startTime = performance.now();
+            const total = Math.max(1, duration);
+            const tick = (now) => {
+                const t = Math.min(1, (now - startTime) / total);
+                const eased = easeInOutQuad(t);
+                for (let i = 0; i < meshes.length; i++) {
+                    const m = meshes[i];
+                    const s = starts[i];
+                    const tar = targets[i];
+                    const cur = s.clone().lerp(tar, eased);
+                    if (m.parent) {
+                        const local = cur.clone();
+                        m.parent.worldToLocal(local);
+                        m.position.copy(local);
+                    }
+                    else {
+                        m.position.copy(cur);
+                    }
+                    m.updateMatrix();
+                }
+                if (this.controls && typeof this.controls.update === 'function')
+                    this.controls.update();
+                if (t < 1) {
+                    this.animId = requestAnimationFrame(tick);
+                }
+                else {
+                    this.animId = null;
+                    this.isExploded = true;
+                    this.log(`explode: completed. contextId=${contextId !== null && contextId !== void 0 ? contextId : 'none'}`);
+                }
+            };
+            this.animId = requestAnimationFrame(tick);
+            return;
+        });
+    }
+    restore(duration = 400) {
+        if (!this.currentSet || this.currentSet.size === 0) {
+            this.log('restore: no currentSet to restore');
+            return Promise.resolve();
+        }
+        this.log(`restore called for currentSet size=${this.currentSet.size}`);
+        return this.restoreSet(this.currentSet, this.stateMap, duration, { debug: true });
+    }
+    /**
+     * 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)
+     */
+    restoreSet(set, stateMap, duration = 400, opts) {
+        if (!set || set.size === 0) {
+            if (opts === null || opts === void 0 ? void 0 : opts.debug)
+                this.log('restoreSet: empty set, nothing to restore');
+            return Promise.resolve();
+        }
+        this.cancelAnimations();
+        const meshes = Array.from(set);
+        this.log(`restoreSet: starting restore for ${meshes.length} meshes (duration=${duration})`);
+        const starts = [];
+        const targets = [];
+        for (const m of meshes) {
+            try {
+                m.updateMatrixWorld(true);
+            }
+            catch (_a) { }
+            const s = new THREE__namespace.Vector3();
+            try {
+                m.getWorldPosition(s);
+            }
+            catch (_b) {
+                s.set(0, 0, 0);
+            }
+            starts.push(s);
+            const st = stateMap.get(m);
+            if (st) {
+                const tar = new THREE__namespace.Vector3();
+                tar.setFromMatrixPosition(st.originalMatrixWorld);
+                targets.push(tar);
+            }
+            else {
+                // fallback attempts
+                const ud = m.userData.__originalMatrixWorld;
+                if (ud instanceof THREE__namespace.Matrix4) {
+                    const tar = new THREE__namespace.Vector3();
+                    tar.setFromMatrixPosition(ud);
+                    targets.push(tar);
+                    this.log(`restoreSet: used userData.__originalMatrixWorld for mesh ${m.name || m.id}`);
+                }
+                else {
+                    // fallback to current position to avoid NaN; will be effectively a no-op but avoids error
+                    const tar = s.clone();
+                    targets.push(tar);
+                    this.log(`restoreSet: missing stateMap entry for mesh ${m.name || m.id} -> fallback to current pos`);
+                }
+            }
+        }
+        const startTime = performance.now();
+        const total = Math.max(1, duration);
+        return new Promise((resolve) => {
+            const tick = (now) => {
+                const t = Math.min(1, (now - startTime) / total);
+                const eased = easeInOutQuad(t);
+                for (let i = 0; i < meshes.length; i++) {
+                    const m = meshes[i];
+                    const s = starts[i];
+                    const tar = targets[i];
+                    const cur = s.clone().lerp(tar, eased);
+                    // final step: ensure reparent to original parent if possible
+                    const st = stateMap.get(m);
+                    if (st && t >= 0.999) {
+                        try {
+                            const origParent = st.originalParent || this.scene;
+                            origParent.updateMatrixWorld(true);
+                            const parentInv = new THREE__namespace.Matrix4().copy(origParent.matrixWorld).invert();
+                            const localMat = new THREE__namespace.Matrix4().multiplyMatrices(parentInv, st.originalMatrixWorld);
+                            // reparent (if needed)
+                            if (m.parent !== origParent) {
+                                origParent.add(m);
+                            }
+                            m.matrix.copy(localMat);
+                            m.matrix.decompose(m.position, m.quaternion, m.scale);
+                            m.updateMatrixWorld(true);
+                        }
+                        catch (e) {
+                            // fallback: set world position
+                            if (m.parent) {
+                                const local = tar.clone();
+                                m.parent.worldToLocal(local);
+                                m.position.copy(local);
+                            }
+                            else {
+                                m.position.copy(tar);
+                            }
+                            m.updateMatrixWorld(true);
+                            this.log(`restoreSet: error finalizing reparent for ${m.name || m.id}: ${e.message}`);
+                        }
+                    }
+                    else {
+                        // intermediate frames: lerp world -> convert to local relative to current parent
+                        if (m.parent) {
+                            const local = cur.clone();
+                            m.parent.worldToLocal(local);
+                            m.position.copy(local);
+                        }
+                        else {
+                            m.position.copy(cur);
+                        }
+                        m.updateMatrix();
+                    }
+                }
+                if (this.controls && typeof this.controls.update === 'function')
+                    this.controls.update();
+                if (t < 1) {
+                    this.animId = requestAnimationFrame(tick);
+                }
+                else {
+                    this.animId = null;
+                    this.cleanContextsForMeshes(meshes);
+                    this.isExploded = false;
+                    this.log('restoreSet: completed and cleaned contexts for restored meshes');
+                    resolve();
+                }
+            };
+            this.animId = requestAnimationFrame(tick);
+        });
+    }
+    // material dim with context id
+    applyDimToOthers(explodingMeshes, opacity = 0.25, opts) {
+        const contextId = `ctx_${Date.now()}_${Math.floor(Math.random() * 10000)}`;
+        const explodingSet = new Set(explodingMeshes);
+        const touched = new Set();
+        this.scene.traverse((obj) => {
+            if (!obj.isMesh)
+                return;
+            const mesh = obj;
+            if (explodingSet.has(mesh))
+                return;
+            const applyMat = (mat) => {
+                var _a;
+                if (!this.materialSnaps.has(mat)) {
+                    this.materialSnaps.set(mat, {
+                        transparent: !!mat.transparent,
+                        opacity: (_a = mat.opacity) !== null && _a !== void 0 ? _a : 1,
+                        depthWrite: mat.depthWrite,
+                    });
+                }
+                let s = this.materialContexts.get(mat);
+                if (!s) {
+                    s = new Set();
+                    this.materialContexts.set(mat, s);
+                }
+                s.add(contextId);
+                touched.add(mat);
+                mat.transparent = true;
+                mat.opacity = opacity;
+                mat.needsUpdate = true;
+            };
+            if (Array.isArray(mesh.material)) {
+                mesh.material.forEach((m) => applyMat(m));
+            }
+            else if (mesh.material) {
+                applyMat(mesh.material);
+            }
+        });
+        this.contextMaterials.set(contextId, touched);
+        this.log(`applyDimToOthers: context=${contextId}, touchedMaterials=${touched.size}`);
+        return contextId;
+    }
+    // clean contexts for meshes (restore materials whose contexts are removed)
+    cleanContextsForMeshes(meshes) {
+        // conservative strategy: for each context we created, delete it and restore materials accordingly
+        for (const [contextId, mats] of Array.from(this.contextMaterials.entries())) {
+            mats.forEach((mat) => {
+                const ctxSet = this.materialContexts.get(mat);
+                if (ctxSet) {
+                    ctxSet.delete(contextId);
+                    if (ctxSet.size === 0) {
+                        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);
+                    }
+                    else {
+                        this.materialContexts.set(mat, ctxSet);
+                    }
+                }
+            });
+            this.contextMaterials.delete(contextId);
+            this.log(`cleanContextsForMeshes: removed context ${contextId}`);
+        }
+    }
+    // robust bounding sphere computation; if mesh world pos invalid, try stateMap's originalMatrixWorld as backoff
+    computeBoundingSphereForMeshes(meshes) {
+        const box = new THREE__namespace.Box3();
+        meshes.forEach((m) => {
+            try {
+                m.updateMatrixWorld(true);
+                const pos = new THREE__namespace.Vector3();
+                m.getWorldPosition(pos);
+                if (!isFinite(pos.x) || !isFinite(pos.y) || !isFinite(pos.z)) {
+                    // fallback to stateMap's originalMatrixWorld if available
+                    const st = this.stateMap.get(m);
+                    if (st) {
+                        const fallback = new THREE__namespace.Vector3();
+                        fallback.setFromMatrixPosition(st.originalMatrixWorld);
+                        if (isFinite(fallback.x) && isFinite(fallback.y) && isFinite(fallback.z)) {
+                            this.log(`computeBoundingSphereForMeshes: using stateMap originalMatrixWorld for mesh ${m.name || m.id}`);
+                            pos.copy(fallback);
+                        }
+                        else {
+                            this.log(`computeBoundingSphereForMeshes: skipping mesh ${m.name || m.id} due to invalid positions`);
+                            return;
+                        }
+                    }
+                    else {
+                        this.log(`computeBoundingSphereForMeshes: skipping mesh ${m.name || m.id} due to invalid world pos and no snapshot`);
+                        return;
+                    }
+                }
+                let radius = 0;
+                const geom = m.geometry || null;
+                if (geom) {
+                    if (!geom.boundingSphere)
+                        geom.computeBoundingSphere();
+                    if (geom.boundingSphere) {
+                        radius = geom.boundingSphere.radius;
+                        const ws = new THREE__namespace.Vector3();
+                        m.getWorldScale(ws);
+                        radius = radius * Math.max(ws.x, ws.y, ws.z, 1e-6);
+                    }
+                }
+                if (!isFinite(radius) || radius < 0 || radius > 1e8)
+                    radius = 0;
+                const min = pos.clone().addScalar(-radius);
+                const max = pos.clone().addScalar(radius);
+                box.expandByPoint(min);
+                box.expandByPoint(max);
+            }
+            catch (e) {
+                this.log(`computeBoundingSphereForMeshes: error for mesh ${m.name || m.id}: ${e.message}`);
+            }
+        });
+        const center = new THREE__namespace.Vector3();
+        if (box.isEmpty()) {
+            center.set(0, 0, 0);
+            box.expandByPoint(center);
+        }
+        box.getCenter(center);
+        const sphere = new THREE__namespace.Sphere();
+        box.getBoundingSphere(sphere);
+        const radius = sphere.radius || Math.max(box.getSize(new THREE__namespace.Vector3()).length() * 0.5, 1.0);
+        return { center, radius };
+    }
+    // compute bounding sphere for positions + mesh radii
+    computeBoundingSphereForPositionsAndMeshes(positions, meshes) {
+        const box = new THREE__namespace.Box3();
+        for (let i = 0; i < positions.length; i++) {
+            const p = positions[i];
+            if (!isFinite(p.x) || !isFinite(p.y) || !isFinite(p.z)) {
+                this.log(`computeBoundingSphereForPositionsAndMeshes: skipping invalid target pos idx=${i}`);
+                continue;
+            }
+            let radius = 0;
+            const m = meshes[i];
+            try {
+                const geom = m.geometry || null;
+                if (geom) {
+                    if (!geom.boundingSphere)
+                        geom.computeBoundingSphere();
+                    if (geom.boundingSphere) {
+                        radius = geom.boundingSphere.radius;
+                        const ws = new THREE__namespace.Vector3();
+                        m.getWorldScale(ws);
+                        radius = radius * Math.max(ws.x, ws.y, ws.z, 1e-6);
+                    }
+                }
+            }
+            catch (_a) {
+                radius = 0;
+            }
+            if (!isFinite(radius) || radius < 0 || radius > 1e8)
+                radius = 0;
+            const min = p.clone().addScalar(-radius);
+            const max = p.clone().addScalar(radius);
+            box.expandByPoint(min);
+            box.expandByPoint(max);
+        }
+        const center = new THREE__namespace.Vector3();
+        if (box.isEmpty()) {
+            center.set(0, 0, 0);
+            box.expandByPoint(center);
+        }
+        box.getCenter(center);
+        const tmp = new THREE__namespace.Sphere();
+        box.getBoundingSphere(tmp);
+        const radius = tmp.radius || Math.max(box.getSize(new THREE__namespace.Vector3()).length() * 0.5, 1.0);
+        return { center, radius };
+    }
+    // computeTargetsByMode (unchanged logic but pure function)
+    computeTargetsByMode(meshes, center, baseRadius, opts) {
+        var _a, _b;
+        const n = meshes.length;
+        const lift = (_a = opts.lift) !== null && _a !== void 0 ? _a : 0.5;
+        const mode = (_b = opts.mode) !== null && _b !== void 0 ? _b : 'ring';
+        const targets = [];
+        if (mode === 'ring') {
+            for (let i = 0; i < n; i++) {
+                const angle = (i / n) * Math.PI * 2;
+                targets.push(new THREE__namespace.Vector3(center.x + Math.cos(angle) * baseRadius, center.y + lift, center.z + Math.sin(angle) * baseRadius));
+            }
+            return targets;
+        }
+        if (mode === 'spiral') {
+            const turns = Math.max(1, Math.ceil(n / 6));
+            for (let i = 0; i < n; i++) {
+                const t = i / (n - 1 || 1);
+                const angle = t * Math.PI * 2 * turns;
+                const radius = baseRadius * (0.3 + 0.7 * t);
+                targets.push(new THREE__namespace.Vector3(center.x + Math.cos(angle) * radius, center.y + lift + t * 0.5, center.z + Math.sin(angle) * radius));
+            }
+            return targets;
+        }
+        if (mode === 'grid') {
+            const cols = Math.ceil(Math.sqrt(n));
+            const rows = Math.ceil(n / cols);
+            const spacing = Math.max(0.5, baseRadius / Math.max(cols, rows));
+            const startX = center.x - ((cols - 1) * spacing) / 2;
+            const startZ = center.z - ((rows - 1) * spacing) / 2;
+            for (let i = 0; i < n; i++) {
+                const r = Math.floor(i / cols);
+                const c = i % cols;
+                targets.push(new THREE__namespace.Vector3(startX + c * spacing, center.y + lift, startZ + r * spacing));
+            }
+            return targets;
+        }
+        // radial
+        for (let i = 0; i < n; i++) {
+            const t = i / n;
+            const angle = t * Math.PI * 2;
+            const r = baseRadius * (1 + (i % 3) * 0.4 + Math.floor(i / 3) * 0.6);
+            targets.push(new THREE__namespace.Vector3(center.x + Math.cos(angle) * r, center.y + lift + Math.floor(i / 3) * 0.2, center.z + Math.sin(angle) * r));
+        }
+        return targets;
+    }
+    animateCameraToFit(targetCenter, targetRadius, opts) {
+        var _a, _b, _c;
+        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();
+            }
+            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)
+            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();
+        return new Promise((resolve) => {
+            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)
+                    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));
+    }
+    cancelAnimations() {
+        if (this.animId) {
+            cancelAnimationFrame(this.animId);
+            this.animId = null;
+        }
+        if (this.cameraAnimId) {
+            cancelAnimationFrame(this.cameraAnimId);
+            this.cameraAnimId = null;
+        }
+    }
+    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');
+        });
+    }
+}
+
+/**
+ * 自动设置相机与基础灯光 - 优化版
+ *
+ * ✨ 优化内容：
+ * - 添加灯光强度调整方法
+ * - 完善错误处理
+ * - 优化dispose逻辑
+ *
+ * - camera: THREE.PerspectiveCamera（会被移动并指向模型中心）
+ * - scene: THREE.Scene（会把新创建的 light group 加入 scene）
+ * - model: THREE.Object3D 已加载的模型（任意 transform/坐标）
+ * - options: 可选配置（见 AutoSetupOptions）
+ *
+ * 返回 AutoSetupHandle，调用方在组件卸载/切换时请调用 handle.dispose()
+ */
+function autoSetupCameraAndLight(camera, scene, model, options = {}) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    // ✨ 边界检查
+    if (!camera || !scene || !model) {
+        throw new Error('autoSetupCameraAndLight: camera, scene, model are required');
+    }
+    const opts = {
+        padding: (_a = options.padding) !== null && _a !== void 0 ? _a : 1.2,
+        elevation: (_b = options.elevation) !== null && _b !== void 0 ? _b : 0.2,
+        enableShadows: (_c = options.enableShadows) !== null && _c !== void 0 ? _c : false,
+        shadowMapSize: (_d = options.shadowMapSize) !== null && _d !== void 0 ? _d : 1024,
+        directionalCount: (_e = options.directionalCount) !== null && _e !== void 0 ? _e : 4,
+        setMeshShadowProps: (_f = options.setMeshShadowProps) !== null && _f !== void 0 ? _f : true,
+        renderer: (_g = options.renderer) !== null && _g !== void 0 ? _g : null,
+    };
+    try {
+        // --- 1) 计算包围数据
+        const box = new THREE__namespace.Box3().setFromObject(model);
+        // ✨ 检查包围盒有效性
+        if (!isFinite(box.min.x)) {
+            throw new Error('autoSetupCameraAndLight: Invalid bounding box');
+        }
+        const sphere = new THREE__namespace.Sphere();
+        box.getBoundingSphere(sphere);
+        const center = sphere.center.clone();
+        const radius = Math.max(0.001, sphere.radius);
+        // --- 2) 计算相机位置
+        const fov = (camera.fov * Math.PI) / 180;
+        const halfFov = fov / 2;
+        const sinHalfFov = Math.max(Math.sin(halfFov), 0.001);
+        const distance = (radius * opts.padding) / sinHalfFov;
+        const dir = new THREE__namespace.Vector3(0, Math.sin(opts.elevation), Math.cos(opts.elevation)).normalize();
+        const desiredPos = center.clone().add(dir.multiplyScalar(distance));
+        camera.position.copy(desiredPos);
+        camera.lookAt(center);
+        camera.near = Math.max(0.001, radius / 1000);
+        camera.far = Math.max(1000, radius * 50);
+        camera.updateProjectionMatrix();
+        // --- 3) 启用阴影
+        if (opts.renderer && opts.enableShadows) {
+            opts.renderer.shadowMap.enabled = true;
+            opts.renderer.shadowMap.type = THREE__namespace.PCFSoftShadowMap;
+        }
+        // --- 4) 创建灯光组
+        const lightsGroup = new THREE__namespace.Group();
+        lightsGroup.name = 'autoSetupLightsGroup';
+        lightsGroup.position.copy(center);
+        scene.add(lightsGroup);
+        // 4.1 基础光
+        const hemi = new THREE__namespace.HemisphereLight(0xffffff, 0x444444, 0.6);
+        hemi.name = 'auto_hemi';
+        hemi.position.set(0, radius * 2.0, 0);
+        lightsGroup.add(hemi);
+        const ambient = new THREE__namespace.AmbientLight(0xffffff, 0.25);
+        ambient.name = 'auto_ambient';
+        lightsGroup.add(ambient);
+        // 4.2 方向光
+        const dirCount = Math.max(1, Math.floor(opts.directionalCount));
+        const directionalLights = [];
+        const dirs = [];
+        dirs.push(new THREE__namespace.Vector3(0, 1, 0));
+        for (let i = 0; i < Math.max(1, dirCount); i++) {
+            const angle = (i / Math.max(1, dirCount)) * Math.PI * 2;
+            const v = new THREE__namespace.Vector3(Math.cos(angle), 0.3, Math.sin(angle)).normalize();
+            dirs.push(v);
+        }
+        const shadowCamSize = Math.max(1, radius * 1.5);
+        for (let i = 0; i < dirs.length; i++) {
+            const d = dirs[i];
+            const light = new THREE__namespace.DirectionalLight(0xffffff, i === 0 ? 1.5 : 1.2);
+            light.position.copy(d.clone().multiplyScalar(radius * 2.5));
+            light.target.position.copy(center);
+            light.name = `auto_dir_${i}`;
+            lightsGroup.add(light);
+            lightsGroup.add(light.target);
+            if (opts.enableShadows) {
+                light.castShadow = true;
+                light.shadow.mapSize.width = opts.shadowMapSize;
+                light.shadow.mapSize.height = opts.shadowMapSize;
+                const cam = light.shadow.camera;
+                const s = shadowCamSize;
+                cam.left = -s;
+                cam.right = s;
+                cam.top = s;
+                cam.bottom = -s;
+                cam.near = 0.1;
+                cam.far = radius * 10 + 50;
+                light.shadow.bias = -0.0005;
+            }
+            directionalLights.push(light);
+        }
+        // 4.3 点光补光
+        const fill1 = new THREE__namespace.PointLight(0xffffff, 0.5, radius * 4);
+        fill1.position.copy(center).add(new THREE__namespace.Vector3(radius * 0.5, 0.2 * radius, 0));
+        fill1.name = 'auto_fill1';
+        lightsGroup.add(fill1);
+        const fill2 = new THREE__namespace.PointLight(0xffffff, 0.3, radius * 3);
+        fill2.position.copy(center).add(new THREE__namespace.Vector3(-radius * 0.5, -0.2 * radius, 0));
+        fill2.name = 'auto_fill2';
+        lightsGroup.add(fill2);
+        // --- 5) 设置 Mesh 阴影属性
+        if (opts.setMeshShadowProps) {
+            model.traverse((ch) => {
+                if (ch.isMesh) {
+                    const mesh = ch;
+                    const isSkinned = mesh.isSkinnedMesh;
+                    mesh.castShadow = opts.enableShadows && !isSkinned ? true : mesh.castShadow;
+                    mesh.receiveShadow = opts.enableShadows ? true : mesh.receiveShadow;
+                }
+            });
+        }
+        // --- 6) 返回 handle ---
+        const handle = {
+            lightsGroup,
+            center,
+            radius,
+            // ✨ 新增灯光强度调整
+            updateLightIntensity(factor) {
+                lightsGroup.traverse((node) => {
+                    if (node.isLight) {
+                        const light = node;
+                        const originalIntensity = parseFloat(light.name.split('_').pop() || '1');
+                        light.intensity = originalIntensity * Math.max(0, factor);
+                    }
+                });
+            },
+            dispose: () => {
+                try {
+                    // 移除灯光组
+                    if (lightsGroup.parent)
+                        lightsGroup.parent.remove(lightsGroup);
+                    // 清理阴影资源
+                    lightsGroup.traverse((node) => {
+                        if (node.isLight) {
+                            const l = node;
+                            if (l.shadow && l.shadow.map) {
+                                try {
+                                    l.shadow.map.dispose();
+                                }
+                                catch (err) {
+                                    console.warn('Failed to dispose shadow map:', err);
+                                }
+                            }
+                        }
+                    });
+                }
+                catch (error) {
+                    console.error('autoSetupCameraAndLight: dispose failed', error);
+                }
+            }
+        };
+        return handle;
+    }
+    catch (error) {
+        console.error('autoSetupCameraAndLight: setup failed', error);
+        throw error;
+    }
+}
+
+/**
+ * three-model-render
+ * Professional Three.js Model Visualization and Interaction Toolkit
+ *
+ * @packageDocumentation
+ */
+// Core utilities
+// Version
+const VERSION = '1.0.0';
+
+exports.ArrowGuide = ArrowGuide;
+exports.BlueSky = BlueSky;
+exports.FOLLOW_ANGLES = FOLLOW_ANGLES;
+exports.GroupExploder = GroupExploder;
+exports.LiquidFillerGroup = LiquidFillerGroup;
+exports.VERSION = VERSION;
+exports.ViewPresets = ViewPresets;
+exports.addChildModelLabels = addChildModelLabels;
+exports.autoSetupCameraAndLight = autoSetupCameraAndLight;
+exports.cancelFollow = cancelFollow;
+exports.cancelSetView = cancelSetView;
+exports.createModelClickHandler = createModelClickHandler;
+exports.createModelsLabel = createModelsLabel;
+exports.disposeMaterial = disposeMaterial;
+exports.disposeObject = disposeObject;
+exports.enableHoverBreath = enableHoverBreath;
+exports.followModels = followModels;
+exports.initPostProcessing = initPostProcessing;
+exports.loadCubeSkybox = loadCubeSkybox;
+exports.loadEquirectSkybox = loadEquirectSkybox;
+exports.loadModelByUrl = loadModelByUrl;
+exports.loadSkybox = loadSkybox;
+exports.releaseSkybox = releaseSkybox;
+exports.setView = setView;
+//# sourceMappingURL=index.js.map