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

```ts
  /**
   * 生成用于温度点云的点数据。
   */
  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`

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