@ridp/threejs 1.4.6 → 1.5.0

package/README.md

@@ -61,6 +61,24 @@ yarn add @ridp/threejs dexie@^4 vue@^3 three@^0.178
 pnpm add @ridp/threejs dexie@^4 vue@^3 three@^0.178
 ```
 
+### vite.config.js 配置
+因为涉及 worker，需要添加以下配置项：
+```javascript
+import { defineConfig } from 'vite';
+
+export default defineConfig(() => {
+  return {
+    // plugins,
+    // build: { ... }
+    optimizeDeps: {
+      // ...
+      exclude: ['@ridp/threejs']
+    },
+  }
+})
+
+```
+
 ## 快速开始
 
 ### 基础场景初始化
@@ -162,18 +180,20 @@ new ThreeIns(selector: string, options: ThreeInsOptions)
 
 ##### setView()
 
-设置模型视角。
+设置模型视角 - 通过移动相机位置来实现视角切换。
 
 ```javascript
 threeJsIns.setView(
   model: Object3D,
   viewType: ViewType,
   options?: {
-    scale?: number,        // 缩放比例,1=占满画布,0.5=50%,2=0%(默认: 1)
+    scale?: number,        // 缩放比例,1=占满画布,0.5=50%,2.0=200%(默认: 0.8)
+    position?: string | Vector3,  // 模型在画布中的位置
     showBox?: boolean,     // 是否显示包围盒(默认: false)
-    animate?: boolean,     // 是否启用动画(默认: false)
+    animate?: boolean,     // 是否启用动画(默认: true)
     duration?: number,     // 动画时长(毫秒,默认: 1000)
-    offset?: Vector3       // 中心点偏移
+    offset?: Vector3,      // 额外的手动偏移量
+    boxColor?: number      // 包围盒颜色(默认: 0xffff00)
   }
 ): void
 ```
@@ -184,9 +204,13 @@ threeJsIns.setView(
 - `ViewType.LEFT` - 左侧视(从左往右)
 - `ViewType.ISO` - 等轴测视角(对角线上方俯视)
 
+**position 参数选项:**
+- 字符串选项：`'center'`（居中）、`'top-left'`（左上）、`'top-right'`（右上）、`'bottom-left'`（左下）、`'bottom-right'`（右下）
+- Vector3：自定义偏移向量
+
 **示例:**
 ```javascript
-// 设置等轴测视角,模型占满画布
+// 基础用法 - 设置等轴测视角,模型占满画布
 threeJsIns.setView(model, ViewType.ISO, {
   scale: 1.0,
   showBox: true,
@@ -199,8 +223,73 @@ 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
+});
+```
+
+##### 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()` 方法代替。
@@ -244,8 +333,8 @@ threeJsIns.setView(model, ViewType.ISO, {
 ```
 
 **迁移指南:**
-| 旧用法 (frameArea) | 新用法 (setView) |
-|-------------------|------------------|
+| 旧用法 (frameArea)      | 新用法 (setView)                               |
+| ----------------------- | ---------------------------------------------- |
 | `frameArea(model, 1.0)` | `setView(model, ViewType.ISO, { scale: 1.0 })` |
 | `frameArea(model, 0.5)` | `setView(model, ViewType.ISO, { scale: 0.5 })` |
 | `frameArea(model, 2.0)` | `setView(model, ViewType.ISO, { scale: 2.0 })` |
@@ -338,15 +427,15 @@ threeJsIns.setView(model, ViewType.ISO, { scale: 1.0, animate: true });
 
 **迁移对照表:**
 
-| 功能 | useThreeJs (已弃用) | ThreeIns 类 (推荐) |
-|------|-------------------|-------------------|
-| 初始化场景 | `useThreeJs('#el', opts)` | `new ThreeIns('#el', opts)` |
-| 访问 scene | `const { scene } = useThreeJs(...)` | `threeJsIns.scene` |
-| 访问 camera | `const { camera } = useThreeJs(...)` | `threeJsIns.camera` |
-| 添加动画 | `addAnimate(fn)` | `threeJsIns.addAnimate(fn)` |
-| 视角切换 | ❌ 不支持 | ✅ `setView(model, ViewType.ISO)` |
-| 资源清理 | `dispose()` | ✅ `threeJsIns.dispose()` |
-| 适用范围 | 仅 Vue 3 | 所有 JS/TS 项目 |
+| 功能        | useThreeJs (已弃用)                  | ThreeIns 类 (推荐)               |
+| ----------- | ------------------------------------ | -------------------------------- |
+| 初始化场景  | `useThreeJs('#el', opts)`            | `new ThreeIns('#el', opts)`      |
+| 访问 scene  | `const { scene } = useThreeJs(...)`  | `threeJsIns.scene`               |
+| 访问 camera | `const { camera } = useThreeJs(...)` | `threeJsIns.camera`              |
+| 添加动画    | `addAnimate(fn)`                     | `threeJsIns.addAnimate(fn)`      |
+| 视角切换    | ❌ 不支持                             | ✅ `setView(model, ViewType.ISO)` |
+| 资源清理    | `dispose()`                          | ✅ `threeJsIns.dispose()`         |
+| 适用范围    | 仅 Vue 3                             | 所有 JS/TS 项目                  |
 
 ---
 
@@ -383,6 +472,10 @@ const {
   getMemoryCacheInfo,    // 获取内存缓存统计
   deleteMemoryCache,     // 删除指定模型的内存缓存
 
+  // 缓存迁移和验证 (v1.5.0+)
+  cleanLegacyCache,      // 清理旧版本格式的缓存数据
+  validateCache,         // 验证并修复缓存
+
   // 性能监控
   cacheMonitor       // 缓存监控器实例
 } = loader;
@@ -613,6 +706,92 @@ 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()
 
 射线拾取工具,用于鼠标交互和物体选择。
@@ -725,8 +904,7 @@ import {
   createRaycaster,       // 创建射线投射器
   createAxesHelper,      // 创建坐标轴辅助器
   createArrowHelper,     // 创建箭头辅助器
-  createStats,           // 创建性能监控器
-  createTransformControls // 创建变换控制器
+  createStats            // 创建性能监控器
 } from '@ridp/threejs';
 
 // 示例
@@ -737,6 +915,20 @@ const stats = createStats();
 document.body.appendChild(stats.dom);
 ```
 
+**功能说明:**
+- `createCameraHelper(camera)` - 创建相机辅助线,显示相机视锥体
+- `createGridHelper(size, divisions, color1, color2)` - 创建网格辅助线
+  - `size`: 网格大小,默认 150
+  - `divisions`: 分段数
+  - `color1/color2`: 中心线和其他线的颜色
+- `createBox3Helper(model)` - 创建包围盒辅助线
+- `createOrbitControl(camera, dom)` - 创建轨道控制器
+- `createMapControls(camera, dom)` - 创建地图控制器
+- `createRaycaster()` - 创建射线投射器,用于鼠标拾取
+- `createAxesHelper(size)` - 创建坐标轴辅助线,默认大小 10
+- `createArrowHelper(dir, origin, length, color)` - 创建箭头辅助线
+- `createStats()` - 创建性能监控器(基于 stats.js)
+
 ### initEnvImage()
 
 初始化场景环境贴图。
@@ -754,6 +946,30 @@ await initEnvImage(scene, '/hdr/outdoor.hdr');
 await initEnvImage(scene, '/textures/env.jpg');
 ```
 
+### getCommonParent()
+
+查找多个网格对象的公共父节点。
+
+```javascript
+import { getCommonParent } from '@ridp/threejs';
+
+// 查找多个选中对象的公共父节点
+const meshes = [mesh1, mesh2, mesh3];
+const commonParent = getCommonParent(meshes, scene);
+
+console.log('公共父节点:', commonParent);
+```
+
+**功能说明:**
+- 遍历每个网格的所有父节点,统计出现频率最高的父节点
+- 返回的公共父节点可作为分组、操作的目标对象
+- 常用于批量操作、场景组织等场景
+
+**使用场景:**
+- 批量选择对象时查找共同的容器
+- 场景层级分析
+- 分组操作前的父节点确定
+
 ### modelOptimizer
 
 模型优化工具,用于减少多边形数量和优化材质。
@@ -779,26 +995,28 @@ const optimized = modelOptimizer.simplifyModel(model, {
 modelOptimizer.optimizeMaterials(model);
 ```
 
-### disposeObject()
+### disposeThreeObject()
 
 深度释放 3D 对象及其子对象的资源。
 
 ```javascript
-import { disposeObject } from '@ridp/threejs';
+import { disposeThreeObject } from '@ridp/threejs';
 
 // 释放模型资源
-disposeObject(model);
+disposeThreeObject(model);
 
 // 释放整个场景
-disposeObject(scene);
+disposeThreeObject(scene);
 ```
 
 **清理内容:**
-- 几何体 (geometry)
-- 材质 (material)
-- 纹理 (textures)
+- 几何体 (geometry.dispose())
+- 材质 (material.dispose())
+- 材质中的所有纹理 (texture.dispose())
 - 子对象递归清理
 
+**注意:** 此函数会递归遍历对象的所有子对象,确保所有资源都被正确释放,避免内存泄漏。
+
 ### sceneRebuilder
 
 渐进式场景重建工具,用于大型模型的分批渲染。
@@ -817,45 +1035,93 @@ const builder = new ProgressiveSceneBuilder(scene, camera, {
 await builder.build(model);
 ```
 
-### objectQuery
+### 模型序列化工具
 
-3D 对象查询工具,支持按名称、UUID、类型等条件查询。
+用于 Three.js 对象的序列化和反序列化,支持将 3D 对象转换为可存储的数据格式。
 
 ```javascript
-import { objectQuery } from '@ridp/threejs';
+import {
+  object3DToData,
+  object3DToDataSync,
+  dataToObject3D,
+  dataToObject3DSync
+} from '@ridp/threejs';
 
-// 按名称查询
-const wheels = objectQuery.queryByName(scene, 'wheel_*');
+// 异步序列化(推荐,避免阻塞主线程)
+const data = await object3DToData(model, 50);
 
-// 按 UUID 查询
-const mesh = objectQuery.queryByUuid(scene, 'uuid-123');
+// 同步序列化
+const data = object3DToDataSync(model);
 
-// 按类型查询
-const allMeshes = objectQuery.queryByType(scene, 'Mesh');
+// 异步反序列化(推荐,避免阻塞主线程)
+const restoredModel = await dataToObject3D(data, 50);
 
-// 按条件查询
-const largeObjects = objectQuery.query(scene, (obj) => {
-  return obj.scale.x > 10;
-});
+// 同步反序列化
+const restoredModel = dataToObject3DSync(data);
 ```
 
+**功能说明:**
+- `object3DToData(object, chunkSize)` - 异步序列化对象,使用分块处理避免阻塞
+  - `chunkSize`: 每帧处理的对象数量,默认 50
+- `object3DToDataSync(object)` - 同步序列化对象
+- `dataToObject3D(data, chunkSize)` - 异步反序列化数据为 3D 对象
+- `dataToObject3DSync(data)` - 同步反序列化数据为 3D 对象
+
+**序列化内容:**
+- 对象类型、名称、位置、旋转、缩放
+- 几何体数据(顶点、索引、UV 等)
+- 材质数据(颜色、纹理、属性等)
+- userData 自定义数据
+- 子对象层级关系
+
+**使用场景:**
+- 场景状态保存和恢复
+- 模型数据的本地存储
+- 跨页面/跨会话的模型传输
+
+### 对象查询工具
+
+基于 userData 的对象查找工具。
+
+```javascript
+import { getObjectByUserData, getRootObj } from '@ridp/threejs';
+
+// 向下遍历查找首个匹配 userData 的对象
+const target = getObjectByUserData(mesh, 'type', 'wheel');
+
+// 向上查找根节点（根据 userData 判定）
+const root = getRootObj(mesh, 'isRoot', true);
+```
+
+**功能说明:**
+- `getObjectByUserData(obj, key, value)` - 从指定对象开始向下遍历,查找首个 userData[key]=value 的对象(包括自身)
+- `getRootObj(obj, rootKey, value)` - 从指定对象开始向上查找父级,直到找到 userData[rootKey]=value 的根对象
+
 ### CSS3D 辅助工具
 
 ```javascript
-import { createCSS3DObject, createCSS3DSprite } from '@ridp/threejs';
+import { createInfoPlane, createTagPlane } from '@ridp/threejs';
 
-// 创建 CSS3D 对象
-const css3dObject = createCSS3DObject(domElement);
-css3dObject.position.set(0, 10, 0);
-scene.add(css3dObject);
+// 从 DOM ID 创建 CSS3D 信息面板
+const infoPlane = createInfoPlane('my-info-panel', [0.3, 0.3, 0.3]);
+infoPlane.position.set(0, 10, 0);
+scene.add(infoPlane);
 
-// 创建 CSS3D 精灵(始终面向相机)
-const sprite = createCSS3DSprite(domElement, {
-  scale: 0.01
-});
-scene.add(sprite);
+// 创建 CSS3D 标签面板
+const tagPlane = createTagPlane('设备名称', 0.01);
+tagPlane.position.set(5, 5, 5);
+scene.add(tagPlane);
 ```
 
+**功能说明:**
+- `createInfoPlane(id, scale)` - 从页面中已存在的 DOM 元素创建 CSS3D 精灵
+  - `id`: DOM 元素的 ID
+  - `scale`: 缩放比例数组 `[x, y, z]`,默认 `[0.3, 0.3, 0.3]`
+  - ⚠️ 注意: HTML 元素不能设置为绝对定位
+- `createTagPlane(text, scale)` - 创建带文本的 CSS3D 标签
+  - `text`: 标签文本内容
+  - `scale`: 统一缩放比例(三个维度相同)
+
 ### CacheMonitor
 
 缓存性能监控工具。
@@ -1227,9 +1493,8 @@ otherObjects.castShadow = false;
 A: 使用 `asyncFetch` 的重试机制:
 
 ```javascript
-const [err, model] = await asyncFetch(url, version, {
-  retryCount: 5,
-  timeout: 60000
+const [err, model] = await asyncFetch(url, version, null, {
+  maxRetries: 5
 });
 
 if (err || !model) {
@@ -1238,7 +1503,50 @@ if (err || !model) {
 }
 ```
 
-### Q: 如何清理模型缓存?
+### 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: 如何清空所有缓存?
 
 A: 使用 `clearCache` 方法:
 
@@ -1300,6 +1608,71 @@ function captureScreenshot() {
 
 ## 更新日志
 
+### v1.5.0 (2026-01-12)
+
+**🎉 重大更新:**
+
+- ✨ **新增 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() 方法**:
+  - 新增 `position` 参数控制模型在画布中的位置
+  - 新增 `boxColor` 参数自定义包围盒颜色
+  - 优化视角偏移计算逻辑
+  - 完善文档和 JSDoc 注释
+
+- 🐛 **修复缓存版本兼容性问题**:
+  - 旧版本（v1-v3）使用序列化对象格式
+  - 新版本（v4+）使用 ArrayBuffer 格式
+  - 自动识别并删除旧格式数据
+  - 添加完整的格式验证逻辑
+
+**API 变更:**
+
+```javascript
+// 新增 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();      // 验证和修复缓存
+```
+
+**迁移说明:**
+
+- 数据库会自动从 v4 升级到 v5
+- 旧版本序列化格式数据会被自动删除
+- ArrayBuffer 格式数据会被保留
+- 提供手动清理工具供用户使用
+
 ### v1.4.2 (2026-01-07)
 
 **🎉 重大更新:**