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

From Slicer Wiki
Jump to: navigation, search
m
m (Text replacement - "https?:\/\/www.slicer.org\/slicerWiki\/index.php\/([^ ]+) " to "https://www.slicer.org/wiki/$1")
 
(146 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
[[Documentation|Return to Slicer Documentation]]
+
[[Documentation|Return to Slicer Documentation]]
  
−
[[Image:ModelMakerModule.png|thumb|350px|right|The Model Maker Module]]
 
  
−
The Modelmaker is used to create 3D surface models from segmented image data, called label maps. Label maps can be the result of automated segmentation or interactive editing.
+
=Diffusion Editor=
  
−
The model maker is a pipeline of algorithms that start from the input label map, creates a binary label map with just the label(s) of interest set to 1, everything else to 0, generates a marching cubes model, runs triangle reduction and triangle smoothing algorithms. The pipeline was optimized for 1mm brain MRI data. For other geometries, adjustments of the parameters might be necessary.
+
{|
 +
|[[Image:DiffusionEditor helix.jpg|thumb|250px|Diffusion Editor, showing tracts and glyphs on helix example]]
 +
|[[Image:Tracts_glyphs.jpg|thumb|250px|tracts and glyphs view]]
 +
|[[Image:Tracts_glyphs_90degrees.jpg|thumb|250px|tracts and glyphs view - +90° rotation of measurement frame]]
 +
|}
  
−
The model maker is compiled as both a command line executable passed arguments via the command line, and as a binary plug in that communicates through shared memory with Slicer3. The automatically created GUI, found by clickign on the Modules menu, Model Generation category, has the following elements:
+
= General Information =
 +
==Module Type & Category==
  
−
* Input/Output:
+
Type: Interactive
−
**The Input Volume drop down menu is populated with the label map volumes that are present in the scene
+
 
−
**Models are imported into Slicer under a model hierarchy node, and their colors are set by the color table associated with the input label map volume. The model hierarchy node must be created before running the model maker, by selecting ''Create New ModelHierarchy'' from the Models drop down menu.
+
Category: Diffusion Imaging
−
*Create Multiple:
+
 
−
**Any text entered in the ''Model Prefix'' box will be the starting string for the created model's file names. The label number and the color name will also be part of the file name.
+
==Authors, Collaborators & Contact==
−
**If you want to create all models that correspond to all values in a labelmap volume, click the ''Generate All Models'' and ''Joint Smoothing'' boxes
+
* Author: Kerstin Kessel
−
**''Joint Smoothing'' will ensure that all resulting models fit together smoothly, like jigsaw puzzle pieces. Otherwise the models will be smoothed independently and may overlap.
+
* Supervisor: Steve Pieper, Ron Kikinis
−
**If you specify a list of Labels, it will override any start/end label settings. If you click ''Generate All Models'' it will over ride the list of labels and any start/end label settings.  
+
 
−
*Model Maker Parameters:  
+
==Module Description==
−
**You can set the number of smoothing iterations, target reduction in number of polygons (decimal percentage). Use 0 and 1 if you wish no smoothing nor decimation.
+
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.
−
**You can control the type of smoothing done on the models by selecting a ''Filter Type''.
+
 
−
**You can set the flags to split normals or generate point normals in this pane as well.  
+
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.
−
***''Split Normals'' is useful for visualizing sharp features. However it creates holes in surfaces which affects measurements.
+
 
−
***''Point Normals'' is turned on if you wish to calculate the normal vectors for the points.
+
=== Measurement Frame ===
−
**You can save a copy of the models after intermediate steps (marching cubes, smoothing, and decimation if not joint smoothing, otherwise just after decimation); these models are not saved in the mrml file, turn off deleting temporary files first in the tcl window, and then load them manually:  
+
The measurement frame of all DWI is always displayed in the RAS space. That's because Slicer stores all internal coordinates in RAS.
−
  [$::slicer3::CommandLineModuleGUI_Model_Maker GetLogic] DeleteTemporaryFilesOff
+
 
−
*Anatomical Information:
+
If you save changes in a new .nhdr file the measurement frame will always be in RAS.
−
**Here you can specify an external file linking label values with anatomical names.
+
 
−
This was the original method of linking label map values to resultant model colors and names, but it has been superceded by an internal linkage between the input label map volume and it's color node. If you wish to specify a file for a volume node that does not have a color node associated with it. It must be a comma separated file, extension .csv, in the format:
+
=== Used Tensor Estimation ===
−
  anatomyName1,label1
+
The Diffusion Editor uses the Tensor Estimation CLM (Command Line Module) of Slicer to compute tensors.  
−
  anatomyName2,label2
+
* 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.
−
where anatomyName is a string, and label is an integer. If the volume node has a color node associated with it, that will override the anatomy label file.
+
* 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.
−
**You can choose to not generate models from labels that do not have names.
+
 
 +
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.
 +
 
 +
=== Current features of the Diffusion Editor===
 +
For DWI
 +
* Edit gradients manually or load existing gradients from file (.txt or .nhdr).
 +
* Edit the [[Modules:Volumes:Diffusion_Editor-Documentation#Measurement_Frame| measurement frame]] manually or simply rotate/swap/invert columns by selecting them.
 +
* Test the parameters by estimating a tensor and displaying glyphs and tracts.
 +
For DTI
 +
* Edit the measurement frame as described above. 
 +
* Test by displaying glyphs and tracts.
 +
 
 +
= Usage =
 +
 
 +
==Examples & Tutorials==
 +
 
 +
=== Preparation ===
 +
 
 +
* 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.
 +
 
 +
=== Tutorials ===
 +
To start a tutorial video simply click on the link in the table.
 +
{| border="1"
 +
|- bgcolor="#abcdef"
 +
! 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==
 +
 
 +
[[Image:DiffusionEditor_v8.jpg|right|overview]]
 +
 
 +
* '''Measurement frame:'''
 +
 
 +
# The determinant of the measurement frame has to be 1. This is checked by the editor.
 +
# '''Invert''': Select the columns you want to invert.
 +
# '''Swap''': Select two columns you want to swap.
 +
# '''Rotate''': Select one column you want to rotate by an angle you can choose from a given set of values or set yourself.
 +
# '''Identity''': Set the measurement frame to the identity matrix.
 +
# Set your own values.
 +
 
 +
* '''Gradients frame:'''
 +
# If the active volume is a DWI the editor will put the gradients in the text field; otherwise this frame is disabled.
 +
# 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.
 +
 
 +
= Development =
 +
 
 +
== Status / Implementation Progress ==
 +
The editor is now successfully integrated in the Volumes module of the trunk version of Slicer3.
 +
*measurement frame (gui/load/change/save): 100%
 +
*gradients (gui/load/change/save): 100%
 +
*undo/redo/restore mechanism: 100%
 +
*testing frame: 100%
 +
** tensor estimation for DWI with existing clm: 100%
 +
** glyphs view in all three planes with the possibility to change spacing: 100%
 +
** tractography fiducial seeding: 100%
 +
*ctest: 100%
 +
*documentation, tutorials (videos): 100%
 +
*writing master thesis: 60% :-)
 +
 
 +
== Known issues / bugs ==
 +
 
 +
Follow this link to the Slicer3 bug tracker to see known bugs, or to report a new one. Please select the '''usability issue category''' when browsing or contributing:
 +
 
 +
http://na-mic.org/Mantis/main_page.php
 +
 
 +
Queries, feature requests and other feedback should be posted on [https://discourse.slicer.org/ Slicer discourse website]. You can also sign up at the website to make sure you hear of new developments, releases and bug fixes.
 +
 
 +
=== Issues ===
 +
* 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 is available here:
 +
 
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorWidget.cxx
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorWidget.h
 +
 
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorLogic.cxx
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorLogic.h
 +
 
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerMeasurementFrameWidget.cxx
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerMeasurementFrameWidget.h
 +
 
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerGradientsWidget.cxx
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerGradientsWidget.h
 +
 
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionTestingWidget.cxx
 +
http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionTestingWidget.h
 +
 
 +
Links to documentation generated by doxygen:
 +
 
 +
http://www.na-mic.org/Slicer/Documentation/Slicer3/html/
 +
 
 +
= More Information =
 +
 
 +
== Acknowledgement ==
 +
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: [[Image:Thesis_letter.pdf|https://www.slicer.org/wiki/Media:Thesis_letter.pdf]] DTMRI: [[Slicer3:DTMRI|https://www.slicer.org/wiki/Slicer3:DTMRI]] Nrrd format: [http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:Nrrd_format http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:Nrrd_format]
 +
 
 +
DICOM for DWI and DTI : [http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI]

Latest revision as of 14:52, 27 November 2019

Home < Modules:Volumes:Diffusion Editor-Documentation

Return to Slicer Documentation


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
  • Supervisor: Steve Pieper, Ron Kikinis

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.

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.

Current features of the Diffusion Editor

For DWI

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

For DTI

  • Edit the measurement frame as described above.
  • Test by displaying glyphs and tracts.

Usage

Examples & 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.

Tutorials

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

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

Development

Status / Implementation Progress

The editor is now successfully integrated in the Volumes module of the trunk version of Slicer3.

  • measurement frame (gui/load/change/save): 100%
  • gradients (gui/load/change/save): 100%
  • undo/redo/restore mechanism: 100%
  • testing frame: 100%
    • tensor estimation for DWI with existing clm: 100%
    • glyphs view in all three planes with the possibility to change spacing: 100%
    • tractography fiducial seeding: 100%
  • ctest: 100%
  • documentation, tutorials (videos): 100%
  • writing master thesis: 60% :-)

Known issues / bugs

Follow this link to the Slicer3 bug tracker to see known bugs, or to report a new one. Please select the usability issue category when browsing or contributing:

http://na-mic.org/Mantis/main_page.php

Queries, feature requests and other feedback should be posted on Slicer discourse website. You can also sign up at the website to make sure you hear of new developments, releases and bug fixes.

Issues

  • 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

Source code is available here:

http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorWidget.cxx http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorWidget.h

http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorLogic.cxx http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionEditorLogic.h

http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerMeasurementFrameWidget.cxx http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerMeasurementFrameWidget.h

http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerGradientsWidget.cxx http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerGradientsWidget.h

http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionTestingWidget.cxx http://viewvc.slicer.org/viewcvs.cgi/trunk/Modules/Volumes/vtkSlicerDiffusionTestingWidget.h

Links to documentation generated by doxygen:

http://www.na-mic.org/Slicer/Documentation/Slicer3/html/

More Information

Acknowledgement

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: https://www.slicer.org/wiki/Media:Thesis_letter.pdf DTMRI: https://www.slicer.org/wiki/Slicer3:DTMRI Nrrd format: http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:Nrrd_format

DICOM for DWI and DTI : http://wiki.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI

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