deep-engine-demo/packages/docs/api/manager/ClippingManager.md

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 选项透传剖切补面默认配置。

import { Viewer } from "@deep/engine";

const viewer = new Viewer("app", {
	clipping: {
		singlePlaneCapMeshName: "地层网格",
		singlePlaneCapEnabled: true,
	},
});

函数示例

• 单面剖切补面的典型流程：

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