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

feat(all): 更新文档

Browse Source
This commit is contained in:
plum
2026-05-06 22:16:20 +08:00
parent 8a1436d3a8
commit d2329a6854
14 changed files with 233574 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/demo/src/main.ts
+1 -1
View File
@@ -4,7 +4,7 @@ import App from './App.vue'
import router from './router'
import {Bus} from "./hooks/Bus.ts";
import DisableDevtool from 'disable-devtool';
import * as THREE from 'three';
const app = createApp(App)
app.config.globalProperties.bus = new Bus();
window.bus = app.config.globalProperties.bus
packages/demo/vite.config.ts
+1 -1
View File
@@ -39,7 +39,7 @@ export default defineConfig({
// 监听所有网络接口（0.0.0.0），允许外部IP访问
host: '0.0.0.0',
// 可选：指定端口（如8099，和你之前的Caddy端口一致）
port: 8099,
port: 8059,
// 可选：端口被占用时自动切换可用端口
strictPort: false,
// 可选：自动打开浏览器
packages/docs/api-examples.md
+20 -4
View File
@@ -22,17 +22,33 @@ Deep Engine 是一个**基于 Three.js WebGPU 进行封装的三维引擎库**
当前文档主要分为以下几部分：
- `API 示例说明`：说明文档的组织方式与阅读建议
- `首页`：说明库的整体定位与核心能力
- `API`：按源码模块整理的接口文档
- `API 示例说明`：说明文档的组织方式与阅读建议
## 适合阅读人群
本文档更适合具备以下基础的开发者阅读和使用：
- 需要具备前端开发基础，能够理解工程结构、模块组织和基础构建流程
- 需要具备基础的三维图形能力，理解场景、相机、材质、几何体、坐标系等基本概念
- 需要具备 Three.js 使用经验，能够理解常见对象、渲染流程以及场景交互方式
## 文档导航布局
当前文档站已经调整为双栏导航结构，便于同时浏览模块层级与当前页面内容：
- 左侧显示大目录：按文档入口、API 模块分类、源码扩展分类组织页面
- 右侧显示小目录：自动提取当前页面的 `H2` 与 `H3` 标题，便于页内快速跳转
## 阅读建议
如果你是第一次接触这个库，建议按下面顺序阅读：
1. 先阅读首页，了解该库是基于 Three.js WebGPU 的封装库。
2. 再阅读 `packages/docs/api` 下的 API 文档，熟悉 `Viewer`、`Tool`、`Parametric`、`Effect` 等模块。
3. 最后结合 `packages/demo/src` 中的示例场景，对照查看具体调用方式。
1. 先阅读文档说明，明确文档结构、阅读方式和前置能力要求。
2. 再阅读首页，了解该库是基于 Three.js WebGPU 的封装库。
3. 然后阅读 `packages/docs/api` 下的 API 文档，熟悉 `Viewer`、`Tool`、`Parametric`、`Effect` 等模块。
4. 最后结合 `packages/demo/src` 中的示例场景，对照查看具体调用方式。
## 与 Demo 的关系
packages/docs/api/effect/FlowParticles.md
+65
View File
@@ -7,6 +7,19 @@ outline: [2, 3]
- 源文件：`packages/sdk/src/effect/FlowParticles.ts`
- 文档位置：`packages/docs/api/effect/FlowParticles.md`
## 地热注采流动说明
`FlowParticles` 在地热注采场景中支持两类模式：
- `bidirectional`：双向对向流动，左右侧粒子分别向中段推进。
- `single`：单向流动，支持按左右流量差异发射“补差粒子”，并在中段附近显隐以模拟注采不均衡。
最新业务逻辑包含：
- 单向模式的左右段隐藏特例（某侧速度为 0 时，该侧默认隐藏）。
- 基于几何投影的显隐判定，避免仅按参数 `t` 带来的路径不均问题。
- 右侧流量高于左侧时，自动发射补差粒子。
## 接口：`FlowParticlesGPUOptions`
- 作用：流动粒子配置。
@@ -19,6 +32,11 @@ outline: [2, 3]
| `endPipe` | `ParametricPipe` | 是 | 结束管道。 |
| `particleCount` | `number` | 否 | 粒子总数量。 |
| `speedMultiplier` | `number` | 否 | 粒子流动速度倍率。 |
| `flowMode` | `"single" \| "bidirectional"` | 否 | 流动模式，默认 `single`。 |
| `leftFlowRate` | `number` | 否 | 左侧流量权重。 |
| `rightFlowRate` | `number` | 否 | 右侧流量权重。 |
| `leftSpeedMultiplier` | `number` | 否 | 左侧速度倍率。 |
| `rightSpeedMultiplier` | `number` | 否 | 右侧速度倍率。 |
| `particleSize` | `number` | 否 | 粒子半径。 |
| `heatingThreshold` | `number` | 否 | 加热阈值。 |
| `flowPathCount` | `number` | 否 | 流动路径数量。 |
@@ -65,6 +83,11 @@ outline: [2, 3]
| `endPipe` | `public` | `ParametricPipe` | 用于保存 `endPipe` 对应的数据。 |
| `particleCount` | `public` | `number` | 用于保存 `particleCount` 对应的数据。 |
| `speedMultiplier` | `public` | `number` | 用于保存 `speedMultiplier` 对应的数据。 |
| `flowMode` | `public` | `"single" \| "bidirectional"` | 当前流动模式。 |
| `leftFlowRate` | `public` | `number` | 左侧流量权重。 |
| `rightFlowRate` | `public` | `number` | 右侧流量权重。 |
| `leftSpeedMultiplier` | `public` | `number` | 左侧速度倍率。 |
| `rightSpeedMultiplier` | `public` | `number` | 右侧速度倍率。 |
| `particleSize` | `public` | `number` | 用于保存 `particleSize` 对应的数据。 |
| `heatingThreshold` | `public` | `number` | 用于保存 `heatingThreshold` 对应的数据。 |
| `flowPathCount` | `public` | `number` | 用于保存 `flowPathCount` 对应的数据。 |
@@ -104,6 +127,34 @@ outline: [2, 3]
- 出参：`void`
- 返回说明：无返回值。
#### `setSideFlowRates(leftRate: number, rightRate: number): void`
- 作用：设置左右流量权重。双向模式下会重建粒子系统；单向模式下用于更新发射和保留判定。
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `leftRate` | `number` | 是 | 左侧流量权重。 |
| `rightRate` | `number` | 是 | 右侧流量权重。 |
- 出参：`void`
- 返回说明：无返回值。
#### `setSideSpeedMultipliers(leftSpeed: number, rightSpeed: number): void`
- 作用：设置左右速度倍率，用于控制两侧流动推进速度。
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `leftSpeed` | `number` | 是 | 左侧速度倍率。 |
| `rightSpeed` | `number` | 是 | 右侧速度倍率。 |
- 出参：`void`
- 返回说明：无返回值。
#### `setFrozenProbability(probability: number): void`
- 作用：设置冻结概率。
@@ -232,8 +283,13 @@ outline: [2, 3]
const flowParticles = new FlowParticles(viewer, {
startPipe: pipe1,
endPipe: pipe2,
flowMode: "single",
particleCount: particleCount.value,
speedMultiplier: speedMultiplier.value,
leftFlowRate: 1,
rightFlowRate: 1.2,
leftSpeedMultiplier: 1,
rightSpeedMultiplier: 1,
particleSize: particleSize.value,
heatingThreshold: heatingThreshold.value,
colorStops: [
@@ -287,6 +343,15 @@ outline: [2, 3]
};
```
### `FlowParticles.setSideFlowRates`
```ts
if (flowParticles) {
flowParticles.setSideFlowRates(1, 1.4);
flowParticles.setSideSpeedMultipliers(1, 0.9);
}
```
### `FlowParticles.dispose`
- 来源：`packages/demo/src/panels/GeothermalScene/GeothermalInjectionProductionPanel.vue`
packages/docs/api/effect/volume/VtkStructuredPointsParser.md
+111
View File
@@ -0,0 +1,111 @@
---
outline: [2, 3]
---
# VtkStructuredPointsParser
- 源文件：`packages/sdk/src/effect/volume/vtk/VtkStructuredPointsParser.ts`
- 文档位置：`packages/docs/api/effect/volume/VtkStructuredPointsParser.md`
## 类：`VtkStructuredPointsParser`
- 作用：解析 legacy VTK 体数据，提取指定分量，返回可直接用于体渲染的数据和元信息。
## 支持范围
- 支持 `ASCII` / `BINARY` 编码自动识别。
- 支持 `DATASET STRUCTURED_POINTS`（binary）。
- 支持 `ASCII UNSTRUCTURED_GRID` 规则网格转体数据。
- 支持从 `CELL_DATA` 或 `POINT_DATA` 自动解析标量来源。
## 相关类型
### `IVtkParseFromUrlOptions`
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | 是 | 远程 VTK 文件地址。 |
| `componentIndex` | `number` | 是 | 要提取的分量索引，从 0 开始。 |
| `fileName` | `string` | 否 | 可选文件名，默认从 URL 推断。 |
| `requestInit` | `RequestInit` | 否 | `fetch` 附加参数。 |
### `IVtkParseFromBufferOptions`
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `buffer` | `ArrayBuffer \| Uint8Array` | 是 | VTK 原始二进制内容。 |
| `componentIndex` | `number` | 是 | 要提取的分量索引，从 0 开始。 |
| `fileName` | `string` | 否 | 可选文件名，默认 `unknown.vtk`。 |
### `IVtkParsedComponentResult`
| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `metadata` | `IVtkStructuredPointsMetadata` | 体数据元信息。 |
| `componentIndex` | `number` | 当前提取的分量索引。 |
| `valueRange` | `[number, number]` | 当前分量值域。 |
| `values` | `Float32Array` | 当前分量一维标量数组。 |
### `IVtkStructuredPointsMetadata`
| 字段名 | 类型 | 说明 |
| --- | --- | --- |
| `fileName` | `string` | 文件名。 |
| `fileSize` | `number` | 文件字节数。 |
| `sourceDimensions` | `TVector3` | 原始点维度。 |
| `cellDimensions` | `TVector3` | 渲染采样维度。 |
| `spacing` | `TVector3` | 网格间距。 |
| `sourceOrigin` | `TVector3` | 原始原点。 |
| `pointOrigin` | `TVector3` | 体素中心原点。 |
| `scalarName` | `string` | 标量名称。 |
| `scalarType` | `string` | 标量类型描述。 |
| `componentCount` | `number` | 标量分量数。 |
| `cellCount` | `number` | 元组数量（通常对应体素数）。 |
| `scalarSource` | `"cell" \| "point"` | 标量来源。 |
## 方法
### `parseFromUrl(options: IVtkParseFromUrlOptions): Promise<IVtkParsedComponentResult>`
- 作用：从 URL 下载并解析 VTK 数据。
- 典型错误：下载失败、编码不支持、数据集类型不支持、分量越界。
### `parseFromBuffer(options: IVtkParseFromBufferOptions): IVtkParsedComponentResult`
- 作用：从内存缓冲区解析 VTK 数据。
- 适用场景：文件上传、自定义网络层、离线缓存解析。
## 使用示例
```ts
import { VtkStructuredPointsParser, VolumeMesh, VolumeRenderMode } from "@deep/engine";
const parser = new VtkStructuredPointsParser();
const parsed = await parser.parseFromUrl({
url: "/model/vtk/stress_cells_256.vtk",
componentIndex: 0,
});
const [minValue, maxValue] = parsed.valueRange;
const values = parsed.values;
const voxels = new Uint8Array(values.length);
const denominator = Math.max(maxValue - minValue, Number.EPSILON);
for (let i = 0; i < values.length; i += 1) {
const normalized = (values[i] - minValue) / denominator;
voxels[i] = Math.round(Math.max(0, Math.min(1, normalized)) * 255);
}
const volume = new VolumeMesh(voxels, {
shape: parsed.metadata.cellDimensions,
mode: VolumeRenderMode.EmissionAbsorptionModel,
});
```
## 注意事项
- `componentIndex` 必须在 `[0, componentCount - 1]` 范围内。
- `UNSTRUCTURED_GRID` 仅支持规则网格输入，非规则点云会抛错。
- Binary 读取按大端浮点处理（legacy VTK 约定）。
- 数据值域映射通常需要在业务层完成（如映射到 `Uint8Array` 供体渲染）。
packages/docs/api/index.md
+3 -1
View File
@@ -6,6 +6,8 @@ outline: [2, 3]
本文档基于 `packages/sdk/src` 的实际源码结构整理，并参考 `packages/demo/src` 中的调用方式补充了常见入口。每个页面都包含函数入参、出参以及属性作用说明。
SDK 执行 `pnpm sdk:build` 后，会同时输出运行时代码到 `packages/sdk/dist`，并输出类型声明到 `packages/sdk/types`。外部项目通过 `@deep/engine` 导入时，可直接获得对应的 TypeScript 类型信息。
## 快速使用流程
```ts
@@ -89,6 +91,7 @@ viewer.emitter.once(ViewerEvents.INIT).then(() => {
- [PointCloud](/api/effect/volume/PointCloud)
- [PointCloudTool](/api/effect/volume/PointCloudTool)
- [VtkStructuredPointsParser](/api/effect/volume/VtkStructuredPointsParser)
- [VolumeMesh](/api/effect/volume/VolumeMesh)
- [VolumeNode](/api/effect/volume/VolumeNode)
- [VolumeTool](/api/effect/volume/VolumeTool)
@@ -133,4 +136,3 @@ viewer.emitter.once(ViewerEvents.INIT).then(() => {
### 源码扩展 Curves
- [CatmullRomCurve3](/api/source/curves/CatmullRomCurve3)
packages/docs/api/manager/ClippingManager.md
+105 -14
View File
@@ -9,11 +9,20 @@ outline: [2, 3]
## 类：`ClippingManager`
- 作用：剖切管理器 管理剖切组和任意数量的剖切面（通过 addPlane 手动创建）
- 作用：剖切管理器，负责剖切对象收拢、剖切平面管理，以及单面剖切补面（CSG）结果生成。
## 剖切补面能力说明
`single` 平面启用后，管理器会在 `clippingGroup` 中按名称查找目标网格，执行一次“目标网格 - 刀具体”的 CSG 运算，将结果放到 `singlePlaneCapGroup`，并临时隐藏原网格。
- 目标网格通过 `setSinglePlaneCapTargetByName` 指定。
- 开关通过 `setSinglePlaneCapEnabled` 控制。
- 仅当剖切平面与目标网格包围盒相交时才生成结果。
- 平面移动时自动刷新补面结果。
### 构造函数
#### `new ClippingManager(viewer: Viewer)`
#### `new ClippingManager(viewer: Viewer, options?: IClippingManagerOptions)`
- 作用：创建 ClippingManager 实例。
@@ -22,6 +31,7 @@ outline: [2, 3]
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
| `options` | `IClippingManagerOptions` | 否 | 剖切管理配置，支持默认补面目标网格和默认启用状态。 |
- 出参：`ClippingManager`
- 返回说明：返回当前类实例。
@@ -39,6 +49,16 @@ outline: [2, 3]
| `scene` | `public` | `THREE.Scene` | 用于保存 `scene` 对应的数据。 |
| `viewer` | `public` | `Viewer` | 用于保存 `viewer` 对应的数据。 |
| `planeHelperGroup` | `public` | `THREE.Group` | 平面辅助对象组 |
| `singlePlaneCapGroup` | `public` | `THREE.Group` | 单面剖切补面结果组 |
### 接口
#### `IClippingManagerOptions`
| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `singlePlaneCapMeshName` | `string` | 否 | 单面剖切补面的目标网格名称，对应 `THREE.Mesh.name`。 |
| `singlePlaneCapEnabled` | `boolean` | 否 | 是否默认启用单面剖切补面。 |
### 方法
@@ -91,6 +111,50 @@ outline: [2, 3]
- 出参：`ClippingPlane \| undefined`
- 返回说明：返回 `ClippingPlane | undefined`。
#### `setSinglePlaneCapTargetByName(meshName: string | null): void`
- 作用：设置单面剖切补面的目标网格名称。仅对 `single` 剖切面生效。
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `meshName` | `string \| null` | 是 | 目标网格名称，传入 `null` 可关闭补面。 |
- 出参：`void`
- 返回说明：无返回值。
#### `setSinglePlaneCapEnabled(enabled: boolean): void`
- 作用：设置单面剖切补面是否启用。仅对 `single` 剖切面生效。
- 入参：
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `enabled` | `boolean` | 是 | 是否启用单面剖切补面。 |
- 出参：`void`
- 返回说明：无返回值。
#### `getSinglePlaneCapEnabled(): boolean`
- 作用：获取当前单面剖切补面的启用状态。
- 入参：无
- 出参：`boolean`
- 返回说明：返回当前是否启用单面剖切补面。
#### `getSinglePlaneCapTargetName(): string | null`
- 作用：获取当前单面剖切补面的目标网格名称。
- 入参：无
- 出参：`string \| null`
- 返回说明：返回当前配置的目标网格名称。
#### `autoPlanePosition(offset: number = 2): void`
- 作用：根据剖切组包围盒自动定位 X/Y/Z 三个剖切面 必须先调用 addDefaultPlanes() 注册剖切面
@@ -106,7 +170,7 @@ outline: [2, 3]
#### `addClippingObjectsByUuid(uuids: Array<string>): void`
- 作用：─── 剖切组对象管理（保持不变）────────────────────────────────────────
- 作用：按 uuid 将场景对象加入剖切组。
- 入参：
@@ -119,7 +183,7 @@ outline: [2, 3]
#### `addClippingObjects(objects: Array<THREE.Object3D>): void`
- 作用：添加 Clipping Objects。
- 作用：批量加入剖切组，并触发单面补面刷新。
- 入参：
@@ -132,7 +196,7 @@ outline: [2, 3]
#### `addClippingToObject(object: THREE.Object3D): void`
- 作用：添加 Clipping To Object。
- 作用：将对象从原父节点迁入剖切组，并保留原始变换信息。
- 入参：
@@ -145,7 +209,7 @@ outline: [2, 3]
#### `removeClippingObjectsByUuid(uuids: Array<string>): void`
- 作用：移除 Clipping Objects By Uuid。
- 作用：按 uuid 从剖切组移除对象并恢复原父节点与原始变换。
- 入参：
@@ -158,7 +222,7 @@ outline: [2, 3]
#### `clearClippingGroups(): void`
- 作用：清理 Clipping Groups。
- 作用：清空剖切组对象、移除平面辅助，并刷新补面状态。
- 入参：无
@@ -167,7 +231,7 @@ outline: [2, 3]
#### `clearClippingPlanes(): void`
- 作用：清理 Clipping Planes。
- 作用：清空所有剖切平面并解绑单面补面监听。
- 入参：无
@@ -176,7 +240,7 @@ outline: [2, 3]
#### `hideClippingPlanes(): void`
- 作用：执行 hide Clipping Planes 相关逻辑。
- 作用：隐藏历史平面辅助对象。
- 入参：无
@@ -185,7 +249,7 @@ outline: [2, 3]
#### `computeBoundingBox(): THREE.Box3`
- 作用：执行 compute Bounding Box 相关逻辑。
- 作用：计算当前剖切组中网格对象的世界包围盒。
- 入参：无
@@ -207,7 +271,7 @@ outline: [2, 3]
#### `startClipping(): void`
- 作用：执行 start Clipping 相关逻辑。
- 作用：将剖切状态设为启用并发出 `clippingStart` 事件。
- 入参：无
@@ -216,7 +280,7 @@ outline: [2, 3]
#### `stopClipping(): void`
- 作用：执行 stop Clipping 相关逻辑。
- 作用：将剖切状态设为关闭并发出 `clippingEnd` 事件。
- 入参：无
@@ -234,8 +298,35 @@ outline: [2, 3]
## 构造示例
- 当前 Demo 中没有直接展示 `ClippingManager` 的构造调用。
- `Viewer` 初始化时会自动创建 `ClippingManager`，可通过 `Viewer` 选项透传剖切补面默认配置。
```ts
import { Viewer } from "@deep/engine";
const viewer = new Viewer("app", {
clipping: {
singlePlaneCapMeshName: "地层网格",
singlePlaneCapEnabled: true,
},
});
```
## 函数示例
- 当前 Demo 中没有直接展示 `ClippingManager` 的公开方法调用。
- 单面剖切补面的典型流程：
```ts
const [planeX, planeY, planeZ] = viewer.clipping.addDefaultPlanes();
const singlePlane = viewer.clipping.addPlane("single", {
normal: new THREE.Vector3(1, 0, 0),
color: new THREE.Color(0xffff00),
});
viewer.clipping.addClippingObjects([targetObject]);
viewer.clipping.setSinglePlaneCapTargetByName("地层网格");
viewer.clipping.setSinglePlaneCapEnabled(true);
// 平面位姿变化会自动刷新补面结果
singlePlane.setTransformMode("translate");
```
packages/docs/api/parametric/ParametricPipe.md
+1 -1
View File
@@ -74,6 +74,7 @@ outline: [2, 3]
#### `createGeometry(): PathTubeGeometry`
- 作用：创建管道几何体
- 行为说明：初始化 `PathTubeGeometry` 时会按整条路径的最大容量预分配顶点缓冲与索引缓冲。即使初始 `progress` 较小，后续动画推进也会尽量复用同一组缓冲区，避免在渲染过程中因为索引扩容而替换 `geometry.index`。
- 入参：无
@@ -609,4 +610,3 @@ const clearVerticalPipes = () => {
- `packages/demo/src/panels/GoldMineScene/VentilationFillingPanel.vue`
- `packages/demo/src/panels/OilGasScene/DrillingAndCementingPanel.vue`
- `packages/demo/src/panels/OilGasScene/FluidApplicationPanel.vue`
packages/docs/package.json
+1 -1
View File
@@ -9,4 +9,4 @@
"devDependencies": {
"vitepress": "2.0.0-alpha.17"
}
}
}
packages/sdk/package.json
+4 -1
View File
@@ -3,5 +3,8 @@
"version": "1.0.0",
"type": "module",
"main": "./public/DeepEngine.es.js",
"types": "./types/index.d.ts"
"types": "./types/index.d.ts",
"dependencies": {
"three": "catalog:"
}
}
packages/sdk/public/model/fracture/obj_7.FBX
BIN
View File
Binary file not shown.
packages/sdk/public/model/raw/head256x256x256.raw
+233261
View File
File diff suppressed because one or more lines are too long
packages/sdk/public/model/raw/volume-data.raw
+1
View File
File diff suppressed because one or more lines are too long