Documentation/4.2/Modules/Annotations

From SlicerWiki
Jump to: navigation, search
Home < Documentation < 4.2 < Modules < Annotations

For the latest Slicer documentation, visit the 4.8 page.


Introduction and Acknowledgements

This work is part of the National Alliance for Medical Image Computing (NA-MIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on NA-MIC can be obtained from the NA-MIC website.
Author: Nicole Aucoin, BWH
Contributor: Kilian Pohl, UPenn
Contributor: Daniel Haehn, UPenn
Contributors: Yong Zhang, BWH
Contributor: Alex Yarmarkovich, Isomics
Contact: Nicole Aucoin,

Surgical Planning Laboratory (SPL)  
National Alliance for Medical Image Computing (NA-MIC)  
Neuroimage Analysis Center (NAC)  

Module Description

Create and edit annotations, supplementary information associated with a scene. Currently supported annotations are fiducial points, rulers, and regions of interest (ROIs).


Use Cases

Most frequently used for these scenarios:

  • Use Case 1: placing fiducial markers at points of interest on images
  • Use Case 2: using fiducials to seed tractography
  • Use Case 3: using rulers to measure tumor diameters
  • Use Case 4: using ROIs to crop volume rendering

Tutorials

To delete multiple fiducials from a list press down the Control key and left click to select fiducials in the Annotations GUI, then click on the trash can to delete them.

To move multiple fiducials from one list to another, hold down the Shift key and left click to select a group of fiducials, then while still holding down the shift key, left click on the selection to drag and drop it.


Panels and their use

A list of all the panels in the interface, their features, what they mean, and how to use them.

Annotations
Modify Annotation Properties
Modify Hierarchy Properties
Annotation tool bar

Parameters:

  • Annotations
    • Edit: Edit the properties of all the annotations in the scene
    • Select All Button: Select all annotations and hierarchies
    • Unselect All Button: Unselect all annotations and hierarchies
    • Visible Selected Button: Toggle the visibility of highlighted Annotations. Hierarchies are ignored.
    • Lock Selected Button: Lock or unlock highlighted annotations. Hierarchies are ignored.
    • Jump Slices Button: Reset slice views to the first coordinate of the highlighted annotation.
    • Add HierarchyButton: Create a new hierarchy. If a hierarchy is currently highlighted, the new one will be a sub-hierarchy
    • Generate Report: Display a report of highlighted annotations
    • Delete Selected Button: Delete highlighted annotations. Hierarchies have to single selected to get deleted.
    • Active list: The name of the currently active list, which controls which list new annotations will be added to. If the top level All Annotations list is active, the module will automatically create separate lists for each type of annotation. Click on a hierarchy in the tree view to make it active and to add new annotations to it.
    • Visible Hierarchy Button: Set all annotations in active list visible
    • Invisible Hierarchy Button: Set all annotations in active list invisible
    • Lock Hierarchy Button: Set all annotations in active list locked
    • Unlock Hierarchy Button: Set all annotations in active list to be unlocked
  • Annotation Hierarchy tree view
    • Selected: Selected annotations can be passed to command line modules.
    • Vis: Click on this button (eye open or closed) to toggle the visibility of the annotation in the 2D and 3D views
    • Lock: Click on this button to make the annotation be locked into place, not responding to mouse events. This is useful if you need to manipulate other things in the scene.
    • Edit: Click on the icon in the Edit column to bring up the Modify Annotation Properties dialog box
    • Value: A useful value associated with the annotation (location for fiducials, length for rulers)
    • Name: The name of the annotation, usually kept short, one letter and a number, as it's displayed in the 3D and 2D windows.
    • Description: A longer text describing this annotation
  • Modify Annotation Hierarchy Properties
    • Type: The class type for this annotation hierarchy
    • Color: Click on this button to bring up a color picker widget to set the color used for all annotations in this hierarchy when the hierarchy is collapsed (not implemented yet)
    • Apply to List: If this checkbox is ticked, change the color on all the annotations in this hierarchy. Default true.
    • Visibility: Click on this button (eye open or closed) to toggle the visibility of the annotations in this hierarchy in the 2D and 3D views.
    • Name: The name of the annotation hierarchy, describing the annotations below it.
    • Description: A longer text describing this annotation hierarchy
  • Modify Annotation Properties
    • Type: The class type for this annotation, is it a fiducial, ruler, region of interest?
    • Color: Click on this button to bring up a color picker widget to set the color for all parts of the annotation (text, glyphs, lines)
    • Visibility: Click on this button (eye open or closed) to toggle the visibility of the annotation in the 2D and 3D views.
    • Lock: Click on this button to make the annotation be locked into place, not responding to mouse events. This is useful if you need to manipulate other things in the scene.
    • Name: The name of the annotation, usually kept short, one letter and a number, as it's displayed in the 3D and 2D windows.
    • Size: Click on the small, Medium, Large buttons to change the scaling of the annotation
    • RAS: The world coordinates of this annotation in the default Slicer Right-Anterior-Superior coordinate system. Double click to edit the values
    • Description: A longer text describing this annotation
  • Modify Annotation Properties: Advanced
    • Text: Set the descriptive text, text color, scale, opacity on this panel
    • Points: Set the coordinate location of the point(s), glyph color, scale, glyph type, opacity, ambient, diffuse, specular material properites on this panel
    • Lines: This panel is only enabled for rulers. Set the line color, label visibility, label position along the line (from 0-1), tick spacing, maximum number of ticks, opacity, ambient, diffuse, specular material properites on this panel
    • ROI: This panel is only enabled for regions of interest. Set the ranges for the ROI along it's axes, LR, PA, IS. Toggle the ROI visibility and if it's updated interactively on this panel
  • Toolbar
    • Annotations toolbar: Create new annotations by selecting them from the drop down menu. Return to rotate mouse mode by clicking on the rotate idcon. Toggle persistent placement of annotations by checking and unchecking the Persistent checkbox


Similar Modules

  • The Annotations tool bar at the top of the main Slicer window is used to add new annotations to the scene.

References

N/A

Information for Developers


Access to Fiducial Locations from Python

Starting from the ID of an Annotation hierarchy node that collects a group of fiducials, you can get a fiducial location using the following python code:

 # get the first list of annotations
 listNodeID = "vtkMRMLAnnotationHierarchyNode2"
 annotationHierarchyNode = slicer.mrmlScene.GetNodeByID(listNodeID)
 # get the first in the list
 listIndex = 0
 annotation = annotationHierarchyNode.GetNthChildNode(listIndex).GetAssociatedNode()
 coords = [0,0,0]
 annotation.GetFiducialCoordinates(coords)
 print coords

If you have the id of the fiducial node, it's more direct:

 fidID = "vtkMRMLAnnotationFiducialNode1"
 fid = slicer.mrmlScene.GetNodeByID(fidID)
 coords = [0,0,0]
 fid.GetFiducialCoordinates(coords)
 print coords[0], coords[1], coords[2]

You can also look at the sample code in the Endoscopy module to see how python is used to access fiducials.

Transforms

Individual annotations are transformable (able to be placed under a transform node), but lists are not. In order to apply a transform to a set of annotations, open the python console (View -> Python Interctor) and use the following code. First you'll need to get the transform node MRML id from the Data module (click on Display MRML IDs), and save it to a variable:

 transformNodeID = "vtkMRMLLinearTransformNode5"

Then get the id of the annotation hierarchy list node that holds the annotations that you wish to transform:

 listNodeID = "vtkMRMLAnnotationHierarchyNode3"

Then use this code snippet to apply the transform to all the annotations under the hierarchy node:

 annotationHierarchyNode = slicer.mrmlScene.GetNodeByID(listNodeID)
 numNodes = annotationHierarchyNode.GetNumberOfChildrenNodes()
 for i in range(numNodes):
   annotation = annotationHierarchyNode.GetNthChildNode(i).GetAssociatedNode()
   annotation.SetAndObserveTransformNodeID(transformNodeID)

Programmatic Access to Fiducials

This section explains how to access fiducial nodes added into the scene by the user.

In your module's Logic class, overwrite SetMRMLSceneInternal to observe the NodeAddedEvent of the scene:

void vtkSlicerMYMODULEModuleLogic::SetMRMLSceneInternal(vtkMRMLScene * newScene)
  {
  vtkIntArray *events = vtkIntArray::New();
  events->InsertNextValue(vtkMRMLScene::NodeAddedEvent);
  // Optionally you can add here more events
  // you can be interested in such as vtkMRMLScene::NodeRemovedEvent
  this->SetAndObserveMRMLSceneEventsInternal(newScene, events);
  events->Delete();
  }

Via the set and observe mrml scene macro, anytime a node is added into the scene, it will trigger the base Logic class method vtkMRMLAbstractLogic::ProcessMRMLNodesEvents which calls the virtual method vtkMRMLAbstractLogic::OnMRMLSceneNodeAdded(vtkMRMLNode* node) to reimplement in your logic:

void vtkSlicerMYMODULEModuleLogic::OnMRMLSceneNodeAdded(vtkMRMLNode* addedNode)
  {
  vtkMRMLAnnotationFiducialNode* fidNode =
    vtkMRMLAnnotationFiducialNode::SafeDownCast(addedNode);
  if (fidNode)
    {
    // here you write what you need to do when a 
    // fiducial node is added into the scene
    }
  }

Selection and interaction

This section indicates how to change in the GUI the mouse placing mode to start placing nodes.

For the selection and interaction nodes, make sure that you access the singleton nodes already in the scene (rather than making your own) via (caveat: this call works on displayable managers, you may have to go a different route to get at the application logic):

 vtkMRMLApplicationLogic *mrmlAppLogic = this->GetMRMLApplicationLogic();
 vtkMRMLInteractionNode *inode = mrmlAppLogic->GetInteractionNode();
 vtkMRMLSelectionNode *snode = mrmlAppLogic->GetSelectionNode();

If you can't get at the mrml application logic, you can get the nodes from the scene:

 vtkMRMLInteractionNode *interactionNode = vtkMRMLInteractionNode::SafeDownCast(this->GetMRMLScene()->GetNodeByID("vtkMRMLInteractionNodeSingleton"));

You can then call methods on the nodes or add your own event observers as in

 vtkSlicerAnnotationModuleLogic::ObserveMRMLScene

You can see vtkSlicerAnnotationModuleLogic::ProcessMRMLNodesEvents to see how to respond to interaction node changes, but I don't think you'll need to do that.

Slicer4/Base/QTGUI/qSlicerMouseModeToolBar.cxx has a lot of the code you'll need as well, with a slightly different way of getting at the mrml app logic to access the nodes.

The calls you need to make to switch into placing fiducials with the mouse are:

 selectionNode->SetActiveAnnotationID ("vtkMRMLAnnotationFiducialNode");
 interactionNode->SetCurrentInteractionMode(vtkMRMLInteractionNode::Place);

If you don't set PlaceModePersistence on the interaction node, the mouse mode/current interaction mode will automatically go back to view transform after one fiducial has been placed, and you just need to reset the current interaction mode for future placing (the active annotation id is persistent).