---
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");
```