Documentation/Labs/SubjectHierarchy

Motivation

• Slicer has a great number of modules that the user has to be able to juggle. This leads to confusion for many users.
• Data module allows exploring the loaded data, but
  • It presents the nodes in a flat list that is hard to manage
  • Offers multiple modes (transforms, displayable), but it makes it more confusing
  • The user has to find the modules needed to operate on the data, so this module cannot act as a "home" module
• Subject hierarchy aspires to be a convenient central organizing point for data loaded into Slicer and many of the operations that Slicer and its extensions perform

Subject hierarchy features

• Convenient central organizing point where users start their workflows: "home" module
  • Nice and intuitive way of organizing and handling data in a tree view that allows easy identification of the data through icons
• Bring basic features in a data-centered tree view, such as
  • Show/hide of any data
  • Transform object or branch
  • Edit properties. Same idea as in Data module, takes the user to the module handling that specific type. The difference is that in subject hierarchy it is possible to do further steps, such as populating the module with inputs, or set suitable parameters automatically.
  • Expand tree to certain level
  • Dynamic help box populated by the plugins
  • Rename, remove, reparent
• Provides a multitude of features through the plugin mechanism

Subject hierarchy plugin mechanism

The Plugins extend abstract plugin class providing broad API offering many customizations. These plugins are the building blocks that make subject hierarchy a really useful central organizing point.

Plugin types

• Role plugins: each node in the tree is "owned" by a certain plugin
  • A plugin is automatically assigned to added nodes by collecting confidence values for the new node from all registered plugins and assigning the one returning the highest confidence value
  • When a subject hierarchy node is modified, a plugin search is automatically performed unless disabled
  • Role-related features
    • Role icon, visibility icon
    • Displayed name, tooltip
    • Show/hide
    • Edit properties
    • Add note to subject hierarchy / reparent inside subject hierarchy
  • Plugins can define levels (e.g. Series, Subseries by DICOM plugin), and parent-children level pairs for child creation actions
• Function plugins: not offering roles but functions, cannot own nodes
  • Returned confidence value is always 0
  • Provides context menu actions (for nodes or the scene) based on rules defined in the plugin

List of implemented plugins

• Core plugins
  • Default: fallback role plugin if no registered plugin can own a node; Provides create subject and study actions
  • Clone node: Make a copy of a node
  • Parse local data: Adds a scene context menu action that re-creates the directory structure of data loaded from local storage
  • DICOM: provides study, series, and sub-series roles, levels, and parent-children pairs
  • Register: Allows user to select two volumes to register, then offers registration methods. When the user chooses one, that module will become active and the inputs and basic parameters are set
  • Volumes: adds Volume role, differentiates labelmaps by a separate icon, provides show volume icon and action, adds "show volumes in study" context menu action
  • Models: role
  • Markups: role
  • Charts: provides Chart role. Layout is changed to quantitative when shown
• RT plugins (to illustrate further possibilities)
  • Contours + ContourSets (will be integrated into core soon): Provides roles for contours and contour sets. Allows creation of contour nodes from labelmaps or models. Handles associated color table when adding/reparenting. Provides show/hide
  • RT image: special type of volume that has a different icon, and is displayed as a textured plane in the 3D view
  • DVH: role for double array nodes having a specific attribute. Allows show/hide plot in chart
  • Gamma: Output of gamma dose comparison, automatically created and added to hierarchy by the DoseComparison module
  • ...

Code branch on github

https://github.com/cpinter/Slicer/tree/subject-hierarchy-integration

For code examples, see C++ and python tests

Slicer core changes

• SubjectHierarchy module added in Modules/Loadables
• Subject hierarchy plugins added in Markups, Models, and Volumes
  • Plugins for other modules have to be put in the <module>/SubjectHierarchyPlugins folder
• qMRMLNodeAttributeTableView and qMRMLNodeAttributeTableWidget moved from Data module widgets to MRMLWidgets, because they are now used both in Data and Subject hierarchy modules
• addSeriesInSubjectHierarchy function added to abstract DICOMPlugin class.
  DICOM plugins should call this in their load() function with the loadable and the loaded node to add it to subject hierarchy as a series. It creates subject (patient) and study nodes based on the DICOM tags
  • Subject hierarchy support added in DICOMScalarVolumePlugin.py: temporary conditional call of a function injected from SlicerRT replaced with the actual function
  • Also added to DICOMDiffusionVolumePlugin
• vtkMRMLHierarchyNode::GetAssociatedChildrendNodes renamed to GetAssociatedChildrenNodes and made virtual.
  This change could break extensions if this is used in them, although there was only one usage in the whole Slicer source tree
• vtkMRMLHierarchyNode::GetAssociatedNode made virtual (overridden in vtkMRMLSubjectHierarchyNode to support nested associations)
• Export MRMLCLI_INCLUDE_DIRS CMake variable in SlicerConfig.cmake for subject hierarchy plugins in extensions
• Added two subject hierarchy python self tests in Applications/SlicerApp/Testing

Future features

• DICOM export. A simple control starting the export process, which opens a window with the tree and a DICOM tag editor on the bottom
• Set/change level manually
• AddNode and Reparent should make sure the invalid drag&drop operations are not allowed
• Allow re-ordering nodes in the tree
• Add a "reference inspector" widget where these references can be explored and edited (it can be part of the current MRML Node Inspector widget or a separate one)
• Improve visibility controls - multiple 3D and 2D views, volume rendering, etc.
• Select and drag&drop multiple nodes from the potential list
• Create subject hierarchy based node selector that replaces qMRMLNodeComboBox. Provides a small window with a simple tree view showing only the nodes of the requested type (and attributes)

Issues

• Not all data is automatically added to subject hierarchy
  • DICOM data is covered
  • Data loaded from local storage can be added to the hierarchy, but the user has to know about the feature
  • The user can drag&drop supported nodes in the hierarchy, but currently only one can be moved at a time
  • Outputs of analysis and processing modules have to be added manually, unless it supports subject hierarchy