Documentation/Nightly/Modules/VolumeRendering

From SlicerWiki
Jump to: navigation, search
Home < Documentation < Nightly < Modules < VolumeRendering

For the stable Slicer documentation, visit the 4.8 page.


Introduction and Acknowledgements

Title: Volume Rendering
Author(s)/Contributor(s): Julien Finet (Kitware), Alex Yarmarkovich (Isomics), Yanling Liu (SAIC-Frederick, NCI-Frederick), Andreas Freudling (SPL, BWH), Ron Kikinis(SPL, BWH)
License: slicer4
Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Some of the transfer functions were contributed by Kitware Inc. (VolView)
Contact: Julien Finet,
Kitware, Inc.  
Isomics, Inc.  
Surgical Planning Laboratory (SPL)  
National Alliance for Medical Image Computing (NA-MIC)  

Module Description

This module provides interactive visualization of 3D image data.

Only UNSIGNED CHAR images are supported for now. You can convert your images into UCHAR by using the Cast Scalar Volume module.

Use Cases

Tutorials

Tutorial about using the volume rendering module.

Labelmap rendering

Modules-VolumeRendering-LabelMap.png

A labelmap is a volume, and as such it can be visualized using the Volume Rendering method. It can be an alternative from creating surface models from a labelmap.

  1. First you need to load your labelmap.
    1. Make sure you check the "Labelmap" check box at load time.
    2. Make sure the labelmap is a Unsigned Char image, not Unsigned/Signed Short, Int or Long. If needed, you can cast the labelmap to UCHAR.
  2. Open the Volume Rendering module
    1. Click on the eye to start the Volume Rendering.
  3. To turn off shading:
    1. Go to Advanced../Volume Properties/Advanced group box and uncheck the "Shade" checkbox
  4. To turn on/off a specific label:
    1. Go to the Advanced.../Volume Properties/Scalar Opacity Mapping group box
    2. Toggle down the '>>' button to show the Opacity controls.
    3. Browse each label with the "Point:" spinbox. When the spinbox shows the current label value,
    4. Set the Opacity spinbox value to 0.0/1.0 to hide/show the label.

Render 2 volumes in 2 views

DualVR.png
  1. Change layout into "Dual 3D"
  2. Load your 2 volumes
  3. Open Volume Rendering module
  4. For the first volume:
    1. Open the "Inputs" section
    2. Uncheck "View2". Only "View1" should be checked.
    3. Don't click the "eye" icon yet.
  5. Select the second volume.
    1. Check "View2".
    2. Uncheck "View1". Only "View2" should be checked.
    3. Click the eye icon for the VR to show up in View2
  6. Select the 1st volume
    1. Click the eye icon for the VR to show up in View1

Panels and their use

VolumeRenderingPanel.png

Parameters:

  • Inputs: Contains the list of nodes required for VolumeRendering. It is unlikely that you need to interact with controllers.
    • Volume: Select the current volume to render. Note that only one volume can be rendered at a time.
    • Display: Select the current volume rendering display properties. Volume rendering display nodes contains all the information relative to volume rendering. They contain pointers to the ROI, volume property and view nodes. A new display node is automatically created if none exist for the current volume.
    • ROI: Select the current ROI to optionally crop with 6 planes the volume rendering.
    • Property: Select the current Volume Property. Volume properties contain the opacity, color and gradient transfer functions for each component.
    • View: Select the 3D views where the volume rendering must be displayed into. If no view is selected, the volume rendering is visible in all views
  • Display: Main properties for the volume rendering.
    • Preset: Apply a pre-defined set of functions for the opacity, color and gradient transfer functions. The generic presets have been tuned for a combination of modalities and organs. They may need some manual tuning to fit your data.
    • Shift: Move all the inner points (first and last excluded) of the current transfer functions to the right/left (lower/higher). It can be useful when a preset defines a ramp from 0 to 200 but your data requires a ramp from 1000 to 1200.
    • Crop: Simple controls for the cropping box (ROI). More controls are available in the "Advanced..." section. Enable/Disable cropping of the volume. Show/Hide the cropping box. Reset the box ROI to the volume's bounds.
    • Rendering: Select a volume rendering method. A default method can be set in the application settings Volume Rendering panel.
        VTK CPU Ray Casting: Available on all platforms, the volume rendering is enterily realized on the CPU (default)
        VTK GPU Ray Casting: Available on all platforms except on Mac with an NVidia graphic card, fastest method to volume render
        VTK OpenGL 3D Texture Mapping: Available on all platforms, use the GPU but it is not ray casting
        NCI GPU Ray Casting: Available on all platforms, ray caster on the GPU, doesn't support compositing.
    • Advanced: More controls to control the volume rendering. Contains 3 tabs: "Techniques", "Volume Properties" and "ROI"
      • Technique: Advanced properties of the current volume rendering method.
      • GPU Memory Size: Amount of memory to allocate on the GPU for volume rendering. By default, all the memory of the GPU is allocated. You can change the default behavior in the application settings Volume Rendering panel.
      • Quality Control: Not supported yet.
      • Interactive speed: Ensure the given frame per second (FPS) is enforced in the views during interaction. The higher the FPS, the lower the resolution of the volume rendering
      • Synchronize with Volumes module:
             Click: Apply once the properties (window/level, threshold, lut) of the Volumes module to the Volume Rendering module.
             Toggled: By clicking on the checkbox, you can toggle the button. When toggled, any modification occuring in the Volumes module is instantaneously applied to the volume rendering
    • Volume Properties: Advanced views of the transfer functions.
      • Left button click: Set current point or create a new point if no point is under the mouse.
      • Left button move: Move the current or selected points if any.
      • Right button click: Select/unselect point. Selected points can be moved at once
      • Right button move: Define an area to select points:
      • Middle button click : Delete point under the mouse cursor.
      • Right/Left arrow keys: Change of current point
      • Delete key: Delete the current point and set the next point as current
      • Backspace key : Delete the current point and set the previous point as current
      • ESC key: Unselect all points.
      • Unsupported : "ALT to move selected points", "CTRL-A to select all points"
      • Control Inputs::
             X: scalar value
             O: opacity
             M: mid-point
             S: sharpness
      • Scalar Opacity Mapping: Opacity transfer function. Threshold mode: enabling threshold controls the transfer function using range sliders in addition to control points.
      • Scalar Color Mapping: Color transfer function.
      • Gradient Opacity: Gradient opacity transfer function. This controls the opacity according to how large a density gradient next to the voxel is.
      • Interpolation: Linear (default for scalar volumes) or nearest neighboor (default for labelmaps) interpolation.
      • Shade: Enable/Disable shading. Shading uses light and material properties.
      • Material: Material properties of the volume to compute shading effect.
      • ROI: More controls for the cropping box.
      • Display Clipping box: Show hide the bounds of the ROI box.
      • Interactive mode: Control wether the cropping box is instantaneously updated when dragging the sliders or only when the mouse button is released.


    List of parameters generated transforming this XML file using this XSL file. To update the URL of the XML file, edit this page.


    Similar Modules

    Volumes

    References

    Publications related to this module go here. Links to pdfs would be useful. For extensions: link to the source code repository and additional documentation


    Information for Developers

    Limitations

    • To date, only 1 volume can be visible at a time. This happens because the current volume rendering displayable node is hidden when changing to a different volume node.
    • Only UNSIGNED CHAR images are supported for now. You can convert your images into UCHAR by using the Cast Scalar Volume module.

    Key nodes and classes

    How Tos

    How to programmatically volume render your volume node

    C++ Python
    qSlicerAbstractCoreModule* volumeRenderingModule =
      qSlicerCoreApplication::application()->moduleManager()->module("VolumeRendering");
    vtkSlicerVolumeRenderingLogic* volumeRenderingLogic = 
      volumeRenderingModule ? vtkSlicerVolumeRenderingLogic::SafeDownCast(volumeRenderingModule->logic()) : 0;
    vtkMRMLVolumeNode* volumeNode = mrmlScene->GetNodeByID('vtkMRMLScalarVolumeNode1');
    if (volumeRenderingLogic)
      {
      vtkMRMLVolumeRenderingDisplayNode* displayNode =
        volumeRenderingLogic->CreateVolumeRenderingDisplayNode();
      mrmlScene->AddNode(displayNode);
      displayNode->Delete();
      volumeRenderingLogic->UpdateDisplayNodeFromVolumeNode(displayNode, volumeNode);
      volumeNode->AddAndObserveDisplayNodeID(displayNode->GetID());
      }
    

    See here for more about volume dependency.

    >>> logic = slicer.modules.volumerendering.logic()
    >>> volumeNode = slicer.mrmlScene.GetNodeByID('vtkMRMLScalarVolumeNode1')
    >>> displayNode = logic.CreateVolumeRenderingDisplayNode()
    >>> slicer.mrmlScene.AddNode(displayNode)
    >>> displayNode.UnRegister(logic)
    >>> logic.UpdateDisplayNodeFromVolumeNode(displayNode, volumeNode)
    >>> volumeNode.AddAndObserveDisplayNodeID(displayNode.GetID())
    

    How to programmatically apply a custom color/opacity transfer function

    C++ Python
    vtkColorTransferFunction* colors = ...
    vtkPiecewiseFunction* opacities = ...
    vtkMRMLVolumeRenderingDisplayNode* displayNode = ...
    vtkMRMLVolumePropertyNode* propertyNode = displayNode->GetVolumePropertyNode();
    propertyNode->SetColor(colorTransferFunction);
    propertyNode->SetScalarOpacity(opacities);
    // optionally set the gradients opacities with SetGradientOpacity
    

    The logic has utility functions to help you create those transfer functions:

    volumeRenderingLogic->SetWindowLevelToVolumeProp(...)
    volumeRenderingLogic->SetThresholdToVolumeProp(...)
    volumeRenderingLogic->SetLabelMapToVolumeProp(...)
    
    >>> propertyNode = displayNode.GetVolumePropertyNode()
    >>> ...
    

    How to programmatically limit volume rendering to a subset of the volume

    C++ Python
    vtkMRMLAnnotationROINode* roiNode =...
    vtkMRMLVolumeRenderingDisplayNode* displayNode = ...
    displayNode->SetAndObserveROINodeID(roiNode->GetID());
    displayNode->SetCroppingEnabled(1);
    
    >>> displayNode.SetAndObserveROINodeID(roiNode.GetID())
    >>> displayNode.CroppingEnabled = 1
    

    How to register a new Volume Rendering mapper

    You need to derive from vtkMRMLVolumeRenderingDisplayNode and register your class within vtkSlicerVolumeRenderingLogic.

    C++ Python
    void qSlicerMyABCVolumeRenderingModule::setup()
    {
      vtkMRMLThreeDViewDisplayableManagerFactory::GetInstance()->
        RegisterDisplayableManager("vtkMRMLMyABCVolumeRenderingDisplayableManager");
    
      this->Superclass::setup();
    
      qSlicerAbstractCoreModule* volumeRenderingModule =
        qSlicerCoreApplication::application()->moduleManager()->module("VolumeRendering");
      if (volumeRenderingModule)
        {
        vtkNew<vtkMRMLMyABCVolumeRenderingDisplayNode> displayNode;
        vtkSlicerVolumeRenderingLogic* volumeRenderingLogic =
          vtkSlicerVolumeRenderingLogic::SafeDownCast(volumeRenderingModule->logic());
        volumeRenderingLogic->RegisterRenderingMethod(
          "My ABC Volume Rendering", displayNode->GetClassName());
        }
      else
        {
        qWarning() << "Volume Rendering module is not found";
        }
    }
    

    If you want to expose control widgets for your volume rendering method, then register your widget with addRenderingMethodWidget()

    How to register custom volume rendering presets

    Custom presets can be added to the volume rendering module by calling AddPreset() method of the volume rendering module logic. The example below shows how to define multiple custom volume rendering presets in an external MRML scene file and add them to the volume rendering module user interface.

    Create a 'MyPresets.mrml' file that describes two custom volume rendering presets:

    <MRML version="Slicer4.4.0">
    
      <VolumeProperty id="vtkMRMLVolumeProperty1" name="MyPreset1"     references="IconVolume:vtkMRMLVectorVolumeNode1;" interpolation="1" shade="1" diffuse="0.66" ambient="0.1" specular="0.62" specularPower="14" scalarOpacity="10 -3.52844023704529 0 56.7852325439453 0 79.2550277709961 0.428571432828903 415.119384765625 1 641 1" gradientOpacity="4 0 1 160.25 1" colorTransfer="16 0 0 0 0 98.7223 0.196078431372549 0.945098039215686 0.956862745098039 412.406 0 0.592157 0.807843 641 1 1 1" />
      <VectorVolume id="vtkMRMLVectorVolumeNode1" references="storage:vtkMRMLVolumeArchetypeStorageNode1;" />  
      <VolumeArchetypeStorage id="vtkMRMLVolumeArchetypeStorageNode1" fileName="MyPreset1.png"  fileListMember0="MyPreset1.png" />
    
      <VolumeProperty id="vtkMRMLVolumeProperty2" name="MyPreset2"     references="IconVolume:vtkMRMLVectorVolumeNode2;" interpolation="1" shade="1" diffuse="0.66" ambient="0.1" specular="0.62" specularPower="14" scalarOpacity="10 -3.52844023704529 0 56.7852325439453 0 79.2550277709961 0.428571432828903 415.119384765625 1 641 1" gradientOpacity="4 0 1 160.25 1" colorTransfer="16 0 0 0 0 98.7223 0.196078431372549 0.945098039215686 0.956862745098039 412.406 0 0.592157 0.807843 641 1 1 1" />
      <VectorVolume id="vtkMRMLVectorVolumeNode2" references="storage:vtkMRMLVolumeArchetypeStorageNode2;" />  
      <VolumeArchetypeStorage id="vtkMRMLVolumeArchetypeStorageNode2" fileName="MyPreset2.png"  fileListMember0="MyPreset2.png" />
    
    </MRML>
    

    For this example, thumbnail images for the presets should be located in the same directory as 'MyPresets.mrml', with the file names 'MyPreset1.png' and 'MyPreset2.png'.

    Use the following code to read all the custom presets from 'MyPresets.mrml' and load it into the scene:

    presetsScenePath = "MyPresets.mrml"
    
    # Read presets scene
    customPresetsScene = slicer.vtkMRMLScene()
    vrPropNode = slicer.vtkMRMLVolumePropertyNode()
    customPresetsScene.RegisterNodeClass(vrPropNode)
    customPresetsScene.SetURL(presetsScenePath)
    customPresetsScene.Connect()
    
    # Add presets to volume rendering logic
    vrLogic = slicer.modules.volumerendering.logic()
    presetsScene = vrLogic.GetPresetsScene()
    vrNodes = customPresetsScene.GetNodesByClass("vtkMRMLVolumePropertyNode")
    vrNodes.UnRegister(None)
    for itemNum in range(vrNodes.GetNumberOfItems()):
      node = vrNodes.GetItemAsObject(itemNum)
      vrLogic.AddPreset(node)