@ridp/threejs 1.4.6 → 1.4.7

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']
+    },
+  }
+})
+
+```
+
 ## 快速开始
 
 ### 基础场景初始化
@@ -244,8 +262,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 +356,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 项目                  |
 
 ---
 
@@ -725,8 +743,7 @@ import {
   createRaycaster,       // 创建射线投射器
   createAxesHelper,      // 创建坐标轴辅助器
   createArrowHelper,     // 创建箭头辅助器
-  createStats,           // 创建性能监控器
-  createTransformControls // 创建变换控制器
+  createStats            // 创建性能监控器
 } from '@ridp/threejs';
 
 // 示例
@@ -737,6 +754,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 +785,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 +834,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 +874,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
 
 缓存性能监控工具。