NAMIC Wiki - User contributions [en]

NAMIC Wiki:DTI:TeemExamples

2011-02-18T16:28:31Z

Kindlmann:

The goal of this page is to accumulate helpful usage examples of [[TeemSummary|Teem software]] used on DWI and DTI data. Teem is now shipping as a component of Slicer 2.6, and can be built via CMake. Compiling Teem results in a number of libraries, as well as a set of command-line tools. The two most useful of these are:

* <tt>unu</tt><nowiki>: for general manipulation of raster data </nowiki>
* <tt>tend</tt><nowiki>: for handling of DWI and DTI data specifically </nowiki>

For both of these tools, you can get a list of available commands just by typing "unu" or "tend", and then get usage info for each command by running the command with no extra options (e.g. "unu slice").

The examples below use the first of the [[NAMIC-Dartmouth-DWI|Dartmouth DWI datasets ]], <tt>01-dwi.nhdr</tt>, as a running example of the processing possible.

== unu minmax: Basic syntax checking ==

unu minmax 01-dwi.nhdr

This will read in the entire volume and print out the range of values:

min: 0
max: 14618

The purpose of this is not to learn the range of values so much as it is to verify that the nrrd software reader can read in the header (and detached data files, if any) without any errors. If there are problems in the NRRD format itself (not the key/value pair DWI convention), you will see them here.

== unu slice, crop, tile: Looking at DWIs on one slice ==

<div class="thumb tright"><div style="width: 182px">[[Image:01-dwi-z20.png|[[Image:180px-01-dwi-z20.png|01-dwi-z20.png]]]]<div class="thumbcaption"><div class="magnify" style="float: right">[[Image:01-dwi-z20.png|[[Image:magnify-clip.png|Enlarge]]]]</div>01-dwi-z20.png</div></div></div>

unu slice -i 01-dwi.nhdr -a 2 -p 20 \
| unu crop -min 0 0 2 -max M M M \
| unu tile -a 2 0 1 -s 4 3 \
| unu quantize -b 8 -o 01-dwi-z20.png

This slices along axis 2 (the IS image coordinate) at index 20, crops out the non-DWI baseline images, tiles the 12 DWIs into a 4-by-3 array, quantizes to 8 bits, and save out to a PNG image:

This allows one to verify that axis ordering is right- if the "<tt>sizes</tt>" field was wrong you would not see coherent images, or they would not show the same anatomical slice shown here.

== unu project, tile: Looking at eddy-current distortion ==

<div class="thumb tright"><div style="width: 182px">[[Image:01-dwi-stdv.png|[[Image:180px-01-dwi-stdv.png|Description]]]]<div class="thumbcaption"><div class="magnify" style="float: right">[[Image:01-dwi-stdv.png|[[Image:magnify-clip.png|Enlarge]]]]</div>Description</div></div></div>

unu crop -i 01-dwi.nhdr -min 0 0 0 2 -max M M M M \
| unu project -a 3 -m stdv \
| unu tile -a 2 0 1 -s 9 4 \
| unu quantize -b 8 -min 0 -max 300 -o 01-dwi-stdv.png

This crops out the B0 images, projects along the DWI images by measuring the standard deviation of the DWI values, tiles to a 9-by-4 image, quantizes and saves to PNG.

The fact that there is a lot of brightness above and below the brain is the sign of mis-registration: variance among the DWI implies anisotropy, and there should not be major anisotropy on the cortical surface.

== tend epireg: fixing eddy-current distortion ==

<div class="thumb tright"><div style="width: 182px">[[Image:01-dwireg-stdv.png|[[Image:180px-01-dwireg-stdv.png|DWI registration reduces ghost anisotropy]]]]<div class="thumbcaption"><div class="magnify" style="float: right">[[Image:01-dwireg-stdv.png|[[Image:magnify-clip.png|Enlarge]]]]</div>DWI registration reduces ghost anisotropy</div></div></div>

setenv NRRD_STATE_KEYVALUEPAIRS_PROPAGATE

tend epireg -i 01-dwi.nhdr -g kvp -f 0.65 -o 01-dwireg.nhdr

unu crop -i 01-dwireg.nhdr -min 0 0 0 2 -max M M M M \
| unu project -a 3 -m stdv \
| unu tile -a 2 0 1 -s 9 4 \
| unu quantize -b 8 -min 0 -max 300 -o 01-dwireg-stdv.png

This runs a http://www.sci.utah.edu/%7Egk/ismrm04/ on the DWIs, which models the shear/scale/translate distortion along the phase-encode direction as a linear function of the difffusion-sensitizing gradient that is creating the eddy currents that lead to imaging distortion. Then a new DWI stdv image is created like the first. The need to set the <tt>NRRD_STATE_KEYVALUEPAIRS_PROPAGATE</tt> environment variable is currently a bug, this will be fixed soon.

Like any registration method, the results can be improved by tuning the various parameter settings (type "<tt>tend epireg</tt>" for all the details); these are just the results from using mainly the defaults.

== tend estim: tensor estimation ==

tend estim -i 01-dwireg.nhdr -B kvp -knownB0 true -o 01-ten.nhdr

By default, this uses linear-least-squares fitting on the log(DWI) to estimate the tensor from the DWIs, with learning all the DWI-specific information from the key/value pairs in the NRRD header ("<tt>-B kvp</tt>"). The API used by this code (in the "ten" library of Teem) also includes methods for non-linear-least squares and weighted-least-squares, but these are not stable and reliable enough to be advertised at this point.

The way diffusion tensors are represented in NRRD is with 7 values: a mask or confidence value, and then the 6 unique diffusion tensor components. The mask value is determined by a soft-thresholding of an Otsu classification of all the DWI values. This has the effect of masking out the air (because the original T2 is dark), as well as the CSF (its high diffusivity means that it loses all signal with diffusion-weighting).

== tend anvol, evecrgb: slice-based data inspection ==

<div class="thumb tright"><div style="width: 182px">[[Image:01-fa.png|[[Image:180px-01-fa.png|FA volume]]]]<div class="thumbcaption"><div class="magnify" style="float: right">[[Image:01-fa.png|[[Image:magnify-clip.png|Enlarge]]]]</div>FA volume</div></div></div><div class="thumb tright"><div style="width: 182px">[[Image:01-rgb.png|[[Image:180px-01-rgb.png|RGB(evec0) volume]]]]<div class="thumbcaption"><div class="magnify" style="float: right">[[Image:01-rgb.png|[[Image:magnify-clip.png|Enlarge]]]]</div>RGB(evec0) volume</div></div></div>

tend anvol -i 01-ten.nhdr -a fa \
| unu tile -a 2 0 1 -s 9 4 \
| unu quantize -b 8 -min 0 -max 1 -o 01-fa.png
tend unmf -i 01-ten.nhdr \
| tend evecrgb -a cl2 -c 0 \
| unu tile -a 3 1 2 -s 9 4 \
| unu quantize -b 8 -min 0 -max 1 -o 01-rgb.png

The first command creates a volume of FA (fractional anisotropy) measurements everywhere in the volume, then tiles it into an image. Many other anisotropy measures are supported; typing "<tt>tend anvol</tt>" shows the usage info which lists these:

tend anvol: Apply an anisotropy metric to a DT volume. The anisotropy value
will be zero in the locations which don't meet the given confidence threshold.

Usage: tend anvol -a <aniso> [-t <thresh>] [-i <nin>] [-o <nout>]

-a <aniso> = Which anisotropy metric to plot. All the Westin metrics come in
two versions. Currently supported:
o "cl1", "cl2": Westin's linear
o "cp1", "cp2": Westin's planar
o "ca1", "ca2": Westin's linear + planar
o "cs1", "cs2": Westin's spherical (1-ca)
o "ct1", "ct2": GK's anisotropy type (cp/ca)
o "ra": Basser/Pierpaoli relative anisotropy/sqrt(2)
o "fa": Basser/Pierpaoli fractional anisotropy
o "vf": volume fraction = 1-(Basser/Pierpaoli volume ratio)
o "tr": trace
-t <thresh> = confidence threshold (float); default: "0.5"
-i <nin> = input diffusion tensor volume; default: "-"
-o <nout> = output image (floating point) (string); default: "-"

== tend unmf: applying/removing the measurement frame ==

tend unmf -i 01-ten.nhdr -o 01-ten-nomf.nhdr

For software that does not know what a measurement frame is, you can use this to apply the measurement frame transform to all the tensor values, so that the coefficients of the tensor are expressed in the same coordinate system as the image orientation.

Note that "<tt>tend unmf</tt>" was used to make the RGB image above so that the corpus was red instead of green.

AHM2010:NA-MIC Kit Update

2010-01-04T15:36:23Z

Kindlmann: /* Teem */

Back to [[AHM_2010#Agenda|AHM 2010]]
==Goals==
Information about NA-MIC Kit component developments over the past year so that developers will have an idea of what new features are available for their use.

=== ITK ===

* [http://www.itk.org/Wiki/ITK_10th_Anniversary_Activities ITK turned 10 years old!]
* Slicer currently uses [http://www.kitware.com/news/home/browse/ITK?2009_09_16&ITK+3.16+Released ITK 3.16]
* [http://www.insight-journal.org/browse/publication/149 Label image classes], [http://hdl.handle.net/1926/584 Label map classes], Label map morphology
* [http://hdl.handle.net/10380/3055 Region based Level Sets]
* Improvements in Streaming large images
* QuadEdgeMesh spherical registration
** Rigid (in NAMIC Sandbox)
** Deformable (Diffeomorphic Demons) (in NAMIC Sandbox)
** Improvements in the QuadEdgeMesh filter class (in ITK to support the two above).
* Pixel coordinates consistency
* Multi-threaded registration framework (fixes)
** multi-threaded metrics
** thread-safe transforms
* Hessian-based shape descriptors
* Fractal dimensions
* [http://hdl.handle.net/1926/585 FFT based image reconstruction]

=== VTK ===
* VTK 5.4 released
* vtkWidgets
* [http://www.vtk.org/Wiki/VTK/ARB VTK ARB] formed
* [http://vtk.uservoice.com/pages/31508-general User Voice] added to gather community feedback
* [http://www.midasjournal.org/?journal=35 VTK Journal]
* [http://www.vtkedge.org/ VTK Edge] will be consolidated into VTK
* In progress:
** [http://blog.cryos.net/archives/236-VTK-New-2D-API,-Canvas-and-Charting-Features.html VTK 2D Charting]
** Informatics
** Examples makeover
** git mirror of VTK

=== Teem ===
* [http://teem.sf.net Teem] 1.11 Soon to be Released
** release branch being used in slicer3 nightly builds
** Many improvements and new features described in the [http://sourceforge.net/mailarchive/forum.php?thread_name=9FE12D1D-D52B-40F6-B793-D8AA9D2124CB%40uchicago.edu&forum_name=teem-users Teem 1.11 Change Log Message]
* Python wrappers (auto-generated by ctypeslib) now included in teem/python/ctypes; used previously for [[Two-tensor tractography in Slicer using Python and Teem]]
* The tenGage kind (for doing convolution-based measurements in tensor fields) now includes direct computation of the fiber curving (tenGageFiberCurving) and fiber dispersion (tenGageFiberDispersion) indices used in [[2009_Summer_Project_Week_Slicer3_Fibre_Dispersion|Slicer module for the computation of fibre dispersion and curving measures]] (Peter Savadjiev BWH)
* New [http://people.cs.uchicago.edu/~glk/ssp/ scale space partices] functionality, with applications to lung airway segmentation and white matter skeletonization from DTI
* New applications of scale-space particles for COPD with Raul San Jose (see http://www.airwayinspector.org/)
* New functionality from Thomas Schultz to implement fast crease surface extraction (see his recent TVCG paper [[http://www.ci.uchicago.edu/~schultz/papers/schultz-crease-2008.pdf]])

=== XNAT ===

* [http://groups.google.com/group/xnat_discussion/browse_thread/thread/f46581afed629a5c XNAT 1.4 RC3] available
** More robust QC modeling via xnat:qcManualAssessorData.
** New 'columns' variable for REST based listings.
** LDAP support.
** Improved memory footprint and efficiency.
** Refactored Search UI in the listing engine.
* [http://code.google.com/p/xnatfs/ xnatfs] provides WebDav access to XNAT instances

=== GWE ===

* Interactive experiments' results browser.
* CSV and generated commands dumps and preview.
* Support for LSF and Lava cluster DRMs.
* Ability to override auto-discovered DRMs with configured ones.
* Ability to override default database installation location.
* Function to extract experiments' parameters from text files.
* Operations to delete, pause and resume experiments.
* Recommended to watch: [http://www.youtube.com/watch?v=yXdRks5Wu5Q 5 minutes demo video].

=== BatchMake ===
* Improvement in the integration of grid computing using condor.
* Semi-Automatic conversion of Slicer modules for batch processing
* Parameter exploration is now possible
* Execution of algorithms are faster

=== CMake/CPack/CTest/CDash ===
* parallel ctest (ctest -j)
* cpack
* conversion to cmake in-progress
* linkage between CTest and MIDAS in progress
** Host large datasets for algorithm validation and performance testing
*** Demonstrated using RegisterImages

=== 3D Slicer ===
* List of new modules and features (TBD)
** See here for a list of [http://wiki.slicer.org/slicerWiki/index.php/Documentation-3.5#List_of_Modules_new_to_3.5 modules new to 3.5].
* 3.4/3.4.1 release information
* Extension Architecture and Extension Modules
* ARRA Supplement Projects
* Qt Port (lead in to Julien's 8:30 session)
** Co-existence of KWWidgets and Qt
** Creation of a subset of the needed Qt widgets
** Full port in Qt of first modules
** Design of the core architecture in Qt (plugin mechanism, Command line modules, widget libraries...)
** Tutorials for the slicer developer community to port modules
** [http://wiki.slicer.org/slicerWiki/index.php/Slicer3:Developers:Projects:QtSlicer/Gallery Gallery] and [http://wiki.slicer.org/slicerWiki/index.php/Slicer3:Developers:Projects:QtSlicer/Tutorials Tutorials]
* More info on the [http://www.slicer.org/slicerWiki/index.php/Main_Page#News Slicer wiki News Page]
* multi-camera view in Slicer (endoscopy application)

=== Other Topics ===

* [http://Commontk.org Common Toolkit]

AHM2010:NA-MIC Kit Update

2010-01-04T15:36:04Z

Kindlmann: /* Teem */

Back to [[AHM_2010#Agenda|AHM 2010]]
==Goals==
Information about NA-MIC Kit component developments over the past year so that developers will have an idea of what new features are available for their use.

=== ITK ===

* [http://www.itk.org/Wiki/ITK_10th_Anniversary_Activities ITK turned 10 years old!]
* Slicer currently uses [http://www.kitware.com/news/home/browse/ITK?2009_09_16&ITK+3.16+Released ITK 3.16]
* [http://www.insight-journal.org/browse/publication/149 Label image classes], [http://hdl.handle.net/1926/584 Label map classes], Label map morphology
* [http://hdl.handle.net/10380/3055 Region based Level Sets]
* Improvements in Streaming large images
* QuadEdgeMesh spherical registration
** Rigid (in NAMIC Sandbox)
** Deformable (Diffeomorphic Demons) (in NAMIC Sandbox)
** Improvements in the QuadEdgeMesh filter class (in ITK to support the two above).
* Pixel coordinates consistency
* Multi-threaded registration framework (fixes)
** multi-threaded metrics
** thread-safe transforms
* Hessian-based shape descriptors
* Fractal dimensions
* [http://hdl.handle.net/1926/585 FFT based image reconstruction]

=== VTK ===
* VTK 5.4 released
* vtkWidgets
* [http://www.vtk.org/Wiki/VTK/ARB VTK ARB] formed
* [http://vtk.uservoice.com/pages/31508-general User Voice] added to gather community feedback
* [http://www.midasjournal.org/?journal=35 VTK Journal]
* [http://www.vtkedge.org/ VTK Edge] will be consolidated into VTK
* In progress:
** [http://blog.cryos.net/archives/236-VTK-New-2D-API,-Canvas-and-Charting-Features.html VTK 2D Charting]
** Informatics
** Examples makeover
** git mirror of VTK

=== Teem ===
* [http://teem.sf.net Teem] 1.11 Soon to be Released
** release branch being used in slicer3 nightly builds
** Many improvements and new features described in the [http://sourceforge.net/mailarchive/forum.php?thread_name=9FE12D1D-D52B-40F6-B793-D8AA9D2124CB%40uchicago.edu&forum_name=teem-users Teem 1.11 Change Log Message]
* Python wrappers (auto-generated by ctypeslib) now included in teem/python/ctypes; used previously for [[Two-tensor tractography in Slicer using Python and Teem]]
* The tenGage kind (for doing convolution-based measurements in tensor fields) now includes direct computation of the fiber curving (tenGageFiberCurving) and fiber dispersion (tenGageFiberDispersion) indices used in [[2009_Summer_Project_Week_Slicer3_Fibre_Dispersion|Slicer module for the computation of fibre dispersion and curving measures]] (Peter Savadjiev BWH)
* New functionality from Thomas Schultz to implement fast crease surface extraction (see his recent TVCG paper [[http://www.ci.uchicago.edu/~schultz/papers/schultz-crease-2008.pdf]])
* New [http://people.cs.uchicago.edu/~glk/ssp/ scale space partices] functionality, with applications to lung airway segmentation and white matter skeletonization from DTI
* New applications of scale-space particles for COPD with Raul San Jose (see http://www.airwayinspector.org/)

=== XNAT ===

* [http://groups.google.com/group/xnat_discussion/browse_thread/thread/f46581afed629a5c XNAT 1.4 RC3] available
** More robust QC modeling via xnat:qcManualAssessorData.
** New 'columns' variable for REST based listings.
** LDAP support.
** Improved memory footprint and efficiency.
** Refactored Search UI in the listing engine.
* [http://code.google.com/p/xnatfs/ xnatfs] provides WebDav access to XNAT instances

=== GWE ===

* Interactive experiments' results browser.
* CSV and generated commands dumps and preview.
* Support for LSF and Lava cluster DRMs.
* Ability to override auto-discovered DRMs with configured ones.
* Ability to override default database installation location.
* Function to extract experiments' parameters from text files.
* Operations to delete, pause and resume experiments.
* Recommended to watch: [http://www.youtube.com/watch?v=yXdRks5Wu5Q 5 minutes demo video].

=== BatchMake ===
* Improvement in the integration of grid computing using condor.
* Semi-Automatic conversion of Slicer modules for batch processing
* Parameter exploration is now possible
* Execution of algorithms are faster

=== CMake/CPack/CTest/CDash ===
* parallel ctest (ctest -j)
* cpack
* conversion to cmake in-progress
* linkage between CTest and MIDAS in progress
** Host large datasets for algorithm validation and performance testing
*** Demonstrated using RegisterImages

=== 3D Slicer ===
* List of new modules and features (TBD)
** See here for a list of [http://wiki.slicer.org/slicerWiki/index.php/Documentation-3.5#List_of_Modules_new_to_3.5 modules new to 3.5].
* 3.4/3.4.1 release information
* Extension Architecture and Extension Modules
* ARRA Supplement Projects
* Qt Port (lead in to Julien's 8:30 session)
** Co-existence of KWWidgets and Qt
** Creation of a subset of the needed Qt widgets
** Full port in Qt of first modules
** Design of the core architecture in Qt (plugin mechanism, Command line modules, widget libraries...)
** Tutorials for the slicer developer community to port modules
** [http://wiki.slicer.org/slicerWiki/index.php/Slicer3:Developers:Projects:QtSlicer/Gallery Gallery] and [http://wiki.slicer.org/slicerWiki/index.php/Slicer3:Developers:Projects:QtSlicer/Tutorials Tutorials]
* More info on the [http://www.slicer.org/slicerWiki/index.php/Main_Page#News Slicer wiki News Page]
* multi-camera view in Slicer (endoscopy application)

=== Other Topics ===

* [http://Commontk.org Common Toolkit]