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
- VolumeCroppingControlTool - Companion tool for 2D viewport reference lines
- BaseTool - Base class providing core tool functionality
Extends
Constructors
new VolumeCroppingTool()
new VolumeCroppingTool(
toolProps
,defaultToolProps
):VolumeCroppingTool
Parameters
• toolProps: PublicToolProps
= {}
• defaultToolProps: SharedToolProp
= ...
Returns
Overrides
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
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
Defined in
tools/src/tools/base/BaseTool.ts:28
mode
mode:
ToolModes
Tool Mode - Active/Passive/Enabled/Disabled/
Inherited from
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
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
Defined in
tools/src/tools/base/BaseTool.ts:33
toolName
static
toolName:any
Static tool identifier: 'VolumeCropping'
Overrides
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
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
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
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
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
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
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
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
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
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
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
Defined in
tools/src/tools/base/BaseTool.ts:269
endGroupRecording()
static
endGroupRecording():void
Ends a group recording of history memo
Returns
void
Inherited from
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
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