173 lines
5.8 KiB
Markdown
173 lines
5.8 KiB
Markdown
---
|
||
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`
|
||
|