Skip to main content

Class: VolumeCroppingTool

VolumeCroppingTool provides manipulatable spheres and real-time volume cropping capabilities. It renders interactive handles (spheres) at face centers and corners of a cropping box, allowing users to precisely adjust volume boundaries through direct manipulation in 3D space.

Remarks

This tool creates a complete 3D cropping interface with:

  • 6 face spheres for individual axis cropping
  • 8 corner spheres for multi-axis cropping
  • 12 edge lines connecting corner spheres
  • Real-time clipping plane updates
  • Synchronization with VolumeCroppingControlTool working on the same series instance UID for cross-viewport interaction

Example

// Basic setup
const toolGroup = ToolGroupManager.createToolGroup('volume3D');
toolGroup.addTool(VolumeCroppingTool.toolName);

// Configure with custom settings
toolGroup.setToolConfiguration(VolumeCroppingTool.toolName, {
showCornerSpheres: true,
showHandles: true,
initialCropFactor: 0.1,
sphereColors: {
SAGITTAL: [1.0, 1.0, 0.0], // Yellow for sagittal (X-axis) spheres
CORONAL: [0.0, 1.0, 0.0], // Green for coronal (Y-axis) spheres
AXIAL: [1.0, 0.0, 0.0], // Red for axial (Z-axis) spheres
CORNERS: [0.0, 0.0, 1.0] // Blue for corner spheres
},
sphereRadius: 10,
grabSpherePixelDistance: 25
});

// Activate the tool
toolGroup.setToolActive(VolumeCroppingTool.toolName);

// Programmatically control visibility
const tool = toolGroup.getToolInstance(VolumeCroppingTool.toolName);
tool.setHandlesVisible(true);
tool.setClippingPlanesVisible(true);

// Toggle visibility for interactive UI
function toggleCroppingInterface() {
const handlesVisible = tool.getHandlesVisible();
const planesVisible = tool.getClippingPlanesVisible();

// Toggle handles (spheres and edge lines)
tool.setHandlesVisible(!handlesVisible);

// Toggle clipping effect
tool.setClippingPlanesVisible(!planesVisible);

console.log(`Handles: ${!handlesVisible ? 'shown' : 'hidden'}`);
console.log(`Cropping: ${!planesVisible ? 'active' : 'disabled'}`);
}

// Common UI scenarios
// Show handles but disable cropping (for positioning)
tool.setHandlesVisible(true);
tool.setClippingPlanesVisible(false);

// Hide handles but keep cropping active (for clean view)
tool.setHandlesVisible(false);
tool.setClippingPlanesVisible(true);

VolumeCroppingTool

Configuration

Events

VOLUMECROPPING_TOOL_CHANGED - Fired when sphere positions change or clipping planes are updated VOLUMECROPPINGCONTROL_TOOL_CHANGED - Listens for changes from VolumeCroppingControlTool VOLUME_VIEWPORT_NEW_VOLUME - Listens for new volume loading to reinitialize cropping bounds TOOLGROUP_VIEWPORT_ADDED - Listens for new viewport additions to extend resize observation

Methods

  • setHandlesVisible(visible: boolean): Show/hide manipulation spheres and edge lines
  • setClippingPlanesVisible(visible: boolean): Enable/disable volume clipping planes
  • getHandlesVisible(): Get current handle visibility state
  • getClippingPlanesVisible(): Get current clipping plane visibility state

See

Extends

Constructors

new VolumeCroppingTool()

new VolumeCroppingTool(toolProps, defaultToolProps): VolumeCroppingTool

Parameters

toolProps: PublicToolProps = {}

defaultToolProps: SharedToolProp = ...

Returns

VolumeCroppingTool

Overrides

BaseTool.constructor

Defined in

tools/src/tools/VolumeCroppingTool.ts:227

Properties

_hasResolutionChanged

_hasResolutionChanged: boolean = false

Flag tracking if rendering resolution has been modified during interaction

Defined in

tools/src/tools/VolumeCroppingTool.ts:201


_resizeObservers

_resizeObservers: Map<any, any>

Map of ResizeObserver instances for viewport resize handling

Defined in

tools/src/tools/VolumeCroppingTool.ts:199


_viewportAddedListener()

_viewportAddedListener: (evt) => void

Event listener for new viewport additions

Parameters

evt: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:200


cleanUp()

cleanUp: () => void

Cleanup function for resetting tool state after interactions

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:198


configuration

configuration: Record<string, any>

Inherited from

BaseTool.configuration

Defined in

tools/src/tools/base/BaseTool.ts:19


cornerDragOffset

cornerDragOffset: [number, number, number] = null

3D offset vector for corner sphere dragging [dx, dy, dz]

Defined in

tools/src/tools/VolumeCroppingTool.ts:205


draggingSphereIndex

draggingSphereIndex: number = null

Index of currently dragged sphere, null when not dragging

Defined in

tools/src/tools/VolumeCroppingTool.ts:203


edgeLines

edgeLines: object = {}

Dictionary of edge line actors connecting corner spheres for wireframe visualization

Index Signature

[uid: string]: object

Defined in

tools/src/tools/VolumeCroppingTool.ts:218


faceDragOffset

faceDragOffset: number = null

1D offset value for face sphere dragging along single axis

Defined in

tools/src/tools/VolumeCroppingTool.ts:206


memo

protected memo: Memo

A memo recording the starting state of a tool. This will be updated as changes are made, and reflects the fact that a memo has been created.

Inherited from

BaseTool.memo

Defined in

tools/src/tools/base/BaseTool.ts:28


mode

mode: ToolModes

Tool Mode - Active/Passive/Enabled/Disabled/

Inherited from

BaseTool.mode

Defined in

tools/src/tools/base/BaseTool.ts:23


mouseDragCallback()

mouseDragCallback: (evt) => void

Mouse drag event handler for desktop interactions

Parameters

evt: InteractionEventType

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:197


originalClippingPlanes

originalClippingPlanes: object[] = []

Array of clipping plane objects with origin and normal vectors

Defined in

tools/src/tools/VolumeCroppingTool.ts:202


seriesInstanceUID?

optional seriesInstanceUID: string

Frame of reference for the tool

Defined in

tools/src/tools/VolumeCroppingTool.ts:195


sphereStates

sphereStates: object[] = []

Array of sphere state objects containing position, VTK actors, and metadata

Defined in

tools/src/tools/VolumeCroppingTool.ts:208


supportedInteractionTypes

supportedInteractionTypes: InteractionTypes[]

Supported Interaction Types - currently only Mouse

Inherited from

BaseTool.supportedInteractionTypes

Defined in

tools/src/tools/base/BaseTool.ts:17


toolCenter

toolCenter: Point3

Center point of the cropping volume in world coordinates [x, y, z]

Defined in

tools/src/tools/VolumeCroppingTool.ts:204


toolGroupId

toolGroupId: string

ToolGroup ID the tool instance belongs to

Inherited from

BaseTool.toolGroupId

Defined in

tools/src/tools/base/BaseTool.ts:21


touchDragCallback()

touchDragCallback: (evt) => void

Touch drag event handler for mobile interactions

Parameters

evt: InteractionEventType

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:196


defaults

static defaults: object

Has the defaults associated with the base tool.

configuration

configuration: object

configuration.activeStrategy

activeStrategy: any = undefined

configuration.defaultStrategy

defaultStrategy: any = undefined

configuration.strategies

strategies: object = {}

configuration.strategyOptions

strategyOptions: object = {}

Inherited from

BaseTool.defaults

Defined in

tools/src/tools/base/BaseTool.ts:33


toolName

static toolName: any

Static tool identifier: 'VolumeCropping'

Overrides

BaseTool.toolName

Defined in

tools/src/tools/VolumeCroppingTool.ts:194

Accessors

toolName

get toolName(): string

Newer method for getting the tool name as a property

Returns

string

Inherited from

BaseTool.toolName

Defined in

tools/src/tools/base/BaseTool.ts:82

Methods

_addLine3DBetweenPoints()

_addLine3DBetweenPoints(viewport, point1, point2, color, uid): object

Parameters

viewport: any

point1: any

point2: any

color: [number, number, number] = ...

uid: string = ''

Returns

object

actor

actor: vtkActor

source

source: vtkPolyData = polyData

Defined in

tools/src/tools/VolumeCroppingTool.ts:936


_addSphere()

_addSphere(viewport, point, axis, position, cornerKey, adaptiveRadius): void

Parameters

viewport: any

point: any

axis: any

position: any

cornerKey: any = null

adaptiveRadius: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:982


_calculateAdaptiveSphereRadius()

_calculateAdaptiveSphereRadius(diagonal): number

Calculate an adaptive sphere radius based on the diagonal of the volume. This allows the sphere size to scale with the volume size.

Parameters

diagonal: any

The diagonal length of the volume in world coordinates.

Returns

number

The calculated adaptive radius, clamped between min and max limits.

Defined in

tools/src/tools/VolumeCroppingTool.ts:1050


_calculateNewCornerPosition()

_calculateNewCornerPosition(world): any[]

Parameters

world: any

Returns

any[]

Defined in

tools/src/tools/VolumeCroppingTool.ts:1343


_dragCallback()

_dragCallback(evt): void

Parameters

evt: InteractionEventType

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:621


_getViewport()

_getViewport(): Viewport

Returns

Viewport

Defined in

tools/src/tools/VolumeCroppingTool.ts:1300


_getViewportAndWorldCoords()

_getViewportAndWorldCoords(evt): object

Parameters

evt: any

Returns

object

viewport

viewport: Viewport

world

world: Point3

Defined in

tools/src/tools/VolumeCroppingTool.ts:1291


_getViewportsInfo()

_getViewportsInfo(): any[]

Returns

any[]

Defined in

tools/src/tools/VolumeCroppingTool.ts:977


_handleCornerSphereMovement()

_handleCornerSphereMovement(sphereState, world, viewport): void

Parameters

sphereState: any

world: any

viewport: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1307


_handleFaceSphereMovement()

_handleFaceSphereMovement(sphereState, world, viewport): void

Parameters

sphereState: any

world: any

viewport: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1325


_initialize3DViewports()

_initialize3DViewports(viewportsInfo): void

Parameters

viewportsInfo: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1068


_onControlToolChange()

_onControlToolChange(evt): void

Parameters

evt: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:759


_onMouseMoveSphere()

_onMouseMoveSphere(evt): boolean

Parameters

evt: any

Returns

boolean

Defined in

tools/src/tools/VolumeCroppingTool.ts:702


_onNewVolume()

_onNewVolume(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1655


_parseCornerKey()

_parseCornerKey(uid): object

Parameters

uid: any

Returns

object

isXMax

isXMax: any

isXMin

isXMin: any

isYMax

isYMax: any

isYMin

isYMin: any

isZMax

isZMax: any

isZMin

isZMin: any

Defined in

tools/src/tools/VolumeCroppingTool.ts:1358


_rotateCamera()

_rotateCamera(viewport, centerWorld, axis, angle): void

Parameters

viewport: any

centerWorld: any

axis: any

angle: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1693


_shouldUpdateCorner()

_shouldUpdateCorner(cornerKey, axisFlags): any

Parameters

cornerKey: any

axisFlags: any

Returns

any

Defined in

tools/src/tools/VolumeCroppingTool.ts:1394


_subscribeToViewportNewVolumeSet()

_subscribeToViewportNewVolumeSet(viewports): void

Parameters

viewports: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1678


_triggerToolChangedEvent()

_triggerToolChangedEvent(sphereState): void

Parameters

sphereState: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1452


_unsubscribeToViewportNewVolumeSet()

_unsubscribeToViewportNewVolumeSet(viewportsInfo): void

Parameters

viewportsInfo: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1663


_updateAfterCornerMovement()

_updateAfterCornerMovement(viewport): void

Parameters

viewport: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1437


_updateAfterFaceMovement()

_updateAfterFaceMovement(viewport): void

Parameters

viewport: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1444


_updateClippingPlanes()

_updateClippingPlanes(viewport): void

Parameters

viewport: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:849


_updateClippingPlanesFromFaceSpheres()

_updateClippingPlanesFromFaceSpheres(viewport): void

Parameters

viewport: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1461


_updateCornerCoordinates()

_updateCornerCoordinates(state, newCorner, cornerKey, axisFlags): void

Parameters

state: any

newCorner: any

cornerKey: any

axisFlags: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1406


_updateCornerSpheres()

_updateCornerSpheres(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1606


_updateCornerSpheresFromFaces()

_updateCornerSpheresFromFaces(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1503


_updateFaceSpheresFromCorners()

_updateFaceSpheresFromCorners(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1536


_updateHandlesVisibility()

_updateHandlesVisibility(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:920


_updateRelatedCorners()

_updateRelatedCorners(draggedSphere, newCorner, axisFlags): void

Parameters

draggedSphere: any

newCorner: any

axisFlags: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1378


_updateSpherePosition()

_updateSpherePosition(sphereState, newPosition): void

Parameters

sphereState: any

newPosition: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:1371


applyActiveStrategy()

applyActiveStrategy(enabledElement, operationData): any

Applies the active strategy function to the enabled element with the specified operation data.

Parameters

enabledElement: IEnabledElement

The element that is being operated on.

operationData: unknown

The data that needs to be passed to the strategy.

Returns

any

The result of the strategy.

Inherited from

BaseTool.applyActiveStrategy

Defined in

tools/src/tools/base/BaseTool.ts:102


applyActiveStrategyCallback()

applyActiveStrategyCallback(enabledElement, operationData, callbackType, ...extraArgs): any

Applies the active strategy, with a given event type being applied. The event type function is found by indexing it on the active strategy function.

Parameters

enabledElement: IEnabledElement

The element that is being operated on.

operationData: unknown

The data that needs to be passed to the strategy.

callbackType: string

the type of the callback

• ...extraArgs: any[]

Returns

any

The result of the strategy.

Inherited from

BaseTool.applyActiveStrategyCallback

Defined in

tools/src/tools/base/BaseTool.ts:126


doneEditMemo()

doneEditMemo(): void

This clears and edit memo storage to allow for further history functions to be called. Calls the complete function if present, and pushes the memo to the history memo stack.

This should be called when a tool has finished making a change which should be separated from future/other changes in terms of the history. Usually that means on endCallback (mouse up), but some tools also make changes on the initial creation of an object or have alternate flows and the doneEditMemo has to be called on mouse down or other initiation events to ensure that new changes are correctly recorded.

If the tool has no end callback, then the doneEditMemo is called from the pre mouse down callback. See ZoomTool for an example of this usage.

Returns

void

Inherited from

BaseTool.doneEditMemo

Defined in

tools/src/tools/base/BaseTool.ts:305


getClippingPlanesVisible()

getClippingPlanesVisible(): any

Gets the current visibility state of the clipping planes.

Returns

any

Whether the clipping planes are currently visible and actively cropping the volume

Example

// Check if clipping planes are currently active
const planesVisible = volumeCroppingTool.getClippingPlanesVisible();
if (planesVisible) {
console.log('Volume is currently being cropped');
} else {
console.log('Volume is displayed in full');
}

Remarks

This method returns the configuration state that controls whether:

  • The volume rendering respects the current clipping plane boundaries
  • Parts of the volume outside the crop bounds are hidden from view
  • The cropping effect is applied to the 3D volume visualization

Defined in

tools/src/tools/VolumeCroppingTool.ts:585


getHandlesVisible()

getHandlesVisible(): any

Gets the current visibility state of the cropping handles.

Returns

any

Whether the cropping handles (spheres and edge lines) are currently visible

Example

// Check if handles are currently visible
const handlesVisible = volumeCroppingTool.getHandlesVisible();
if (handlesVisible) {
console.log('Cropping handles are currently shown');
} else {
console.log('Cropping handles are currently hidden');
}

Remarks

This method returns the configuration state, which controls the visibility of:

  • Face spheres (6 spheres for individual axis cropping)
  • Corner spheres (8 spheres for multi-axis cropping)
  • Edge lines connecting the corner spheres

Defined in

tools/src/tools/VolumeCroppingTool.ts:559


getTargetId()

protected getTargetId(viewport): string

Get the target Id for the viewport which will be used to store the cached statistics scoped to that target in the annotations. For StackViewport, targetId is the viewportId, but for the volume viewport, the targetId will be grabbed from the volumeId if particularly specified in the tool configuration, or if not, the first actorUID in the viewport.

Parameters

viewport: Viewport

viewport to get the targetId for

Returns

string

targetId

Inherited from

BaseTool.getTargetId

Defined in

tools/src/tools/base/BaseTool.ts:238


getTargetImageData()

protected getTargetImageData(targetId): IImageData | CPUIImageData

Get the image that is displayed for the targetId in the cachedStats which can be

  • imageId:<imageId>
  • volumeId:<volumeId>
  • videoId:<basePathForVideo>/frames/<frameSpecifier>

Parameters

targetId: string

annotation targetId stored in the cached stats

Returns

IImageData | CPUIImageData

The image data for the target.

Inherited from

BaseTool.getTargetImageData

Defined in

tools/src/tools/base/BaseTool.ts:181


getToolName()

getToolName(): string

Returns the name of the tool

Returns

string

The name of the tool.

Inherited from

BaseTool.getToolName

Defined in

tools/src/tools/base/BaseTool.ts:90


onCameraModified()

onCameraModified(evt): void

Parameters

evt: any

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:358


onSetToolActive()

onSetToolActive(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:257


onSetToolConfiguration()

onSetToolConfiguration(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:329


onSetToolDisabled()

onSetToolDisabled(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:338


onSetToolEnabled()

onSetToolEnabled(): void

Returns

void

Defined in

tools/src/tools/VolumeCroppingTool.ts:334


preMouseDownCallback()

preMouseDownCallback(evt): boolean

Parameters

evt: InteractionEventType

Returns

boolean

Defined in

tools/src/tools/VolumeCroppingTool.ts:367


redo()

redo(): void

Redo an action (undo the undo)

Returns

void

Inherited from

BaseTool.redo

Defined in

tools/src/tools/base/BaseTool.ts:261


setActiveStrategy()

setActiveStrategy(strategyName): void

Sets the active strategy for a tool. Strategies are multiple implementations of tool behavior that can be switched by tool configuration.

Parameters

strategyName: string

name of the strategy to be set as active

Returns

void

Inherited from

BaseTool.setActiveStrategy

Defined in

tools/src/tools/base/BaseTool.ts:167


setClippingPlanesVisible()

setClippingPlanesVisible(visible): void

Sets the visibility of the clipping planes to enable or disable volume cropping.

When clipping planes are visible, the volume rendering is cropped according to the current sphere positions. When disabled, the full volume is displayed without cropping. The viewport is automatically re-rendered after the change.

Parameters

visible: boolean

Whether to enable (true) or disable (false) volume clipping

Returns

void

Example

// Enable volume cropping
volumeCroppingTool.setClippingPlanesVisible(true);

// Disable volume cropping to show full volume
volumeCroppingTool.setClippingPlanesVisible(false);

Remarks

  • When enabled, parts of the volume outside the crop bounds are hidden
  • When disabled, all clipping planes are removed from the volume mapper
  • The cropping bounds are determined by the current sphere positions
  • The viewport is automatically re-rendered to reflect the change
  • This method updates the internal configuration and applies changes immediately

Defined in

tools/src/tools/VolumeCroppingTool.ts:614


setConfiguration()

setConfiguration(newConfiguration): void

merges the new configuration with the tool configuration

Parameters

newConfiguration: Record<string, any>

Returns

void

Inherited from

BaseTool.setConfiguration

Defined in

tools/src/tools/base/BaseTool.ts:153


setHandlesVisible()

setHandlesVisible(visible): void

Sets the visibility of the cropping handles (spheres and edge lines).

When handles are being shown, this method automatically synchronizes the sphere positions with the current clipping plane positions to ensure visual consistency. This includes updating face spheres, corner spheres, and edge lines to match the current crop bounds.

Parameters

visible: boolean

Whether to show or hide the cropping handles

Returns

void

Example

// Hide all cropping handles
volumeCroppingTool.setHandlesVisible(false);

// Show handles and sync with current crop state
volumeCroppingTool.setHandlesVisible(true);

Defined in

tools/src/tools/VolumeCroppingTool.ts:490


undo()

undo(): void

Undoes an action

Returns

void

Inherited from

BaseTool.undo

Defined in

tools/src/tools/base/BaseTool.ts:251


createZoomPanMemo()

static createZoomPanMemo(viewport): object

Creates a zoom/pan memo that remembers the original zoom/pan position for the given viewport.

Parameters

viewport: any

Returns

object

restoreMemo()

restoreMemo: () => void

Returns

void

Inherited from

BaseTool.createZoomPanMemo

Defined in

tools/src/tools/base/BaseTool.ts:269


endGroupRecording()

static endGroupRecording(): void

Ends a group recording of history memo

Returns

void

Inherited from

BaseTool.endGroupRecording

Defined in

tools/src/tools/base/BaseTool.ts:318


mergeDefaultProps()

static mergeDefaultProps(defaultProps, additionalProps?): any

Does a deep merge of property options. Allows extending the default values for a child class.

Parameters

defaultProps = {}

this is a base set of defaults to merge into

additionalProps?: any

the additional properties to merge into the default props

Returns

any

defaultProps if additional props not defined, or a merge into a new object containing additionalProps adding onto and overriding defaultProps.

Inherited from

BaseTool.mergeDefaultProps

Defined in

tools/src/tools/base/BaseTool.ts:72


startGroupRecording()

static startGroupRecording(): void

Starts a group recording of history memo, so that with a single undo you can undo multiple actions that are related to each other

Returns

void

Inherited from

BaseTool.startGroupRecording

Defined in

tools/src/tools/base/BaseTool.ts:313