---
outline: [2, 3]
---

# PointCloud

- 源文件：`packages/sdk/src/effect/volume/PointCloud.ts`
- 文档位置：`packages/docs/api/effect/volume/PointCloud.md`

## 接口：`PointCloudColorStop`

- 作用：点云颜色停靠点配置。

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `color` | `string` | 是 | 颜色值（支持十六进制、rgb、hsl 等 Canvas 支持的格式）。 |
| `step` | `number` | 是 | 渐变位置，范围 0~1。 |

## 接口：`PointCloudOptions`

- 作用：点云渲染配置。

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | 场景树显示名称。 |
| `pointCloudData` | `PointCloudData` | 是 | 外部已准备好的点云数据。 |
| `colorStops` | `PointCloudColorStop[]` | 否 | 颜色映射节点。 |
| `pointSize` | `number` | 否 | 点大小（像素单位）。 |

## 类：`PointCloud`

- 作用：点云渲染对象。 参考 `webgpu_instance_points.html`： 使用 `Sprite + PointsNodeMaterial + instancedBufferAttribute + count` 的模式进行实例化点渲染。
- 继承/实现：`extends THREE.Sprite`

### 构造函数

#### `new PointCloud(viewer: Viewer, options: PointCloudOptions)`

- 作用：创建点云渲染对象。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `viewer` | `Viewer` | 是 | 视图实例 |
| `options` | `PointCloudOptions` | 是 | 点云渲染配置 |

- 出参：`PointCloud`
- 返回说明：返回当前类实例。

### 属性

| 属性名 | 可见性 | 类型 | 作用 |
| --- | --- | --- | --- |
| `viewer` | `public readonly` | `Viewer` | 场景视图实例。 |
| `opacity` | `public` | `THREE.UniformNode<'float', number>` | 控制对象或材质的透明度。 |
| `densityRange` | `public` | `THREE.UniformNode<'vec2', THREE.Vector2>` | 用于保存 `densityRange` 对应的数据。 |

### 方法

#### `filterByIntensity(min: number, max: number = 1): void`

- 作用：按强度区间过滤点云显示。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `min` | `number` | 是 | 最小强度 |
| `max` | `number` | 否 | 最大强度 |

- 出参：`void`
- 返回说明：无返回值。

#### `setPointSize(pointSize: number): void`

- 作用：批量更新点大小。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pointSize` | `number` | 是 | 新的点大小（像素单位） |

- 出参：`void`
- 返回说明：无返回值。

#### `dispose(): void`

- 作用：销毁点云对象并释放资源。

- 入参：无

- 出参：`void`
- 返回说明：无返回值。

## 构造示例

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

```ts
  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
  });

  volume = new PointCloud(viewer, {
    name: '粉尘浓度',
    pointCloudData,
    pointSize: pointSize.value,
    colorStops: [
      {color: '#d18f0a', step: 0.0},
      {color: '#f23100', step: 0.05},
      {color: '#6609ff', step: 0.1},
      {color: '#06ffaa', step: 0.15},
      {color: '#ce0e59', step: 0.2},
      {color: '#00f60b', step: 0.3},
      {color: '#ffef00', step: 0.5},
      {color: '#fd0000', step: 1.0}
    ],
  });
  volume.filterByIntensity(intensityRange.value[0], intensityRange.value[1]);
  volume.setPointSize(pointSize.value);
  hasVolume.value = true;
  bus.triggerSceneTreeUpdate();
```

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

```ts
  /**
   * 创建点云并绑定颜色映射。
   */
  cloud = new PointCloud(viewer, {
    name: "地热温度点云",
    pointCloudData,
    pointSize: pointSize.value,
    colorStops: [
      {color: "#0000FF", step: 0.0},
      {color: "#00FF00", step: 0.33},
      {color: "#FFFF00", step: 0.66},
      {color: "#FF0000", step: 1.0},
    ],
  });
```

## 函数示例

### `PointCloud.filterByIntensity`

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

```ts
    pointSize: pointSize.value,
    colorStops: [
      {color: '#d18f0a', step: 0.0},
      {color: '#f23100', step: 0.05},
      {color: '#6609ff', step: 0.1},
      {color: '#06ffaa', step: 0.15},
      {color: '#ce0e59', step: 0.2},
      {color: '#00f60b', step: 0.3},
      {color: '#ffef00', step: 0.5},
      {color: '#fd0000', step: 1.0}
    ],
  });
  volume.filterByIntensity(intensityRange.value[0], intensityRange.value[1]);
  volume.setPointSize(pointSize.value);
  hasVolume.value = true;
  bus.triggerSceneTreeUpdate();
};
```

### `PointCloud.setPointSize`

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

```ts
    colorStops: [
      {color: '#d18f0a', step: 0.0},
      {color: '#f23100', step: 0.05},
      {color: '#6609ff', step: 0.1},
      {color: '#06ffaa', step: 0.15},
      {color: '#ce0e59', step: 0.2},
      {color: '#00f60b', step: 0.3},
      {color: '#ffef00', step: 0.5},
      {color: '#fd0000', step: 1.0}
    ],
  });
  volume.filterByIntensity(intensityRange.value[0], intensityRange.value[1]);
  volume.setPointSize(pointSize.value);
  hasVolume.value = true;
  bus.triggerSceneTreeUpdate();
};
```

## Demo 参考

### `PointCloud`

以下示例文件中可以看到该 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`
- `packages/demo/src/views/GeothermalScene.vue`
- `packages/demo/src/views/TunnelScene.vue`