@chocozhang/three-model-render 1.0.1

package/dist/loader/index.js

@@ -0,0 +1,786 @@
+'use strict';
+
+var THREE = require('three');
+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);
+
+/******************************************************************************
+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();
+
+exports.BlueSky = BlueSky;
+exports.disposeMaterial = disposeMaterial;
+exports.disposeObject = disposeObject;
+exports.loadCubeSkybox = loadCubeSkybox;
+exports.loadEquirectSkybox = loadEquirectSkybox;
+exports.loadModelByUrl = loadModelByUrl;
+exports.loadSkybox = loadSkybox;
+exports.releaseSkybox = releaseSkybox;
+//# sourceMappingURL=index.js.map