feat: volume cropping

[mbellehumeur]

Context

ticket: 9248395925

This pull request adds two tools: VolumeCroppingTool and VolumeCroppingControlTool.

The VolumeCroppingTool acts on a VRT viewport and provides the ability to crop the volume using control spheres/handles along the axial, sagittal and coronal axis and the corners of the cropping volume.
The display of the control spheres can be enabled/disabled through the setHandlesVisible/ getHandlesVisible methods.

The VolumeCroppingControlTool acts on 1, 2 or 3 orthographic viewports and adds reference lines that control the cropping volume and react to changes in the cropping volume.

Messaging between the tools is handled through Cornerstone events that are validated by the series instance UID of the volume. Therefore the tools do not need to be in the same tool group as the volume cropping tool. Multiple cropping & control instances can be used on different series in the same display.

Configurable items of the VolumeCroppingTool are the following:

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

// Configure with custom colors and settings
 toolGroup.setToolConfiguration(VolumeCroppingControlTool.toolName, {
 lineColors: {
   AXIAL: [1.0, 0.0, 0.0],    // Red for axial views
   CORONAL: [0.0, 1.0, 0.0],  // Green for coronal views
   SAGITTAL: [1.0, 1.0, 0.0], // Yellow for sagittal views
  },
  lineWidth: 2.0,
  extendReferenceLines: true,
  viewportIndicators: true
});

toolGroup.setToolConfiguration(VolumeCroppingTool.toolName, {
    showCornerSpheres: true,
    showHandles: true,
    showClippingPlanes: true,
    initialCropFactor: 0.08,
    sphereColors: {
      AXIAL: [1.0, 0.0, 0.0], // Red for axial (Z-axis)
      CORONAL: [0.0, 1.0, 0.0], // Green for coronal (Y-axis)
      SAGITTAL: [1.0, 1.0, 0.0], //  Yellow for sagittal (X-axis)
      CORNERS: [0.0, 0.0, 1.0], // Blue for corners
    },
    sphereRadius: 8,
    grabSpherePixelDistance: 20, //pixels threshold for closeness to the sphere being grabbed
    rotateIncrementDegrees: 2,
    rotateSampleDistanceFactor: 2, // Factor to increase sample distance (lower resolution) when rotating
},


// Activate the tool
toolGroup.setToolActive(VolumeCroppingControlTool.toolName);
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'}`);
}

The volumeCroppingTool example demonstrates the two tools working together.

A dropdown box allows to select the number of orthographic viewports for the VolumeCroppingControl tool: 1, 2 or 3.

There are two toggle buttons to toggle the display of the control spheres and clipping planes:

The toggle buttons demonstrate the use of the following public 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

Changes & Results

New files are VolumeCropping, VolumeCroppingControl and index.js for the example.

Testing

Run the example and use the spheres to modify the cropping. The volume should change the control lines in the orthogonal views as well.
Use the control lines in the orthogonal views to change the cropping volume.
Use the 'Toggle 3D handles' button to hide/show the control spheres.

In OHIF, do not use the 'run dev:fast' option. It will cause rendering problems when moving the first sphere quickly. Use 'bun run dev'.

Checklist

PR

• My Pull Request title is descriptive, accurate and follows the
  semantic-release format and guidelines.

Code

• My code has been well-documented (function documentation, inline comments,
  etc.)

Public Documentation Updates

• The documentation page has been updated as necessary for any public API
  additions or removals.

[sedghi]

Thanks, great addition

[igoroctaviano]

LGTM, great work @mbellehumeur