@ridp/threejs 1.5.1 → 1.5.2

package/dist/utils.js

@@ -1,37 +1,46 @@
-import { C as r, E as t, M as o, P as s, q as c, R as i, n as d, h as l, g as n, b as p, c as m, a as b, e as g, d as j, f as O, i as D, l as T, m as y, j as C, o as H, k as M, p as P, r as f } from "./PredictiveLoader-C9zJlZEQ.js";
-import { I as S, c as h, a as v, g as E, b as I, d as L, i as R } from "./objectQuery-BfHUGPET.js";
-import { ModelOptimizer as u, modelOptimizer as z } from "./modelOptimizer-D6fRg-DF.js";
+import { C as r, E as t, M as s, P as o, x as c, R as l, t as i, q as n, n as d, h as p, g as m, b, c as g, a as h, e as C, d as T, f as j, i as y, l as D, m as M, j as O, r as I, p as S, o as f, k as x, s as H, v as P, w as v } from "./PredictiveLoader-Ce8DXwbW.js";
+import { I as E, b as L, c as R, a as k, g as B, d as G, e as w, i as z, p as A, r as q, t as U } from "./objectQuery-BcL0iGx1.js";
+import { ModelOptimizer as F, modelOptimizer as J } from "./modelOptimizer-B7zPcU53.js";
 export {
   r as CacheMonitor,
   t as ErrorType,
-  S as ImageLoader,
-  o as ModelLoadError,
-  u as ModelOptimizer,
-  s as PredictiveLoader,
+  E as ImageLoader,
+  s as ModelLoadError,
+  F as ModelOptimizer,
+  o as PredictiveLoader,
   c as ProgressiveSceneBuilder,
-  i as RetryHelper,
-  d as cacheMonitor,
-  l as createArrowHelper,
-  n as createAxesHelper,
-  p as createBox3Helper,
-  m as createCameraHelper,
-  b as createGridHelper,
-  h as createInfoPlane,
-  g as createMapControls,
-  j as createOrbitControl,
-  O as createRaycaster,
-  D as createStats,
-  v as createTagPlane,
-  T as dataToObject3D,
-  y as dataToObject3DSync,
-  C as disposeThreeObject,
-  E as getCommonParent,
-  I as getObjectByUserData,
-  L as getRootObj,
-  R as initEnvImage,
-  z as modelOptimizer,
-  H as object3DToData,
-  M as object3DToDataSync,
+  l as RetryHelper,
+  i as cacheMonitor,
+  L as cancelIdleTask,
+  n as clearGeometryCache,
+  d as clearMaterialCache,
+  p as createArrowHelper,
+  m as createAxesHelper,
+  b as createBox3Helper,
+  g as createCameraHelper,
+  h as createGridHelper,
+  R as createInfoPlane,
+  C as createMapControls,
+  T as createOrbitControl,
+  j as createRaycaster,
+  y as createStats,
+  k as createTagPlane,
+  D as dataToObject3D,
+  M as dataToObject3DSync,
+  O as disposeThreeObject,
+  B as getCommonParent,
+  I as getGeometryCacheStats,
+  S as getMaterialCacheStats,
+  G as getObjectByUserData,
+  w as getRootObj,
+  z as initEnvImage,
+  J as modelOptimizer,
+  f as object3DToData,
+  x as object3DToDataSync,
+  H as object3DToTransferable,
   P as predictiveLoader,
-  f as rebuildScene
+  A as processInChunks,
+  v as rebuildScene,
+  q as runWhenIdle,
+  U as throttle
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ridp/threejs",
   "private": false,
-  "version": "1.5.1",
+  "version": "1.5.2",
   "type": "module",
   "main": "dist/threejs.js",
   "exports": {

package/{README.md → readme.md}

@@ -180,46 +180,31 @@ new ThreeIns(selector: string, options: ThreeInsOptions)
 
 ##### setView()
 
-设置模型视角 - 通过移动相机位置来实现视角切换。支持预设视角类型和自定义方向向量。
+设置模型视角。
 
 ```javascript
 threeJsIns.setView(
   model: Object3D,
-  viewType: ViewType | Vector3,  // 视角类型：可以是预设枚举或自定义 Vector3 方向
+  viewType: ViewType,
   options?: {
-    scale?: number,        // 缩放比例,1=占满画布,0.5=50%,2.0=200%(默认: 0.8)
-    position?: string | Vector3,  // 模型在画布中的位置
+    scale?: number,        // 缩放比例,1=占满画布,0.5=50%,2=0%(默认: 1)
     showBox?: boolean,     // 是否显示包围盒(默认: false)
-    animate?: boolean,     // 是否启用动画(默认: true)
+    animate?: boolean,     // 是否启用动画(默认: false)
     duration?: number,     // 动画时长(毫秒,默认: 1000)
-    offset?: Vector3,      // 额外的手动偏移量
-    boxColor?: number      // 包围盒颜色(默认: 0xffff00)
+    offset?: Vector3       // 中心点偏移
   }
 ): void
 ```
 
-**视角类型:**
-
-**方式 1: 使用 ViewType 枚举（预设视角）**
+**视角类型 (ViewType):**
 - `ViewType.TOP` - 俯视(从上往下)
 - `ViewType.RIGHT` - 右视图(从右往左)
 - `ViewType.LEFT` - 左侧视(从左往右)
 - `ViewType.ISO` - 等轴测视角(对角线上方俯视)
 
-**方式 2: 使用自定义 Vector3 方向向量**
-- 任意方向向量，如 `Vector3(1, 1, 1)`、`Vector3(2, 0, 1)`
-- 向量会被自动归一化，实现相对模型中心的任意角度查看
-- 支持负值和零值，如 `Vector3(0, -1, 1)` (仰视)、`Vector3(0, 0, 1)` (平视)
-
-**position 参数选项:**
-- 字符串选项：`'center'`（居中）、`'top-left'`（左上）、`'top-right'`（右上）、`'bottom-left'`（左下）、`'bottom-right'`（右下）
-- Vector3：自定义偏移向量
-
 **示例:**
-
-**使用预设 ViewType:**
 ```javascript
-// 基础用法 - 设置等轴测视角,模型占满画布
+// 设置等轴测视角,模型占满画布
 threeJsIns.setView(model, ViewType.ISO, {
   scale: 1.0,
   showBox: true,
@@ -232,113 +217,8 @@ threeJsIns.setView(model, ViewType.TOP, {
   scale: 0.5,
   animate: true
 });
-
-// 使用位置控制 - 左上角显示
-threeJsIns.setView(model, ViewType.ISO, {
-  position: 'top-left',
-  scale: 0.8
-});
-
-// 组合使用 position 和 offset
-threeJsIns.setView(model, ViewType.TOP, {
-  position: 'top-left',     // 先自动定位到左上
-  offset: new THREE.Vector3(50, 0, 0),  // 再额外向右偏移 50
-  scale: 0.8
-});
-```
-
-**使用自定义 Vector3 方向:**
-```javascript
-// 从对角线方向查看模型（类似等轴测）
-threeJsIns.setView(model, new THREE.Vector3(1, 1, 1));
-
-// 从右前方查看模型
-threeJsIns.setView(model, new THREE.Vector3(2, 1, 1));
-
-// 从左侧平视模型
-threeJsIns.setView(model, new THREE.Vector3(0, 0, 1));
-
-// 从下方仰视模型
-threeJsIns.setView(model, new THREE.Vector3(0, -1, 1));
-
-// 自定义方向 + 其他选项
-threeJsIns.setView(model, new THREE.Vector3(1, 2, 1), {
-  scale: 0.6,
-  position: 'center',
-  showBox: true,
-  animate: true,
-  duration: 1500
-});
-
-// 从左前方查看（负值 X）
-threeJsIns.setView(model, new THREE.Vector3(-2, 1, 1));
-
-// 从反方向对角线查看
-threeJsIns.setView(model, new THREE.Vector3(-1, 1, 1));
-```
-
-**两种方式对比:**
-
-| 特性 | ViewType 枚举 | Vector3 自定义方向 |
-|------|--------------|-------------------|
-| 易用性 | ⭐⭐⭐⭐⭐ 简单直观 | ⭐⭐⭐ 需要理解 3D 向量 |
-| 灵活性 | ⭐⭐⭐ 固定 4 种视角 | ⭐⭐⭐⭐⭐ 无限可能 |
-| 适用场景 | 常用标准视角 | 特殊角度查看 |
-| 向量归一化 | 自动处理 | 自动归一化 |
-| 组合使用 | ✅ 支持 | ✅ 支持 |
-
-##### setViewByRotation()
-
-通过旋转物体切换视角 - 保持相机固定，通过旋转物体来实现视角切换。
-
-```javascript
-threeJsIns.setViewByRotation(
-  model: Object3D,
-  viewType: ViewType,
-  options?: {
-    animate?: boolean,      // 是否启用动画(默认: true)
-    duration?: number,      // 动画时长(毫秒,默认: 1000)
-    resetRotation?: boolean // 旋转前是否重置物体旋转(默认: true)
-  }
-): { rotation: object, viewType: string, degrees: object }
-```
-
-**旋转角度配置:**
-- `ViewType.LEFT` - 物体绕 X 轴旋转 45°，Y 轴旋转 45°
-- `ViewType.RIGHT` - 物体绕 Y 轴旋转 90°
-- `ViewType.TOP` - 物体绕 X 轴旋转 90°
-- `ViewType.ISO` - 物体绕 X 轴旋转 45°，Y 轴旋转 45°
-
-**示例:**
-```javascript
-// 左侧视：物体绕 X 轴 45°，Y 轴 45°
-const result = threeJsIns.setViewByRotation(model, ViewType.LEFT);
-
-// 俯视：物体绕 X 轴 90°，无动画
-threeJsIns.setViewByRotation(model, ViewType.TOP, {
-  animate: false
-});
-
-// 自定义动画时间
-threeJsIns.setViewByRotation(model, ViewType.ISO, {
-  duration: 1500
-});
-
-// 不重置旋转，在当前基础上累加
-threeJsIns.setViewByRotation(model, ViewType.LEFT, {
-  resetRotation: false
-});
 ```
 
-**两种视角切换方式对比:**
-
-| 特性 | setView() | setViewByRotation() |
-|------|-----------|---------------------|
-| 实现方式 | 移动相机位置 | 旋转物体 |
-| 相机位置 | 改变 | 固定 |
-| 物体姿态 | 保持不变 | 改变 |
-| 适用场景 | 通用视角切换 | 特殊视觉效果 |
-
 ##### frameArea()
 
 > **⚠️ 已弃用** - 此方法仅为兼容旧版本保留，请使用 `setView()` 方法代替。
@@ -521,10 +401,6 @@ const {
   getMemoryCacheInfo,    // 获取内存缓存统计
   deleteMemoryCache,     // 删除指定模型的内存缓存
 
-  // 缓存迁移和验证 (v1.5.0+)
-  cleanLegacyCache,      // 清理旧版本格式的缓存数据
-  validateCache,         // 验证并修复缓存
-
   // 性能监控
   cacheMonitor       // 缓存监控器实例
 } = loader;
@@ -755,92 +631,6 @@ const model3 = await loader.asyncFetch('/models/car.glb', '1.0.0');
 // [ asyncFetch ] ====> IndexedDB 缓存命中
 ```
 
-##### 缓存迁移和验证 API (v1.5.0+)
-
-**cleanLegacyCache()**
-
-清理旧版本格式的缓存数据，手动触发清理不需要等待数据库版本升级。
-
-```javascript
-const result = await loader.cleanLegacyCache();
-
-// 返回值:
-{
-  total: 10,        // 总记录数
-  deleted: 3,       // 删除的记录数
-  kept: 7,          // 保留的记录数
-  deletedPaths: [   // 被删除的路径列表
-    '/models/old1.glb',
-    '/models/old2.glb',
-    '/models/old3.glb'
-  ]
-}
-```
-
-**validateCache()**
-
-验证并修复缓存完整性。
-
-```javascript
-const result = await loader.validateCache();
-
-// 返回值:
-{
-  total: 10,        // 总记录数
-  valid: 8,         // 有效记录数
-  invalid: 2,       // 无效记录数
-  repairs: 1        // 修复的操作数
-}
-```
-
-**使用场景:**
-
-```javascript
-// 场景 1: 应用启动时验证缓存
-async function initApp() {
-  const { validateCache, asyncFetch } = useGLTFLoader();
-
-  // 验证并修复缓存
-  const result = await validateCache();
-  if (result.invalid > 0) {
-    console.warn(`发现 ${result.invalid} 条无效缓存，已自动清理`);
-  }
-
-  // 继续加载模型
-  const model = await asyncFetch('/models/car.glb', '1.0.0');
-}
-
-// 场景 2: 手动清理旧版本格式
-async function cleanupOldCache() {
-  const { cleanLegacyCache } = useGLTFLoader();
-
-  const result = await cleanLegacyCache();
-  console.log(`清理完成: 删除 ${result.deleted} 条，保留 ${result.kept} 条`);
-}
-
-// 场景 3: 用户遇到缓存问题时一键修复
-async function repairCache() {
-  const { validateCache, cleanLegacyCache } = useGLTFLoader();
-
-  // 先验证
-  const validation = await validateCache();
-  console.log('验证结果:', validation);
-
-  // 如果仍有问题，强制清理旧版本
-  if (validation.invalid > 0) {
-    const cleaned = await cleanLegacyCache();
-    console.log('清理结果:', cleaned);
-  }
-}
-```
-
-**缓存版本说明:**
-
-- **v1-v3 (旧版本)**: 使用序列化对象格式 (`object3DToData`)
-- **v4+ (新版本)**: 直接存储 ArrayBuffer 原始数据
-- **自动迁移**: 数据库会自动从旧版本升级，清理旧格式数据
-- **手动清理**: 可使用 `cleanLegacyCache()` 手动清理
-
 ### useRaycaster()
 
 射线拾取工具,用于鼠标交互和物体选择。
@@ -1542,8 +1332,9 @@ otherObjects.castShadow = false;
 A: 使用 `asyncFetch` 的重试机制:
 
 ```javascript
-const [err, model] = await asyncFetch(url, version, null, {
-  maxRetries: 5
+const [err, model] = await asyncFetch(url, version, {
+  retryCount: 5,
+  timeout: 60000
 });
 
 if (err || !model) {
@@ -1552,50 +1343,7 @@ if (err || !model) {
 }
 ```
 
-### Q: 如何清理旧版本缓存数据?
-
-A: 使用 `cleanLegacyCache` 方法手动清理旧版本格式:
-
-```javascript
-import { useGLTFLoader } from '@ridp/threejs';
-
-const { cleanLegacyCache } = useGLTFLoader();
-
-// 清理旧版本序列化格式
-const result = await cleanLegacyCache();
-console.log('清理结果:', result);
-// 输出: { total: 10, deleted: 3, kept: 7, deletedPaths: [...] }
-```
-
-**自动迁移**: 当用户首次使用新版本时，数据库会自动从 v4 升级到 v5，自动清理旧版本格式数据。
-
-### Q: 如何验证缓存完整性?
-
-A: 使用 `validateCache` 方法:
-
-```javascript
-import { useGLTFLoader } from '@ridp/threejs';
-
-const { validateCache } = useGLTFLoader();
-
-// 验证并修复缓存
-const result = await validateCache();
-console.log('验证结果:', result);
-// 输出: { total: 10, valid: 8, invalid: 2, repairs: 1 }
-
-if (result.invalid > 0) {
-  console.warn(`发现 ${result.invalid} 条无效缓存，已自动清理`);
-}
-```
-
-### Q: 升级后原有缓存会被删除吗?
-
-A: 只有旧版本序列化格式的数据会被删除。ArrayBuffer 格式的数据会被保留。自动迁移过程会：
-- ✅ 保留所有 ArrayBuffer 格式的数据
-- ❌ 删除所有旧版本序列化格式的数据
-- 📊 在控制台输出迁移日志
-
-### Q: 如何清空所有缓存?
+### Q: 如何清理模型缓存?
 
 A: 使用 `clearCache` 方法:
 
@@ -1657,121 +1405,6 @@ function captureScreenshot() {
 
 ## 更新日志
 
-### v1.5.0 (2026-01-12)
-
-**🎉 重大更新:**
-
-- ✨ **增强 setView() 方法 - 支持自定义 Vector3 方向**:
-  - **新增自定义方向支持**: 除了预设的 ViewType 枚举，现在可以直接传入 Vector3 方向向量
-  - **无限视角可能性**: 支持任意相机角度，如 `Vector3(1,1,1)`、`Vector3(2,0,1)` 等
-  - **自动归一化**: 向量会被自动归一化，确保相机距离计算准确
-  - **完整兼容性**: 向后兼容 ViewType 枚举，同时支持新的 Vector3 参数
-  - **灵活组合**: 自定义方向可以与 scale、position、offset 等参数组合使用
-  - 使用示例:
-    ```javascript
-    // 从对角线方向查看
-    threeJsIns.setView(model, new THREE.Vector3(1, 1, 1));
-
-    // 从右前方查看
-    threeJsIns.setView(model, new THREE.Vector3(2, 1, 1));
-
-    // 从左侧平视
-    threeJsIns.setView(model, new THREE.Vector3(0, 0, 1));
-
-    // 从下方仰视
-    threeJsIns.setView(model, new THREE.Vector3(0, -1, 1));
-    ```
-
-- ✨ **新增 setViewByRotation() 方法**: 通过旋转物体切换视角
-  - 提供另一种视角切换方式（与 setView 互补）
-  - 左视图：物体绕 X 轴 45°，Y 轴旋转 45°
-  - 支持动画过渡和旋转重置选项
-  - 适用于特殊视觉效果需求
-
-- ✨ **新增 setView() position 参数**: 控制模型在画布中的位置
-  - 支持 5 种预设位置：`center`、`top-left`、`top-right`、`bottom-left`、`bottom-right`
-  - 支持自定义 Vector3 偏移
-  - 可与 offset 参数组合使用
-
-- ✨ **新增缓存迁移和验证工具**:
-  - 数据库版本升级：v4 → v5
-  - 自动清理旧版本序列化格式数据
-  - 新增 `cleanLegacyCache()` - 手动清理旧版本缓存
-  - 新增 `validateCache()` - 验证并修复缓存完整性
-  - 新增 `cleanLegacyFormats()` - IDBCache 实例方法
-  - 新增 `validateAndRepair()` - IDBCache 实例方法
-
-- 🔧 **增强 setView() 方法**:
-  - **重大增强**: 支持 Vector3 自定义方向向量
-  - 新增 `position` 参数控制模型在画布中的位置
-  - 新增 `boxColor` 参数自定义包围盒颜色
-  - 优化视角偏移计算逻辑
-  - 完善文档和 JSDoc 注释
-
-- 🐛 **修复缓存版本兼容性问题**:
-  - 旧版本（v1-v3）使用序列化对象格式
-  - 新版本（v4+）使用 ArrayBuffer 格式
-  - 自动识别并删除旧格式数据
-  - 添加完整的格式验证逻辑
-
-**API 变更:**
-
-```javascript
-// ============ 新功能：自定义 Vector3 方向 ============
-// 从对角线方向查看模型
-threeJsIns.setView(model, new THREE.Vector3(1, 1, 1));
-
-// 从右前方查看
-threeJsIns.setView(model, new THREE.Vector3(2, 1, 1), {
-  scale: 0.8,
-  position: 'center',
-  animate: true
-});
-
-// 从左侧平视
-threeJsIns.setView(model, new THREE.Vector3(0, 0, 1));
-
-// 从下方仰视
-threeJsIns.setView(model, new THREE.Vector3(0, -1, 1));
-
-// ============ 其他新功能 ============
-// 新增 setViewByRotation
-threeJsIns.setViewByRotation(model, ViewType.LEFT, {
-  animate: true,
-  duration: 1000,
-  resetRotation: true
-});
-
-// setView position 参数
-threeJsIns.setView(model, ViewType.ISO, {
-  position: 'top-left',  // 位置控制
-  scale: 0.8,
-  offset: new THREE.Vector3(50, 0, 0)
-});
-
-// 缓存迁移和验证
-const { cleanLegacyCache, validateCache } = useGLTFLoader();
-await cleanLegacyCache();  // 清理旧版本缓存
-await validateCache();      // 验证和修复缓存
-```
-
-**Breaking Changes:**
-
-无破坏性变更，所有新功能都是向后兼容的增强。
-
-**升级指南:**
-
-- 如果使用预设视角（ViewType），无需修改任何代码
-- 如果需要自定义视角，可以直接传入 Vector3 对象替代 ViewType
-- 建议查看新示例代码了解更多用法
-
-**迁移说明:**
-
-- 数据库会自动从 v4 升级到 v5
-- 旧版本序列化格式数据会被自动删除
-- ArrayBuffer 格式数据会被保留
-- 提供手动清理工具供用户使用
-
 ### v1.4.2 (2026-01-07)
 
 **🎉 重大更新:**