Documentation/Labs/SubjectHierarchy

Motivation: convenient central organizing point for many of the operations that 3D Slicer and its extensions perform

• 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 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

Plugins extend abstract plugin class providing broad API offering many customizations. 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 becoma 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

• TODO

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