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

# VolumeMesh

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

## 接口：`ColorStop`

- 作用：ColorStop 的结构定义。

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `color` | `string` | 是 | 颜色配置。 |
| `step` | `number` | 是 | 用于保存 `step` 对应的数据。 |

## 枚举：`VolumeRenderMode`

- 作用：VolumeRenderMode 枚举定义。

| 枚举项 | 值 | 说明 |
| --- | --- | --- |
| `EmissionAbsorptionModel` | `0` | 枚举值 `EmissionAbsorptionModel`。 |
| `MinimumIntensityProjection` | `1` | 枚举值 `MinimumIntensityProjection`。 |
| `MaximumIntensityProjection` | `2` | 枚举值 `MaximumIntensityProjection`。 |

## 接口：`VolumeRenderingOptions`

- 作用：VolumeRenderingOptions 的结构定义。

### 字段

| 字段名 | 类型 | 必填 | 作用 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | 名称。 |
| `scale` | `number` | 否 | 用于保存 `scale` 对应的数据。 |
| `size` | `number` | 否 | 尺寸参数。 |
| `sizeX` | `number` | 否 | 用于保存 `sizeX` 对应的数据。 |
| `sizeY` | `number` | 否 | 用于保存 `sizeY` 对应的数据。 |
| `sizeZ` | `number` | 否 | 用于保存 `sizeZ` 对应的数据。 |
| `data` | `Uint8Array` | 是 | 输入数据。 |
| `colorStops` | `ColorStop[]` | 否 | 用于保存 `colorStops` 的集合数据。 |
| `range` | `number` | 否 | 用于保存 `range` 对应的数据。 |
| `threshold` | `number` | 否 | 阈值配置。 |
| `steps` | `number` | 否 | 用于保存 `steps` 对应的数据。 |
| `useSmoothing` | `boolean` | 否 | 用于标记 `useSmoothing` 的启用状态。 |
| `mode` | `VolumeRenderMode` | 否 | 用于保存 `mode` 对应的数据。 |
| `clipMode` | `0 \| 1` | 否 | 用于保存 `clipMode` 对应的数据。 |
| `clipPlane` | `THREE.Vector4` | 否 | 用于保存 `clipPlane` 对应的数据。 |
| `showWireframe` | `boolean` | 否 | 用于标记 `showWireframe` 的启用状态。 |

## 函数：`isVolumeMesh`

- 作用：执行 is Volume Mesh 相关逻辑。

### 签名

```ts
function isVolumeMesh(value: any): boolean
```

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `value` | `any` | 是 | 要写入的新值。 |

- 出参：`boolean`
- 返回说明：返回布尔结果。

## 类：`VolumeMesh`

- 作用：VolumeMesh 类。
- 继承/实现：`extends THREE.Mesh<THREE.BufferGeometry, THREE.NodeMaterial>`

### 构造函数

#### `new VolumeMesh(viewer: Viewer, options: VolumeRenderingOptions)`

- 作用：创建 VolumeMesh 实例。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
| `options` | `VolumeRenderingOptions` | 是 | 当前功能对应的配置项。 |

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

### 属性

| 属性名 | 可见性 | 类型 | 作用 |
| --- | --- | --- | --- |
| `panelCounter` | `public static` | `number` | 用于保存 `panelCounter` 对应的数据。 |
| `range` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `range` 对应的数据。 |
| `threshold` | `public` | `THREE.UniformNode<'float', number>` | 阈值配置。 |
| `opacity` | `public` | `THREE.UniformNode<'float', number>` | 控制对象或材质的透明度。 |
| `steps` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `steps` 对应的数据。 |
| `useSmoothing` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `useSmoothing` 对应的数据。 |
| `mode` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `mode` 对应的数据。 |
| `clipMode` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `clipMode` 对应的数据。 |
| `clipPlane` | `public` | `THREE.UniformNode<'vec4', THREE.Vector4>` | 用于保存 `clipPlane` 对应的数据。 |
| `clipPlaneX` | `public` | `THREE.UniformNode<'vec4', THREE.Vector4>` | 用于保存 `clipPlaneX` 对应的数据。 |
| `clipPlaneY` | `public` | `THREE.UniformNode<'vec4', THREE.Vector4>` | 用于保存 `clipPlaneY` 对应的数据。 |
| `clipPlaneZ` | `public` | `THREE.UniformNode<'vec4', THREE.Vector4>` | 用于保存 `clipPlaneZ` 对应的数据。 |
| `uniformScale` | `public` | `number` | 用于保存 `uniformScale` 对应的数据。 |
| `data` | `public` | `Uint8Array` | 输入数据。 |
| `viewer` | `public` | `Viewer` | 用于保存 `viewer` 对应的数据。 |
| `volumeTexture` | `public` | `THREE.Data3DTexture` | 用于保存 `volumeTexture` 对应的数据。 |
| `transferTexture` | `public` | `THREE.Texture` | 用于保存 `transferTexture` 对应的数据。 |
| `material` | `public` | `THREE.NodeMaterial` | 材质参数。 |
| `wireframe` | `public` | `ParametricWireframe` | 用于保存 `wireframe` 对应的数据。 |
| `sizeX` | `public` | `number` | 用于保存 `sizeX` 对应的数据。 |
| `sizeY` | `public` | `number` | 用于保存 `sizeY` 对应的数据。 |
| `sizeZ` | `public` | `number` | 用于保存 `sizeZ` 对应的数据。 |
| `canvas` | `public` | `HTMLCanvasElement` | 用于保存 `canvas` 对应的数据。 |
| `colorStops` | `public` | `ColorStop[]` | 用于保存 `colorStops` 的集合数据。 |
| `isVolumeMesh` | `public` | `boolean` | 用于标记 `isVolumeMesh` 的启用状态。 |

### 方法

#### `updateTransferTexture(colorStops: ColorStop[]): void`

- 作用：更新 Transfer Texture。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `colorStops` | `ColorStop[]` | 是 | 参数 `colorStops`，类型为 `ColorStop[]`。 |

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

#### `updateVolumeData(data: Uint8Array): void`

- 作用：更新 Volume Data。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `Uint8Array` | 是 | 输入数据。 |

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

#### `setWireframeVisible(visible: boolean): void`

- 作用：设置 Wireframe Visible。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `visible` | `boolean` | 是 | 是否可见。 |

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

#### `updateTransferTextureCanvas(colorStops: ColorStop[]): void`

- 作用：更新 Transfer Texture Canvas。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `colorStops` | `ColorStop[]` | 是 | 参数 `colorStops`，类型为 `ColorStop[]`。 |

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

#### `createTransferTexture(colorStops: ColorStop[]): THREE.Texture<unknown, THREE.TextureEventMap>`

- 作用：创建 Transfer Texture。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `colorStops` | `ColorStop[]` | 是 | 参数 `colorStops`，类型为 `ColorStop[]`。 |

- 出参：`THREE.Texture<unknown, THREE.TextureEventMap>`
- 返回说明：返回 `THREE.Texture<unknown, THREE.TextureEventMap>`。

#### `numberToHex(n: number): string`

- 作用：执行 number To Hex 相关逻辑。

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `n` | `number` | 是 | 参数 `n`，类型为 `number`。 |

- 出参：`string`
- 返回说明：返回字符串结果。

#### `dispose(): void`

- 作用：释放资源并销毁当前实例。

- 入参：无

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

#### `createDebugPanel(): void`

- 作用：创建 Debug Panel。

- 入参：无

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

## 构造示例

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

```ts
      rangeMin: 6,
      rangeMax: 53,
      baseData: data
    });
		// 获取 RAW 后重新遍历体数据，使用 noise3d 重新生成体素值。
		data = regenerateVolumeDataWithNoise3D(data, size);
	} catch (error: unknown) {
		// RAW 加载失败时回退为全 0 数据，保证面板不崩溃。
		console.error("温度体 RAW 加载失败，已回退为默认空数据：", error);
		data = new Uint8Array(size * size * size);
	}

	volume = new VolumeMesh(viewer, {
		name: "温度",
		size,
		scale: 4.99,
		data: data,
		mode: VolumeRenderMode.MaximumIntensityProjection,
		colorStops: [
			{ color: "#ae1be9", step: 0.0 },
			{ color: "#0bdb04", step: 0.05 },
			{ color: "#10e52b", step: 0.1 },
			{ color: "#1232db", step: 0.15 },
			{ color: "#0000FF", step: 0.2 },
			{ color: "#00FFFF", step: 0.33 },
			{ color: "#FFFF00", step: 0.66 },
			{ color: "#FF0000", step: 1.0 },
		],
	});
	volume.renderOrder = 3;
	// volume.material.depthTest = true
```

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

```ts
  const volumeData = generatePipeFilledVolumeData(outerBox);

  volume = new VolumeMesh(viewer, {
    name: '形变场数据',
    size: VOLUME_SIZE,
    scale: 4.99,
    data: volumeData,
    mode: VolumeRenderMode.MaximumIntensityProjection,
    colorStops: [
      // 强度 10（step≈0.04）起始为亮绿色，随强度升高过渡至深绿，热点高强度区映射为红色。
      {color: "#335b33", step: 0.04},
      {color: "#00ff00", step: 0.62},
      {color: "#b31414", step: 0.90},
      {color: "#FF0000", step: 1.00},
    ],
  });
  volume.renderOrder = 1
  // volume.material.depthTest = true
  volume.material.opacity = 0.5
  hasVolume.value = true;
  bus.triggerSceneTreeUpdate()
```

## 函数示例

- 当前 Demo 中没有直接展示 `VolumeMesh` 的公开方法调用。

## Demo 参考

### `VolumeRenderMode`

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

- `packages/demo/src/disasterFormationPanel/GoldMineScene/TemperaturePanel.vue`
- `packages/demo/src/panels/GeothermalScene/DustConcentrationPanel.vue`
- `packages/demo/src/panels/TunnelScene/FieldData/StrainDisplayPanel.vue`
- `packages/demo/src/panels/TunnelScene/FieldData/StressDisplayPanel.vue`
- `packages/demo/src/panels/TunnelScene/FieldData/TemperatureDisplayPanel.vue`

### `VolumeMesh`

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

- `packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue`
- `packages/demo/src/disasterFormationPanel/GoldMineScene/TemperaturePanel.vue`
- `packages/demo/src/panels/GeothermalScene/DustConcentrationPanel.vue`
- `packages/demo/src/panels/TunnelScene/FieldData/StrainDisplayPanel.vue`
- `packages/demo/src/panels/TunnelScene/FieldData/StressDisplayPanel.vue`
- `packages/demo/src/panels/TunnelScene/FieldData/TemperatureDisplayPanel.vue`