CrossSectionPlugin

Interactive cross-sectional views. Composes CrossSectionService (clipping, contours, cap) with TransformControlsService (drag the plane) and auto-sizes a visual plane mesh to scene bounds.

Usage

import { ViewerCore, CrossSectionPlugin } from "@optellix/xviewr-sdk";

const viewer = new ViewerCore(container, config);
await viewer.ready();
await viewer.loadPlugin(new CrossSectionPlugin());

const xsec = viewer.pluginManager.getPlugin("crosssection") as CrossSectionPlugin;
await xsec.enable();           // creates a default Y-axis section
await xsec.createAxisSection("X");

Service dependencies: crosssection, transformcontrols.

Since 4.0

• Object-scoped clipping planes: createObjectClippingPlane(object, position, normal) and createObjectAxisSection(object, axis, position?) (via CrossSectionService.createObjectSectionPlane / createAxisSection with a CrossSectionPlaneScope = { type: "object"; object }). Scoped planes only clip meshes under the target object; other meshes render normally.
• Scoped material clipping: the service clones materials only on meshes inside an object scope and disposes the clones when the plane is removed. Non-scoped meshes keep their original materials.
• Live clipping: THREE.Plane instances are mutated in place on drag, so highlight/section-aware materials that hold a getLiveClippingPlanes() reference stay in sync across frames without a per-frame traversal.
• BVH-driven contours: SectionContourGenerator uses the AdvancedMeshService BVH provider, so contour regeneration is incremental and scoped per plane.
• Contour refresh: CrossSectionService.refreshContours() recomputes contours from external triggers such as visibility, transform, or explosion changes on a sectioned mesh.
• Safer plane removal: removeClippingPlane(index) and clearClippingPlanes() reindex planeScopes in step with clippingPlanes, restore any cloned materials, and rebuild the clip cap on the remaining planes.

Public API

Lifecycle

Method	Description
enable()	Activate clipping. Creates a default Y plane if none exist.
disable()	Deactivate, detach gizmo, remove plane visuals.
isEnabled()	Boolean.

Configuration

Method	Description
updateConfig(config)	Partial update of CrossSectionConfig.
getConfig()	Current CrossSectionConfig.

Plane management

Method	Description
createClippingPlane(position, normal)	Create an arbitrary plane. Returns its index.
createAxisSection(axis, position?)	Create an axis-aligned plane on "X" | "Y" | "Z". Defaults to scene center.
removeClippingPlane(index)	Remove a plane.
updateClippingPlane(index, plane)	Replace plane definition.
getClippingPlane(index)	Get a THREE.Plane by index.
getClippingPlanes()	Get all planes.
clearClippingPlanes()	Remove all planes.

Transform controls

Method	Description
attachTransformControls(planeIndex)	Attach the translate gizmo to a plane.
detachTransformControls()	Detach the gizmo.
getAttachedPlaneIndex()	Returns the attached plane index or null.

Orientation, rotation, sizing

Method	Description
setPlaneOrientation("X" | "Y" | "Z")	Clear and recreate a single axis plane.
rotatePlane(rx, ry, rz)	Rotate the attached plane mesh in degrees and update the clip plane.
getCurrentPlaneRotation()	Returns { x, y, z } in degrees or null.
fitPlaneToScene()	Rebuild plane geometry to fit scene bounds.
centerPlane(planeIndex)	Move the plane constant so it passes through the scene center.

Visual controls

Method	Description
setPlaneColor(color)	Set the visible plane color.
setPlaneOpacity(opacity)	0..1.
showBoundary(show)	Toggle the plane edge outline.
setBoundaryColor(color)	Color for the edge outline.
setContourColor(color)	Color for the section contours.
showHelper(show)	Toggle the service's PlaneHelper.
showContours(show)	Toggle contour rendering.
showClipCap(show, color?)	Toggle the clip cap fill.
setClipCapColor(color)	Cap color.
setClipCapStyle(style)	SectionCapStyle from services/crosssection.
generateContours()	Force a contour regeneration.
getContourLineSegments()	Returns the current contour THREE.LineSegments (or undefined).
exportContoursAsIges(filename?)	Export contour lines as an IGES file and trigger download.

Animation

Method	Description
animatePlane(index, targetPosition, duration?)	Animate plane along its normal toward targetPosition. Default 800 ms.

Event registration

The plugin exposes typed callback registration helpers in addition to bus events:

Method	Callback signature
onPlaneCreated(cb)	(index, plane) => void
onPlaneUpdated(cb)	(index, plane) => void
onPlaneRemoved(cb)	(index) => void
onTransformStarted(cb)	(planeIndex) => void
onTransformEnded(cb)	(planeIndex) => void

Events

Emitted on the event bus:

Event	Payload
crosssection:plugin-activated	{}
crosssection:plugin-deactivated	{}

Example

const xsec = viewer.pluginManager.getPlugin("crosssection") as CrossSectionPlugin;

await xsec.enable();
const idx = await xsec.createAxisSection("Z");
xsec.showContours(true);
xsec.setPlaneOpacity(0.2);
xsec.showClipCap(true, "#ff8800");

xsec.onTransformEnded((planeIndex) => {
  console.log("plane moved", planeIndex);
});

xsec.exportContoursAsIges("section.iges");