deep-engine-demo/packages/docs/api/effect/volume/PointCloudTool.md

outline
2 3

PointCloudTool

• 源文件：packages/sdk/src/effect/volume/PointCloudTool.ts
• 文档位置：packages/docs/api/effect/volume/PointCloudTool.md

接口：PointCloudData

• 作用：点云数据结构。

字段

字段名	类型	必填	作用
positions	Float32Array	是	点位坐标数组，格式为 xyzxyz...
densities	Float32Array	是	点位强度数组，范围为 0~1。

接口：PointCloudNoiseOptions

• 作用：噪声点云生成参数。

字段

字段名	类型	必填	作用
x	number	否	X 方向分辨率（可选，如果提供 size 则忽略）。
y	number	否	Y 方向分辨率（可选，如果提供 size 则忽略）。
z	number	否	Z 方向分辨率（可选，如果提供 size 则忽略）。
size	number	否	统一分辨率，同时设置 x/y/z。
spaceSize	number	否	点云空间边长。
min	[number, number, number]	否	点云空间最小边界 [x, y, z]。
max	[number, number, number]	否	点云空间最大边界 [x, y, z]。
threshold	number	否	强度阈值，范围 0~1。
noiseScale	number	否	噪声空间缩放。

接口：PointCloudGridOptions

• 作用：规则网格点云参数。

字段

字段名	类型	必填	作用
xRange	[number, number]	是	X 轴最小值与最大值。
yRange	[number, number]	是	Y 轴最小值与最大值。
zRange	[number, number]	是	Z 轴最小值与最大值。
xCount	number	是	X 轴采样数量。
yCount	number	是	Y 轴采样数量。
zCount	number	是	Z 轴采样数量。
density	number | ((x: number, y: number, z: number) => number)	否	强度值或强度计算函数。

接口：PointCloudFromVolumeOptions

• 作用：体积数据转点云参数。

字段

字段名	类型	必填	作用
data	Uint8Array | Uint16Array | Float32Array	是	体素数据，通常来自 VolumeTool（如 Uint8Array）。
x	number	否	X 方向分辨率（可选，如果提供 size 则忽略）。
y	number	否	Y 方向分辨率（可选，如果提供 size 则忽略）。
z	number	否	Z 方向分辨率（可选，如果提供 size 则忽略）。
size	number	否	统一分辨率，同时设置 x/y/z。
spaceSize	number	否	点云空间边长。
min	[number, number, number]	否	点云空间最小边界 [x, y, z]。
max	[number, number, number]	否	点云空间最大边界 [x, y, z]。
threshold	number	否	强度阈值，范围 0~1，仅保留大于该值的点。
sourceMin	number	否	原始数据最小值，默认 0。
sourceMax	number	否	原始数据最大值，默认 255（兼容 VolumeTool 输出）。

类：PointCloudTool

• 作用：点云数据工具类。

方法

generateNoisePointCloudData(options: PointCloudNoiseOptions): PointCloudData

• 作用：直接生成噪声点云数据。 生成逻辑基于点云密度： 1. 使用 3D 噪声采样 2. 将噪声值映射到 0~1 强度 3. 根据阈值筛选有效点

• 入参：

参数名	类型	必填	说明
options	PointCloudNoiseOptions	是	生成参数

• 出参：PointCloudData
• 返回说明：点云数据

generateGridPointCloud(options: PointCloudGridOptions): PointCloudData

• 作用：生成规则网格点云数据。

• 入参：

参数名	类型	必填	说明
options	PointCloudGridOptions	是	规则网格参数

• 出参：PointCloudData
• 返回说明：点云数据

convertVolumeToPointCloudData(options: PointCloudFromVolumeOptions): PointCloudData

• 作用：将体积数据转换为点云数据。 默认按 VolumeTool 输出规则将 0~255 映射为 0~1 强度，并根据阈值筛选。

• 入参：

参数名	类型	必填	说明
options	PointCloudFromVolumeOptions	是	转换参数

• 出参：PointCloudData
• 返回说明：点云数据

构造示例

• 当前 Demo 中没有直接展示 PointCloudTool 的构造调用。

函数示例

PointCloudTool.generateNoisePointCloudData

• 来源：packages/demo/src/panels/GeothermalScene/PointCloud/PointCloudTemperatureDisplayPanel.vue

  /**
   * 生成用于温度点云的点数据。
   */
  const pointCloudData = PointCloudTool.generateNoisePointCloudData({
    min: [-2.5, -2.5, -2.5],
    max: [2.5, 2.5, 2.5],
    x: 170,
    y: 170,
    z: 170,
    threshold: 0,
  });

PointCloudTool.convertVolumeToPointCloudData

• 来源：packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue

  const box = new THREE.Box3().setFromObject(mesh);
  const pointCloudData = PointCloudTool.convertVolumeToPointCloudData({
    data: mesh.data,
    x: mesh.sizeX,
    y: mesh.sizeY,
    z: mesh.sizeZ,
    min: [box.min.x, box.min.y, box.min.z],
    max: [box.max.x, box.max.y, box.max.z],
    threshold: 0
  });

Demo 参考

PointCloudTool

以下示例文件中可以看到该 API 的实际调用方式：

• packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue
• packages/demo/src/panels/GeothermalScene/PointCloud/PointCloudTemperatureDisplayPanel.vue
• packages/demo/src/panels/TunnelScene/PointCloud/PointCloudStrainDisplayPanel.vue
• packages/demo/src/panels/TunnelScene/PointCloud/PointCloudStressDisplayPanel.vue
• packages/demo/src/panels/TunnelScene/PointCloud/PointCloudTemperatureDisplayPanel.vue