deep-engine-demo/packages/docs/api/tool/Tool.md

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

    setSection(section: ParametricBox | THREE.Mesh) {
        Tool.defineMaterialOpacityMapping(section);
        this.section = section;
    }

Tool.setSelectionExclude

• 来源：packages/demo/src/components/SceneTree.vue

    if (object) {
      Tool.setSelectionExclude(object, selectable);
    }
  }
};

Tool.setExcludeAll

• 来源：packages/demo/src/panels/TunnelScene/RobotExcavationPanel.vue

  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