ljq/deep-engine-demo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(all): init commit

Browse Source
This commit is contained in:
plum
2026-04-19 18:46:28 +08:00
commit 5d7f479765
479 changed files with 178500 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/docs/api/effect/volume/PointCloud.md
+218
View File
@@ -0,0 +1,218 @@
---
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`
packages/docs/api/effect/volume/PointCloudTool.md
+172
View File
@@ -0,0 +1,172 @@
---
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`
packages/docs/api/effect/volume/VolumeMesh.md
+314
View File
@@ -0,0 +1,314 @@
---
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`
packages/docs/api/effect/volume/VolumeNode.md
+104
View File
@@ -0,0 +1,104 @@
---
outline: [2, 3]
---
# VolumeNode
- 源文件：`packages/sdk/src/effect/volume/VolumeNode.ts`
- 文档位置：`packages/docs/api/effect/volume/VolumeNode.md`
## 接口：`IVoxelMaterialOptions`
- 作用：IVoxelMaterialOptions 的结构定义。
### 定义
```ts
export interface IVoxelMaterialOptions {
readonly colorTexture: NodeElements;
readonly texture: NodeElements;
readonly range: NodeElements;
readonly threshold: NodeElements;
readonly opacity: NodeElements;
readonly steps: NodeElements;
readonly useSmoothing: NodeElements;
readonly mode: NodeElements;
readonly clipMode: NodeElements;
readonly clipPlane: NodeElements;
readonly clipPlaneX: NodeElements;
readonly clipPlaneY: NodeElements;
readonly clipPlaneZ: NodeElements;
readonly [key: string]: unknown;
}
```
## 接口：`IEmissionAbsorptionModelOptions`
- 作用：IEmissionAbsorptionModelOptions 的结构定义。
### 定义
```ts
export interface IEmissionAbsorptionModelOptions {
readonly colorTexture: NodeElements;
readonly texture: NodeElements;
readonly range: NodeElements;
readonly threshold: NodeElements;
readonly opacity: NodeElements;
readonly steps: NodeElements;
readonly useSmoothing: NodeElements;
readonly clipMode: NodeElements;
readonly clipPlane: NodeElements;
readonly clipPlaneX: NodeElements;
readonly clipPlaneY: NodeElements;
readonly clipPlaneZ: NodeElements;
readonly [key: string]: unknown;
}
```
## 接口：`IMaximumIntensityProjectionOptions`
- 作用：IMaximumIntensityProjectionOptions 的结构定义。
### 定义
```ts
export interface IMaximumIntensityProjectionOptions {
readonly colorTexture: NodeElements;
readonly texture: NodeElements;
readonly opacity: NodeElements;
readonly steps: NodeElements;
readonly clipMode: NodeElements;
readonly clipPlane: NodeElements;
readonly clipPlaneX: NodeElements;
readonly clipPlaneY: NodeElements;
readonly clipPlaneZ: NodeElements;
readonly [key: string]: unknown;
}
```
## 接口：`IMinimumIntensityProjectionOptions`
- 作用：IMinimumIntensityProjectionOptions 的结构定义。
### 定义
```ts
export interface IMinimumIntensityProjectionOptions {
readonly colorTexture: NodeElements;
readonly texture: NodeElements;
readonly opacity: NodeElements;
readonly steps: NodeElements;
readonly clipMode: NodeElements;
readonly clipPlane: NodeElements;
readonly clipPlaneX: NodeElements;
readonly clipPlaneY: NodeElements;
readonly clipPlaneZ: NodeElements;
readonly [key: string]: unknown;
}
```
packages/docs/api/effect/volume/VolumeTool.md
+213
View File
@@ -0,0 +1,213 @@
---
outline: [2, 3]
---
# VolumeTool
- 源文件：`packages/sdk/src/effect/volume/VolumeTool.ts`
- 文档位置：`packages/docs/api/effect/volume/VolumeTool.md`
## 类：`VolumeTool`
- 作用：体积数据工具类
### 方法
#### `remap(value: number, fromMin: number, fromMax: number, toMin = 0, toMax = 1): number`
- 作用：线性映射：将值从输入范围映射到输出范围
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `value` | `number` | 是 | 输入值 |
| `fromMin` | `number` | 是 | 输入范围最小值 |
| `fromMax` | `number` | 是 | 输入范围最大值 |
| `toMin` | `number` | 否 | 输出范围最小值（默认0） |
| `toMax` | `number` | 否 | 输出范围最大值（默认1） |
- 出参：`number`
- 返回说明：映射后的值
#### `generateVolumeData({ x, y, z, size = 256, rangeMin, rangeMax, }: { x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; }): Uint8Array<ArrayBufferLike>`
- 作用：生成3D体积数据，使用Simplex噪声算法
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `{ x, y, z, size = 256, rangeMin, rangeMax, }` | `{ x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; }` | 是 | 参数 `{ x, y, z, size = 256, rangeMin, rangeMax, }`，类型为 `{ x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; }`。 |
- 出参：`Uint8Array<ArrayBufferLike>`
- 返回说明：Uint8Array格式的体积数据
#### `generateVolumeDataWithClearLayers({ x, y, z, size = 256, rangeMin, rangeMax, clearLayers = 0 }: { x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; clearLayers?: number; }): Uint8Array<ArrayBufferLike>`
- 作用：生成3D体积数据并清除外层，使用Simplex噪声算法
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `{ x, y, z, size = 256, rangeMin, rangeMax, clearLayers = 0 }` | `{ x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; clearLayers?: number; }` | 是 | 参数 `{ x, y, z, size = 256, rangeMin, rangeMax, clearLayers = 0 }`，类型为 `{ x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; clearLayers?: number; }`。 |
- 出参：`Uint8Array<ArrayBufferLike>`
- 返回说明：Uint8Array格式的体积数据
#### `generateNoiseAroundPoints({ size = 256, worldOrigin, worldSize, points, rangeMin, rangeMax }: { size?: number; worldOrigin: [number, number, number]; worldSize: number; points: Array<{ position: [number, number, number]; radius: number, density: number }>; rangeMin: number; rangeMax: number; }): Uint8Array<ArrayBufferLike>`
- 作用：在指定世界空间坐标周围生成3D噪声值
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `{ size = 256, worldOrigin, worldSize, points, rangeMin, rangeMax }` | `{ size?: number; worldOrigin: [number, number, number]; worldSize: number; points: Array<{ position: [number, number, number]; radius: number, density: number }>; rangeMin: number; rangeMax: number; }` | 是 | 参数 `{ size = 256, worldOrigin, worldSize, points, rangeMin, rangeMax }`，类型为 `{ size?: number; worldOrigin: [number, number, number]; worldSize: number; points: Array<{ position: [number, number, number]; radius: number, density: number }>; rangeMin: number; rangeMax: number; }`。 |
- 出参：`Uint8Array<ArrayBufferLike>`
- 返回说明：Uint8Array格式的体积数据
#### `clearOuterLayers({ data, width, height, depth, layers }: { data: Uint8Array; width: number; height: number; depth: number; layers: number; }): void`
- 作用：清除体素空间最外层的数据，将其设置为0
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `{ data, width, height, depth, layers }` | `{ data: Uint8Array; width: number; height: number; depth: number; layers: number; }` | 是 | 参数 `{ data, width, height, depth, layers }`，类型为 `{ data: Uint8Array; width: number; height: number; depth: number; layers: number; }`。 |
- 出参：`void`
- 返回说明：无返回值。
#### `generateRandomVolumeInBox({ outerBox, innerBox, size = 256, rangeMin = 0, rangeMax = 255 }: { outerBox: THREE.Box3; innerBox: THREE.Box3; size?: number; rangeMin?: number; rangeMax?: number; }): Uint8Array<ArrayBufferLike>`
- 作用：在内部包围盒中生成随机体积数据
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `{ outerBox, innerBox, size = 256, rangeMin = 0, rangeMax = 255 }` | `{ outerBox: THREE.Box3; innerBox: THREE.Box3; size?: number; rangeMin?: number; rangeMax?: number; }` | 是 | 参数 `{ outerBox, innerBox, size = 256, rangeMin = 0, rangeMax = 255 }`，类型为 `{ outerBox: THREE.Box3; innerBox: THREE.Box3; size?: number; rangeMin?: number; rangeMax?: number; }`。 |
- 出参：`Uint8Array<ArrayBufferLike>`
- 返回说明：Uint8Array格式的体积数据
#### `generateRandomVolumeAroundPipe({ outerBox, pipeStart, pipeEnd, pipeRadius, size = 256, rangeMin = 0, rangeMax = 255 }: TRandomVolumeAroundPipeOptions): Uint8Array<ArrayBufferLike>`
- 作用：在管道周围生成随机体积数据
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `{ outerBox, pipeStart, pipeEnd, pipeRadius, size = 256, rangeMin = 0, rangeMax = 255 }` | `TRandomVolumeAroundPipeOptions` | 是 | 参数 `{ outerBox, pipeStart, pipeEnd, pipeRadius, size = 256, rangeMin = 0, rangeMax = 255 }`，类型为 `TRandomVolumeAroundPipeOptions`。 |
- 出参：`Uint8Array<ArrayBufferLike>`
- 返回说明：Uint8Array格式的体积数据
#### `generateRandomVolumeAroundPipeWithBaseData({ outerBox, pipeStart, pipeEnd, pipeRadius, size = 256, rangeMin = 0, rangeMax = 255, baseData }: TRandomVolumeAroundPipeOptions & { baseData: Uint8Array; }): Uint8Array<ArrayBufferLike>`
- 作用：在已有体积数据基础上按管道规则继续生成数据
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `{ outerBox, pipeStart, pipeEnd, pipeRadius, size = 256, rangeMin = 0, rangeMax = 255, baseData }` | `TRandomVolumeAroundPipeOptions & { baseData: Uint8Array; }` | 是 | 参数 `{ outerBox, pipeStart, pipeEnd, pipeRadius, size = 256, rangeMin = 0, rangeMax = 255, baseData }`，类型为 `TRandomVolumeAroundPipeOptions & { baseData: Uint8Array; }`。 |
- 出参：`Uint8Array<ArrayBufferLike>`
- 返回说明：Uint8Array格式的体积数据
## 构造示例
- 当前 Demo 中没有直接展示 `VolumeTool` 的构造调用。
## 函数示例
### `VolumeTool.remap`
- 来源：`packages/demo/src/panels/GeothermalScene/DustConcentrationPanel.vue`
```ts
const mappedZList = new Float32Array(VOLUME_SIZE);
for (let x = 0; x < VOLUME_SIZE; x++) {
mappedXList[x] = VolumeTool.remap(x, 0, VOLUME_SIZE - 1, outerBox.min.x, outerBox.max.x);
}
for (let y = 0; y < VOLUME_SIZE; y++) {
mappedYList[y] = VolumeTool.remap(y, 0, VOLUME_SIZE - 1, outerBox.min.y, outerBox.max.y);
}
for (let z = 0; z < VOLUME_SIZE; z++) {
mappedZList[z] = VolumeTool.remap(z, 0, VOLUME_SIZE - 1, outerBox.min.z, outerBox.max.z);
}
```
### `VolumeTool.generateVolumeData`
- 来源：`packages/demo/src/panels/TunnelScene/FieldData/StrainDisplayPanel.vue`
```ts
const viewer = bus.getViewer();
const data = VolumeTool.generateVolumeData({size: 256, rangeMin: 10, rangeMax: 50});
volume = new VolumeMesh(viewer, {
name: "应变场",
size: 256,
data,
mode: VolumeRenderMode.EmissionAbsorptionModel,
clipMode: bus.clippingMode === 'single' ? 1 : 0,
scale: 4.99,
colorStops: [
{color: '#00FFFF', step: 0.2},
{color: '#0080FF', step: 0.5},
{color: '#8000FF', step: 0.7},
{color: '#FF00FF', step: 1.0},
],
});
volume.renderOrder = 1
// 如果加载面面板已打开，则启用体材质深度测试
if (bus.getLoadSurfaceExists && bus.getLoadSurfaceExists()) {
```
### `VolumeTool.generateRandomVolumeAroundPipeWithBaseData`
- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/TemperaturePanel.vue`
```ts
try {
// 与 StressDisplayPanel 一致：通过 resources.loadRawData 加载 RAW。
data = await getTemperatureVolumeData();
data = VolumeTool.generateRandomVolumeAroundPipeWithBaseData({
outerBox: outerBox,
pipeStart: new THREE.Vector3(-0.11, 0, -2.505),
pipeEnd: new THREE.Vector3(-0.11, 0, -1.4),
pipeRadius: 0.25,
size: 256,
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);
}
```
## Demo 参考
### `VolumeTool`
以下示例文件中可以看到该 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`