333 lines
9.1 KiB
Markdown
333 lines
9.1 KiB
Markdown
---
|
||
outline: [2, 3]
|
||
---
|
||
|
||
# ClippingManager
|
||
|
||
- 源文件：`packages/sdk/src/manager/ClippingManager.ts`
|
||
- 文档位置：`packages/docs/api/manager/ClippingManager.md`
|
||
|
||
## 类：`ClippingManager`
|
||
|
||
- 作用：剖切管理器，负责剖切对象收拢、剖切平面管理，以及单面剖切补面（CSG）结果生成。
|
||
|
||
## 剖切补面能力说明
|
||
|
||
`single` 平面启用后，管理器会在 `clippingGroup` 中按名称查找目标网格，执行一次“目标网格 - 刀具体”的 CSG 运算，将结果放到 `singlePlaneCapGroup`，并临时隐藏原网格。
|
||
|
||
- 目标网格通过 `setSinglePlaneCapTargetByName` 指定。
|
||
- 开关通过 `setSinglePlaneCapEnabled` 控制。
|
||
- 仅当剖切平面与目标网格包围盒相交时才生成结果。
|
||
- 平面移动时自动刷新补面结果。
|
||
|
||
### 构造函数
|
||
|
||
#### `new ClippingManager(viewer: Viewer, options?: IClippingManagerOptions)`
|
||
|
||
- 作用：创建 ClippingManager 实例。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
|
||
| `options` | `IClippingManagerOptions` | 否 | 剖切管理配置，支持默认补面目标网格和默认启用状态。 |
|
||
|
||
- 出参：`ClippingManager`
|
||
- 返回说明：返回当前类实例。
|
||
|
||
### 属性
|
||
|
||
| 属性名 | 可见性 | 类型 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `panelCounter` | `public static` | `number` | 用于保存 `panelCounter` 对应的数据。 |
|
||
| `emitter` | `public` | `Emittery<{ clippingStart: undefined; clippingEnd: undefined; }, { clippingStart: undefined; clippingEnd: undefined; } & OmnipresentEventData, DatalessEventNames<{ clippingStart: undefined; clippingEnd: undefined; }>>` | 用于保存 `emitter` 对应的数据。 |
|
||
| `isClipping` | `public` | `boolean` | 剖切是否已开始 |
|
||
| `clippingPlanes` | `public` | `THREE.Plane[]` | 所有注册的剖切平面（THREE.Plane），同步到 clippingGroup |
|
||
| `clippingPlaneHelpers` | `public` | `THREE.PlaneHelper[]` | 已废弃的辅助对象数组（保留以防外部引用） |
|
||
| `clippingGroup` | `public` | `THREE.ClippingGroup` | 用于保存 `clippingGroup` 对应的数据。 |
|
||
| `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` | 否 | 是否默认启用单面剖切补面。 |
|
||
|
||
### 方法
|
||
|
||
#### `addDefaultPlanes(): [ClippingPlane, ClippingPlane, ClippingPlane]`
|
||
|
||
- 作用：创建默认的 X / Y / Z 三个剖切面
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`[ClippingPlane, ClippingPlane, ClippingPlane]`
|
||
- 返回说明：[planeX, planeY, planeZ]
|
||
|
||
#### `addPlane(id: string, options: IClippingPlaneOptions): ClippingPlane`
|
||
|
||
- 作用：创建并注册一个剖切面
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `string` | 是 | 唯一标识 |
|
||
| `options` | `IClippingPlaneOptions` | 是 | 剖切面配置 |
|
||
|
||
- 出参：`ClippingPlane`
|
||
- 返回说明：返回 `ClippingPlane`。
|
||
|
||
#### `removePlane(id: string): void`
|
||
|
||
- 作用：移除剖切面
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `string` | 是 | 参数 `id`，类型为 `string`。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `getPlane(id: string): ClippingPlane | undefined`
|
||
|
||
- 作用：获取剖切面
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `string` | 是 | 参数 `id`，类型为 `string`。 |
|
||
|
||
- 出参：`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() 注册剖切面
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `offset` | `number` | 否 | 从包围盒 min 边的偏移量 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `addClippingObjectsByUuid(uuids: Array<string>): void`
|
||
|
||
- 作用：按 uuid 将场景对象加入剖切组。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `uuids` | `Array<string>` | 是 | 参数 `uuids`，类型为 `Array<string>`。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `addClippingObjects(objects: Array<THREE.Object3D>): void`
|
||
|
||
- 作用：批量加入剖切组，并触发单面补面刷新。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `objects` | `Array<THREE.Object3D>` | 是 | 目标对象集合。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `addClippingToObject(object: THREE.Object3D): void`
|
||
|
||
- 作用：将对象从原父节点迁入剖切组，并保留原始变换信息。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `object` | `THREE.Object3D` | 是 | 目标对象。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `removeClippingObjectsByUuid(uuids: Array<string>): void`
|
||
|
||
- 作用：按 uuid 从剖切组移除对象并恢复原父节点与原始变换。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `uuids` | `Array<string>` | 是 | 参数 `uuids`，类型为 `Array<string>`。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `clearClippingGroups(): void`
|
||
|
||
- 作用：清空剖切组对象、移除平面辅助，并刷新补面状态。
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `clearClippingPlanes(): void`
|
||
|
||
- 作用：清空所有剖切平面并解绑单面补面监听。
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `hideClippingPlanes(): void`
|
||
|
||
- 作用：隐藏历史平面辅助对象。
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `computeBoundingBox(): THREE.Box3`
|
||
|
||
- 作用：计算当前剖切组中网格对象的世界包围盒。
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`THREE.Box3`
|
||
- 返回说明：返回 `THREE.Box3`。
|
||
|
||
#### `createDebugPanel(clippingObjects: THREE.Object3D[] = []): void`
|
||
|
||
- 作用：创建调试面板
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `clippingObjects` | `THREE.Object3D[]` | 否 | 参数 `clippingObjects`，类型为 `THREE.Object3D[]`。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `startClipping(): void`
|
||
|
||
- 作用：将剖切状态设为启用并发出 `clippingStart` 事件。
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `stopClipping(): void`
|
||
|
||
- 作用：将剖切状态设为关闭并发出 `clippingEnd` 事件。
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `dispose(): void`
|
||
|
||
- 作用：释放资源并销毁当前实例。
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
## 构造示例
|
||
|
||
- `Viewer` 初始化时会自动创建 `ClippingManager`，可通过 `Viewer` 选项透传剖切补面默认配置。
|
||
|
||
```ts
|
||
import { Viewer } from "@deep/engine";
|
||
|
||
const viewer = new Viewer("app", {
|
||
clipping: {
|
||
singlePlaneCapMeshName: "地层网格",
|
||
singlePlaneCapEnabled: true,
|
||
},
|
||
});
|
||
```
|
||
|
||
## 函数示例
|
||
|
||
- 单面剖切补面的典型流程：
|
||
|
||
```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");
|
||
```
|