Difference between revisions of "Modules:DicomToNRRD-3.6"

From Slicer Wiki
Jump to: navigation, search
 
(18 intermediate revisions by 3 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]]
  
−
[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]
 
 
__NOTOC__
 
__NOTOC__
 
===Module Name===
 
===Module Name===
Line 7: Line 6:
  
 
{|
 
{|
−
|[[Image:DWIDicomToNrrdGUI.jpg|thumb|280px|Screenshot of the UI]]
+
|[[Image:DWIDicomToNrrdGUI.png|thumb|280px|Screenshot of the UI]]
 
|}
 
|}
  
Line 36: Line 35:
 
This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.  
 
This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.  
  
−
In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images.
+
In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.
  
 +
====Supported DWI formats====
 +
*Philips scanner/software version combinations:
 +
**Achieva 2.1.3.6
 +
**Achieva 2.5.3.0
 +
**Achieva 2.5.3.3
 +
**Achieva 2.6.1.0
 +
**Acheiva 2.6.3.4
 +
**Intera 2.1.3.6
 +
**Intera 2.6.3.5
 +
*Siemens
 +
**Trio B13
 +
**Trio B15
 +
**Trio B17
 +
**Verio B15V
 +
*GE
 +
**SIGNA HDx14.0
 +
**SIGNA HDxt 15.0
 +
**DVMR 20.0M4
 +
**DVMR 20.1
 +
 +
====Command Line Usage====
 
A command line example for running the module is:
 
A command line example for running the module is:
  
 
  d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr
 
  d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr
 +
 +
The module is currently set to quit and alert the user of gradients whose magnitudes are unreasonably small (greater than 0 and less than the smallGradientThreshold) via the '''smallGradientThreshold''' flag (default value for smallGradientThreshold: 0.2). This flag was created after encountering gradient vectors whose magnitudes were unusually small in Siemens Trio Tim B13 data due to incorrect metadata for diffusion gradient vector coordinate entries in the DICOM header public element tags.
 +
 +
'''For Siemens data:''' In event of incorrect metadata for diffusion gradient vector coordinates in the DICOM header public element tags, please set the '''useBMatrixGradientDirections''' flag. When the useBMatrixGradientDirections flag is set, gradient direction coordinates and b values are derived from the '''bMatrix''' DICOM header private element tag for each gradient. In Siemens DWI data, the b matrix elements are the product of the b value and unit gradient direction vector (column vector) multiplied by the transpose of the unit gradient direction vector. Therefore, for a given gradient direction, the unit gradient direction vector coordinates are the first column of the 3x3 unitary matrix from a singular value decomposition of its b matrix, while the b value is the trace of its b matrix.
  
 
===Quick Tour of Features and Use===
 
===Quick Tour of Features and Use===
  
−
[[Image:DicomToNrrd-IOPanels-3-6.png|thumb|right|280px|Input/Output panels]]
+
[[Image:DicomToNrrdConverter_wiki.png|thumb|right|280px|Input/Output panels]]
−
When this module is run from Slicer UI, simply select the "DICOM Directory", enter the filename in the "Output Image Volume" field (the file name need to end with extension .nhdr), and press "Apply" button.
+
When this module is run from Slicer UI, simply select the directories for '''Input Dicom Data''' and '''Output Directory''', enter the filename (without path name, but '''with''' extension, such as '''mydti.nrrd''') in the '''Output Filename''' field, and press "Apply" button.
  
 
The module can also be run from command line to enable batch process. An example command line look like:
 
The module can also be run from command line to enable batch process. An example command line look like:
Line 77: Line 101:
  
 
<pre>
 
<pre>
−
./DicomToNrrdConverter --help
+
./lib/Slicer3/Plugins/DicomToNrrdConverter --help
  
−
USAGE:
+
USAGE:  
  
−
   d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe
+
   ./lib/Slicer3/Plugins/DicomToNrrdConverter [--returnparameterfile
 +
                                        <std::string>]
 
                                         [--processinformationaddress
 
                                         [--processinformationaddress
 
                                         <std::string>] [--xml] [--echo]
 
                                         <std::string>] [--xml] [--echo]
 
                                         [--useIdentityMeaseurementFrame]
 
                                         [--useIdentityMeaseurementFrame]
 
                                         [--writeProtocolGradientsFile]
 
                                         [--writeProtocolGradientsFile]
−
                                         [--useLPS] [--outputVolume
+
                                         [--outputVolume <std::string>]
−
                                        <std::string>]
+
                                        [--outputDirectory <std::string>]
 
                                         [--inputDicomDirectory
 
                                         [--inputDicomDirectory
 
                                         <std::string>] [--] [--version]
 
                                         <std::string>] [--] [--version]
 
                                         [-h]
 
                                         [-h]
  
−
Where:
+
 
 +
Where:  
 +
 
 +
  --returnparameterfile <std::string>
 +
    Filename in which to write simple return parameters (int, float,
 +
    int-vector, etc.) as opposed to bulk return parameters (image,
 +
    geometry, transform, measurement, table).
  
 
   --processinformationaddress <std::string>
 
   --processinformationaddress <std::string>
Line 104: Line 135:
 
     Echo the command line arguments (default: 0)
 
     Echo the command line arguments (default: 0)
  
−
   --useIdentityMeaseurementFrame (advanced option, use default)
+
   --useBMatrixGradientDirections
 +
    Fill the nhdr header with the gradient directions and bvalues computed
 +
    out of the BMatrix. Only changes behavior for Siemens data. (default:
 +
    0)
 +
 
 +
  --useIdentityMeaseurementFrame
 
     Adjust all the gradients so that the measurement frame is an identity
 
     Adjust all the gradients so that the measurement frame is an identity
 
     matrix. (default: 0)
 
     matrix. (default: 0)
  
−
   --writeProtocolGradientsFile (advanced option, for debug)
+
   --writeProtocolGradientsFile
 
     Write the protocol gradients to a file suffixed by '.txt' as they were
 
     Write the protocol gradients to a file suffixed by '.txt' as they were
 
     specified in the procol by multiplying each diffusion gradient
 
     specified in the procol by multiplying each diffusion gradient
Line 115: Line 151:
 
     debugging of new dicom formats is necessary. (default: 0)
 
     debugging of new dicom formats is necessary. (default: 0)
  
−
   --useLPS (advanced option, use default)
+
   --smallGradientThreshold <double>
−
     For GE data only.  Specifies that the output should be in LPS space
+
    If a gradient magnitude is greater than 0 and less than
−
     like the original DICOM data.  The default is to use Slicer3
+
    smallGradientThreshold, then DicomToNrrdConverter will display an
−
    consistent RAS space. (default: 0)
+
     error message and quit, unless the useBMatrixGradientDirections option
 +
     is set. (default: 0.2)
  
 
   --outputVolume <std::string>
 
   --outputVolume <std::string>
−
     Output Image in NRRD format (.nhdr)
+
     Output filename (.nhdr)
 +
 
 +
  --outputDirectory <std::string>
 +
    Directory holding the output NRRD format
  
 
   --inputDicomDirectory <std::string>
 
   --inputDicomDirectory <std::string>
Line 135: Line 175:
 
     Displays usage information and exits.
 
     Displays usage information and exits.
  
−
   Description: Converts diffusion weighted MR images in dicom series into Nrrd
+
 
−
   format for analysis in Slicer. This program has been tested on only
+
   Description: Converts diffusion weighted MR images in dicom series into
−
   a limited subset of DTI dicom formats available from Siemens, GE,
+
   Nrrd format for analysis in Slicer. This program has been tested on only
−
   and Phillips scanners. Work in progress to support dicom multi-frame
+
   a limited subset of DTI dicom formats available from Siemens, GE, and
−
   data. The program parses dicom header to extract necessary
+
   Phillips scanners. Work in progress to support dicom multi-frame data.
−
   information about measurement frame, diffusion weighting directions,
+
   The program parses dicom header to extract necessary information about
−
  b-values, etc, and write out a nrrd image.  
+
   measurement frame, diffusion weighting directions, b-values, etc, and
 +
  write out a nrrd image. For non-diffusion weighted dicom images, it
 +
  loads in an entire dicom series and writes out a single dicom volume in
 +
  a .nhdr/.raw pair.
  
 
   Author(s): Xiaodong Tao
 
   Author(s): Xiaodong Tao
Line 147: Line 190:
 
   Acknowledgements: This work is part of the National Alliance for Medical
 
   Acknowledgements: This work is part of the National Alliance for Medical
 
   Image Computing (NAMIC), funded by the National Institutes of Health
 
   Image Computing (NAMIC), funded by the National Institutes of Health
−
   through the NIH Roadmap for Medical Research, Grant U54 EB005149.
+
   through the NIH Roadmap for Medical Research, Grant U54 EB005149.  
 
   Additional support for DTI data produced on Philips scanners was
 
   Additional support for DTI data produced on Philips scanners was
 
   contributed by Vincent Magnotta and Hans Johnson at the University of
 
   contributed by Vincent Magnotta and Hans Johnson at the University of
Line 158: Line 201:
  
 
Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.
 
Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.
 +
 +
===References===
 +
 +
More information on Dicom format for diffusion weighted images on [http://www.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI NA-MIC Wiki.]

Latest revision as of 20:27, 14 March 2011

Home < Modules:DicomToNRRD-3.6

Return to Slicer 3.6 Documentation


Module Name

DWI Dicom To NRRD

Screenshot of the UI

General Information

Module Type & Category

Type: Command line module

Category: Converters

Authors, Collaborators & Contact

  • Author: Xiaodong Tao (with contribution from Vince Magnotta and Hans Johnson)
  • Contact: taox @ research.ge.com

Module Description

This module converts diffusion weighted MR images in dicom series into Nrrd format for analysis in Slicer. This program has been tested on only a limited subset of DTI dicom formats available from Siemens, GE, and Phillips scanners. Work in progress to support dicom multi-frame data. The program parses dicom header to extract necessary information about measurement frame, diffusion weighting directions, b-values, etc, and write out a nrrd image.

Usage

Examples, Use cases & Tutorials

This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.

In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.

Supported DWI formats

  • Philips scanner/software version combinations:
    • Achieva 2.1.3.6
    • Achieva 2.5.3.0
    • Achieva 2.5.3.3
    • Achieva 2.6.1.0
    • Acheiva 2.6.3.4
    • Intera 2.1.3.6
    • Intera 2.6.3.5
  • Siemens
    • Trio B13
    • Trio B15
    • Trio B17
    • Verio B15V
  • GE
    • SIGNA HDx14.0
    • SIGNA HDxt 15.0
    • DVMR 20.0M4
    • DVMR 20.1

Command Line Usage

A command line example for running the module is: 

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr

The module is currently set to quit and alert the user of gradients whose magnitudes are unreasonably small (greater than 0 and less than the smallGradientThreshold) via the smallGradientThreshold flag (default value for smallGradientThreshold: 0.2). This flag was created after encountering gradient vectors whose magnitudes were unusually small in Siemens Trio Tim B13 data due to incorrect metadata for diffusion gradient vector coordinate entries in the DICOM header public element tags.

For Siemens data: In event of incorrect metadata for diffusion gradient vector coordinates in the DICOM header public element tags, please set the useBMatrixGradientDirections flag. When the useBMatrixGradientDirections flag is set, gradient direction coordinates and b values are derived from the bMatrix DICOM header private element tag for each gradient. In Siemens DWI data, the b matrix elements are the product of the b value and unit gradient direction vector (column vector) multiplied by the transpose of the unit gradient direction vector. Therefore, for a given gradient direction, the unit gradient direction vector coordinates are the first column of the 3x3 unitary matrix from a singular value decomposition of its b matrix, while the b value is the trace of its b matrix.

Quick Tour of Features and Use

Input/Output panels

When this module is run from Slicer UI, simply select the directories for Input Dicom Data and Output Directory, enter the filename (without path name, but with extension, such as mydti.nrrd) in the Output Filename field, and press "Apply" button.

The module can also be run from command line to enable batch process. An example command line look like: 

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe 
  --inputDicomDirectory MyDicomDir 
  --outputDirectory /scratch/Diffusion
  --outputVolume MyNrrdImage.nrrd

Development

Dependencies

This module depends only on the core "Volumes" module of slice for data IO.

Known Bugs

Usability Issues

Because different vendors used different private tags to store information related to diffusion weighting and documentation on how to interoperate this information is scarce, the current version support diffusion weighted images from GE, Siemens, and Philips scanners. For Siemens, both mosaic and split formats are supported. For Philips, both multi-slice and signal-slice formats are supported.

The current version also support non-diffusion weighted images from any vendors (that GDCM supports), in which case, the module acts as a dicom series to nrrd volume converter.

Source Code and Documentation

Source Code: DicomToNrrdConverter.cxx

XML Description: DicomToNrrdConverter.xml

Test: DicomToNrrdConverterTest.cxx 

./lib/Slicer3/Plugins/DicomToNrrdConverter --help

USAGE: 

   ./lib/Slicer3/Plugins/DicomToNrrdConverter  [--returnparameterfile
                                        <std::string>]
                                        [--processinformationaddress
                                        <std::string>] [--xml] [--echo]
                                        [--useIdentityMeaseurementFrame]
                                        [--writeProtocolGradientsFile]
                                        [--outputVolume <std::string>]
                                        [--outputDirectory <std::string>]
                                        [--inputDicomDirectory
                                        <std::string>] [--] [--version]
                                        [-h]


Where: 

   --returnparameterfile <std::string>
     Filename in which to write simple return parameters (int, float,
     int-vector, etc.) as opposed to bulk return parameters (image,
     geometry, transform, measurement, table).

   --processinformationaddress <std::string>
     Address of a structure to store process information (progress, abort,
     etc.). (default: 0)

   --xml
     Produce xml description of command line arguments (default: 0)

   --echo
     Echo the command line arguments (default: 0)

   --useBMatrixGradientDirections
     Fill the nhdr header with the gradient directions and bvalues computed
     out of the BMatrix. Only changes behavior for Siemens data. (default:
     0)

   --useIdentityMeaseurementFrame
     Adjust all the gradients so that the measurement frame is an identity
     matrix. (default: 0)

   --writeProtocolGradientsFile
     Write the protocol gradients to a file suffixed by '.txt' as they were
     specified in the procol by multiplying each diffusion gradient
     direction by the measurement frame.  This file is for debugging
     purposes only, the format is not fixed, and will likely change as
     debugging of new dicom formats is necessary. (default: 0)

   --smallGradientThreshold <double>
     If a gradient magnitude is greater than 0 and less than
     smallGradientThreshold, then DicomToNrrdConverter will display an
     error message and quit, unless the useBMatrixGradientDirections option
     is set. (default: 0.2)

   --outputVolume <std::string>
     Output filename (.nhdr)

   --outputDirectory <std::string>
     Directory holding the output NRRD format

   --inputDicomDirectory <std::string>
     Directory holding Dicom series

   --,  --ignore_rest
     Ignores the rest of the labeled arguments following this flag.

   --version
     Displays version information and exits.

   -h,  --help
     Displays usage information and exits.


   Description: Converts diffusion weighted MR images in dicom series into
   Nrrd format for analysis in Slicer. This program has been tested on only
   a limited subset of DTI dicom formats available from Siemens, GE, and
   Phillips scanners. Work in progress to support dicom multi-frame data.
   The program parses dicom header to extract necessary information about
   measurement frame, diffusion weighting directions, b-values, etc, and
   write out a nrrd image. For non-diffusion weighted dicom images, it
   loads in an entire dicom series and writes out a single dicom volume in
   a .nhdr/.raw pair.

   Author(s): Xiaodong Tao

   Acknowledgements: This work is part of the National Alliance for Medical
   Image Computing (NAMIC), funded by the National Institutes of Health
   through the NIH Roadmap for Medical Research, Grant U54 EB005149. 
   Additional support for DTI data produced on Philips scanners was
   contributed by Vincent Magnotta and Hans Johnson at the University of
   Iowa.

More Information

Acknowledgement

Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.

References

More information on Dicom format for diffusion weighted images on NA-MIC Wiki.

Retrieved from "https://www.slicer.org/w/index.php?title=Modules:DicomToNRRD-3.6&oldid=19376"