feat(all): init commit

packages/docs/api/parametric/ParametricArch.md

@@ -0,0 +1,273 @@
+---
+outline: [2, 3]
+---
+
+# ParametricArch
+
+- 源文件：`packages/sdk/src/parametric/ParametricArch.ts`
+- 文档位置：`packages/docs/api/parametric/ParametricArch.md`
+
+## 类：`ParametricArch`
+
+- 作用：高性能参数化城门洞 (基于 PathArchGeometry) 使用增量更新而非重建几何体，性能更优
+- 继承/实现：`extends ParametricGeometryBase；implements IParametricGeometry`
+
+### 构造函数
+
+#### `new ParametricArch(viewer: Viewer, options: IArchOptions = {})`
+
+- 作用：创建参数化城门洞
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
+| `options` | `IArchOptions` | 否 | - 城门洞配置选项 |
+
+- 出参：`ParametricArch`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `geometry` | `public` | `PathArchGeometry` | 用于保存 `geometry` 对应的数据。 |
+| `material` | `public` | `THREE.Material` | 材质参数。 |
+| `options` | `public` | `Required<IArchOptions>` | 用于保存 `options` 对应的数据。 |
+| `isAnimating` | `public` | `boolean` | 动画相关属性 |
+| `animationRequestId` | `public` | `number \| null` | 用于保存 `animationRequestId` 对应的数据。 |
+| `originalExtrudePathPoints` | `public` | `any[] \| null` | 用于保存 `originalExtrudePathPoints` 的集合数据。 |
+| `pathPointList` | `public` | `PathPointList \| null` | 用于保存 `pathPointList` 对应的数据。 |
+| `spline` | `public` | `THREE.CatmullRomCurve3 \| null` | 用于保存 `spline` 对应的数据。 |
+| `animationDuration` | `public` | `number` | 用于保存 `animationDuration` 对应的数据。 |
+| `animationDelay` | `public` | `number` | 用于保存 `animationDelay` 对应的数据。 |
+| `animationProgress` | `public` | `number` | 用于保存 `animationProgress` 对应的数据。 |
+| `followMesh` | `public` | `THREE.Mesh \| THREE.Object3D \| null` | 跟随动画的 mesh |
+| `viewer` | `public` | `Viewer \| null` | 用于保存 `viewer` 对应的数据。 |
+| `collisionProxyMesh` | `public` | `THREE.Mesh \| null` | 碰撞代理 mesh |
+| `outerShape` | `public` | `THREE.Shape \| null` | 用于创建碰撞代理的形状 |
+
+### 方法
+
+#### `createGeometry(): PathArchGeometry`
+
+- 作用：创建城门洞几何体
+
+- 入参：无
+
+- 出参：`PathArchGeometry`
+- 返回说明：返回 `PathArchGeometry`。
+
+#### `updateParameters(options: Partial<IArchOptions>): void`
+
+- 作用：更新城门洞参数
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `Partial<IArchOptions>` | 是 | 当前功能对应的配置项。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateGeometry(): void`
+
+- 作用：更新几何体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `startAnimation(): void`
+
+- 作用：开始动画
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `stopAnimation(): void`
+
+- 作用：停止动画
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `resetAnimation(): void`
+
+- 作用：重置动画
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setAnimationDuration(duration: number): void`
+
+- 作用：设置动画时长
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `duration` | `number` | 是 | 参数 `duration`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setAnimationDelay(delay: number): void`
+
+- 作用：设置动画延迟
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `delay` | `number` | 是 | 参数 `delay`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `createDebugPanel(): void`
+
+- 作用：创建调试面板
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：销毁资源
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `createShapes(): void`
+
+- 作用：创建形状（外轮廓，用于碰撞代理）
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `createCollisionProxyMesh(): void`
+
+- 作用：创建碰撞代理 mesh 使用前两个路径点创建简化的城门洞几何体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateCollisionProxyTransform(p1: THREE.Vector3, p2: THREE.Vector3): void`
+
+- 作用：更新碰撞代理 mesh 的位置和旋转
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `p1` | `THREE.Vector3` | 是 | - 第一个点 |
+| `p2` | `THREE.Vector3` | 是 | - 第二个点 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `loadFollowMesh(url: string): Promise<void>`
+
+- 作用：加载跟随动画的模型
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 资源地址。 |
+
+- 出参：`Promise<void>`
+- 返回说明：返回 Promise，解析结果类型为 `void`。
+
+#### `animate(data: RenderEventData): void`
+
+- 作用：动画循环
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `RenderEventData` | 是 | 输入数据。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `subtractMesh(): number`
+
+- 作用：直接对所有已添加的碰撞目标执行 CSG 减法操作 使用 addCollisionTarget 添加的目标
+
+- 入参：无
+
+- 出参：`number`
+- 返回说明：成功处理的目标数量
+
+## 构造示例
+
+- 来源：`packages/demo/src/panels/TunnelScene/RobotExcavationPanel.vue`
+
+```ts
+    // 底部
+    topEnabled: true,
+    followMeshUrl: "/model/机器人.glb",
+    followMeshOffset: new THREE.Vector3(0, -0.2, 0.1),
+    // extrudePathPoints: straightPathPoints,
+    extrudePathPoints: straightPathPoints1,
+    enableCSGOperation: true,
+    animate: true,
+    // animate: false,
+    // debugCollisionProxy: true,
+  };
+
+  excavationTunnel = new ParametricArch(viewer, geometrySettings);
+  Tool.defineMaterialOpacityMapping(excavationTunnel);
+  excavationTunnel.name = "机器人开挖隧道";
+```
+
+- 来源：`packages/demo/src/panels/TunnelScene/RobotExcavationPanel.vue`
+
+```ts
+  excavationTunnel = new ParametricArch(viewer, geometrySettings);
+  Tool.defineMaterialOpacityMapping(excavationTunnel);
+  excavationTunnel.name = "机器人开挖隧道";
+
+  let defaultExcavationTunnel = new ParametricArch(viewer, {
+    ...geometrySettings,
+    animate:false
+  });
+  defaultExcavationTunnel.name = "机器人开挖隧道碰撞体";
+  defaultExcavationTunnel.visible = false;
+  Tool.setExcludeAll(defaultExcavationTunnel)
+  viewer.rangeCullingManager.add(defaultExcavationTunnel);
+```
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ParametricArch` 的公开方法调用。
+
+## Demo 参考
+
+### `ParametricArch`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/panels/TunnelScene/RobotExcavationPanel.vue`
+- `packages/demo/src/views/TunnelScene.vue`
+

packages/docs/api/parametric/ParametricBox.md

@@ -0,0 +1,166 @@
+---
+outline: [2, 3]
+---
+
+# ParametricBox
+
+- 源文件：`packages/sdk/src/parametric/ParametricBox.ts`
+- 文档位置：`packages/docs/api/parametric/ParametricBox.md`
+
+## 类：`ParametricBox`
+
+- 作用：高精度参数化长方体 支持完全自定义的长方体生成，包括宽度、高度、深度、分段数等参数
+- 继承/实现：`extends Mesh<BufferGeometry, Material>；implements IParametricGeometry`
+
+### 构造函数
+
+#### `new ParametricBox(options: IBoxOptions = {})`
+
+- 作用：创建参数化长方体
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `IBoxOptions` | 否 | - 长方体配置选项 |
+
+- 出参：`ParametricBox`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<IBoxOptions>` | 用于保存 `options` 对应的数据。 |
+| `clippingPlanes` | `public` | `Plane[]` | 用于保存 `clippingPlanes` 的集合数据。 |
+| `bvhHelper` | `public` | `BVHHelper \| null` | 用于保存 `bvhHelper` 对应的数据。 |
+
+### 方法
+
+#### `createGeometry(): BoxGeometry`
+
+- 作用：创建长方体几何体
+
+- 入参：无
+
+- 出参：`BoxGeometry`
+- 返回说明：返回 `BoxGeometry`。
+
+#### `updateParameters(options: Partial<IBoxOptions>): void`
+
+- 作用：更新长方体参数
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `Partial<IBoxOptions>` | 是 | - 新的长方体配置选项 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateGeometry(): void`
+
+- 作用：更新几何体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `getBVHBoundingBox(): Box3 | undefined`
+
+- 作用：获取 BVH 包围盒
+
+- 入参：无
+
+- 出参：`Box3 \| undefined`
+- 返回说明：返回 `Box3 | undefined`。
+
+#### `createClippingPlanes(): Plane[]`
+
+- 作用：创建对应长方体 6 个面的裁剪平面
+
+- 入参：无
+
+- 出参：`Plane[]`
+- 返回说明：包含 6 个 THREE.Plane 的数组 [右, 左, 上, 下, 前, 后]
+
+#### `updateClippingPlanes(): void`
+
+- 作用：更新裁剪平面
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：销毁资源
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `createDebugPanel(viewer: Viewer): void`
+
+- 作用：创建调试面板
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 来源：`packages/demo/src/hooks/useRockSample.ts`
+
+```ts
+    const boxMaterial = createRock6Material({
+        opacity: 0.6,
+        // depthWrite:false
+    });
+
+    const box = new ParametricBox({
+        width: 5,
+        height: 5,
+        depth: 5,
+        material: boxMaterial
+    });
+```
+
+- 来源：`packages/demo/src/hooks/useSection.ts`
+
+```ts
+    const viewer = bus.getViewer();
+
+    const section = new ParametricBox({
+        width: 0.1,
+        height: 4.8,
+        depth: 4.7,
+        material: createRock2Material({}, false)
+    });
+    section.name = "断面";
+```
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ParametricBox` 的公开方法调用。
+
+## Demo 参考
+
+### `ParametricBox`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/hooks/Bus.ts`
+- `packages/demo/src/hooks/useRockSample.ts`
+- `packages/demo/src/hooks/useSection.ts`
+- `packages/demo/src/panels/TunnelScene/DisturbanceLoadingPanel.vue`
+

packages/docs/api/parametric/ParametricCylinder.md

@@ -0,0 +1,161 @@
+---
+outline: [2, 3]
+---
+
+# ParametricCylinder
+
+- 源文件：`packages/sdk/src/parametric/ParametricCylinder.ts`
+- 文档位置：`packages/docs/api/parametric/ParametricCylinder.md`
+
+## 类：`ParametricCylinder`
+
+- 作用：高精度参数化圆柱体 支持完全自定义的圆柱体生成，包括顶部/底部半径、高度、分段数等参数 可以创建圆柱、圆锥、圆台等多种形状
+- 继承/实现：`extends Mesh<BufferGeometry, Material>；implements IParametricGeometry`
+
+### 构造函数
+
+#### `new ParametricCylinder(options: ICylinderOptions = {})`
+
+- 作用：创建参数化圆柱体
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `ICylinderOptions` | 否 | - 圆柱体配置选项 |
+
+- 出参：`ParametricCylinder`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<ICylinderOptions>` | 用于保存 `options` 对应的数据。 |
+
+### 方法
+
+#### `createCone(radius: number = 1, height: number = 2, radialSegments: number = 64): ParametricCylinder`
+
+- 作用：创建圆锥体（顶部半径为0的圆柱体）
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `radius` | `number` | 否 | - 底部半径 |
+| `height` | `number` | 否 | - 高度 |
+| `radialSegments` | `number` | 否 | - 径向分段数 |
+
+- 出参：`ParametricCylinder`
+- 返回说明：圆锥体实例
+
+#### `createGeometry(): CylinderGeometry`
+
+- 作用：创建圆柱体几何体 作用：基于当前实例的 `options` 构造并返回一个新的 `THREE.CylinderGeometry`。 入参：无 出参：`CylinderGeometry` 行为说明：读取 `options`（包括 `radiusTop`、`radiusBottom`、`height`、`radialSegments` 等）并以这些参数构造 `THREE.CylinderGeometry`，用于初始化或替换实例的 `geometry`。
+
+- 入参：无
+
+- 出参：`CylinderGeometry`
+- 返回说明：返回 `CylinderGeometry`。
+
+#### `updateParameters(options: Partial<ICylinderOptions>): void`
+
+- 作用：更新圆柱体参数并触发几何体重建 作用：合并并应用提供的参数到内部 `options`，随后重新生成几何体。 入参：
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `Partial<ICylinderOptions>` | 是 | - `Partial<ICylinderOptions>` 要更新的参数字段集合 出参：`void` 行为说明：仅覆盖提供的字段，然后调用 `updateGeometry()` 以使几何体反映新的参数。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateGeometry(): void`
+
+- 作用：更新几何体 作用：根据当前 `options` 重新生成并替换网格的几何体。 入参：无 出参：`void` 行为说明：销毁现有几何体（调用 `dispose()`），调用 `createGeometry()` 创建新几何并赋值给 `this.geometry`。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：销毁资源 作用：释放几何体与材质占用的 GPU/内存资源并断开引用。 入参：无 出参：`void` 行为说明：依次调用 `geometry.dispose()` 和 `material.dispose()`（若材质支持），并清理内部引用，便于垃圾回收。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 来源：`packages/demo/src/disasterFormationPanel/GeothermalScene/GeothermalCasingDamageDisasterPanel.vue`
+
+```ts
+  const position = {x: 0, y: 0.5, z: 0};
+
+  const cylinder = new ParametricCylinder({
+    radiusTop: 0.21,
+    radiusBottom: 0.21,
+    height: 0.2,
+    //------ 圆柱上下不闭合 开始------
+    openEnded: true,
+    //------ 圆柱上下不闭合 结束------
+    //------ 圆柱细分优化 开始------
+    radialSegments: 96,
+    //------ 圆柱细分优化 结束------
+    material: new THREE.MeshBasicMaterial({
+      color: '#ff0000',
+      side: THREE.DoubleSide,
+    }),
+  });
+  cylinder.renderOrder = 1;
+  cylinder.position.set(position.x, position.y, position.z);
+  viewer!.scene.add(cylinder);
+```
+
+- 来源：`packages/demo/src/disasterFormationPanel/GeothermalScene/GeothermalWellboreInstabilityDisasterPanel.vue`
+
+```ts
+  const position = {x: 1.5019181086420077, y: 1.1203964954097632, z: 1.5};
+
+  const cylinder = new ParametricCylinder({
+    radiusTop: 0.21,
+    radiusBottom: 0.21,
+    height: 0.2,
+    //------ 圆柱上下不闭合 开始------
+    openEnded: true,
+    //------ 圆柱上下不闭合 结束------
+    //------ 圆柱细分优化 开始------
+    radialSegments: 96,
+    //------ 圆柱细分优化 结束------
+    material: new THREE.MeshBasicMaterial({
+      color: '#ffff00',
+      side: THREE.DoubleSide,
+    }),
+  });
+  cylinder.renderOrder = 1;
+  cylinder.name = 'WellboreInstability_1';
+  cylinder.position.set(position.x, position.y, position.z);
+  viewer!.scene.add(cylinder);
+```
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ParametricCylinder` 的公开方法调用。
+
+## Demo 参考
+
+### `ParametricCylinder`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/GeothermalScene/GeothermalCasingDamageDisasterPanel.vue`
+- `packages/demo/src/disasterFormationPanel/GeothermalScene/GeothermalWellboreInstabilityDisasterPanel.vue`
+- `packages/demo/src/disasterFormationPanel/OilGasScene/CasingDamageDisasterPanel.vue`
+- `packages/demo/src/disasterFormationPanel/OilGasScene/WellboreInstabilityDisasterPanel.vue`
+- `packages/demo/src/panels/TunnelScene/StressApplicationPanel.vue`
+

packages/docs/api/parametric/ParametricGeometryBase.md

@@ -0,0 +1,107 @@
+---
+outline: [2, 3]
+---
+
+# ParametricGeometryBase
+
+- 源文件：`packages/sdk/src/parametric/ParametricGeometryBase.ts`
+- 文档位置：`packages/docs/api/parametric/ParametricGeometryBase.md`
+
+## 类：`ParametricGeometryBase`
+
+- 作用：参数化几何体基类 提供碰撞检测和 CSG 操作的通用功能
+- 继承/实现：`extends THREE.Mesh`
+
+### 构造函数
+
+#### `new ParametricGeometryBase()`
+
+- 作用：创建 ParametricGeometryBase 实例。
+
+- 入参：无
+
+- 出参：`ParametricGeometryBase`
+- 返回说明：返回当前类实例。
+
+### 方法
+
+#### `addCollisionTarget(target: THREE.Mesh, operationType?: CSGOperationType, maxCollisionCount?: number): void`
+
+- 作用：添加碰撞目标
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `target` | `THREE.Mesh` | 是 | - 碰撞目标网格 |
+| `operationType` | `CSGOperationType` | 否 | - CSG 操作类型，默认为 HOLLOW_SUBTRACTION |
+| `maxCollisionCount` | `number` | 否 | - 最大碰撞处理次数，默认 1，-1 为无限碰撞 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `removeCollisionTarget(target: THREE.Mesh): void`
+
+- 作用：移除碰撞目标
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `target` | `THREE.Mesh` | 是 | - 要移除的碰撞目标 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `clearCollisionTargets(): void`
+
+- 作用：清除所有碰撞目标
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `getCollisionTargets(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>[]`
+
+- 作用：获取所有碰撞目标
+
+- 入参：无
+
+- 出参：`THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> \| THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>[]`
+- 返回说明：返回数组结果，元素类型为 `THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>`。
+
+#### `resetProcessedTargets(): void`
+
+- 作用：重置碰撞处理计数 允许重新对目标执行 CSG 操作
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateGeometry(): void`
+
+- 作用：抽象方法，子类必须实现
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：释放资源并销毁当前实例。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 当前 Demo 中没有直接展示 `ParametricGeometryBase` 的构造调用。
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ParametricGeometryBase` 的公开方法调用。

packages/docs/api/parametric/ParametricPipe.md

@@ -0,0 +1,612 @@
+---
+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`
+- 返回说明：返回 `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`
+

packages/docs/api/parametric/ParametricRing.md

@@ -0,0 +1,84 @@
+---
+outline: [2, 3]
+---
+
+# ParametricRing
+
+- 源文件：`packages/sdk/src/parametric/ParametricRing.ts`
+- 文档位置：`packages/docs/api/parametric/ParametricRing.md`
+
+## 类：`ParametricRing`
+
+- 作用：高精度参数化圆环 支持完全自定义的圆环生成，包括内外半径、分段数等参数 可用于创建套管损害、裂缝等可视化效果
+- 继承/实现：`extends Mesh<BufferGeometry, Material>；implements IParametricGeometry`
+
+### 构造函数
+
+#### `new ParametricRing(options: IRingOptions = {})`
+
+- 作用：创建参数化圆环
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `IRingOptions` | 否 | - 圆环配置选项 |
+
+- 出参：`ParametricRing`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<IRingOptions>` | 用于保存 `options` 对应的数据。 |
+
+### 方法
+
+#### `createGeometry(): RingGeometry`
+
+- 作用：创建圆环几何体
+
+- 入参：无
+
+- 出参：`RingGeometry`
+- 返回说明：返回 `RingGeometry`。
+
+#### `updateParameters(options: Partial<IRingOptions>): void`
+
+- 作用：更新圆环参数
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `Partial<IRingOptions>` | 是 | - 新的圆环配置选项 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateGeometry(): void`
+
+- 作用：更新几何体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：销毁资源
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 当前 Demo 中没有直接展示 `ParametricRing` 的构造调用。
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ParametricRing` 的公开方法调用。

packages/docs/api/parametric/ParametricSphere.md

@@ -0,0 +1,93 @@
+---
+outline: [2, 3]
+---
+
+# ParametricSphere
+
+- 源文件：`packages/sdk/src/parametric/ParametricSphere.ts`
+- 文档位置：`packages/docs/api/parametric/ParametricSphere.md`
+
+## 类：`ParametricSphere`
+
+- 作用：高精度参数化球体 支持完全自定义的球体生成，包括半径、分段数、起始角度等参数
+- 继承/实现：`extends Mesh<BufferGeometry, Material>；implements IParametricGeometry`
+
+### 构造函数
+
+#### `new ParametricSphere(options: ISphereOptions = {})`
+
+- 作用：创建参数化球体
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `ISphereOptions` | 否 | - 球体配置选项 |
+
+- 出参：`ParametricSphere`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<ISphereOptions>` | 用于保存 `options` 对应的数据。 |
+
+### 方法
+
+#### `createGeometry(): SphereGeometry`
+
+- 作用：创建球体几何体
+
+- 入参：无
+
+- 出参：`SphereGeometry`
+- 返回说明：返回 `SphereGeometry`。
+
+#### `updateParameters(options: Partial<ISphereOptions>): void`
+
+- 作用：更新球体参数
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `Partial<ISphereOptions>` | 是 | - 新的球体配置选项 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateGeometry(): void`
+
+- 作用：更新几何体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `getParameters(): ISphereOptions`
+
+- 作用：获取当前参数
+
+- 入参：无
+
+- 出参：`ISphereOptions`
+- 返回说明：返回 `ISphereOptions`。
+
+#### `dispose(): void`
+
+- 作用：销毁资源
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 当前 Demo 中没有直接展示 `ParametricSphere` 的构造调用。
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ParametricSphere` 的公开方法调用。

packages/docs/api/parametric/ParametricTorus.md

@@ -0,0 +1,84 @@
+---
+outline: [2, 3]
+---
+
+# ParametricTorus
+
+- 源文件：`packages/sdk/src/parametric/ParametricTorus.ts`
+- 文档位置：`packages/docs/api/parametric/ParametricTorus.md`
+
+## 类：`ParametricTorus`
+
+- 作用：高精度参数化圆环体（甜甜圈形状） 支持完全自定义的圆环体生成，包括半径、管道半径、分段数等参数 可用于创建套管损害、管道连接等可视化效果
+- 继承/实现：`extends Mesh<BufferGeometry, Material>；implements IParametricGeometry`
+
+### 构造函数
+
+#### `new ParametricTorus(options: ITorusOptions = {})`
+
+- 作用：创建参数化圆环体
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `ITorusOptions` | 否 | - 圆环体配置选项 |
+
+- 出参：`ParametricTorus`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<ITorusOptions>` | 用于保存 `options` 对应的数据。 |
+
+### 方法
+
+#### `createGeometry(): TorusGeometry`
+
+- 作用：创建圆环体几何体
+
+- 入参：无
+
+- 出参：`TorusGeometry`
+- 返回说明：返回 `TorusGeometry`。
+
+#### `updateParameters(options: Partial<ITorusOptions>): void`
+
+- 作用：更新圆环体参数
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `Partial<ITorusOptions>` | 是 | - 新的圆环体配置选项 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateGeometry(): void`
+
+- 作用：更新几何体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：销毁资源
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 当前 Demo 中没有直接展示 `ParametricTorus` 的构造调用。
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ParametricTorus` 的公开方法调用。

packages/docs/api/parametric/ParametricWireframe.md

@@ -0,0 +1,115 @@
+---
+outline: [2, 3]
+---
+
+# ParametricWireframe
+
+- 源文件：`packages/sdk/src/parametric/ParametricWireframe.ts`
+- 文档位置：`packages/docs/api/parametric/ParametricWireframe.md`
+
+## 接口：`IWireframeOptions`
+
+- 作用：线框参数配置
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `color` | `number` | 否 | 线框颜色 |
+| `linewidth` | `number` | 否 | 线宽 |
+| `width` | `number` | 否 | 盒子宽度 |
+| `height` | `number` | 否 | 盒子高度 |
+| `depth` | `number` | 否 | 盒子深度 |
+| `box` | `ParametricBox` | 否 | ParametricBox 实例（可选，如果提供则从中提取尺寸） |
+
+## 类：`ParametricWireframe`
+
+- 作用：参数化线框 显示盒子的12条边
+- 继承/实现：`extends LineSegments<BufferGeometry, Material>；implements IParametricGeometry`
+
+### 构造函数
+
+#### `new ParametricWireframe(options: IWireframeOptions = {})`
+
+- 作用：创建参数化线框
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `IWireframeOptions` | 否 | - 线框配置选项 |
+
+- 出参：`ParametricWireframe`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<Omit<IWireframeOptions, 'box'>>` | 用于保存 `options` 对应的数据。 |
+| `sourceBox` | `public` | `ParametricBox` | 用于保存 `sourceBox` 对应的数据。 |
+
+### 方法
+
+#### `createWireframeGeometry(width: number, height: number, depth: number): THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>`
+
+- 作用：创建线框几何体 盒子有12条边： - 顶面4条边 - 底面4条边 - 连接顶底的4条垂直边
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `width` | `number` | 是 | 宽度参数。 |
+| `height` | `number` | 是 | 高度参数。 |
+| `depth` | `number` | 是 | 深度参数。 |
+
+- 出参：`THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>`
+- 返回说明：返回 `THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>`。
+
+#### `updateParameters(options: Partial<IWireframeOptions>): void`
+
+- 作用：更新线框参数
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `Partial<IWireframeOptions>` | 是 | - 新的线框配置选项 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `syncFromBox(): void`
+
+- 作用：从关联的 ParametricBox 同步尺寸
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateGeometry(): void`
+
+- 作用：更新几何体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：销毁资源
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 当前 Demo 中没有直接展示 `ParametricWireframe` 的构造调用。
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `ParametricWireframe` 的公开方法调用。

packages/docs/api/parametric/types.md

@@ -0,0 +1,184 @@
+---
+outline: [2, 3]
+---
+
+# types
+
+- 源文件：`packages/sdk/src/parametric/types.ts`
+- 文档位置：`packages/docs/api/parametric/types.md`
+
+## 接口：`IParametricGeometryOptions`
+
+- 作用：参数化几何体的基础配置接口
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `material` | `THREE.Material` | 否 | 材质 |
+
+## 接口：`ISphereOptions`
+
+- 作用：球体参数配置
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `radius` | `number` | 否 | 半径 |
+| `widthSegments` | `number` | 否 | 水平分段数（经度） |
+| `heightSegments` | `number` | 否 | 垂直分段数（纬度） |
+| `phiStart` | `number` | 否 | 水平起始角度 |
+| `phiLength` | `number` | 否 | 水平扫描角度 |
+| `thetaStart` | `number` | 否 | 垂直起始角度 |
+| `thetaLength` | `number` | 否 | 垂直扫描角度 |
+
+## 接口：`ICylinderOptions`
+
+- 作用：圆柱体参数配置
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `radiusTop` | `number` | 否 | 顶部半径 |
+| `radiusBottom` | `number` | 否 | 底部半径 |
+| `height` | `number` | 否 | 高度 |
+| `radialSegments` | `number` | 否 | 径向分段数 |
+| `heightSegments` | `number` | 否 | 高度分段数 |
+| `openEnded` | `boolean` | 否 | 是否开放端面 |
+| `thetaStart` | `number` | 否 | 起始角度 |
+| `thetaLength` | `number` | 否 | 扫描角度 |
+
+## 接口：`IBoxOptions`
+
+- 作用：长方体参数配置
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `width` | `number` | 否 | 宽度 |
+| `height` | `number` | 否 | 高度 |
+| `depth` | `number` | 否 | 深度 |
+| `widthSegments` | `number` | 否 | 宽度分段数 |
+| `heightSegments` | `number` | 否 | 高度分段数 |
+| `depthSegments` | `number` | 否 | 深度分段数 |
+
+## 接口：`IArchOptions`
+
+- 作用：城门洞参数配置
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `width` | `number` | 否 | 宽度 |
+| `height` | `number` | 否 | 高度 |
+| `depth` | `number` | 否 | 深度 |
+| `thickness` | `number` | 否 | 厚度 |
+| `depthSegments` | `number` | 否 | 深度分段数 |
+| `curveSegments` | `number` | 否 | 用于保存 `curveSegments` 对应的数据。 |
+| `steps` | `number` | 否 | 用于保存 `steps` 对应的数据。 |
+| `hasHole` | `boolean` | 否 | 是否有内轮廓（洞） |
+| `extrudePathPoints` | `Array<THREE.Vector3 \| { x: number; y: number; z: number }>` | 否 | 挤压路径点数组，可以是 THREE.Vector3 数组或包含 x,y,z 属性的对象数组 |
+| `animate` | `boolean` | 否 | 是否启用动画，启用时第一次创建只取第一个点 |
+| `bottomEnabled` | `boolean` | 否 | 是否生成底部面 |
+| `topEnabled` | `boolean` | 否 | 是否生成顶部面 |
+| `followMesh` | `THREE.Mesh \| THREE.Object3D` | 否 | 跟随动画的 mesh 对象 |
+| `followMeshUrl` | `string` | 否 | 跟随动画的 mesh 模型 URL 路径 |
+| `followMeshOffset` | `THREE.Vector3` | 否 | 跟随动画的 mesh 在动画时的位置偏移 |
+| `upVector` | `THREE.Vector3` | 否 | 向上方向向量，用于控制挤出时的坐标系方向 |
+| `enableCSGOperation` | `boolean` | 否 | 动画时是否启用 CSG 操作（含碰撞检测） |
+| `showDebugMesh` | `boolean` | 否 | 是否显示 CSG 调试 mesh |
+| `collisionCheckProgressStep` | `number` | 否 | 碰撞检测触发的进度步长（0-1），<=0 表示每帧检测 |
+| `collisionProxyDepth` | `number` | 否 | 碰撞代理体深度（挙伸幼度），默认为 0.3 |
+| `debugCollisionProxy` | `boolean` | 否 | 是否启用碰撞代理网格调试显示 |
+
+## 接口：`IPipeOptions`
+
+- 作用：管道参数配置
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `points` | `Array<THREE.Vector3 \| { x: number; y: number; z: number }>` | 否 | 路径点数组 |
+| `radius` | `number` | 否 | 管道半径 |
+| `radialSegments` | `number` | 否 | 径向分段数 |
+| `cornerRadius` | `number` | 否 | 拐角半径 |
+| `cornerSplit` | `number` | 否 | 拐角分段数 |
+| `progress` | `number` | 否 | 动画进度 (0-1) |
+| `startRad` | `number` | 否 | 起始旋转角度 |
+| `upVector` | `THREE.Vector3 \| null` | 否 | 向上方向向量 |
+| `close` | `boolean` | 否 | 是否闭合路径 |
+| `capStart` | `boolean` | 否 | 是否封闭起始端 |
+| `capEnd` | `boolean` | 否 | 是否封闭结束端 |
+| `enableDrillingRobot` | `boolean` | 否 | 是否启用钻进机器人 |
+| `robotColor` | `number` | 否 | 钻进机器人颜色 |
+| `robotCylinderLengthRatio` | `number` | 否 | 机器人圆柱体长度系数（相对于管道半径） |
+| `robotConeLengthRatio` | `number` | 否 | 机器人圆锥体长度系数（相对于管道半径） |
+| `useStaticCollisionProxy` | `boolean` | 否 | 是否使用静态碰撞代理 (true: CylinderGeometry, false: TubeGeometry) |
+| `collisionProxyHeight` | `number` | 否 | 碰撞代理圆柱高度（动态/静态共用，<=0 或不传时使用默认值） |
+| `metadata` | `Record<string, any>` | 否 | 元数据 |
+| `collisionCheckProgressStep` | `number` | 否 | 碰撞检测触发的进度步长（0-1），<=0 表示每帧检测 |
+| `debugCollisionProxy` | `boolean` | 否 | 是否启用碰撞代理网格调试显示 |
+
+## 接口：`IRingOptions`
+
+- 作用：圆环参数配置
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `innerRadius` | `number` | 否 | 内半径 |
+| `outerRadius` | `number` | 否 | 外半径 |
+| `thetaSegments` | `number` | 否 | 圆周分段数 |
+| `phiSegments` | `number` | 否 | 径向分段数 |
+| `thetaStart` | `number` | 否 | 起始角度 |
+| `thetaLength` | `number` | 否 | 扫描角度 |
+
+## 接口：`ITorusOptions`
+
+- 作用：圆环体（甜甜圈）参数配置
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `radius` | `number` | 否 | 圆环半径（从圆环中心到管道中心的距离） |
+| `tube` | `number` | 否 | 管道半径 |
+| `radialSegments` | `number` | 否 | 径向分段数（管道圆周方向） |
+| `tubularSegments` | `number` | 否 | 管状分段数（圆环圆周方向） |
+| `arc` | `number` | 否 | 圆环弧度（默认 2π 为完整圆环） |
+
+## 接口：`IParametricGeometry`
+
+- 作用：参数化几何体基类接口 实现此接口的类应该直接继承 THREE.Mesh
+
+### 定义
+
+```ts
+export interface IParametricGeometry {
+    /** 几何体 */
+    geometry: THREE.BufferGeometry;
+    /** 材质 */
+    material: THREE.Material | THREE.Material[];
+
+    /** 更新几何体参数 */
+    updateGeometry(): void;
+
+    /** 销毁资源 */
+    dispose(): void;
+}
+```
+
+## Demo 参考
+
+### `IArchOptions`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/panels/TunnelScene/RobotExcavationPanel.vue`
+