Difference between revisions of "Modules:ChangeTracker-Documentation-3.6"

From Slicer Wiki
Jump to: navigation, search
m (Text replacement - "\[http:\/\/www\.slicer\.org\/slicerWiki\/images\/([^ ]+) ([^]]+)]" to "[http://www.slicer.org/w/img_auth.php/$1 $2]")
 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Documentation-3.6|Return to Slicer 3.6 Documentation]]
 
[[Documentation-3.6|Return to Slicer 3.6 Documentation]]
−
 
−
'''This documentation page is under development'''
 
  
 
__NOTOC__
 
__NOTOC__
Line 46: Line 44:
  
 
===Tutorials===
 
===Tutorials===
 +
 +
[http://www.slicer.org/w/img_auth.php/4/4d/Slicer3.4.1-ChangeTrackerTutorial.pdf Tutorial slides]
 +
{|
 +
|The supplemental data for the tutorial can be loaded automatically (you need to have access to the Internet to do this). Go to the "Help and Acknowledgment" tab, and hit "Load tutorial data" button.
 +
|[[Image:ChangeTracker_tutorial_data.png|thumb|250px|Access to tutorial data is provided within the module]]
 +
|}
  
 
===Quick Tour of Features and Use===
 
===Quick Tour of Features and Use===
Line 55: Line 59:
 
|Use drop-down controls to choose the two scans where you would like to measure pathology development. Currently, we support analysis of the images that correspond to two time points. Extending of the module to accept more than two time points is the feature under development.
 
|Use drop-down controls to choose the two scans where you would like to measure pathology development. Currently, we support analysis of the images that correspond to two time points. Extending of the module to accept more than two time points is the feature under development.
  
−
Note, that ChangeTracker does not "see" transforms located above volume nodes in the MRML hierarchy. If you want any transform in the MRML tree to be used as the initial pose of the image, you will need to create a new volume by resampling the original volume. Slicer3 module [http://www.slicer.org/slicerWiki/index.php/Modules:ResampleVolume2-Documentation-3.4 ResampleVolume2] can be used for this purpose.
+
Note, that ChangeTracker does not "see" transforms located above volume nodes in the MRML hierarchy. If you want any transform in the MRML tree to be used as the initial pose of the image, you will need to create a new volume by resampling the original volume. Slicer3 module [[Modules:ResampleVolume2-Documentation-3.4|ResampleVolume2]] can be used for this purpose.
  
 
|[[Image:ChangeTracker_Step1.png|thumb|250px|Step 1: Scan selection]]
 
|[[Image:ChangeTracker_Step1.png|thumb|250px|Step 1: Scan selection]]
Line 62: Line 66:
 
* '''Step 2: Define volume of interest'''
 
* '''Step 2: Define volume of interest'''
  
−
This step of wizard includes the following user cotrols to facilitate Volume of Interest (VOI) selection:
+
This step of wizard includes the following user controls to facilitate Volume of Interest (VOI) selection:
 
* "Hide/show render" button: used to control visibility of volume rendering for the selected region
 
* "Hide/show render" button: used to control visibility of volume rendering for the selected region
 
* "Reset" button: reset the selected region to start over
 
* "Reset" button: reset the selected region to start over
 
* "ROI Widget Controls: RAS Space" frame: contains sliders to initialize VOI in RAS (physical) space
 
* "ROI Widget Controls: RAS Space" frame: contains sliders to initialize VOI in RAS (physical) space
−
* "ROI Widget Controls: IJK Space" frame: contains sliders to initialize VOI in IJK (voxel) space
 
 
"ROI Widget" refers to the three-dimensional selection box that appears in the 3d slice view once you begin to select VOI.
 
"ROI Widget" refers to the three-dimensional selection box that appears in the 3d slice view once you begin to select VOI.
  
 
You can define VOI using either one or combination of the following methods:
 
You can define VOI using either one or combination of the following methods:
−
* Red/Yellow/Green Slice view bounding box: click left mouse button to define the coordinates of the bounding box that encloses analyzed target in the image. Volume of interest is highlighted in the slice views by semi-transparent blue overlay.
+
* Red/Yellow/Green Slice view bounding box: click left mouse button to define the coordinates of the bounding box that encloses analyzed target in the image. Click right mouse button to re-center the ROI. Volume of interest is highlighted in the slice views by semi-transparent blue overlay.
 
* 3d Slice view: use the ROI Widget controls to resize and/or drag the VOI
 
* 3d Slice view: use the ROI Widget controls to resize and/or drag the VOI
 
* Slider controls: use the slider controls in the wizard frame to resize or move VOI
 
* Slider controls: use the slider controls in the wizard frame to resize or move VOI
 
Note, that the last method is recommended only if you want to enter the VOI parameters you already know. This method is not practical to identify VOI in a new image.
 
Note, that the last method is recommended only if you want to enter the VOI parameters you already know. This method is not practical to identify VOI in a new image.
 +
 +
In the next step, the ROI will be resampled to decrease the effects of partial voluming. The '''Advanced''' tab of Step 2 allows to control how much the ROI will be resampled. Legacy resampling mode will perform resampling as in 3.4. Isotropic resampling mode allows to specify resampling constant (default 0.5, there will be two voxels in the resampled image for each input voxel of ROI)
 +
 
{|
 
{|
 
|[[Image:roi_widget.jpg|thumb|250px|Step 2: ROI Widget in 3D slice view with volume rendering "on"]]
 
|[[Image:roi_widget.jpg|thumb|250px|Step 2: ROI Widget in 3D slice view with volume rendering "on"]]
−
|[[Image:roi_widget_scales.jpg|thumb|250px|Step 2: ROI Widget controls in wizard GUI]]
+
|[[Image:roi_widget_scales_3-6.jpg|thumb|250px|Step 2: ROI Widget controls in wizard GUI]]
 
|[[Image:roi_slice_view.jpg|thumb|250px|Step 2: ROI visualization in slice view]]
 
|[[Image:roi_slice_view.jpg|thumb|250px|Step 2: ROI visualization in slice view]]
 
|}
 
|}
Line 88: Line 94:
 
Note, that currently ChangeTracker expects that the tissue you monitor corresponds to the high part of the image intensity distribution.
 
Note, that currently ChangeTracker expects that the tissue you monitor corresponds to the high part of the image intensity distribution.
  
−
|[[Image:threshold_selection.jpg|thumb|450px|Step 3: ChangeTracker Threshold selection]]
+
In the cases when threshold is not effective in segmenting the structure of interest, '''Advanced''' tab allows to prescribe the segmentation label image directly, instead of using threshold.
 +
 
 +
|[[Image:threshold_selection_3-6.jpg|thumb|450px|Step 3: ChangeTracker Threshold selection]]
 
|}
 
|}
  
Line 95: Line 103:
 
{|
 
{|
 
|We provide two metrics to quantify tumor progression: intensity-based and deformation-based (see details in this [http://www.spl.harvard.edu/pages/Special:PubDB_View?dspaceid=1430 paper]). Choose the metric(s) you would like to use.
 
|We provide two metrics to quantify tumor progression: intensity-based and deformation-based (see details in this [http://www.spl.harvard.edu/pages/Special:PubDB_View?dspaceid=1430 paper]). Choose the metric(s) you would like to use.
−
|[[Image:ChangeTracker_Step4.png|thumb|250px|Step 4: Metric selection]]
+
 
 +
In some cases, the automatic registration functionality in ChangeTracker may not be able to accurately register your data. If this happens, you can use the '''Advanced''' tab to register your data, place Scan2 under the transform, and select "I have a transform that aligns my data" option. If your data is already aligned, choose "Do not align my data".
 +
 
 +
|[[Image:ChangeTracker_Step4_3-6.png|thumb|250px|Step 4: Metric selection]]
 
|}
 
|}
  
Line 137: Line 148:
 
===Dependencies===
 
===Dependencies===
  
−
ChangeTracker depends on the following modules: [http://wiki.slicer.org/slicerWiki/index.php/Modules:Volumes-Documentation-3.6 Volumes], [http://wiki.slicer.org/slicerWiki/index.php/Modules:RigidRegistration-Documentation-3.6 Rigid Registration], [http://wiki.slicer.org/slicerWiki/index.php?title=Modules:DiffeomorphicDemonsAlgorithm-Documentation03.4&action=edit DiffeomorphicDemons]
+
ChangeTracker depends on the following modules: [[Modules:Volumes-Documentation-3.6|Volumes]], [[Modules:RigidRegistration-Documentation-3.6|Rigid Registration]], [http://wiki.slicer.org/slicerWiki/index.php?title=Modules:DiffeomorphicDemonsAlgorithm-Documentation03.4&action=edit DiffeomorphicDemons]
  
 
{|
 
{|
 
|
 
|
−
[http://wiki.slicer.org/slicerWiki/index.php/Modules:Volumes-Documentation-3.6 Volumes] module is required for the general tasks of new volume creation etc. This module should always be available in your Slicer, but can be turned off in the Slicer Application Settings. Make sure it is available.
+
[[Modules:Volumes-Documentation-3.6|Volumes]] module is required for the general tasks of new volume creation etc. This module should always be available in your Slicer, but can be turned off in the Slicer Application Settings. Make sure it is available.
  
 
ChangeTracker is using [http://slicer.spl.harvard.edu/slicerWiki/index.php/Modules:LinearRegistration-Documentation-3.6 Rigid Registration module] through the CommandLineModule shared object invocation. Note, that there are two distinct rigid registration modules in Slicer, which have identical functionality: "Linear registration" and "Rigid registration". Both of these modules should be available in your build, but "Rigid registration" *must* be available for ChangeTracker to function properly. You can verify the availability of the module manually by looking at the list of modules in the registration category.
 
ChangeTracker is using [http://slicer.spl.harvard.edu/slicerWiki/index.php/Modules:LinearRegistration-Documentation-3.6 Rigid Registration module] through the CommandLineModule shared object invocation. Note, that there are two distinct rigid registration modules in Slicer, which have identical functionality: "Linear registration" and "Rigid registration". Both of these modules should be available in your build, but "Rigid registration" *must* be available for ChangeTracker to function properly. You can verify the availability of the module manually by looking at the list of modules in the registration category.
Line 150: Line 161:
 
The following tests verify some of the functionality of the module on the [http://www.cdash.org/CDash/index.php?project=Slicer3 Slicer dashboard].
 
The following tests verify some of the functionality of the module on the [http://www.cdash.org/CDash/index.php?project=Slicer3 Slicer dashboard].
  
−
[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/ChangeTracker/Testing/vtkChangeTrackerGUITest.cxx vtkChangeTrackerGUITest.cxx]
+
[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/ChangeTracker/Testing/vtkChangeTrackerGUITest.cxx vtkChangeTrackerGUITest.cxx]: exercise basic functionality of the GUI classes
 +
 
 +
[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/ChangeTracker/Testing/vtkMRMLChangeTrackerNodeTest.cxx vtkMRMLChangeTrackerNodeTest.cxx]: exercise basic functionality of the MRML node
 +
 
 +
[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/ChangeTracker/Testing/CMakeLists.txt ChangeTrackerCL_Help]: verify correct execution of the command line module without any action
  
−
[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/ChangeTracker/Testing/vtkMRMLChangeTrackerNodeTest.cxx vtkMRMLChangeTrackerNodeTest.cxx]
+
[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/ChangeTracker/Testing/CMakeLists.txt ChangeTrackerCL_TestFull_Intensity]: command line module to exercise some of the functionality in ChangeTracker logic
  
 
===Known bugs===
 
===Known bugs===
Line 165: Line 180:
 
|ChangeTracker is using rigid registration module to automatically align the input images and selected volumes of interest. It is possible, that rigid registration can fail to align your data. If this happens, you will see error message in the pop-up box, as shown to the right.
 
|ChangeTracker is using rigid registration module to automatically align the input images and selected volumes of interest. It is possible, that rigid registration can fail to align your data. If this happens, you will see error message in the pop-up box, as shown to the right.
  
−
You can try to solve this problem by manually registering your data prior to using it with ChangeTracker. You can try to register your data by using the [http://www.slicer.org/slicerWiki/index.php?title=Modules:Rigid-registration-Documentation-3.4 Rigid registration module] and manually adjusting the registration parameters to have satisfactory result of registration. Note, that you will need to select "Create new volume" while running registration, and use that volume together with the fixed image as inputs to ChangeTracker.
+
You can try to solve this problem by manually registering your data prior to using it with ChangeTracker, placing Scan2 under the transform in the MRML hierarchy, and choosing "I have a transform that aligns my data" in the '''Advanced''' tab of Step 4.
−
 
 
−
In the case if Rigid registration module fails to align your data, you can use [http://www.slicer.org/slicerWiki/index.php?title=Modules:Transforms-Documentation-3.4 Transforms module] to perform manual registration of your data.
 
  
 
Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker to report any usability issues. Please select the '''usability issue category''' when browsing or contributing.
 
Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker to report any usability issues. Please select the '''usability issue category''' when browsing or contributing.
Line 179: Line 192:
  
 
[http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/classes.html Documentation] generated by doxygen.
 
[http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/classes.html Documentation] generated by doxygen.
−
 
−
[http://www.slicer.org/slicerWiki/images/4/4d/Slicer3.4.1-ChangeTrackerTutorial.pdf Tutorial slides]
 
  
 
== More Information ==  
 
== More Information ==  

Latest revision as of 12:39, 27 November 2019

Home < Modules:ChangeTracker-Documentation-3.6

Return to Slicer 3.6 Documentation


ChangeTracker

ChangeTracker analysis results
ChangeTracker greetings

General Information

Module Type & Category

Type: Interactive

Category: Wizards

Authors, Collaborators & Contact

  • Andriy Fedorov, SPL
  • Kilian Pohl, IBM Research/SPL
  • Ron Kikinis, SPL
  • Contact: Andriy Fedorov, fedorov at spl dot bwh dot edu

Module Description

ChangeTracker is a software tool for quantification of the subtle changes in pathology. The module provides a workflow pipeline that combines user input with the medical data. As a result we provide quantitative volumetric measurements of growth/shrinkage together with the volume rendering of the tumor and color-coded visualization of the tumor growth/shrinkage.

ChangeTracker is not yet a generic tool for detecting small changes. It has been tuned specifically for meningioma growth analysis. Specifically, the assumptions made by ChangeTracker are

  • the analyzed images are roughly aligned
  • the pathology area is characterized by bright image intensities (contrast-enhanced meningioma MRI)
  • images have similar, close to isotropic, spacing
  • the change in pathology between the consequtive scans is small in relation to the total pathology volume

If you want to apply ChangeTracker on non-meningioma data, please let us know. The algorithm is likely to require tuning of the parameters for registration and other processing steps.

Usage

Use Cases, Examples

  • The module has been designed and tested for measuring meningioma development.
  • Detecting subtle change in pathology tutorial: slides, data

Tutorials

Tutorial slides

The supplemental data for the tutorial can be loaded automatically (you need to have access to the Internet to do this). Go to the "Help and Acknowledgment" tab, and hit "Load tutorial data" button.
Access to tutorial data is provided within the module

Quick Tour of Features and Use

ChangeTracker uses workflow processing of the input data guided by minimal user interaction. There are 4 processing steps.

  • Step 1: Define input scans
Use drop-down controls to choose the two scans where you would like to measure pathology development. Currently, we support analysis of the images that correspond to two time points. Extending of the module to accept more than two time points is the feature under development.

Note, that ChangeTracker does not "see" transforms located above volume nodes in the MRML hierarchy. If you want any transform in the MRML tree to be used as the initial pose of the image, you will need to create a new volume by resampling the original volume. Slicer3 module ResampleVolume2 can be used for this purpose.

Step 1: Scan selection
  • Step 2: Define volume of interest

This step of wizard includes the following user controls to facilitate Volume of Interest (VOI) selection:

  • "Hide/show render" button: used to control visibility of volume rendering for the selected region
  • "Reset" button: reset the selected region to start over
  • "ROI Widget Controls: RAS Space" frame: contains sliders to initialize VOI in RAS (physical) space

"ROI Widget" refers to the three-dimensional selection box that appears in the 3d slice view once you begin to select VOI.

You can define VOI using either one or combination of the following methods:

  • Red/Yellow/Green Slice view bounding box: click left mouse button to define the coordinates of the bounding box that encloses analyzed target in the image. Click right mouse button to re-center the ROI. Volume of interest is highlighted in the slice views by semi-transparent blue overlay.
  • 3d Slice view: use the ROI Widget controls to resize and/or drag the VOI
  • Slider controls: use the slider controls in the wizard frame to resize or move VOI

Note, that the last method is recommended only if you want to enter the VOI parameters you already know. This method is not practical to identify VOI in a new image.

In the next step, the ROI will be resampled to decrease the effects of partial voluming. The Advanced tab of Step 2 allows to control how much the ROI will be resampled. Legacy resampling mode will perform resampling as in 3.4. Isotropic resampling mode allows to specify resampling constant (default 0.5, there will be two voxels in the resampled image for each input voxel of ROI)

Step 2: ROI Widget in 3D slice view with volume rendering "on"
Step 2: ROI Widget controls in wizard GUI
Step 2: ROI visualization in slice view


  • Step 3: Select tumor segmentation threshold
Use threshold control slider to find the intensity that most closely approximates tumor volume. Thresholded volume is rendered interactively in the 3D viewer as you are adjusting the threshold value, and is also visualized as semi-transparent label in the image slice viewers.

Note, that currently ChangeTracker expects that the tissue you monitor corresponds to the high part of the image intensity distribution.

In the cases when threshold is not effective in segmenting the structure of interest, Advanced tab allows to prescribe the segmentation label image directly, instead of using threshold.

Step 3: ChangeTracker Threshold selection
  • Step 4: Define metric
We provide two metrics to quantify tumor progression: intensity-based and deformation-based (see details in this paper). Choose the metric(s) you would like to use.

In some cases, the automatic registration functionality in ChangeTracker may not be able to accurately register your data. If this happens, you can use the Advanced tab to register your data, place Scan2 under the transform, and select "I have a transform that aligns my data" option. If your data is already aligned, choose "Do not align my data".

Step 4: Metric selection
  • Analysis/Results
Results are reported as the change in tumor volume, separately for growth and shrinkage component. The quantitative results are reported in voxels and mm^3. Sensitivity of the analysis can be controlled by choosing Sensitive, Moderate, or Robust analysis approach (Robust being the most conservative). As you change the sensitivity, visualization and quantitative data are updated accordingly. Growth is shown in purple, and shrinkage -- in green color.

The visualization of the analysis results includes the following components upon the completion of analysis:

  • Red slice view: resampled VOI for the second of the analyzed time-points
  • 3d slice viewer: color-coded results of the change analysis. Red color corresponds to the estimated growth regions, Green corresponds to estimated shrinkage.
  • Compare view: first row contains the resampled ROI corresponding to the first time-point as foreground, with the growth analysis results in the background. The second row contains resampled ROI corresponding to the second time-point.

You can choose to display the original sampling grid, and view the coronal slice of the subject using the wizard controls.

ChangeTracker produces a number of new volume images with the temporary and analysis image data, as explained below:

  • <scan1_name>_VOI_Supersampled: scalar image of the volume of interest upsampled to mitigate patial volume effects
  • <scan1_name>_VOI_Segmented: threshold-based mask defining the region of interest in the first scan
  • <scan1_name>_VOI_Thr and <scan2_name>_VOI_Thr: VOIs for the input scans with the intensities below segmentation threshold set to the threshold value
  • <scan2_name>_GlobalReg: scan2 rigidly registered with scan1
  • <scan2_name>_VOI_GlobalReg_Supersampled: VOI in rigidly aligned scan2 after supersampling
  • <scan2_name>_VOI_LocalReg: previous item after rigid registration with the supersampled VOI in scan1
  • <scan2_name>_VOI_Reg_norm: previous item after histogram matching with the supersampled VOI in scan1

The following volumes will be created only when Intensity analysis is requested:

  • ChTracker_Analysis_IntensityInternal: results of growth analysis for internal ChangeTracker use
  • ChTracker_Analysis_IntensityDisplay: label image with the marked growth (red) and shrinkage (green) areas based on Intensity metric

The following volumes will be created only when Deformation analysis is requested:

  • <scan2_name>_VOI_Segmented: estimated segmentation of the region of interest in the second scan
  • ChTracker_Analysis_DeformableMap: label image with the marked growth (red) and shrinkage (green) areas based on Deformation metric
Visualization of the analysis results

Development

Notes from the Developer(s)

Dependencies

ChangeTracker depends on the following modules: Volumes, Rigid Registration, DiffeomorphicDemons

Volumes module is required for the general tasks of new volume creation etc. This module should always be available in your Slicer, but can be turned off in the Slicer Application Settings. Make sure it is available.

ChangeTracker is using Rigid Registration module through the CommandLineModule shared object invocation. Note, that there are two distinct rigid registration modules in Slicer, which have identical functionality: "Linear registration" and "Rigid registration". Both of these modules should be available in your build, but "Rigid registration" *must* be available for ChangeTracker to function properly. You can verify the availability of the module manually by looking at the list of modules in the registration category.

Checking availability of the dependency modules (click to zoom in)

Tests

The following tests verify some of the functionality of the module on the Slicer dashboard.

vtkChangeTrackerGUITest.cxx: exercise basic functionality of the GUI classes

vtkMRMLChangeTrackerNodeTest.cxx: exercise basic functionality of the MRML node

ChangeTrackerCL_Help: verify correct execution of the command line module without any action

ChangeTrackerCL_TestFull_Intensity: command line module to exercise some of the functionality in ChangeTracker logic

Known bugs

This module isn't fully integrated with MRML yet. MRML scene snapshots and restores are not yet supported. Please save your work using the file save dialogs in the user interface.

Follow this link to the Slicer3 bug tracker.

Usability issues

ChangeTracker is using rigid registration module to automatically align the input images and selected volumes of interest. It is possible, that rigid registration can fail to align your data. If this happens, you will see error message in the pop-up box, as shown to the right.

You can try to solve this problem by manually registering your data prior to using it with ChangeTracker, placing Scan2 under the transform in the MRML hierarchy, and choosing "I have a transform that aligns my data" in the Advanced tab of Step 4.

Follow this link to the Slicer3 bug tracker to report any usability issues. Please select the usability issue category when browsing or contributing.

Reported failure of rigid registration

Source code & documentation

Follow this link to the ChangeTracker source code in ViewVC.

Documentation generated by doxygen.

More Information

Acknowledgment

ChangeTracker development has been funded by Brain Science Foundation

References

  • E.Konukoglu, W.M.Wells, S.Novellas, N.Ayache, R.Kikinis, P.M.Black, K.M.Pohl. Monitoring Slowly Evolving Tumors. Proc. of 5th IEEE International Symposium on Biomedical Imaging: From Nano to Macro 2008, pp.812-815 link
Retrieved from "https://www.slicer.org/w/index.php?title=Modules:ChangeTracker-Documentation-3.6&oldid=62541"