Difference between revisions of "Modules:Volumes:Diffusion Editor-Documentation-3.6"

From Slicer Wiki
Jump to: navigation, search
(template)
 
m (Text replacement - "https?:\/\/www.slicer.org\/slicerWiki\/index.php\/([^ ]+) " to "https://www.slicer.org/wiki/$1")
 
(8 intermediate revisions by 2 users not shown)
Line 4: Line 4:
  
 
__NOTOC__
 
__NOTOC__
−
===Module Name===
+
===Module Name ===
−
MyModule
+
Diffusion Editor
  
 
{|
 
{|
−
|[[Image:screenshotBlankNotOptional.png|thumb|280px|User Interface]]
+
|[[Image:DiffusionEditor helix.jpg        |thumb|250px|Diffusion Editor, showing tracts and glyphs on helix example]]
−
|[[Image:screenshotBlank.png|thumb|280px|Output]]
+
|[[Image:Tracts_glyphs.jpg                    |thumb|250px|tracts and glyphs view]]
−
|[[Image:screenshotBlank.png|thumb|280px|Caption]]
+
|[[Image:Tracts_glyphs_90degrees.jpg |thumb|250px|tracts and glyphs view - +90° rotation of measurement frame]]
 
|}
 
|}
  
Line 16: Line 16:
 
===Module Type & Category===
 
===Module Type & Category===
  
−
Type: Interactive or CLI
+
Type: Interactive
  
−
Category: Base or (Filtering, Registration, ''etc.'')
+
Category: Diffusion Imaging
  
 
===Authors, Collaborators & Contact===
 
===Authors, Collaborators & Contact===
−
* Author1: Affiliation & logo, if desired
+
* Author: Kerstin Kessel
−
* Contributor1: Affiliation & logo, if desired
+
* Contributor: Steve Pieper
−
* Contributor2: Affiliation & logo, if desired
+
* Contact: Steve Pieper, pieper at bwh.harvard.edu
−
* Contact: name, email
 
  
 
===Module Description===
 
===Module Description===
−
Overview of what the module does goes here.
+
 
 +
As the documentation of acquisition parameters in dicom data is not standardized, MRI scanners (Siemens, GE) handle gradients/bValues/measurement frame differently in their dicom headers. Because of that there is a big need to add/modify them manually.
 +
 
 +
The Diffusion Editor is a 3D Slicer module, which allows modifying parameters (gradients, bValues, measurement frame) of DWI data and provides a quick way to interpret them. For that it estimates a tensor and shows glyphs and tracts for visual exploration.  
  
 
== Usage ==
 
== Usage ==
Line 35: Line 37:
 
This module is especially appropriate for these use cases:
 
This module is especially appropriate for these use cases:
  
−
* Use Case 1:
+
For DWI
−
* Use Case 2:
+
* Use Case 1: Edit gradients manually or load existing gradients from file (.txt or .nhdr).
 +
* Use Case 2: Edit the [[Modules:Volumes:Diffusion_Editor-Documentation-3.2#Measurement_Frame| measurement frame]] manually or simply rotate/swap/invert columns by selecting them.
 +
* Use Case 3: Test the parameters by estimating a tensor and displaying glyphs and tracts.
 +
For DTI
 +
* Use Case 2: Edit the measurement frame as described above. 
 +
* Use Case 3: Test the parameters by displaying glyphs and tracts.
  
−
Examples of the module in use:
+
===Tutorials===
  
−
* Example 1
+
==== Preparation ====
−
* Example 2
 
  
−
===Tutorials===
+
* Download Slicer. The most recent stable Slicer version can be found [http://www.slicer.org/pages/Downloads here]. Or load Slicer's latest snapshot.
 +
* You can also use SVN to checkout the trunk of the current version of Slicer. See [[Slicer3:Build_Instructions| here]] for more instructions on how to build Slicer.
 +
* Download example data: [[ media:DiffusionEditor_ExampleData.zip | DiffusionEditor_ExampleData.zip ]] and unzip it.
  
−
Links to tutorials explaining how to use this module:
+
To start a tutorial video simply click on the link in the table.
−
 
+
{| border="1"
−
* Tutorial 1
+
|- bgcolor="#abcdef"
−
** Data Set 1
+
! title !!short description
 +
|-
 +
| [[Tutorials:DiffusionEditor-Load DWI-Dicom| Load DICOM]]  ||Load a DWI dicom data set in Slicer.
 +
|-
 +
| [[Tutorials:DiffusionEditor-Edit Gradients | Edit gradients ]]||Change gradients manually and load them from a file. Save your changes afterwards.
 +
|-
 +
| [[Tutorials:DiffusionEditor-Edit Measurement frame| Edit measurement frame]] ||Change the measurement frame by swapping and inverting. Save your changes afterwards.
 +
|-
 +
| [[Tutorials:DiffusionEditor-Testing | Testing ]]||Run tensor estimation and show glyphs and tracts;
 +
Run second estimation with 90°rotation and switch between both tensors and see the impact of that change.
 +
|}
  
 
===Quick Tour of Features and Use===
 
===Quick Tour of Features and Use===
−
 
−
A list panels in the interface, their features, what they mean, and how to use them. For instance:
 
  
 
{|
 
{|
 
|
 
|
−
* '''Input panel:'''
+
* '''Measurement frame:'''
−
** '''First input'''
+
# The determinant of the measurement frame has to be 1. This is checked by the editor.
−
** '''Second input'''
+
# '''Invert''': Select the columns you want to invert.
−
* '''Parameters panel:'''
+
# '''Swap''': Select two columns you want to swap.
−
** '''First parameter'''
+
# '''Rotate''': Select one column you want to rotate by an angle you can choose from a given set of values or set yourself.
−
** '''Second parameter'''
+
# '''Identity''': Set the measurement frame to the identity matrix.
−
* '''Output panel:'''
+
# Set your own values.
−
** '''First output'''
+
 
−
** '''Second output'''
+
* '''Gradients frame:'''
−
* '''Viewing panel:'''
+
# If the active volume is a DWI the editor will put the gradients in the text field; otherwise this frame is disabled.
−
|[[Image:screenshotBlankNotOptional.png|thumb|280px|User Interface]]
+
# You can copy/paste your own gradients in the text field or change them manually.
 +
# You can load gradients from a text file or .nhdr file. For the .txt file the format of gradients is easy, it can contain only values ([[ media:DiffusionEditor_ExampleData.zip | see example data ]]).
 +
 
 +
* '''Undo/Redo/Restore:'''
 +
#'''Undo''': Undo the last change of measurement/gradient values.
 +
#'''Redo''': Redo the last change of measurement/gradient values.
 +
#'''Restore''': All parameters are restored to original.
 +
<font color="Red">NOTE:</font> You lose all previous changes when a new active volume is loaded or selected.
 +
 
 +
* '''Testing frame:'''
 +
# '''Run''' tensor estimation. The new tensor node shows up in the DTI selector.
 +
# Select a DTI node from the current mrml scene and for
 +
## Glyph visibility: Select the planes on which you want to see glyphs and adjust the glyph spacing.
 +
## Tract visibility: Add some fiducials and choose the fiducial list in the selector. Show tracts with Tractography Fiducial Seeding.
 +
 
 +
|[[Image:DiffusionEditor_v8.jpg|thumb|280px|User Interface]]
 
|}
 
|}
  
Line 73: Line 104:
 
===Notes from the Developer(s)===
 
===Notes from the Developer(s)===
  
−
Algorithms used, library classes depended upon, use cases, etc.
+
==== Measurement Frame ====
 +
The measurement frame of all DWI is always displayed in the RAS space. That's because Slicer stores all internal coordinates in RAS.
 +
If you save changes in a new .nhdr file the measurement frame will always be in RAS.
 +
 
 +
==== Used Tensor Estimation ====
 +
The Diffusion Editor uses the Tensor Estimation CLM (Command Line Module) of Slicer to compute tensors.
 +
* The module provides the linear-least-squares, non-linear-least squares and weighted-least-square method for the estimation. But the DiffusionEditor uses the linear-least-squares method by default, as it is the fastest and most robust.
 +
* See [[Slicer3:DTMRI#Tensor_Estimation_from_DWI_Module],|[http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:TeemExamples#tend_estim:_tensor_estimation]] for more information on the Tensor Estimation CLM.
 +
 
 +
The testing frame provides just a small subset of DTI display options. For more detailed settings
 +
* load the DTI as the active volume in the volumes modul
 +
* go to the display frame and adjust parameters.
 +
 
 +
==== Used Tractography Fiducial Seeding ====
 +
The Diffusion Editor uses the Tractography Fiducial Seeding module of Slicer to compute tracts.
 +
* The Diffusion Editor uses the default parameters. To change tractography parameters select the modul: Tractography/Seeding/Fiducial Seeding [[Slicer3:DTMRI#Tractography_Fiducial_Seeding_Module].|Changes there have an immediate impact for the tracts in the Diffusion Editor.
 +
* For more detailed exploring of tracts use the Fiducial Seeding module or for display options select the module Tractography/DisplayLoadSave [https://www.slicer.org/wiki/Slicer3:DTMRI#Tractography_Module]].* See [[Slicer3:DTMRI#Tractography_Module|here]] for more information on the Tractography modules.
  
 
===Dependencies===
 
===Dependencies===
  
−
Other modules or packages that are required for this module's use.
+
No other modules or packages are required for this module's use.
  
 
===Tests===
 
===Tests===
Line 83: Line 130:
 
On the [http://www.cdash.org/CDash/index.php?project=Slicer3 Dashboard], these tests verify that the module is working on various platforms:
 
On the [http://www.cdash.org/CDash/index.php?project=Slicer3 Dashboard], these tests verify that the module is working on various platforms:
  
−
* MyModuleTest1 [http://viewvc.slicer.org/viewcvs.cgi/trunk MyModuleTest1.cxx]
+
*[http://svn.slicer.org/Slicer3/trunk/Modules/Volumes/Testing/DiffusionEditor_GradientsTest.tcl DiffusionEditor_GradientsTest.tcl]
−
* MyModuleTest2 [http://viewvc.slicer.org/viewcvs.cgi/trunk MyModuleTest2.cxx]
+
*[http://svn.slicer.org/Slicer3/trunk/Modules/Volumes/Testing/DiffusionEditorTensorTest.tcl DiffusionEditorTensorTest.tcl]
 +
*[http://svn.slicer.org/Slicer3/trunk/Modules/Volumes/Testing/DiffusionEditorTest.tcl DiffusionEditorTest.tcl]
 +
*[http://svn.slicer.org/Slicer3/trunk/Modules/Volumes/Testing/DiffusionEditor_GradientsTest.tcl DiffusionEditor_GradientsTest.tcl]
  
 
===Known bugs===
 
===Known bugs===
  
−
Links to known bugs in the Slicer3 bug tracker
+
Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker.
−
 
 
−
* [http://www.na-mic.org/Bug/view.php?id=000 Bug 000: description]  
 
−
 
 
  
 
===Usability issues===
 
===Usability issues===
  
 
Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker. 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. Please select the '''usability issue category''' when browsing or contributing.
 +
 +
* Changing the measurement frame of a DTI has no impact. The tensor is not estimated again.
 +
** Future work: Adding new rotation filter for tensors (contributed by Raul San Jose)
 +
* Multiple bValues are not displayed. Currently to describe acquisitions with different b-values the magnitudes of the gradients are changed. See the nrrd format page about [http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:Nrrd_format#Describing_DWIs_with_differen_b-values describing DWIs with different b-values].
 +
** Future work: Adding different views of gradients/bValues.
 +
* Checking gradients when one types new values in the textbox is slowly. Reason: SetDiffusionGradients of the vtkMRMLDiffusionWeightedVolumeNode seems to trigger many events.
 +
** Future work: Use [[Slicer3:EventBroker|Eventbroker]] for performance analysis and if necessary turn off events.
  
 
===Source code & documentation===
 
===Source code & documentation===
Line 102: Line 155:
  
 
Source code:
 
Source code:
−
*[http://viewvc.slicer.org/viewcvs.cgi/trunk file.cxx ]  
+
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorWidget.cxx vtkSlicerDiffusionEditorWidget.cxx]
−
*[http://viewvc.slicer.org/viewcvs.cgi/trunk file.h ]
+
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorWidget.h vtkSlicerDiffusionEditorWidget.h]
 +
 
 +
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorLogic.cxx vtkSlicerDiffusionEditorLogic.cxx]
 +
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorLogic.h vtkSlicerDiffusionEditorLogic.h]
 +
 
 +
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerMeasurementFrameWidget.cxx vtkSlicerMeasurementFrameWidget.cxx]
 +
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerMeasurementFrameWidget.h vtkSlicerMeasurementFrameWidget.h]
 +
 
 +
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerGradientsWidget.cxx vtkSlicerGradientsWidget.cxx]
 +
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerGradientsWidget.h vtkSlicerGradientsWidget.h]
 +
 
 +
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionTestingWidget.cxx vtkSlicerDiffusionTestingWidget.cxx]
 +
*[http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionTestingWidget.h vtkSlicerDiffusionTestingWidget.h]
 
   
 
   
 
Doxygen documentation:
 
Doxygen documentation:
−
*[http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/classes.html class1]
+
*[http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/classvtkSlicerDiffusionEditorWidget.html SlicerDiffusionEditorWidget]
 +
*[http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/classvtkSlicerDiffusionEditorLogic.html DiffusionEditorLogic]
 +
*[http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/classvtkSlicerGradientsWidget.html GradientsWidget]
 +
*[http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/classvtkSlicerDiffusionTestingWidget.html DiffusionTestingWidget]
  
 
== More Information ==  
 
== More Information ==  
  
 
===Acknowledgment===
 
===Acknowledgment===
−
Include funding and other support here.
+
This research project was part of a Master thesis (Diplomarbeit) in cooperation of the faculty of Medical Informatics, University of Heidelberg/Germany and the Surgical Planning Lab. It was supported by a grant of the Lions Club Heilbronn/Franken.
  
 
===References===
 
===References===
−
Publications related to this module go here. Links to pdfs would be useful.
+
[[Image:Thesis_letter.pdf|Thesis]]
 +
 
 +
[[Slicer3:DTMRI|DTMRI]]
 +
 
 +
[http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:Nrrd_format Nrrd format]
 +
 
 +
[http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI DICOM for DWI and DTI]

Latest revision as of 14:52, 27 November 2019

Home < Modules:Volumes:Diffusion Editor-Documentation-3.6

Return to Slicer 3.6 Documentation

Gallery of New Features


Module Name

Diffusion Editor

Diffusion Editor, showing tracts and glyphs on helix example
tracts and glyphs view
tracts and glyphs view - +90° rotation of measurement frame

General Information

Module Type & Category

Type: Interactive

Category: Diffusion Imaging

Authors, Collaborators & Contact

  • Author: Kerstin Kessel
  • Contributor: Steve Pieper
  • Contact: Steve Pieper, pieper at bwh.harvard.edu

Module Description

As the documentation of acquisition parameters in dicom data is not standardized, MRI scanners (Siemens, GE) handle gradients/bValues/measurement frame differently in their dicom headers. Because of that there is a big need to add/modify them manually.

The Diffusion Editor is a 3D Slicer module, which allows modifying parameters (gradients, bValues, measurement frame) of DWI data and provides a quick way to interpret them. For that it estimates a tensor and shows glyphs and tracts for visual exploration.

Usage

Use Cases, Examples

This module is especially appropriate for these use cases:

For DWI

  • Use Case 1: Edit gradients manually or load existing gradients from file (.txt or .nhdr).
  • Use Case 2: Edit the measurement frame manually or simply rotate/swap/invert columns by selecting them.
  • Use Case 3: Test the parameters by estimating a tensor and displaying glyphs and tracts.

For DTI

  • Use Case 2: Edit the measurement frame as described above.
  • Use Case 3: Test the parameters by displaying glyphs and tracts.

Tutorials

Preparation

  • Download Slicer. The most recent stable Slicer version can be found here. Or load Slicer's latest snapshot.
  • You can also use SVN to checkout the trunk of the current version of Slicer. See here for more instructions on how to build Slicer.
  • Download example data: DiffusionEditor_ExampleData.zip and unzip it.

To start a tutorial video simply click on the link in the table.

title short description
Load DICOM Load a DWI dicom data set in Slicer.
Edit gradients Change gradients manually and load them from a file. Save your changes afterwards.
Edit measurement frame Change the measurement frame by swapping and inverting. Save your changes afterwards.
Testing Run tensor estimation and show glyphs and tracts;

Run second estimation with 90°rotation and switch between both tensors and see the impact of that change.

Quick Tour of Features and Use

  • Measurement frame:
  1. The determinant of the measurement frame has to be 1. This is checked by the editor.
  2. Invert: Select the columns you want to invert.
  3. Swap: Select two columns you want to swap.
  4. Rotate: Select one column you want to rotate by an angle you can choose from a given set of values or set yourself.
  5. Identity: Set the measurement frame to the identity matrix.
  6. Set your own values.
  • Gradients frame:
  1. If the active volume is a DWI the editor will put the gradients in the text field; otherwise this frame is disabled.
  2. You can copy/paste your own gradients in the text field or change them manually.
  3. You can load gradients from a text file or .nhdr file. For the .txt file the format of gradients is easy, it can contain only values ( see example data ).
  • Undo/Redo/Restore:
  1. Undo: Undo the last change of measurement/gradient values.
  2. Redo: Redo the last change of measurement/gradient values.
  3. Restore: All parameters are restored to original.

NOTE: You lose all previous changes when a new active volume is loaded or selected.

  • Testing frame:
  1. Run tensor estimation. The new tensor node shows up in the DTI selector.
  2. Select a DTI node from the current mrml scene and for
    1. Glyph visibility: Select the planes on which you want to see glyphs and adjust the glyph spacing.
    2. Tract visibility: Add some fiducials and choose the fiducial list in the selector. Show tracts with Tractography Fiducial Seeding.
User Interface

Development

Notes from the Developer(s)

Measurement Frame

The measurement frame of all DWI is always displayed in the RAS space. That's because Slicer stores all internal coordinates in RAS. If you save changes in a new .nhdr file the measurement frame will always be in RAS.

Used Tensor Estimation

The Diffusion Editor uses the Tensor Estimation CLM (Command Line Module) of Slicer to compute tensors.

  • The module provides the linear-least-squares, non-linear-least squares and weighted-least-square method for the estimation. But the DiffusionEditor uses the linear-least-squares method by default, as it is the fastest and most robust.
  • See [[Slicer3:DTMRI#Tensor_Estimation_from_DWI_Module],|[1]] for more information on the Tensor Estimation CLM.

The testing frame provides just a small subset of DTI display options. For more detailed settings

  • load the DTI as the active volume in the volumes modul
  • go to the display frame and adjust parameters.

Used Tractography Fiducial Seeding

The Diffusion Editor uses the Tractography Fiducial Seeding module of Slicer to compute tracts.

  • The Diffusion Editor uses the default parameters. To change tractography parameters select the modul: Tractography/Seeding/Fiducial Seeding [[Slicer3:DTMRI#Tractography_Fiducial_Seeding_Module].|Changes there have an immediate impact for the tracts in the Diffusion Editor.
  • For more detailed exploring of tracts use the Fiducial Seeding module or for display options select the module Tractography/DisplayLoadSave [2]].* See here for more information on the Tractography modules.

Dependencies

No other modules or packages are required for this module's use.

Tests

On the Dashboard, these tests verify that the module is working on various platforms:

Known bugs

Follow this link to the Slicer3 bug tracker.

Usability issues

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

  • Changing the measurement frame of a DTI has no impact. The tensor is not estimated again.
    • Future work: Adding new rotation filter for tensors (contributed by Raul San Jose)
  • Multiple bValues are not displayed. Currently to describe acquisitions with different b-values the magnitudes of the gradients are changed. See the nrrd format page about describing DWIs with different b-values.
    • Future work: Adding different views of gradients/bValues.
  • Checking gradients when one types new values in the textbox is slowly. Reason: SetDiffusionGradients of the vtkMRMLDiffusionWeightedVolumeNode seems to trigger many events.
    • Future work: Use Eventbroker for performance analysis and if necessary turn off events.

Source code & documentation

Links to the module's source code:

Source code:

Doxygen documentation:

More Information

Acknowledgment

This research project was part of a Master thesis (Diplomarbeit) in cooperation of the faculty of Medical Informatics, University of Heidelberg/Germany and the Surgical Planning Lab. It was supported by a grant of the Lions Club Heilbronn/Franken.

References

Thesis

DTMRI

Nrrd format

DICOM for DWI and DTI

Retrieved from "https://www.slicer.org/w/index.php?title=Modules:Volumes:Diffusion_Editor-Documentation-3.6&oldid=62672"