---
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`