343 lines
10 KiB
Markdown
343 lines
10 KiB
Markdown
---
|
||
outline: [2, 3]
|
||
---
|
||
|
||
# Tool
|
||
|
||
- 源文件：`packages/sdk/src/tool/Tool.ts`
|
||
- 文档位置：`packages/docs/api/tool/Tool.md`
|
||
|
||
## 枚举：`UserDataProperty`
|
||
|
||
- 作用：UserData 属性枚举
|
||
|
||
| 枚举项 | 值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `SELECTION` | `'selection'` | 选择排除属性,为真的时候,在点击事件进行返回 |
|
||
| `SCENE_TREE_EXCLUDE` | `'sceneTreeExclude'` | 场景树排除属性 |
|
||
|
||
## 类：`Tool`
|
||
|
||
- 作用：包围盒工具类 提供计算物体包围盒的静态方法
|
||
|
||
### 属性
|
||
|
||
| 属性名 | 可见性 | 类型 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `originalTransparentMap` | `public static` | `WeakMap<THREE.Material<THREE.MaterialEventMap>, boolean>` | 修改对象及其所有子对象的透明度 |
|
||
|
||
### 方法
|
||
|
||
#### `defineMaterialOpacityMapping(object: THREE.Mesh, propertyName: string = "mappedOpacity", sourceMin: number = 0.3, sourceMax: number = 1): void`
|
||
|
||
- 作用：为对象定义透明度映射属性 读取时将材质 opacity 从 sourceMin~sourceMax 映射到 0~1，设置时反向映射回 sourceMin~sourceMax。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Mesh` | 是 | 目标对象（需包含 material） |
|
||
| `propertyName` | `string` | 否 | 挂载到对象上的属性名，默认 opacity |
|
||
| `sourceMin` | `number` | 否 | 材质真实透明度最小值，默认 0.3 |
|
||
| `sourceMax` | `number` | 否 | 材质真实透明度最大值，默认 1 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `removeMaterialOpacityMapping(object: THREE.Object3D, propertyName: string = "opacity", restoreDirectBinding: boolean = true): void`
|
||
|
||
- 作用：取消对象上的透明度映射属性 可选恢复为材质 opacity 的直接读写绑定（不做区间映射）。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 目标对象（需包含 material） |
|
||
| `propertyName` | `string` | 否 | 挂载在对象上的属性名，默认 opacity |
|
||
| `restoreDirectBinding` | `boolean` | 否 | 是否恢复直接绑定，默认 true |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `computeBoundingBox(object: THREE.Object3D): THREE.Box3 | null`
|
||
|
||
- 作用：计算物体的包围盒，包括所有子对象
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要计算包围盒的物体 |
|
||
|
||
- 出参：`THREE.Box3 \| null`
|
||
- 返回说明：物体的包围盒，如果物体没有几何体则返回 null
|
||
|
||
#### `getBoundingBoxSize(object: THREE.Object3D): THREE.Vector3 | null`
|
||
|
||
- 作用：计算物体包围盒的大小
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要计算大小的物体 |
|
||
|
||
- 出参：`THREE.Vector3 \| null`
|
||
- 返回说明：包围盒的大小向量，如果物体没有几何体则返回 null
|
||
|
||
#### `getBoundingBoxCenter(object: THREE.Object3D): THREE.Vector3 | null`
|
||
|
||
- 作用：计算物体包围盒的中心点
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要计算中心点的物体 |
|
||
|
||
- 出参：`THREE.Vector3 \| null`
|
||
- 返回说明：包围盒的中心点向量，如果物体没有几何体则返回 null
|
||
|
||
#### `getBoundingBoxFaceCenters(object: THREE.Object3D): { YF: THREE.Vector3; YB: THREE.Vector3; ZU: THREE.Vector3; ZD: THREE.Vector3; XL: THREE.Vector3; XR: THREE.Vector3; } | null`
|
||
|
||
- 作用：计算物体包围盒的六个面中心点
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要计算面中心点的物体 |
|
||
|
||
- 出参：`{ YF: THREE.Vector3; YB: THREE.Vector3; ZU: THREE.Vector3; ZD: THREE.Vector3; XL: THREE.Vector3; XR: THREE.Vector3; } \| null`
|
||
- 返回说明：六个面的中心点对象，如果物体没有几何体则返回 null
|
||
|
||
#### `queryObjectsByName(scene: THREE.Object3D, name: string, exactMatch: boolean = false): THREE.Object3D<THREE.Object3DEventMap>[]`
|
||
|
||
- 作用：遍历场景并查询对象名称
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `scene` | `THREE.Object3D` | 是 | 要查询的场景或对象 |
|
||
| `name` | `string` | 是 | 查询的名称 |
|
||
| `exactMatch` | `boolean` | 否 | 是否精确匹配（true: === 匹配, false: 模糊匹配） |
|
||
|
||
- 出参：`THREE.Object3D<THREE.Object3DEventMap>[]`
|
||
- 返回说明：匹配的对象列表
|
||
|
||
#### `setUserDataProperty(object: THREE.Object3D, key: string, value: any): void`
|
||
|
||
- 作用：给 Three.js 对象设置 userData 属性
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要设置属性的对象 |
|
||
| `key` | `string` | 是 | 属性名 |
|
||
| `value` | `any` | 是 | 属性值 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `removeUserDataProperty(object: THREE.Object3D, key: string): void`
|
||
|
||
- 作用：从 Three.js 对象中移除 userData 属性
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要移除属性的对象 |
|
||
| `key` | `string` | 是 | 属性名 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setSelectionExclude(object: THREE.Object3D, exclude: boolean = true): void`
|
||
|
||
- 作用：给 Three.js 对象设置 meta 中的是否选择排除属性
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要设置属性的对象 |
|
||
| `exclude` | `boolean` | 否 | 是否排除选择 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setSceneTreeExclude(object: THREE.Object3D, exclude: boolean = true): void`
|
||
|
||
- 作用：给 Three.js 对象设置 meta 中的是否场景树排除属性
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要设置属性的对象 |
|
||
| `exclude` | `boolean` | 否 | 是否排除场景树 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setExcludeAll(object: THREE.Object3D, exclude: boolean = true): void`
|
||
|
||
- 作用：同时设置选择排除和场景树排除属性
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要设置属性的对象 |
|
||
| `exclude` | `boolean` | 否 | 是否排除，默认为 true |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setHiddenAndUnselectable(object: THREE.Object3D): void`
|
||
|
||
- 作用：设置对象不可在树菜单显示且不可选择
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要设置属性的对象 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `handleMaterialOpacity(object: THREE.Object3D, material: THREE.Material, opacity: number): void`
|
||
|
||
- 作用：处理单个材质的透明度
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 目标对象。 |
|
||
| `material` | `THREE.Material` | 是 | 要处理的材质 |
|
||
| `opacity` | `number` | 是 | 透明度值，范围 0-1 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setOpacity(object: THREE.Object3D, opacity: number): void`
|
||
|
||
- 作用：设置 Opacity。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 目标对象。 |
|
||
| `opacity` | `number` | 是 | 参数 `opacity`，类型为 `number`。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `getOpacity(mesh: THREE.Mesh, materialIndex: number = 0): number`
|
||
|
||
- 作用：获取对象的透明度值
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `mesh` | `THREE.Mesh` | 是 | 要获取透明度的 Mesh 对象 |
|
||
| `materialIndex` | `number` | 否 | 材质索引，当材质为数组时使用，默认为 0 |
|
||
|
||
- 出参：`number`
|
||
- 返回说明：透明度值，范围 0-1
|
||
|
||
#### `getPoints(points: Array<THREE.Vector3 | { x: number; y: number; z: number }>): THREE.Vector3[]`
|
||
|
||
- 作用：获取 Points。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `points` | `Array<THREE.Vector3 \| { x: number; y: number; z: number }>` | 是 | 参数 `points`，类型为 `Array<THREE.Vector3 \| { x: number; y: number; z: number }>`。 |
|
||
|
||
- 出参：`THREE.Vector3[]`
|
||
- 返回说明：返回数组结果，元素类型为 `THREE.Vector3`。
|
||
|
||
#### `setRenderOrder(object: THREE.Object3D, defaultRenderOrder: number, specificMeshes?: Array<{ name: string, renderOrder: number }>): void`
|
||
|
||
- 作用：设置场景中网格的渲染顺序
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 要遍历的根对象 |
|
||
| `defaultRenderOrder` | `number` | 是 | 所有网格的默认渲染顺序值 |
|
||
| `specificMeshes` | `Array<{ name: string, renderOrder: number }>` | 否 | 可选的特定网格数组及其渲染顺序值 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
## 构造示例
|
||
|
||
- 当前 Demo 中没有直接展示 `Tool` 的构造调用。
|
||
|
||
## 函数示例
|
||
|
||
### `Tool.defineMaterialOpacityMapping`
|
||
|
||
- 来源：`packages/demo/src/hooks/Bus.ts`
|
||
|
||
```ts
|
||
setSection(section: ParametricBox | THREE.Mesh) {
|
||
Tool.defineMaterialOpacityMapping(section);
|
||
this.section = section;
|
||
}
|
||
```
|
||
|
||
### `Tool.setSelectionExclude`
|
||
|
||
- 来源：`packages/demo/src/components/SceneTree.vue`
|
||
|
||
```ts
|
||
if (object) {
|
||
Tool.setSelectionExclude(object, selectable);
|
||
}
|
||
}
|
||
};
|
||
```
|
||
|
||
### `Tool.setExcludeAll`
|
||
|
||
- 来源：`packages/demo/src/panels/TunnelScene/RobotExcavationPanel.vue`
|
||
|
||
```ts
|
||
let defaultExcavationTunnel = new ParametricArch(viewer, {
|
||
...geometrySettings,
|
||
animate:false
|
||
});
|
||
defaultExcavationTunnel.name = "机器人开挖隧道碰撞体";
|
||
defaultExcavationTunnel.visible = false;
|
||
Tool.setExcludeAll(defaultExcavationTunnel)
|
||
viewer.rangeCullingManager.add(defaultExcavationTunnel);
|
||
```
|
||
|
||
## Demo 参考
|
||
|
||
### `Tool`
|
||
|
||
以下示例文件中可以看到该 API 的实际调用方式：
|
||
|
||
- `packages/demo/src/components/SceneTree.vue`
|
||
- `packages/demo/src/hooks/Bus.ts`
|
||
- `packages/demo/src/hooks/useDebug.ts`
|
||
- `packages/demo/src/panels/TunnelScene/RobotExcavationPanel.vue`
|
||
- `packages/demo/src/views/GeothermalScene.vue`
|
||
- `packages/demo/src/views/GoldMineScene.vue`
|
||
- `packages/demo/src/views/OilGasScene.vue`
|
||
- `packages/demo/src/views/TunnelScene.vue`
|
||
|