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

# ParametricPipe

- 源文件：`packages/sdk/src/parametric/ParametricPipe.ts`
- 文档位置：`packages/docs/api/parametric/ParametricPipe.md`

## 类：`ParametricPipe`

- 作用：参数化管道 基于 PathTubeGeometry 实现的管道生成器，支持沿路径生成圆形截面的管道
- 继承/实现：`extends ParametricGeometryBase`

### 构造函数

#### `new ParametricPipe(viewer: Viewer, options: IPipeOptions = {})`

- 作用：创建参数化管道

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `viewer` | `Viewer` | 是 | - Viewer 实例 |
| `options` | `IPipeOptions` | 否 | - 管道配置选项 |

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

### 属性

| 属性名 | 可见性 | 类型 | 作用 |
| --- | --- | --- | --- |
| `geometry` | `public` | `THREE.BufferGeometry` | 用于保存 `geometry` 对应的数据。 |
| `material` | `public` | `THREE.Material` | 材质参数。 |
| `options` | `public` | `Required<IPipeOptions>` | 用于保存 `options` 对应的数据。 |
| `emitter` | `public` | `Emittery` | 用于保存 `emitter` 对应的数据。 |
| `pathPointList` | `public` | `PathPointList` | 用于保存 `pathPointList` 对应的数据。 |
| `pathTubeGeometry` | `public` | `PathTubeGeometry` | 用于保存 `pathTubeGeometry` 对应的数据。 |
| `viewer` | `public` | `Viewer \| null` | 用于保存 `viewer` 对应的数据。 |
| `startCapMesh` | `public` | `THREE.Mesh \| null` | 端面封闭 |
| `endCapMesh` | `public` | `THREE.Mesh \| null` | 用于保存 `endCapMesh` 对应的数据。 |
| `drillingRobot` | `public` | `DrillingRobot \| null` | 钻进机器人 |
| `collisionProxyMesh` | `public` | `THREE.Mesh \| null` | 碰撞代理 mesh |
| `staticCollisionProxyMesh` | `public` | `THREE.Mesh \| null` | 用于保存 `staticCollisionProxyMesh` 对应的数据。 |
| `useStaticProxy` | `public` | `boolean` | 用于标记 `useStaticProxy` 的启用状态。 |
| `bvhHelper` | `public` | `BVHHelper \| null` | BVH 辅助显示 |
| `playing` | `public` | `boolean` | 动画相关属性 |
| `duration` | `public` | `number` | 用于保存 `duration` 对应的数据。 |
| `texture` | `public` | `THREE.Texture \| null` | 用于保存 `texture` 对应的数据。 |
| `textureAnimating` | `public` | `boolean` | 用于标记 `textureAnimating` 的启用状态。 |
| `scrollSpeed` | `public` | `number` | 用于保存 `scrollSpeed` 对应的数据。 |
| `scrollDirection` | `public` | `number` | 用于保存 `scrollDirection` 对应的数据。 |
| `scrollAxis` | `public` | `'x' \| 'y'` | 用于保存 `scrollAxis` 对应的数据。 |
| `textureRepeatX` | `public` | `number` | 用于保存 `textureRepeatX` 对应的数据。 |
| `textureRepeatY` | `public` | `number` | 用于保存 `textureRepeatY` 对应的数据。 |

### 方法

#### `setCollisionProxyType(useStatic: boolean): void`

- 作用：设置使用哪种碰撞代理

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `useStatic` | `boolean` | 是 | - true 使用静态代理，false 使用动态代理 |

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

#### `createGeometry(): PathTubeGeometry`

- 作用：创建管道几何体
- 行为说明：初始化 `PathTubeGeometry` 时会按整条路径的最大容量预分配顶点缓冲与索引缓冲。即使初始 `progress` 较小，后续动画推进也会尽量复用同一组缓冲区，避免在渲染过程中因为索引扩容而替换 `geometry.index`。

- 入参：无

- 出参：`PathTubeGeometry`
- 返回说明：返回 `PathTubeGeometry`。

#### `updateParameters(options: Partial<IPipeOptions>): void`

- 作用：更新管道参数

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `options` | `Partial<IPipeOptions>` | 是 | - 新的管道配置选项 |

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

#### `updateGeometry(): void`

- 作用：更新几何体

- 入参：无

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

#### `updatePoints(points: Array<THREE.Vector3 | { x: number; y: number; z: number }>): void`

- 作用：更新路径点

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `points` | `Array<THREE.Vector3 \| { x: number; y: number; z: number }>` | 是 | - 新的路径点数组 |

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

#### `updateRadius(radius: number): void`

- 作用：更新管道半径

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `radius` | `number` | 是 | - 新的半径值 |

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

#### `updateProgress(progress: number): void`

- 作用：更新动画进度

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `progress` | `number` | 是 | - 进度值 (0-1) |

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

#### `getPathDistance(): number`

- 作用：获取路径总长度

- 入参：无

- 出参：`number`
- 返回说明：路径长度

#### `addToScene(): void`

- 作用：添加到场景

- 入参：无

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

#### `removeFromScene(): void`

- 作用：从场景移除

- 入参：无

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

#### `getBVHBoundingBox(): THREE.Box3 | undefined`

- 作用：获取 BVH 包围盒

- 入参：无

- 出参：`THREE.Box3 \| undefined`
- 返回说明：返回 `THREE.Box3 | undefined`。

#### `dispose(): void`

- 作用：销毁资源

- 入参：无

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

#### `startAnimation(targetProgress?: number): void`

- 作用：开始进度动画

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `targetProgress` | `number` | 否 | - 目标进度（0-1），如果不提供则默认为 1.0 |

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

#### `continueAnimation(targetProgress?: number): void`

- 作用：继续进度动画（从当前进度继续到目标进度）

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `targetProgress` | `number` | 否 | - 目标进度（0-1），如果不提供则默认为 1.0 |

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

#### `stopAnimation(): void`

- 作用：停止进度动画

- 入参：无

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

#### `startTextureAnimation(duration?: number): void`

- 作用：开始纹理滚动动画

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `duration` | `number` | 否 | - 动画时长（秒），如果提供则在时长结束后派发 textureAnimationComplete 事件 |

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

#### `stopTextureAnimation(): void`

- 作用：停止纹理滚动动画

- 入参：无

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

#### `setDuration(duration: number): void`

- 作用：设置动画时长

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `duration` | `number` | 是 | - 动画时长（秒） |

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

#### `getDuration(): number`

- 作用：获取动画时长

- 入参：无

- 出参：`number`
- 返回说明：返回数值结果。

#### `setScrollSpeed(speed: number): void`

- 作用：设置纹理滚动速度

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `speed` | `number` | 是 | - 滚动速度 |

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

#### `getScrollSpeed(): number`

- 作用：获取纹理滚动速度

- 入参：无

- 出参：`number`
- 返回说明：返回数值结果。

#### `setScrollDirection(direction: number): void`

- 作用：设置滚动方向

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `direction` | `number` | 是 | - 1 为正向，-1 为反向 |

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

#### `setScrollAxis(axis: 'x' | 'y'): void`

- 作用：设置滚动轴向

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `axis` | `'x' \| 'y'` | 是 | - 'x' 为水平滚动，'y' 为垂直滚动 |

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

#### `getScrollAxis(): "x" | "y"`

- 作用：获取滚动轴向

- 入参：无

- 出参：`"x" \| "y"`
- 返回说明：返回 `"x" | "y"`。

#### `setColorNode(_texture: THREE.Texture, color?: THREE.ColorRepresentation): void`

- 作用：设置颜色节点（纹理与颜色混合）

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `_texture` | `THREE.Texture` | 是 | - 纹理 |
| `color` | `THREE.ColorRepresentation` | 否 | - 混合颜色 |

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

#### `setTextureRepeat(repeatX: number, repeatY: number): void`

- 作用：设置纹理重复次数

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `repeatX` | `number` | 是 | - X 轴重复次数 |
| `repeatY` | `number` | 是 | - Y 轴重复次数 |

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

#### `getTextureRepeat(): { x: number; y: number; }`

- 作用：获取纹理重复次数

- 入参：无

- 出参：`{ x: number; y: number; }`
- 返回说明：返回 `{ x: number; y: number; }`。

#### `setTextureCoverMode(): void`

- 作用：设置纹理为覆盖模式（拉伸填充，不重复）

- 入参：无

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

#### `setTextureScale(scaleX: number, scaleY: number): void`

- 作用：设置纹理缩放

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `scaleX` | `number` | 是 | - X 轴缩放比例（大于1放大，小于1缩小） |
| `scaleY` | `number` | 是 | - Y 轴缩放比例（大于1放大，小于1缩小） |

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

#### `removeTexture(): void`

- 作用：移除纹理

- 入参：无

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

#### `createDebugPanel(): void`

- 作用：创建调试面板

- 入参：无

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

#### `createCaps(): void`

- 作用：创建管道端面

- 入参：无

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

#### `disposeCaps(): void`

- 作用：清除端面

- 入参：无

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

#### `createDrillingRobot(): void`

- 作用：创建钻进机器人

- 入参：无

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

#### `updateDrillingRobotPosition(): void`

- 作用：更新钻进机器人位置

- 入参：无

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

#### `disposeDrillingRobot(): void`

- 作用：销毁钻进机器人

- 入参：无

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

#### `disposeCollisionProxyMeshes(): void`

- 作用：销毁碰撞代理 mesh

- 入参：无

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

#### `updateCollisionProxyMesh(): void`

- 作用：创建或更新碰撞代理 mesh 用于 CSG 计算的简化几何体，只包含钻头部分

- 入参：无

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

#### `createStaticCollisionProxyMesh(): void`

- 作用：创建静态碰撞代理 mesh 使用 CylinderGeometry，只基于前两个点生成，不动态更新

- 入参：无

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

#### `updateProgressAnimation(data: RenderEventData): void`

- 作用：更新进度动画

- 入参：

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

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

#### `updateTextureAnimation(delta: number): void`

- 作用：更新纹理动画

- 入参：

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `delta` | `number` | 是 | 时间增量。 |

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

## 构造示例

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

```ts
  const pipeMaterial = new THREE.MeshBasicNodeMaterial({
    color: 0x808080,
    transparent: true,
    opacity: 0.6,
    side: THREE.DoubleSide,
  });

  const pip = new ParametricPipe(viewer, {
    points: points,
    radius: 0.2,
    radialSegments: 16,
    cornerRadius: 0.1,
    cornerSplit: 5,
    progress: 0,
    material: pipeMaterial,
    capStart: false,
    capEnd: false,
    enableDrillingRobot: true,
    robotColor: 0xff0000,
  });
  pip.renderOrder = 1
  pip.name = `管道`;
  viewer.scene.add(pip);
  pip.setCollisionProxyType(true);
  pip.addCollisionTarget(bus.getRockSample());
```

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

```ts
  const pipeMaterial = new THREE.MeshBasicNodeMaterial({
    color: 0x808080,
    transparent: true,
    opacity: 0.6,
    side: THREE.DoubleSide,
  });

  const pip = new ParametricPipe(viewer, {
    points: points,
    radius: 0.2,
    radialSegments: 16,
    cornerRadius: 0.1,
    cornerSplit: 5,
    progress: 0,
    material: pipeMaterial,
    capStart: false,
    capEnd: false,
    enableDrillingRobot: true,
    robotColor: 0xff0000,
  });
```

## 函数示例

### `ParametricPipe.setCollisionProxyType`

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

```ts
  viewer.scene.add(pip);
  pip.setCollisionProxyType(true);
  pip.addCollisionTarget(bus.getRockSample());
```

### `ParametricPipe.dispose`

- 来源：`packages/demo/src/panels/GoldMineScene/DevelopmentMiningPanel.vue`

```ts
const clearVerticalPipes = () => {
  verticalPipes.forEach(pipe => {
    pipe.dispose();
  });
  verticalPipes = [];
  bus.triggerSceneTreeUpdate();
};
```

### `ParametricPipe.startAnimation`

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

```ts
  viewer.scene.add(pip);
  pip.setCollisionProxyType(true);
  pip.addCollisionTarget(bus.getRockSample());

  pip.setDuration(2);
  pip.startAnimation();
  bus.triggerSceneTreeUpdate();
}
```

## Demo 参考

### `ParametricPipe`

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

- `packages/demo/src/hooks/Bus.ts`
- `packages/demo/src/panels/GeothermalScene/GeothermalDrillingAndCementingPanel.vue`
- `packages/demo/src/panels/GoldMineScene/DevelopmentMiningPanel.vue`
- `packages/demo/src/panels/GoldMineScene/DrillingPanel.vue`
- `packages/demo/src/panels/GoldMineScene/VentilationFillingPanel.vue`
- `packages/demo/src/panels/OilGasScene/DrillingAndCementingPanel.vue`
- `packages/demo/src/panels/OilGasScene/FluidApplicationPanel.vue`