@chocozhang/three-model-render 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,852 @@
+import * as THREE from 'three';
+import { OutlinePass } from 'three/examples/jsm/postprocessing/OutlinePass';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
+
+interface LabelOptions$1 {
+    fontSize?: string;
+    color?: string;
+    background?: string;
+    padding?: string;
+    borderRadius?: string;
+    updateInterval?: number;
+    enableCache?: boolean;
+}
+interface LabelManager$1 {
+    pause: () => void;
+    resume: () => void;
+    dispose: () => void;
+    isRunning: () => boolean;
+}
+/**
+ * 给子模型添加头顶标签（支持 Mesh 和 Group）- 优化版
+ *
+ * ✨ 性能优化：
+ * - 缓存包围盒，避免每帧重复计算
+ * - 支持暂停/恢复更新
+ * - 可配置更新间隔，降低 CPU 占用
+ * - 只在可见时更新，隐藏时自动暂停
+ *
+ * @param camera THREE.Camera - 场景摄像机
+ * @param renderer THREE.WebGLRenderer - 渲染器，用于屏幕尺寸
+ * @param parentModel THREE.Object3D - FBX 根节点或 Group
+ * @param modelLabelsMap Record<string,string> - 模型 name → 标签文字 映射表
+ * @param options LabelOptions - 可选标签样式配置
+ * @returns LabelManager - 包含 pause/resume/dispose 的管理接口
+ */
+declare function addChildModelLabels(camera: THREE.Camera, renderer: THREE.WebGLRenderer, parentModel: THREE.Object3D, modelLabelsMap: Record<string, string>, options?: LabelOptions$1): LabelManager$1;
+
+type HoverBreathOptions = {
+    camera: THREE.Camera;
+    scene: THREE.Scene;
+    renderer: THREE.WebGLRenderer;
+    outlinePass: OutlinePass;
+    highlightNames?: string[] | null;
+    minStrength?: number;
+    maxStrength?: number;
+    speed?: number;
+    throttleDelay?: number;
+};
+/**
+ * 创建单例高亮器 —— 推荐在 mounted 时创建一次
+ * 返回 { updateHighlightNames, dispose, getHoveredName } 接口
+ *
+ * ✨ 性能优化：
+ * - 无 hover 对象时自动暂停动画
+ * - mousemove 节流处理，避免过度计算
+ * - 使用 passive 事件监听器提升滚动性能
+ */
+declare function enableHoverBreath(opts: HoverBreathOptions): {
+    updateHighlightNames: (names: string[] | null) => void;
+    dispose: () => void;
+    refreshSelection: () => void;
+    getHoveredName: () => string | null;
+};
+
+/**
+ * 后期处理配置选项
+ */
+interface PostProcessingOptions {
+    edgeStrength?: number;
+    edgeGlow?: number;
+    edgeThickness?: number;
+    visibleEdgeColor?: string;
+    hiddenEdgeColor?: string;
+    resolutionScale?: number;
+}
+/**
+ * 后期处理管理接口
+ */
+interface PostProcessingManager {
+    composer: EffectComposer;
+    outlinePass: OutlinePass;
+    resize: (width?: number, height?: number) => void;
+    dispose: () => void;
+}
+/**
+ * 初始化描边相关信息（包含 OutlinePass）- 优化版
+ *
+ * ✨ 功能增强：
+ * - 支持窗口 resize 自动更新
+ * - 可配置分辨率缩放提升性能
+ * - 完善的资源释放管理
+ *
+ * @param renderer THREE.WebGLRenderer
+ * @param scene THREE.Scene
+ * @param camera THREE.Camera
+ * @param options PostProcessingOptions - 可选配置
+ * @returns PostProcessingManager - 包含 composer/outlinePass/resize/dispose 的管理接口
+ */
+declare function initPostProcessing(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, options?: PostProcessingOptions): PostProcessingManager;
+
+/**
+ * 点击处理器配置选项
+ */
+interface ClickHandlerOptions {
+    clickThreshold?: number;
+    debounceDelay?: number;
+    raycasterParams?: {
+        near?: number;
+        far?: number;
+        pointsPrecision?: number;
+    };
+    enableDynamicThickness?: boolean;
+    minThickness?: number;
+    maxThickness?: number;
+}
+/**
+ * 创建模型点击高亮工具（OutlinePass 版）- 优化版
+ *
+ * ✨ 功能增强：
+ * - 使用 AbortController 统一管理事件生命周期
+ * - 支持防抖处理避免频繁触发
+ * - 可自定义 Raycaster 参数
+ * - 根据相机距离动态调整描边厚度
+ *
+ * @param camera 相机
+ * @param scene 场景
+ * @param renderer 渲染器
+ * @param outlinePass 已初始化的 OutlinePass
+ * @param onClick 点击回调
+ * @param options 可选配置
+ * @returns dispose 函数，用于清理事件和资源
+ */
+declare function createModelClickHandler(camera: THREE.Camera, scene: THREE.Scene, renderer: THREE.WebGLRenderer, outlinePass: OutlinePass, onClick: (object: THREE.Object3D | null, info?: {
+    name?: string;
+    position?: THREE.Vector3;
+    uuid?: string;
+}) => void, options?: ClickHandlerOptions): () => void;
+
+type FilterFn = (obj: THREE.Object3D) => boolean;
+/**
+ * ArrowGuide - 优化版
+ * 箭头引导效果工具，支持高亮模型并淡化其他对象
+ *
+ * ✨ 优化内容：
+ * - 使用 WeakMap 自动回收材质，避免内存泄漏
+ * - 使用 AbortController 管理事件生命周期
+ * - 添加材质复用机制，减少重复创建
+ * - 改进 dispose 逻辑，确保完全释放资源
+ * - 添加错误处理和边界检查
+ */
+declare class ArrowGuide {
+    private renderer;
+    private camera;
+    private scene;
+    private lxMesh;
+    private flowActive;
+    private modelBrightArr;
+    private pointerDownPos;
+    private clickThreshold;
+    private raycaster;
+    private mouse;
+    private originalMaterials;
+    private fadedMaterials;
+    private abortController;
+    private ignoreRaycastNames;
+    private fadeOpacity;
+    private fadeBrightness;
+    constructor(renderer: THREE.WebGLRenderer, camera: THREE.Camera, scene: THREE.Scene, options?: {
+        clickThreshold?: number;
+        ignoreRaycastNames?: string[];
+        fadeOpacity?: number;
+        fadeBrightness?: number;
+    });
+    private cacheOriginalMaterial;
+    private makeFadedClone;
+    private createFadedMaterialFrom;
+    /**
+     * 设置箭头 Mesh
+     */
+    setArrowMesh(mesh: THREE.Mesh): void;
+    /**
+     * 高亮指定模型
+     */
+    highlight(models: THREE.Object3D[]): void;
+    private applyHighlight;
+    restore(): void;
+    /**
+     * 动画更新（每帧调用）
+     */
+    animate(): void;
+    /**
+     * 初始化事件监听器
+     */
+    private initEvents;
+    /**
+     * 释放所有资源
+     */
+    dispose(): void;
+}
+
+interface LiquidFillerOptions {
+    color?: number;
+    opacity?: number;
+    speed?: number;
+}
+/**
+ * LiquidFillerGroup - 优化版
+ * 支持单模型或多模型液位动画、独立颜色控制
+ *
+ * ✨ 优化内容：
+ * - 使用 renderer.domElement 替代 window 事件
+ * - 使用 AbortController 管理事件生命周期
+ * - 添加错误处理和边界检查
+ * - 优化动画管理，避免内存泄漏
+ * - 完善资源释放逻辑
+ */
+declare class LiquidFillerGroup {
+    private items;
+    private scene;
+    private camera;
+    private renderer;
+    private raycaster;
+    private pointerDownPos;
+    private clickThreshold;
+    private abortController;
+    /**
+     * 构造函数
+     * @param models 单个或多个 THREE.Object3D
+     * @param scene 场景
+     * @param camera 相机
+     * @param renderer 渲染器
+     * @param defaultOptions 默认液体选项
+     * @param clickThreshold 点击阈值，单位像素
+     */
+    constructor(models: THREE.Object3D | THREE.Object3D[], scene: THREE.Scene, camera: THREE.Camera, renderer: THREE.WebGLRenderer, defaultOptions?: LiquidFillerOptions, clickThreshold?: number);
+    /** pointerdown 记录位置 */
+    private handlePointerDown;
+    /** pointerup 判断点击空白，恢复原始材质 */
+    private handlePointerUp;
+    /**
+   * 设置液位
+   * @param models 单个模型或模型数组
+   * @param percent 液位百分比 0~1
+   */
+    fillTo(models: THREE.Object3D | THREE.Object3D[], percent: number): void;
+    /** 设置多个模型液位，percentList 与 items 顺序对应 */
+    fillToAll(percentList: number[]): void;
+    /** 恢复单个模型原始材质并移除液体 */
+    restore(model: THREE.Object3D): void;
+    /** 恢复所有模型 */
+    restoreAll(): void;
+    /** 销毁方法，释放事件和资源 */
+    dispose(): void;
+}
+
+interface FollowOptions {
+    duration?: number;
+    padding?: number;
+    minDistance?: number;
+    maxDistance?: number;
+    controls?: {
+        target?: THREE.Vector3;
+        update?: () => void;
+    } | null;
+    azimuth?: number;
+    elevation?: number;
+    easing?: 'linear' | 'easeInOut' | 'easeOut' | 'easeIn';
+    onProgress?: (progress: number) => void;
+}
+/**
+ * 推荐角度枚举，便于快速选取常见视角
+ */
+declare const FOLLOW_ANGLES: {
+    /** 等距斜视（默认视角）- 适合建筑、机械设备展示 */
+    readonly ISOMETRIC: {
+        readonly azimuth: number;
+        readonly elevation: number;
+    };
+    /** 正前视角 - 适合正面展示、UI 对齐 */
+    readonly FRONT: {
+        readonly azimuth: 0;
+        readonly elevation: 0;
+    };
+    /** 右侧视角 - 适合机械剖面、侧视检查 */
+    readonly RIGHT: {
+        readonly azimuth: number;
+        readonly elevation: 0;
+    };
+    /** 左侧视角 */
+    readonly LEFT: {
+        readonly azimuth: number;
+        readonly elevation: 0;
+    };
+    /** 后视角 */
+    readonly BACK: {
+        readonly azimuth: number;
+        readonly elevation: 0;
+    };
+    /** 顶视图 - 适合地图、平面布局展示 */
+    readonly TOP: {
+        readonly azimuth: 0;
+        readonly elevation: number;
+    };
+    /** 低角度俯视 - 适合车辆、人物等近地物体 */
+    readonly LOW_ANGLE: {
+        readonly azimuth: number;
+        readonly elevation: number;
+    };
+    /** 高角度俯视 - 适合鸟瞰、全景浏览 */
+    readonly HIGH_ANGLE: {
+        readonly azimuth: number;
+        readonly elevation: number;
+    };
+};
+/**
+ * 自动将相机移到目标的斜上角位置，并保证目标在可视范围内（平滑过渡）- 优化版
+ *
+ * ✨ 优化内容：
+ * - 支持多种缓动函数
+ * - 添加进度回调
+ * - 支持取消动画
+ * - WeakMap 跟踪防止泄漏
+ * - 完善错误处理
+ */
+declare function followModels(camera: THREE.Camera, targets: THREE.Object3D | THREE.Object3D[] | null | undefined, options?: FollowOptions): Promise<void>;
+/**
+ * ✨ 取消相机的跟随动画
+ */
+declare function cancelFollow(camera: THREE.Camera): void;
+
+/**
+ * 视角类型
+ */
+type ViewPosition = 'front' | 'back' | 'left' | 'right' | 'top' | 'bottom' | 'iso';
+/**
+ * 视角配置选项
+ */
+interface SetViewOptions {
+    distanceFactor?: number;
+    duration?: number;
+    easing?: 'linear' | 'easeInOut' | 'easeOut' | 'easeIn';
+    onProgress?: (progress: number) => void;
+}
+/**
+ * 平滑切换相机到模型的最佳视角 - 优化版
+ *
+ * ✨ 优化内容：
+ * - 复用 followModels 逻辑，避免代码重复
+ * - 支持更多视角
+ * - 配置选项增强
+ * - 返回 Promise 支持链式调用
+ * - 支持取消动画
+ *
+ * @param camera       THREE.PerspectiveCamera 相机实例
+ * @param controls     OrbitControls 控制器实例
+ * @param targetObj    THREE.Object3D 模型对象
+ * @param position     视角位置
+ * @param options      配置选项
+ * @returns Promise<void>
+ */
+declare function setView(camera: THREE.PerspectiveCamera, controls: OrbitControls, targetObj: THREE.Object3D, position?: ViewPosition, options?: SetViewOptions): Promise<void>;
+/**
+ * ✨ 取消视角切换动画
+ */
+declare function cancelSetView(camera: THREE.PerspectiveCamera): void;
+/**
+ * ✨ 预设视角快捷方法
+ */
+declare const ViewPresets: {
+    /**
+     * 前视图
+     */
+    front: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
+    /**
+     * 等距视图
+     */
+    isometric: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
+    /**
+     * 顶视图
+     */
+    top: (camera: THREE.PerspectiveCamera, controls: OrbitControls, target: THREE.Object3D, options?: SetViewOptions) => Promise<void>;
+};
+
+/** 加载参数：现在有默认值 */
+interface LoadOptions {
+    manager?: THREE.LoadingManager;
+    dracoDecoderPath?: string | null;
+    ktx2TranscoderPath?: string | null;
+    useKTX2?: boolean;
+    mergeGeometries?: boolean;
+    maxTextureSize?: number | null;
+    useSimpleMaterials?: boolean;
+    skipSkinned?: boolean;
+}
+declare function loadModelByUrl(url: string, options?: LoadOptions): Promise<THREE.Object3D>;
+/** 彻底释放对象：几何体，材质和其贴图（危险：共享资源会被释放） */
+declare function disposeObject(obj: THREE.Object3D | null): void;
+/** 释放材质及其贴图 */
+declare function disposeMaterial(mat: any): void;
+
+/**
+ * Skybox 加载工具
+ *
+ * 支持：
+ *  - 立方体贴图：paths: [px, nx, py, ny, pz, nz]
+ *  - 等距 / HDR 全景：url: 'path/to/scene.hdr' 或 jpg
+ *
+ * 返回一个 SkyboxHandle，包含对 scene 的修改记录和 dispose() 方法。
+ */
+/** 统一返回句柄 */
+type SkyboxHandle = {
+    key: string;
+    backgroundTexture: THREE.Texture | null;
+    envRenderTarget: THREE.WebGLRenderTarget | null;
+    pmremGenerator: THREE.PMREMGenerator | null;
+    setAsBackground: boolean;
+    setAsEnvironment: boolean;
+    /** 卸载并释放资源（如果是缓存共享，需要 refCount 逻辑） */
+    dispose: () => void;
+};
+/** 加载选项与默认值 */
+interface SkyboxOptions {
+    setAsBackground?: boolean;
+    setAsEnvironment?: boolean;
+    pmremGenerator?: THREE.PMREMGenerator | null;
+    useSRGBEncoding?: boolean;
+    cache?: boolean;
+}
+/**
+ * 加载立方体贴图（6张）
+ * @param renderer THREE.WebGLRenderer - 用于 PMREM 生成环境贴图
+ * @param scene THREE.Scene
+ * @param paths string[] 6 张图片地址，顺序：[px, nx, py, ny, pz, nz]
+ * @param opts SkyboxOptions
+ */
+declare function loadCubeSkybox(renderer: THREE.WebGLRenderer, scene: THREE.Scene, paths: string[], opts?: SkyboxOptions): Promise<SkyboxHandle>;
+/**
+ * 加载等距/单图（支持 HDR via RGBELoader）
+ * @param renderer THREE.WebGLRenderer
+ * @param scene THREE.Scene
+ * @param url string - *.hdr, *.exr, *.jpg, *.png
+ * @param opts SkyboxOptions
+ */
+declare function loadEquirectSkybox(renderer: THREE.WebGLRenderer, scene: THREE.Scene, url: string, opts?: SkyboxOptions): Promise<SkyboxHandle>;
+type LoadSkyboxParams = {
+    type: 'cube';
+    paths: string[];
+} | {
+    type: 'equirect';
+    url: string;
+};
+declare function loadSkybox(renderer: THREE.WebGLRenderer, scene: THREE.Scene, params: LoadSkyboxParams, opts?: SkyboxOptions): Promise<SkyboxHandle>;
+/** 释放一个缓存的 skybox（会减少 refCount，refCount=0 时才真正 dispose） */
+declare function releaseSkybox(handle: SkyboxHandle): void;
+
+/**
+ * 加载进度回调类型
+ */
+type LoadProgressCallback = (progress: number) => void;
+/**
+ * 加载选项
+ */
+interface LoadSkyOptions {
+    background?: boolean;
+    onProgress?: LoadProgressCallback;
+    onComplete?: () => void;
+    onError?: (error: any) => void;
+}
+/**
+ * BlueSkyManager - 优化版
+ * ---------------------------------------------------------
+ * 一个全局单例管理器，用于加载和管理基于 HDR/EXR 的蓝天白云环境贴图。
+ *
+ * ✨ 优化内容：
+ * - 添加加载进度回调
+ * - 支持加载取消
+ * - 完善错误处理
+ * - 返回 Promise 支持异步
+ * - 添加加载状态管理
+ */
+declare class BlueSkyManager {
+    /** three.js 渲染器实例 */
+    private renderer;
+    /** three.js 场景实例 */
+    private scene;
+    /** PMREM 生成器，用于将 HDR/EXR 转换为高效的反射贴图 */
+    private pmremGen;
+    /** 当前环境贴图的 RenderTarget，用于后续释放 */
+    private skyRT;
+    /** 是否已经初始化 */
+    private isInitialized;
+    /** ✨ 当前加载器，用于取消加载 */
+    private currentLoader;
+    /** ✨ 加载状态 */
+    private loadingState;
+    /**
+     * 初始化
+     * ---------------------------------------------------------
+     * 必须在使用 BlueSkyManager 之前调用一次。
+     * @param renderer WebGLRenderer 实例
+     * @param scene Three.js 场景
+     * @param exposure 曝光度 (默认 1.0)
+     */
+    init(renderer: THREE.WebGLRenderer, scene: THREE.Scene, exposure?: number): void;
+    /**
+     * ✨ 加载蓝天 HDR/EXR 贴图并应用到场景（Promise 版本）
+     * ---------------------------------------------------------
+     * @param exrPath HDR/EXR 文件路径
+     * @param options 加载选项
+     * @returns Promise<void>
+     */
+    loadAsync(exrPath: string, options?: LoadSkyOptions): Promise<void>;
+    /**
+     * 加载蓝天 HDR/EXR 贴图并应用到场景（同步 API，保持向后兼容）
+     * ---------------------------------------------------------
+     * @param exrPath HDR/EXR 文件路径
+     * @param background 是否应用为场景背景 (默认 true)
+     */
+    load(exrPath: string, background?: boolean): void;
+    /**
+     * ✨ 取消当前加载
+     */
+    cancelLoad(): void;
+    /**
+     * ✨ 获取加载状态
+     */
+    getLoadingState(): 'idle' | 'loading' | 'loaded' | 'error';
+    /**
+     * ✨ 是否正在加载
+     */
+    isLoading(): boolean;
+    /**
+     * 释放当前的天空贴图资源
+     * ---------------------------------------------------------
+     * 仅清理 skyRT，不销毁 PMREM
+     * 适用于切换 HDR/EXR 文件时调用
+     */
+    dispose(): void;
+    /**
+     * 完全销毁 BlueSkyManager
+     * ---------------------------------------------------------
+     * 包括 PMREMGenerator 的销毁
+     * 通常在场景彻底销毁或应用退出时调用
+     */
+    destroy(): void;
+}
+/**
+ * 🌐 全局单例
+ * ---------------------------------------------------------
+ * 直接导出一个全局唯一的 BlueSkyManager 实例，
+ * 保证整个应用中只用一个 PMREMGenerator，性能最佳。
+ */
+declare const BlueSky: BlueSkyManager;
+
+interface LabelOptions {
+    fontSize?: string;
+    color?: string;
+    background?: string;
+    padding?: string;
+    borderRadius?: string;
+    lift?: number;
+    dotSize?: number;
+    dotSpacing?: number;
+    lineColor?: string;
+    lineWidth?: number;
+    updateInterval?: number;
+    fadeInDuration?: number;
+}
+interface LabelManager {
+    updateModel: (model: THREE.Object3D) => void;
+    updateLabelsMap: (map: Record<string, string>) => void;
+    pause: () => void;
+    resume: () => void;
+    dispose: () => void;
+}
+/**
+ * 创建模型标签（带连线和脉冲圆点）- 优化版
+ *
+ * ✨ 优化内容：
+ * - 支持暂停/恢复更新
+ * - 可配置更新间隔
+ * - 淡入淡出效果
+ * - 缓存包围盒计算
+ * - RAF 管理优化
+ */
+declare function createModelsLabel(camera: THREE.Camera, renderer: THREE.WebGLRenderer, parentModel: THREE.Object3D, modelLabelsMap: Record<string, string>, options?: LabelOptions): LabelManager;
+
+/**
+ * GroupExploder - 基于 Three.js 的模型爆炸效果工具（支持 Vue3 + TS）
+ * ----------------------------------------------------------------------
+ * 该工具用于对指定 Mesh 的集合进行“爆炸 / 还原”动画：
+ *  - 仅初始化一次（onMounted）
+ *  - 支持动态切换模型并自动还原上一个模型的爆炸状态
+ *  - 支持多种排列模式（ring / spiral / grid / radial）
+ *  - 支持非爆炸对象自动透明化（dimOthers）
+ *  - 支持摄像机自动前置定位到最佳观察点
+ *  - 所有动画均采用原生 requestAnimationFrame 实现
+ *
+ * ----------------------------------------------------------------------
+ * 🔧 构造参数
+ * ----------------------------------------------------------------------
+ * @param scene      Three.js 场景实例
+ * @param camera     Three.js 相机（一般为 PerspectiveCamera）
+ * @param controls   OrbitControls 控件实例（必须绑定 camera）
+ *
+ * ----------------------------------------------------------------------
+ * 🔥 爆炸参数 ExplodeOptions
+ * ----------------------------------------------------------------------
+ * 所有参数均可在 explode() 调用时指定，也可设置默认值。
+ *
+ * type ArrangeMode = 'ring' | 'spiral' | 'grid' | 'radial'
+ *
+ * @param mode?: ArrangeMode
+ *        爆炸排列方式：
+ *        - 'ring'   环形排列（默认）
+ *        - 'spiral' 螺旋上升排列
+ *        - 'grid'   平面网格排列（规则整齐）
+ *        - 'radial' 从中心点向外扩散
+ *
+ * @param spacing?: number
+ *        相邻爆炸对象之间的间距（默认：2.5）
+ *
+ * @param duration?: number
+ *        爆炸动画时长（ms），原生 rAF 完成（默认：1000）
+ *
+ * @param lift?: number
+ *        爆炸对象整体抬升的高度因子，用于让爆炸看起来更立体（默认：0.6）
+ *
+ * @param cameraPadding?: number
+ *        摄像机贴合爆炸后包围球时的额外安全距离（默认：1.2）
+ *
+ * @param autoRestorePrev?: boolean
+ *        当切换模型时，是否自动 restore 上一个模型的爆炸元素（默认：true）
+ *
+ * @param dimOthers?: { enabled: boolean; opacity?: number }
+ *        非爆炸对象透明化配置：
+ *        - enabled: true   开启
+ *        - opacity: number 指定非爆炸对象透明度（默认：0.15）
+ *
+ * @param debug?: boolean
+ *        是否开启调试日志，输出所有内部状态（默认 false）
+ *
+ *
+ * ----------------------------------------------------------------------
+ * 📌 方法说明
+ * ----------------------------------------------------------------------
+ *
+ * ◆ setMeshes(meshSet: Set<Mesh>, contextId?: string)
+ *    设置当前模型的爆炸 Mesh 集合：
+ *      - 会记录 Mesh 的初始 transform
+ *      - 根据 autoRestorePrev 自动还原上次爆炸
+ *      - 第二个参数 contextId 可选，用于区分业务场景
+ *
+ *
+ * ◆ explode(options?: ExplodeOptions)
+ *    对当前 meshSet 执行爆炸动画：
+ *      - 根据 mode 生成爆炸布局
+ *      - 相机先自动飞向最佳观察点
+ *      - 执行 mesh 位移动画
+ *      - 按需将非爆炸模型透明化
+ *
+ *
+ * ◆ restore(duration?: number)
+ *    还原所有爆炸 Mesh 到爆炸前的 transform：
+ *      - 支持平滑动画
+ *      - 自动取消透明化
+ *
+ *
+ * ◆ dispose()
+ *    移除事件监听、取消动画、清理引用（在组件销毁时调用）
+ *
+ *
+ * ----------------------------------------------------------------------
+ * 🎨 排列模式说明
+ * ----------------------------------------------------------------------
+ *
+ * 1. Ring（环形）
+ *    - 按圆均匀分布
+ *    - spacing 控制半径
+ *    - lift 控制整体抬起高度
+ *
+ * 2. Spiral（螺旋）
+ *    - 在环形基础上添加高度递增（y++)
+ *    - 数量大时视觉效果最强
+ *
+ * 3. Grid（网格）
+ *    - 类似棋盘布局
+ *    - spacing 控制网格大小
+ *    - z 不变或小幅度变化
+ *
+ * 4. Radial（径向扩散）
+ *    - 从中心向外 “爆炸式” 发散
+ *    - 对于大型组件分解展示非常适合
+ *
+ *
+ * ----------------------------------------------------------------------
+ * 📌 使用示例（业务层 Vue）
+ * ----------------------------------------------------------------------
+ *
+ * const exploder = new GroupExploder(scene, camera, controls);
+ *
+ * onMounted(() => {
+ *   exploder.setMeshes(new Set([meshA, meshB, meshC]));
+ * });
+ *
+ * const triggerExplode = () => {
+ *   exploder.explode({
+ *     mode: 'ring',
+ *     spacing: 3,
+ *     duration: 1200,
+ *     lift: 0.8,
+ *     cameraPadding: 1.3,
+ *     dimOthers: { enabled: true, opacity: 0.2 },
+ *   });
+ * };
+ *
+ * const triggerRestore = () => {
+ *   exploder.restore(600);
+ * };
+ *
+ */
+
+type ArrangeMode = 'ring' | 'spiral' | 'grid' | 'radial';
+type ExplodeOptions = {
+    mode?: ArrangeMode;
+    spacing?: number;
+    duration?: number;
+    lift?: number;
+    cameraPadding?: number;
+    autoRestorePrev?: boolean;
+    dimOthers?: {
+        enabled: boolean;
+        opacity?: number;
+    };
+    debug?: boolean;
+};
+declare class GroupExploder {
+    private scene;
+    private camera;
+    private controls?;
+    private currentSet;
+    private stateMap;
+    private prevSet;
+    private prevStateMap;
+    private materialContexts;
+    private materialSnaps;
+    private contextMaterials;
+    private animId;
+    private cameraAnimId;
+    private isExploded;
+    private isInitialized;
+    onLog?: (s: string) => void;
+    constructor(scene: THREE.Scene, camera: THREE.PerspectiveCamera | THREE.Camera, controls?: {
+        target?: THREE.Vector3;
+        update?: () => void;
+    });
+    private log;
+    init(): void;
+    /**
+     * setMeshes(newSet):
+     * - Detects content-level changes even if same Set reference is used.
+     * - Preserves prevSet/stateMap to allow async restore when needed.
+     * - Ensures stateMap contains snapshots for *all meshes in the new set*.
+     */
+    setMeshes(newSet: Set<THREE.Mesh> | null, options?: {
+        autoRestorePrev?: boolean;
+        restoreDuration?: number;
+    }): Promise<void>;
+    /**
+     * ensureSnapshotsForSet: for each mesh in set, ensure stateMap has an entry.
+     * If missing, record current matrixWorld as originalMatrixWorld (best-effort).
+     */
+    private ensureSnapshotsForSet;
+    /**
+     * explode: compute targets first, compute targetBound using targets + mesh radii,
+     * animate camera to that targetBound, then animate meshes to targets.
+     */
+    explode(opts?: ExplodeOptions): Promise<void>;
+    restore(duration?: number): Promise<void>;
+    /**
+     * restoreSet: reparent and restore transforms using provided stateMap.
+     * If missing stateMap entry for a mesh, use fallbacks:
+     *  1) mesh.userData.__originalMatrixWorld (if present)
+     *  2) mesh.matrixWorld (current) -> smooth lerp to itself (no-op visually)
+     */
+    private restoreSet;
+    private applyDimToOthers;
+    private cleanContextsForMeshes;
+    private computeBoundingSphereForMeshes;
+    private computeBoundingSphereForPositionsAndMeshes;
+    private computeTargetsByMode;
+    private animateCameraToFit;
+    private getCameraLookAtPoint;
+    private cancelAnimations;
+    dispose(restoreBefore?: boolean): Promise<void>;
+}
+
+interface AutoSetupOptions {
+    /** 相机在包围球基础上的额外填充倍数（>1 扩大可视范围） */
+    padding?: number;
+    /** 相机仰角偏移（弧度），默认小俯视（0.2 rad ≈ 11°） */
+    elevation?: number;
+    /** 是否启用阴影（shadow） - 性能开销大，默认 false */
+    enableShadows?: boolean;
+    /** 阴影贴图尺寸，越高越清晰越耗性能，默认 1024 */
+    shadowMapSize?: number;
+    /** DirectionalLights 的数量（均匀分布在四面） */
+    directionalCount?: number;
+    /** 是否自动把 mesh.castShadow / mesh.receiveShadow 设置为 true（默认 true） */
+    setMeshShadowProps?: boolean;
+    /** 如果传入 renderer，则工具会自动启用 renderer.shadowMap（如果 enableShadows 为 true） */
+    renderer?: THREE.WebGLRenderer | null;
+}
+/**
+ * 返回值句柄，包含 created lights group、computed center/radius、以及 dispose 方法
+ */
+type AutoSetupHandle = {
+    lightsGroup: THREE.Group;
+    center: THREE.Vector3;
+    radius: number;
+    dispose: () => void;
+    updateLightIntensity: (factor: number) => void;
+};
+/**
+ * 自动设置相机与基础灯光 - 优化版
+ *
+ * ✨ 优化内容：
+ * - 添加灯光强度调整方法
+ * - 完善错误处理
+ * - 优化dispose逻辑
+ *
+ * - camera: THREE.PerspectiveCamera（会被移动并指向模型中心）
+ * - scene: THREE.Scene（会把新创建的 light group 加入 scene）
+ * - model: THREE.Object3D 已加载的模型（任意 transform/坐标）
+ * - options: 可选配置（见 AutoSetupOptions）
+ *
+ * 返回 AutoSetupHandle，调用方在组件卸载/切换时请调用 handle.dispose()
+ */
+declare function autoSetupCameraAndLight(camera: THREE.PerspectiveCamera, scene: THREE.Scene, model: THREE.Object3D, options?: AutoSetupOptions): AutoSetupHandle;
+
+/**
+ * three-model-render
+ * Professional Three.js Model Visualization and Interaction Toolkit
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "1.0.0";
+
+export { ArrowGuide, BlueSky, FOLLOW_ANGLES, GroupExploder, LiquidFillerGroup, VERSION, ViewPresets, addChildModelLabels, autoSetupCameraAndLight, cancelFollow, cancelSetView, createModelClickHandler, createModelsLabel, disposeMaterial, disposeObject, enableHoverBreath, followModels, initPostProcessing, loadCubeSkybox, loadEquirectSkybox, loadModelByUrl, loadSkybox, releaseSkybox, setView };
+export type { AutoSetupHandle, AutoSetupOptions, ClickHandlerOptions, ExplodeOptions, FilterFn, FollowOptions, HoverBreathOptions, LiquidFillerOptions, LoadOptions, LoadProgressCallback, LoadSkyOptions, LoadSkyboxParams, PostProcessingManager, PostProcessingOptions, SetViewOptions, SkyboxHandle, SkyboxOptions, ViewPosition };