@chocozhang/three-model-render 1.0.3 → 1.0.5

package/dist/loader/index.mjs

@@ -1,163 +1,166 @@
 import * as THREE from 'three';
 import { EXRLoader } from 'three/examples/jsm/loaders/EXRLoader.js';
 
-/******************************************************************************
-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;
+let globalConfig = {
+    dracoDecoderPath: '/draco/',
+    ktx2TranscoderPath: '/basis/',
 };
+/**
+ * Update global loader configuration (e.g., set path to CDN)
+ */
+function setLoaderConfig(config) {
+    globalConfig = { ...globalConfig, ...config };
+}
+/**
+ * Get current global loader configuration
+ */
+function getLoaderConfig() {
+    return globalConfig;
+}
 
+/**
+ * @file modelLoader.ts
+ * @description
+ * Utility to load 3D models (GLTF, FBX, OBJ, PLY, STL) from URLs.
+ *
+ * @best-practice
+ * - Use `loadModelByUrl` for a unified loading interface.
+ * - Supports Draco compression and KTX2 textures for GLTF.
+ * - Includes optimization options like geometry merging and texture downscaling.
+ */
 const DEFAULT_OPTIONS$1 = {
     useKTX2: false,
     mergeGeometries: false,
     maxTextureSize: null,
     useSimpleMaterials: false,
     skipSkinned: true,
+    useCache: true,
 };
-/** 自动根据扩展名决定启用哪些选项（智能判断） */
+const modelCache = new Map();
+/** Automatically determine which options to enable based on extension (smart judgment) */
 function normalizeOptions(url, opts) {
     const ext = (url.split('.').pop() || '').toLowerCase();
-    const merged = Object.assign(Object.assign({}, DEFAULT_OPTIONS$1), opts);
+    const merged = { ...DEFAULT_OPTIONS$1, ...opts };
     if (ext === 'gltf' || ext === 'glb') {
-        // gltf/glb 默认尝试 draco/ktx2，如果用户没填
+        const globalConfig = getLoaderConfig();
+        // gltf/glb defaults to trying draco/ktx2 if user didn't specify
         if (merged.dracoDecoderPath === undefined)
-            merged.dracoDecoderPath = '/draco/';
+            merged.dracoDecoderPath = globalConfig.dracoDecoderPath;
         if (merged.useKTX2 === undefined)
             merged.useKTX2 = true;
         if (merged.ktx2TranscoderPath === undefined)
-            merged.ktx2TranscoderPath = '/basis/';
+            merged.ktx2TranscoderPath = globalConfig.ktx2TranscoderPath;
     }
     else {
-        // fbx/obj/ply/stl 等不需要 draco/ktx2
+        // fbx/obj/ply/stl etc. do not need 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.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);
+async function loadModelByUrl(url, options = {}) {
+    if (!url)
+        throw new Error('url required');
+    const ext = (url.split('.').pop() || '').toLowerCase();
+    const opts = normalizeOptions(url, options);
+    const manager = opts.manager ?? new THREE.LoadingManager();
+    // Cache key includes URL and relevant optimization options
+    const cacheKey = `${url}_${opts.mergeGeometries}_${opts.maxTextureSize}_${opts.useSimpleMaterials}`;
+    if (opts.useCache && modelCache.has(cacheKey)) {
+        return modelCache.get(cacheKey).clone();
+    }
+    let loader;
+    if (ext === 'gltf' || ext === 'glb') {
+        const { GLTFLoader } = await import('three/examples/jsm/loaders/GLTFLoader.js');
+        const gltfLoader = new GLTFLoader(manager);
+        if (opts.dracoDecoderPath) {
+            const { DRACOLoader } = await import('three/examples/jsm/loaders/DRACOLoader.js');
+            const draco = new DRACOLoader();
+            draco.setDecoderPath(opts.dracoDecoderPath);
+            gltfLoader.setDRACOLoader(draco);
         }
-        else {
-            throw new Error(`Unsupported model extension: .${ext}`);
+        if (opts.useKTX2 && opts.ktx2TranscoderPath) {
+            const { KTX2Loader } = await import('three/examples/jsm/loaders/KTX2Loader.js');
+            const ktx2Loader = new KTX2Loader().setTranscoderPath(opts.ktx2TranscoderPath);
+            gltfLoader.__ktx2Loader = ktx2Loader;
         }
-        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.BufferGeometry()).fromGeometry) === null || _b === void 0 ? void 0 : _b.call(_a, mesh.geometry)) !== null && _c !== void 0 ? _c : mesh.geometry;
-                }
-                catch (_d) { }
+        loader = gltfLoader;
+    }
+    else if (ext === 'fbx') {
+        const { FBXLoader } = await import('three/examples/jsm/loaders/FBXLoader.js');
+        loader = new FBXLoader(manager);
+    }
+    else if (ext === 'obj') {
+        const { OBJLoader } = await import('three/examples/jsm/loaders/OBJLoader.js');
+        loader = new OBJLoader(manager);
+    }
+    else if (ext === 'ply') {
+        const { PLYLoader } = await import('three/examples/jsm/loaders/PLYLoader.js');
+        loader = new PLYLoader(manager);
+    }
+    else if (ext === 'stl') {
+        const { STLLoader } = await import('three/examples/jsm/loaders/STLLoader.js');
+        loader = new STLLoader(manager);
+    }
+    else {
+        throw new Error(`Unsupported model extension: .${ext}`);
+    }
+    const object = await new Promise((resolve, reject) => {
+        loader.load(url, (res) => {
+            if (ext === 'gltf' || ext === 'glb') {
+                const sceneObj = res.scene || res;
+                // --- Critical: Expose animations to scene.userData (or scene.animations) ---
+                // So the caller can access clips simply by getting sceneObj.userData.animations
+                sceneObj.userData = sceneObj?.userData || {};
+                sceneObj.userData.animations = res.animations ?? [];
+                resolve(sceneObj);
             }
-        });
-        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 });
+            else {
+                resolve(res);
             }
-            catch (e) {
-                console.warn('mergeGeometries failed', e);
+        }, undefined, (err) => reject(err));
+    });
+    // Optimize
+    object.traverse((child) => {
+        const mesh = child;
+        if (mesh.isMesh && mesh.geometry && !mesh.geometry.isBufferGeometry) {
+            try {
+                mesh.geometry = new THREE.BufferGeometry().fromGeometry?.(mesh.geometry) ?? mesh.geometry;
             }
+            catch { }
         }
-        return object;
     });
+    if (opts.maxTextureSize && opts.maxTextureSize > 0)
+        await 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 {
+            await tryMergeGeometries(object, { skipSkinned: opts.skipSkinned ?? true });
+        }
+        catch (e) {
+            console.warn('mergeGeometries failed', e);
+        }
+    }
+    if (opts.useCache) {
+        modelCache.set(cacheKey, object);
+        return object.clone();
+    }
+    return object;
 }
-/** 运行时下采样网格中的贴图到 maxSize（canvas drawImage）以节省 GPU 内存 */
-function downscaleTexturesInObject(obj, maxSize) {
+/** Runtime downscale textures in mesh to maxSize (createImageBitmap or canvas) to save GPU memory */
+async function downscaleTexturesInObject(obj, maxSize) {
+    const tasks = [];
     obj.traverse((ch) => {
         if (!ch.isMesh)
             return;
@@ -176,115 +179,128 @@ function downscaleTexturesInObject(obj, maxSize) {
             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.Texture(canvas);
-                    newTex.needsUpdate = true;
-                    // copy common settings (encoding etc)
-                    newTex.encoding = tex.encoding;
-                    mat[p] = newTex;
+            tasks.push((async () => {
+                try {
+                    const scale = Math.min(max / image.width, max / image.height);
+                    const newWidth = Math.floor(image.width * scale);
+                    const newHeight = Math.floor(image.height * scale);
+                    let newSource;
+                    if (typeof createImageBitmap !== 'undefined') {
+                        newSource = await createImageBitmap(image, {
+                            resizeWidth: newWidth,
+                            resizeHeight: newHeight,
+                            resizeQuality: 'high'
+                        });
+                    }
+                    else {
+                        // Fallback for environments without createImageBitmap
+                        const canvas = document.createElement('canvas');
+                        canvas.width = newWidth;
+                        canvas.height = newHeight;
+                        const ctx = canvas.getContext('2d');
+                        if (ctx) {
+                            ctx.drawImage(image, 0, 0, newWidth, newHeight);
+                            newSource = canvas;
+                        }
+                    }
+                    if (newSource) {
+                        const newTex = new THREE.Texture(newSource);
+                        newTex.needsUpdate = true;
+                        newTex.encoding = tex.encoding;
+                        mat[p] = newTex;
+                    }
                 }
-            }
-            catch (e) {
-                console.warn('downscale texture failed', e);
-            }
+                catch (e) {
+                    console.warn('downscale texture failed', e);
+                }
+            })());
         });
     });
+    await Promise.all(tasks);
 }
 /**
- * 尝试合并 object 中的几何体（只合并：非透明、非 SkinnedMesh、attribute 集合兼容的 BufferGeometry）
- * - 合并前会把每个 mesh 的几何体应用 world matrix（so merged geometry in world space）
- * - 合并会按材质 UUID 分组（不同材质不能合并）
- * - 合并函数会兼容 BufferGeometryUtils 的常见导出名
+ * Try to merge geometries in object (Only merge: non-transparent, non-SkinnedMesh, attribute compatible BufferGeometry)
+ * - Before merging, apply world matrix to each mesh's geometry (so merged geometry is in world space)
+ * - Merging will group by material UUID (different materials cannot be merged)
+ * - Merge function is compatible with common export names of 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.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)
+async function tryMergeGeometries(root, opts) {
+    // collect meshes by material uuid
+    const groups = new Map();
+    root.traverse((ch) => {
+        if (!ch.isMesh)
             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.Mesh(merged, material);
-            root.add(mergedMesh);
+        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 = groups.get(key) ?? { material: mat ?? new THREE.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 = await 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;
         }
-        // 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
+        // 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.Mesh(merged, material);
+        root.add(mergedMesh);
+    }
+    // now remove original meshes flagged for removal
+    const toRemove = [];
+    root.traverse((ch) => {
+        if (ch.userData?.__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 { }
+            // we do NOT dispose material because it may be reused by mergedMesh
+        }
     });
 }
 /* ---------------------
-   释放工具
+   Dispose Utils
    --------------------- */
-/** 彻底释放对象：几何体，材质和其贴图（危险：共享资源会被释放） */
+/** Completely dispose object: geometry, material and its textures (Danger: shared resources will be disposed) */
 function disposeObject(obj) {
     if (!obj)
         return;
@@ -295,7 +311,7 @@ function disposeObject(obj) {
                 try {
                     m.geometry.dispose();
                 }
-                catch (_a) { }
+                catch { }
             }
             const mat = m.material;
             if (mat) {
@@ -307,7 +323,7 @@ function disposeObject(obj) {
         }
     });
 }
-/** 释放材质及其贴图 */
+/** Dispose material and its textures */
 function disposeMaterial(mat) {
     if (!mat)
         return;
@@ -317,232 +333,244 @@ function disposeMaterial(mat) {
             try {
                 mat[k].dispose();
             }
-            catch (_a) { }
+            catch { }
         }
     });
     try {
         if (typeof mat.dispose === 'function')
             mat.dispose();
     }
-    catch (_a) { }
+    catch { }
+}
+// Helper to convert to simple material (stub)
+function toSimpleMaterial(mat) {
+    // Basic implementation, preserve color/map
+    const m = new THREE.MeshBasicMaterial();
+    if (mat.color)
+        m.color.copy(mat.color);
+    if (mat.map)
+        m.map = mat.map;
+    return m;
 }
 
-/** 默认值 */
+/**
+ * @file skyboxLoader.ts
+ * @description
+ * Utility for loading skyboxes (CubeTexture or Equirectangular/HDR).
+ *
+ * @best-practice
+ * - Use `loadSkybox` for a unified interface.
+ * - Supports internal caching to avoid reloading the same skybox.
+ * - Can set background and environment map independently.
+ */
+/** Default Values */
 const DEFAULT_OPTIONS = {
     setAsBackground: true,
     setAsEnvironment: true,
     useSRGBEncoding: true,
     cache: true
 };
-/** 内部缓存：key -> { handle, refCount } */
+/** Internal Cache: key -> { handle, refCount } */
 const cubeCache = new Map();
 const equirectCache = new Map();
 /* -------------------------------------------
-   公共函数：加载 skybox（自动选 cube 或 equirect）
+   Public Function: Load skybox (Automatically choose cube or equirect)
    ------------------------------------------- */
 /**
- * 加载立方体贴图（6张）
- * @param renderer THREE.WebGLRenderer - 用于 PMREM 生成环境贴图
+ * Load Cube Texture (6 images)
+ * @param renderer THREE.WebGLRenderer - Used for PMREM generating environment map
  * @param scene THREE.Scene
- * @param paths string[] 6 张图片地址，顺序：[px, nx, py, ny, pz, nz]
+ * @param paths string[] 6 image paths, order: [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.CubeTextureLoader();
-        const texture = yield new Promise((resolve, reject) => {
-            loader.load(paths, (tex) => resolve(tex), undefined, (err) => reject(err));
-        });
-        // 设置编码与映射
-        if (options.useSRGBEncoding)
-            texture.encoding = THREE.sRGBEncoding;
-        texture.mapping = THREE.CubeReflectionMapping;
-        // apply as background if required
+async function loadCubeSkybox(renderer, scene, paths, opts = {}) {
+    const options = { ...DEFAULT_OPTIONS, ...opts };
+    if (!Array.isArray(paths) || paths.length !== 6)
+        throw new Error('cube skybox requires 6 image paths');
+    const key = paths.join('|');
+    // Cache handling
+    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 = 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.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);
+            scene.background = rec.handle.backgroundTexture;
+        if (options.setAsEnvironment && rec.handle.envRenderTarget)
+            scene.environment = rec.handle.envRenderTarget.texture;
+        return rec.handle;
+    }
+    // Load cube texture
+    const loader = new THREE.CubeTextureLoader();
+    const texture = await new Promise((resolve, reject) => {
+        loader.load(paths, (tex) => resolve(tex), undefined, (err) => reject(err));
+    });
+    // Set encoding and mapping
+    if (options.useSRGBEncoding)
+        texture.encoding = THREE.sRGBEncoding;
+    texture.mapping = THREE.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 = options.pmremGenerator ?? new THREE.PMREMGenerator(renderer);
+    pmremGenerator.compileCubemapShader?.( /* optional */);
+    // 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: 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;
+            // fallback: use cube texture directly (works but not prefiltered)
+            scene.environment = texture;
         }
-        if (options.setAsEnvironment) {
+    }
+    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) {
-                scene.environment = envRenderTarget.texture;
+                try {
+                    envRenderTarget.dispose();
+                }
+                catch { }
             }
-            else {
-                // fallback: use cube texture directly (works but not prefiltered)
-                scene.environment = texture;
+            try {
+                texture.dispose();
             }
-        }
-        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) { }
-                }
+            catch { }
+            // dispose pmremGenerator we created
+            if (!options.pmremGenerator && pmremGenerator) {
                 try {
-                    texture.dispose();
-                }
-                catch (_b) { }
-                // dispose pmremGenerator we created
-                if (!options.pmremGenerator && pmremGenerator) {
-                    try {
-                        pmremGenerator.dispose();
-                    }
-                    catch (_c) { }
+                    pmremGenerator.dispose();
                 }
+                catch { }
             }
-        };
-        if (options.cache)
-            cubeCache.set(key, { handle, refCount: 1 });
-        return handle;
-    });
+        }
+    };
+    if (options.cache)
+        cubeCache.set(key, { handle, refCount: 1 });
+    return handle;
 }
 /**
- * 加载等距/单图（支持 HDR via RGBELoader）
+ * Load Equirectangular/Single Image (Supports 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.LinearEncoding;
-        }
-        else {
-            // ordinary image - use TextureLoader
-            const loader = new THREE.TextureLoader();
-            hdrTexture = yield new Promise((resolve, reject) => {
-                loader.load(url, (t) => resolve(t), undefined, (err) => reject(err));
-            });
-            if (options.useSRGBEncoding)
-                hdrTexture.encoding = THREE.sRGBEncoding;
-        }
-        // PMREMGenerator to convert equirectangular to prefiltered cubemap (good for PBR)
-        const pmremGenerator = (_a = options.pmremGenerator) !== null && _a !== void 0 ? _a : new THREE.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;
+async function loadEquirectSkybox(renderer, scene, url, opts = {}) {
+    const options = { ...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;
+    }
+    // Dynamically import RGBELoader (for .hdr/.exr), if loading normal jpg/png directly use TextureLoader
+    const isHDR = /\.hdr$|\.exr$/i.test(url);
+    let hdrTexture;
+    if (isHDR) {
+        const { RGBELoader } = await import('three/examples/jsm/loaders/RGBELoader.js');
+        hdrTexture = await new Promise((resolve, reject) => {
+            new RGBELoader().load(url, (tex) => resolve(tex), undefined, (err) => reject(err));
+        });
+        // RGBE textures typically use LinearEncoding
+        hdrTexture.encoding = THREE.LinearEncoding;
+    }
+    else {
+        // ordinary image - use TextureLoader
+        const loader = new THREE.TextureLoader();
+        hdrTexture = await new Promise((resolve, reject) => {
+            loader.load(url, (t) => resolve(t), undefined, (err) => reject(err));
+        });
+        if (options.useSRGBEncoding)
+            hdrTexture.encoding = THREE.sRGBEncoding;
+    }
+    // PMREMGenerator to convert equirectangular to prefiltered cubemap (good for PBR)
+    const pmremGenerator = options.pmremGenerator ?? new THREE.PMREMGenerator(renderer);
+    pmremGenerator.compileEquirectangularShader?.();
+    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 { }
+    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 { }
+            if (!options.pmremGenerator && pmremGenerator) {
                 try {
-                    envRenderTarget.dispose();
-                }
-                catch (_a) { }
-                if (!options.pmremGenerator && pmremGenerator) {
-                    try {
-                        pmremGenerator.dispose();
-                    }
-                    catch (_b) { }
+                    pmremGenerator.dispose();
                 }
+                catch { }
             }
-        };
-        if (options.cache)
-            equirectCache.set(key, { handle, refCount: 1 });
-        return handle;
-    });
+        }
+    };
+    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);
-    });
+async function loadSkybox(renderer, scene, params, opts = {}) {
+    if (params.type === 'cube')
+        return loadCubeSkybox(renderer, scene, params.paths, opts);
+    return loadEquirectSkybox(renderer, scene, params.url, opts);
 }
 /* -------------------------
-   缓存/引用计数 辅助方法
+   Cache / Reference Counting Helper Methods
    ------------------------- */
-/** 释放一个缓存的 skybox（会减少 refCount，refCount=0 时才真正 dispose） */
+/** Release a cached skybox (decrements refCount, only truly disposes when refCount=0) */
 function releaseSkybox(handle) {
     // check cube cache
     if (cubeCache.has(handle.key)) {
@@ -567,85 +595,94 @@ function releaseSkybox(handle) {
     // handle.dispose()
 }
 
-// utils/BlueSkyManager.ts - 优化版
 /**
- * BlueSkyManager - 优化版
+ * @file blueSkyManager.ts
+ * @description
+ * Global singleton manager for loading and managing HDR/EXR blue sky environment maps.
+ *
+ * @best-practice
+ * - Call `init` once before use.
+ * - Use `loadAsync` to load skyboxes with progress tracking.
+ * - Automatically handles PMREM generation for realistic lighting.
+ */
+/**
+ * BlueSkyManager - Optimized
  * ---------------------------------------------------------
- * 一个全局单例管理器，用于加载和管理基于 HDR/EXR 的蓝天白云环境贴图。
+ * A global singleton manager for loading and managing HDR/EXR based blue sky environment maps.
  *
- * ✨ 优化内容：
- * - 添加加载进度回调
- * - 支持加载取消
- * - 完善错误处理
- * - 返回 Promise 支持异步
- * - 添加加载状态管理
+ * Features:
+ * - Adds load progress callback
+ * - Supports load cancellation
+ * - Improved error handling
+ * - Returns Promise for async operation
+ * - Adds loading state management
  */
 class BlueSkyManager {
     constructor() {
-        /** 当前环境贴图的 RenderTarget，用于后续释放 */
+        /** RenderTarget for current environment map, used for subsequent disposal */
         this.skyRT = null;
-        /** 是否已经初始化 */
+        /** Whether already initialized */
         this.isInitialized = false;
-        /** ✨ 当前加载器，用于取消加载 */
+        /** Current loader, used for cancelling load */
         this.currentLoader = null;
-        /** ✨ 加载状态 */
+        /** Loading state */
         this.loadingState = 'idle';
     }
     /**
-     * 初始化
+     * Initialize
      * ---------------------------------------------------------
-     * 必须在使用 BlueSkyManager 之前调用一次。
-     * @param renderer WebGLRenderer 实例
-     * @param scene Three.js 场景
-     * @param exposure 曝光度 (默认 1.0)
+     * Must be called once before using BlueSkyManager.
+     * @param renderer WebGLRenderer instance
+     * @param scene Three.js Scene
+     * @param exposure Exposure (default 1.0)
      */
     init(renderer, scene, exposure = 1.0) {
         if (this.isInitialized) {
-            console.warn('BlueSkyManager: 已经初始化，跳过重复初始化');
+            console.warn('BlueSkyManager: Already initialized, skipping duplicate initialization');
             return;
         }
         this.renderer = renderer;
         this.scene = scene;
-        // 使用 ACESFilmicToneMapping，效果更接近真实
+        // Use ACESFilmicToneMapping, effect is closer to reality
         this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
         this.renderer.toneMappingExposure = exposure;
-        // 初始化 PMREM 生成器（全局只需一个）
+        // Initialize PMREM generator (only one needed globally)
         this.pmremGen = new THREE.PMREMGenerator(renderer);
         this.pmremGen.compileEquirectangularShader();
         this.isInitialized = true;
     }
     /**
-     * ✨ 加载蓝天 HDR/EXR 贴图并应用到场景（Promise 版本）
+     * Load blue sky HDR/EXR map and apply to scene (Promise version)
      * ---------------------------------------------------------
-     * @param exrPath HDR/EXR 文件路径
-     * @param options 加载选项
+     * @param exrPath HDR/EXR file path
+     * @param options Load options
      * @returns Promise<void>
      */
     loadAsync(exrPath, options = {}) {
         if (!this.isInitialized) {
             return Promise.reject(new Error('BlueSkyManager not initialized!'));
         }
-        // ✨ 取消之前的加载
+        // Cancel previous load
         this.cancelLoad();
         const { background = true, onProgress, onComplete, onError } = options;
         this.loadingState = 'loading';
         this.currentLoader = new EXRLoader();
         return new Promise((resolve, reject) => {
             this.currentLoader.load(exrPath, 
-            // 成功回调
+            // Success callback
             (texture) => {
                 try {
-                    // 设置贴图为球面反射映射
+                    // Set texture mapping to EquirectangularReflectionMapping
                     texture.mapping = THREE.EquirectangularReflectionMapping;
-                    // 清理旧的环境贴图
+                    // Clear old environment map
                     this.dispose();
-                    // 用 PMREM 生成高效的环境贴图
+                    // Generate efficient environment map using PMREM
                     this.skyRT = this.pmremGen.fromEquirectangular(texture);
-                    // 应用到场景：环境光照 & 背景
+                    // Apply to scene: Environment Lighting & Background
                     this.scene.environment = this.skyRT.texture;
                     if (background)
                         this.scene.background = this.skyRT.texture;
-                    // 原始 HDR/EXR 贴图用完即销毁，节省内存
+                    // Dispose original HDR/EXR texture immediately to save memory
                     texture.dispose();
                     this.loadingState = 'loaded';
                     this.currentLoader = null;
@@ -663,14 +700,14 @@ class BlueSkyManager {
                     reject(error);
                 }
             }, 
-            // 进度回调
+            // Progress callback
             (xhr) => {
                 if (onProgress && xhr.lengthComputable) {
                     const progress = xhr.loaded / xhr.total;
                     onProgress(progress);
                 }
             }, 
-            // 错误回调
+            // Error callback
             (err) => {
                 this.loadingState = 'error';
                 this.currentLoader = null;
@@ -682,10 +719,10 @@ class BlueSkyManager {
         });
     }
     /**
-     * 加载蓝天 HDR/EXR 贴图并应用到场景（同步 API，保持向后兼容）
+     * Load blue sky HDR/EXR map and apply to scene (Sync API, for backward compatibility)
      * ---------------------------------------------------------
-     * @param exrPath HDR/EXR 文件路径
-     * @param background 是否应用为场景背景 (默认 true)
+     * @param exrPath HDR/EXR file path
+     * @param background Whether to apply as scene background (default true)
      */
     load(exrPath, background = true) {
         this.loadAsync(exrPath, { background }).catch((error) => {
@@ -693,32 +730,32 @@ class BlueSkyManager {
         });
     }
     /**
-     * ✨ 取消当前加载
+     * Cancel current load
      */
     cancelLoad() {
         if (this.currentLoader) {
-            // EXRLoader 本身没有 abort 方法，但我们可以清空引用
+            // EXRLoader itself does not have abort method, but we can clear the reference
             this.currentLoader = null;
             this.loadingState = 'idle';
         }
     }
     /**
-     * ✨ 获取加载状态
+     * Get loading state
      */
     getLoadingState() {
         return this.loadingState;
     }
     /**
-     * ✨ 是否正在加载
+     * Is loading
      */
     isLoading() {
         return this.loadingState === 'loading';
     }
     /**
-     * 释放当前的天空贴图资源
+     * Release current sky texture resources
      * ---------------------------------------------------------
-     * 仅清理 skyRT，不销毁 PMREM
-     * 适用于切换 HDR/EXR 文件时调用
+     * Only cleans up skyRT, does not destroy PMREM
+     * Suitable for calling when switching HDR/EXR files
      */
     dispose() {
         if (this.skyRT) {
@@ -732,27 +769,26 @@ class BlueSkyManager {
             this.scene.environment = null;
     }
     /**
-     * 完全销毁 BlueSkyManager
+     * Completely destroy BlueSkyManager
      * ---------------------------------------------------------
-     * 包括 PMREMGenerator 的销毁
-     * 通常在场景彻底销毁或应用退出时调用
+     * Includes destruction of PMREMGenerator
+     * Usually called when the scene is completely destroyed or the application exits
      */
     destroy() {
-        var _a;
         this.cancelLoad();
         this.dispose();
-        (_a = this.pmremGen) === null || _a === void 0 ? void 0 : _a.dispose();
+        this.pmremGen?.dispose();
         this.isInitialized = false;
         this.loadingState = 'idle';
     }
 }
 /**
- * 🌐 全局单例
+ * Global Singleton
  * ---------------------------------------------------------
- * 直接导出一个全局唯一的 BlueSkyManager 实例，
- * 保证整个应用中只用一个 PMREMGenerator，性能最佳。
+ * Directly export a globally unique BlueSkyManager instance,
+ * Ensuring only one PMREMGenerator is used throughout the application for best performance.
  */
 const BlueSky = new BlueSkyManager();
 
-export { BlueSky, disposeMaterial, disposeObject, loadCubeSkybox, loadEquirectSkybox, loadModelByUrl, loadSkybox, releaseSkybox };
+export { BlueSky, disposeMaterial, disposeObject, getLoaderConfig, loadCubeSkybox, loadEquirectSkybox, loadModelByUrl, loadSkybox, releaseSkybox, setLoaderConfig };
 //# sourceMappingURL=index.mjs.map