Difference between revisions of "Modules:AtlasCreator"

From Slicer Wiki
Jump to: navigation, search
 
(45 intermediate revisions by one other user not shown)
Line 29: Line 29:
 
* Fixed Registration against a template or Dynamic Registration against a mean image
 
* Fixed Registration against a template or Dynamic Registration against a mean image
 
* Normalization of output atlases to a given value
 
* Normalization of output atlases to a given value
 +
* auto-detection of Structures (labels)
 
* different Output Casts
 
* different Output Casts
 
* Principal Component Analysis
 
* Principal Component Analysis
* Cluster Computation
+
* Cluster Computation Mode
 
* using existing Transforms and skipping the Registration (f.e. to re-run a previous generation)
 
* using existing Transforms and skipping the Registration (f.e. to re-run a previous generation)
  
Line 37: Line 38:
  
 
This module supports different usage types and interfaces:
 
This module supports different usage types and interfaces:
# [[Modules:AtlasCreator#simple|Simple Atlas Creation]]
+
# '''[[Modules:AtlasCreator#simple|Simple Atlas Creation (HowTo)]]'''
 
# [[Modules:AtlasCreator#extended|The extended graphical user interface]]
 
# [[Modules:AtlasCreator#extended|The extended graphical user interface]]
 
# [[Modules:AtlasCreator#cli|The command line interface]]
 
# [[Modules:AtlasCreator#cli|The command line interface]]
# External invocation using the Atlas Creator MRML Node
+
# [[Modules:AtlasCreator#mrml|External invocation using the Atlas Creator MRML Node]]
  
 
===Use Cases, Examples===
 
===Use Cases, Examples===
Line 75: Line 76:
 
|}
 
|}
  
===Quick Tour of Features and Use===
 
  
<span id="extended"></span>
+
'''Output Directory Structure'''
===='''The Extended Graphical User Interface'''====
 
  
[[Image:ACfullGui.png|thumb|280x280px|right|Atlas Creator User Interface in '''extended mode''']]
+
The ''Output Directory'' contains the following content after the Atlas Creator finished.
The Atlas Creator module is organized in panels from which only the ''Input/Output panel'' is expanded by default. Additional features are provided through an extended interface. This extended interface is divided into the ''Parameters'' panel and the ''Advanced'' panel which are collapsed by default.
 
  
 +
* '''./template.nrrd''' - The fixed or dynamic template
 +
* '''./normalizedIntensityMapOfAligned.nrrd''' - An intensity map of all aligned cases, divided by the number of cases.
 +
* '''./registered/''' - A directory containing the registered Original Images, if ''Delete Aligned Images'' is ''off''.
 +
* '''./resampled/''' - A directory containing the resampled Segmentations used for the Atlas Creation, if ''Delete Aligned Segs.'' is ''off''.
 +
* '''./transforms/''' - A directory containing the generated transforms as a result of the registration
 +
* '''./atlasX.nrrd''' - Atlas for label X, if ''Activate PCA'' is ''off''.
 +
* '''./atlasY.nrrd''' - Atlas for label Y, if ''Activate PCA'' is ''off''.
 +
* '''./atlasZ.nrrd''' - Atlas for label Z, if ''Activate PCA'' is ''off''.
 +
* '''./PCA/PCAX/''' - A directory containing generated PCA data for label X, if ''Activate PCA'' is ''on''.
 +
* '''./PCA/PCAY/''' - A directory containing generated PCA data for label Y, if ''Activate PCA'' is ''on''.
 +
* '''./PCA/PCAZ/''' - A directory containing generated PCA data for label Z, if ''Activate PCA'' is ''on''.
 +
* ... more atlases depending on which structures were used
  
 +
===Quick Tour of Features and Use===
  
'''The Input/Output Panel'''
+
<span id="extended"></span>
** ''Original Images'':
+
===='''The Extended Graphical User Interface'''====
** ''Segmentations'':
 
** ''Output directory'':
 
** ''Registration Type'':
 
*** ''Pair Fixed'':
 
*** ''Pair Online'':
 
*** ''Group Online'':
 
[[Image:ACinputoutput.png|thumb|360x360px|The '''Input/Output''' panel]]
 
  
 +
[[Image:ACfullGui.png|thumb|360x360px|right|Atlas Creator User Interface in '''extended mode''']]
 +
The Atlas Creator module is organized in panels from which only the ''Input/Output panel'' is expanded by default. Additional features are provided through an extended interface. This extended interface is divided into the ''Parameters'' panel and the ''Advanced'' panels which are collapsed by default.
  
  
'''The Parameters Panel'''
 
** ''Original Images'':
 
** ''Segmentations'':
 
** ''Output directory'':
 
** ''Registration Type'':
 
*** ''Pair Fixed'':
 
*** ''Pair Online'':
 
*** ''Group Online'':
 
[[Image:ACparameters.png|thumb|360x360px|The '''Parameters''' panel]]
 
  
 +
'''Input/Output Panel'''
  
 +
The Input/Output panel reflects the required settings for any atlas creation, simple or extended.
  
''' The Advanced Panel'''
+
[[Image:ACinputoutput.png|360x360px|The '''Input/Output''' panel]]
* '''The Cluster Configuration Panel'''
+
* ''Original Images'': The folder containing the original images '''Required'''
** ''Original Images'':
+
* ''Segmentations'': The folder containing the segmentations '''Required'''
** ''Segmentations'':
+
* ''Output directory'': The output folder - if it does not exist or is not empty, a new output folder with a similar name will be created '''Required'''
** ''Output directory'':
+
* ''Registration Type'': The type of alignment used during registration stage
** ''Registration Type'':
+
** ''Pair Fixed'': Register all other cases against a fixed template. By default, the Atlas Creator chooses this template.
*** ''Pair Fixed'':
+
** ''Pair Online'': Register all cases against a mean image of all cases which will be generated automatically.
*** ''Pair Online'':
+
** ''Group Online'': Register all cases using the un-biased groupwise registration provided by the [[Modules:AtlasCreator:CongealingCLI|Congeal]] tool.
*** ''Group Online'':
 
[[Image:ACadvancedCluster.png|thumb|360x360px|The advanced '''Cluster Configuration''' panel]]
 
  
  
  
* '''The Principal Component Analysis Panel'''
+
'''Parameters Panel'''
** ''Original Images'':
 
** ''Segmentations'':
 
** ''Output directory'':
 
** ''Registration Type'':
 
*** ''Pair Fixed'':
 
*** ''Pair Online'':
 
*** ''Group Online'':
 
[[Image:ACadvancedPCA.png|thumb|360x360px|The advanced '''Principal Component Analysis''' panel]]
 
  
 +
[[Image:ACparameters.png|360x360px|The '''Parameters''' panel]]
 +
* ''Toolkit'' for ''Pair Fixed'' and ''Pair Online'': By default ''BRAINSFit'' are used for registration and resampling. If the ''CMTK'' extensions are installed, it be used as an alternative. If ''CMTK'' was chosen but not installed, the Atlas Creator falls back to ''BRAINSFit''.
 +
* ''Deformation'': Choose the deformation model for the registration stage.
 +
** ''Affine'': Use linear transformations (faster, less flexible)
 +
** ''Non-rigid'': Use non-rigid transformations on top of linear transformations (slower, more flexible)
 +
* ''Alignment iterations'', for ''Pair Online'': The number of iterations for generating a mean image and registering against it in ''Pair Online'' mode.
 +
* ''Default case'', for ''Pair Fixed'': The default case to use as the fixed template in ''Pair Fixed'' mode. This gets chosen automatically when selecting ''Original Images'' and ''Segmentations'' but can be modified for convenience.
  
  
* '''The Use Existing Transforms Panel'''
 
** ''Original Images'':
 
** ''Segmentations'':
 
** ''Output directory'':
 
** ''Registration Type'':
 
*** ''Pair Fixed'':
 
*** ''Pair Online'':
 
*** ''Group Online'':
 
[[Image:ACadvancedUseExisting.png|thumb|360x360px|The advanced '''Use Existing Transforms''' panel]]
 
  
  
 +
'''Advanced Panels'''
  
* '''The Misc. Panel'''
 
** ''Original Images'':
 
** ''Segmentations'':
 
** ''Output directory'':
 
** ''Registration Type'':
 
*** ''Pair Fixed'':
 
*** ''Pair Online'':
 
*** ''Group Online'':
 
[[Image:ACadvancedMisc.png|thumb|360x360px|The advanced '''Misc.''' panel]]
 
  
<span id="cli"></span>
+
'''Cluster Configuration Panel'''
  
===='''The Command Line Interface'''====
+
The Atlas Creator supports distributing all computations among a Grid Environment. This includes using a scheduler to start all computation jobs (registration, resampling, computing mean images, combine to atlases). All submitted jobs will be monitored for completion and will be re-started up to 4 times on failure. The atlas creation will continue if the failure is not critical but will notify of all failures.
  
Beside using the graphical user interface in 3D Slicer, the Atlas Creator can be accessed using the commandline.
+
[[Image:ACadvancedCluster.png|360x360px|The advanced '''Cluster Configuration''' panel]]
 +
* ''Use Cluster'': If activated, all computation jobs will be submitted using the ''Scheduler Command''.
 +
* ''Scheduler Command'': This command will be used to submit all jobs. For example, if the ''Scheduler Command'' is ''bsub < '', the computation jobs will be run as ''bsub < script1.sh'' instead of just running ''script1.sh''.
  
A help system is available:
 
  
<pre>
 
$ cd Slicer3-release/lib/Slicer3/Modules/AtlasCreator/atlascreator.py
 
$ python atlascreator.py --help
 
AtlasCreator for 3D Slicer
 
Version v0.4
 
  
Usage:
 
  
-h, --help
+
'''Principal Component Analysis Panel'''
        Show this information.
 
  
-i, --images DIR
+
Beside generating statistical atlases, the Atlas Creator module supports a Principal Component Analysis (PCA) to incorporate shape information.
        Directory containing original images.
 
  
-s, --segmentations DIR
+
[[Image:ACadvancedPCA.png|360x360px|The advanced '''Principal Component Analysis''' panel]]
        Directory containing segmentations.
+
* ''Activate PCA'': Use Principal Component Analysis instead of statistical atlas generation.
 +
* ''Max. Eigenvectors'': The maximal number of eigenvectors to analyze during the PCA computation. Should be equal to the number of input cases but can be restricted for convenience. The Atlas Creator will detect if the number exceeds the number of cases.
 +
* ''Combine PCAs'': If activated, all structures (labels) will be defined in one PCA model instead of defining a PCA model for each structure.
  
-o, --output DIR
 
        Output directory.
 
  
--cmtk
 
        Use the CMTK toolkit for registration and resampling, instead of BRAINSFit.
 
        The CMTK4Slicer extensions have to be installed in order to use CMTK.
 
  
--skipRegistration
 
        Skip the registration and use existing transforms.
 
  
        The following arguments have to be specified if the registration is skipped:
+
'''Use Existing Transforms Panel'''
  
        --transforms DIR
+
It is possible to skip the registration stage and directly resample segmentations using existing transforms. This can be used to modify existing atlases.
                Directory containing existing transforms.
 
  
        --existingTemplate FILEPATH
+
[[Image:ACadvancedUseExisting.png|360x360px|The advanced '''Use Existing Transforms''' panel]]
                Filepath to an existing template used for resampling only.
+
* ''Skip Registration'': If activated, the registration stage will be skipped and existing transforms are used for resampling the input segmentations.
 +
* ''Transforms directory'': The directory containing existing transformations. In order to be valid, these transformations must have been generated by the same toolkit (CMTK or BRAINSFit) as configured now.
 +
* ''Existing Template:'': The existing template which was used in the previous atlas generation (''template.nrrd'').
  
--dynamic
 
        Use a dynamic template for registration based on means of images.
 
  
        The following arguments have to be specified if dynamic registration is chosen:
 
  
        -m, --meanIterations INT
 
                Number of iterations to compute and register against a mean image.
 
  
--fixed
+
'''Misc. Panel'''
        Use a fixed template for registration.
 
  
        The following arguments have to be specified if fixed registration is chosen:
+
Miscellaneous settings can be specified using this panel.
  
        --template FILEPATH
+
[[Image:ACadvancedMisc.png|360x360px|The advanced '''Misc.''' panel]]
                Filepath to an image used as a template for fixed registration.
+
* ''Labels'': The list of structures for which to generate the different atlases. Each structure has to be represented by a label number. By default, the Atlas Creator reads this list from the ''default case'' - if specified - or from the first segmentation automatically.
 +
* ''Save Transforms'': If activated, the generated transforms of the registration stage will be saved. (Default setting)
 +
* ''Normalize Atlases'': The generated statistical atlases can be normalized to a value range from 0..X where X is the ''Normalize to'' value.
 +
* ''Normalize to'': If ''Normalize Atlases'' is activated, this value is the upper boundary of the range to which the atlases are normalized to. By default, this is 1.
 +
* ''Output cast for Atlases'': The output cast for the generated atlases can be specified. Default is short.
 +
* ''Delete aligned Images'': If activated, the aligned images will be deleted after atlas generation. If ''not'' activated, a sub-directory ''registered'' containing the aligned images will be available in the output directory.
 +
* ''Delete aligned Segs.'': If activated, the aligned images will be deleted after atlas generation. If ''not'' activated, a sub-directory ''resampled'' containing the aligned segmentations will be available in the output directory.
 +
* ''Debug Output'': This switch enables extra debug and verbose output during all computations.
 +
* ''Dry-Run (Simulaton)'': If activated, no actual computation is performed and the atlas creation will be simulated. This might be helpful to test a long-run computation before actually performing it.
  
        --ignoreTemplateSegmentation
 
                If activated, the template's segmentation will not be added to the atlases.
 
  
-n, --non-rigid
 
        Use Non-Rigid registration additionally.
 
  
-w, --writeTransforms
 
        Write transforms to output directory.
 
  
--keepAligned
 
        Keep the aligned images and segmentations.
 
  
-l, --labels STRING
+
<span id="cli"></span>
        List of labels to include for the atlases, f.e. "3 4 5 6 8 10".
 
        DEFAULT: detect labels automatically
 
  
--normalize
+
===='''The Command Line Interface'''====
        Normalize Atlases to 0..1.
 
        If activated, the output cast will be set to Double.
 
  
        --normalizeTo INT
+
Beside using the graphical user interface in 3D Slicer, the Atlas Creator can be accessed using the '''commandline interface'''.
                The upper value to normalize the atlases to.
 
                DEFAULT: 1
 
  
--outputCast INT
+
<pre>
        Output cast for the atlases. Possible values:
+
$ cd Slicer3-release/lib/Slicer3/Modules/AtlasCreator/
        0: Char
+
$ python atlascreator.py --help
        1: Unsigned Char
+
AtlasCreator for 3D Slicer
        2: Double
+
Version v0.4
        3: Float
 
        4: Int
 
        5: Unsigned Int
 
        6: Long
 
        7: Unsigned Long
 
        8: Short
 
        9: Unsigned Short
 
        DEFAULT: 8
 
  
-c, --cluster
+
Usage:
        Use the cluster mode.
 
  
         The following arguments have to be specified if cluster mode is chosen:
+
-h, --help
 +
         Show this information.
  
        --schedulerCommand EXECUTABLE
+
-i, --images DIR
                The executable to use as a scheduler in cluster mode, f.e. "qsub".
+
        Directory containing original images.
  
--pca
+
-s, --segmentations DIR
         Perform PCA Analysis on top of Resampling.
+
         Directory containing segmentations.
  
        --pcaMaxEigenVectors INT
+
-o, --output DIR
                The number of maximal Eigenvectors to use for model generation.
+
        Output directory.
                DEFAULT: 10
 
  
        --pcaCombine
+
[....]
                Combine the PCA output.
+
</pre>
  
--slicer FILEPATH
+
The '''full documentation of the commandline interface''' is available on [[Modules:AtlasCreator:CLI|a separate page]].
        Filepath to the 3D Slicer launcher including arguments, f.e. "/usr/bin/Slicer3 --tmp_dir /var/tmp".
 
        DEFAULT: Find the 3D Slicer launcher automatically.
 
  
-d, --debug
+
== Development ==
        Enable debug information.
 
  
--dryrun
+
===Notes from the Developer(s)===
        Output executable commands instead of running the registration or resampling.
 
 
 
--examples
 
        Show usage examples.
 
 
 
 
 
Developed by Daniel Haehn and Kilian Pohl, University of Pennsylvania. The research was funded by an ARRA supplement to NIH NCRR (P41 RR13218).
 
 
 
Thanks to everyone!
 
  
 +
<span id='mrml'></span>
 +
===='''External invocation using the Atlas Creator MRML Node'''====
  
</pre>
+
It is easy to include the Atlas Creator in third-party 3D Slicer modules (C++, Tcl and Python are supported) or run it via the Tcl or Python consoles. To do so, one has to configure the vtkMRMLAtlasCreatorNode and fire a launch event.
  
Examples:
+
The following example outlines the procedure by configuring a ''Pair fixed'' computation against a defaultCase (Python was chosen for this example):
  
 
<pre>
 
<pre>
$ python atlascreator.py --examples
+
from Slicer import slicer
AtlasCreator for 3D Slicer
+
import os
Version v0.4
 
 
 
Examples:
 
-----------------------------------------------------------------------------------------------
 
1. Run fixed registration with the testdata and normalize the atlases to 1:
 
 
 
        python atlascreator.py -i TestData/originals/ -s TestData/segmentations/ -o /tmp/acout --fixed --template TestData/originals/case62.nrrd -w -l "3 4 5 6 7 8 9" --normalize
 
 
 
-----------------------------------------------------------------------------------------------
 
2. Run fixed registration with the testdata and use CMTK instead of BRAINSFit and label auto-detection:
 
 
 
        python atlascreator.py -i TestData/originals/ -s TestData/segmentations/ -o /tmp/acout --fixed --template TestData/originals/case62.nrrd -w --cmtk
 
  
-----------------------------------------------------------------------------------------------
+
# we use the testdata which is shipped with the Atlas Creator
3. Run dynamic registration with the testdata and normalize the atlases to 0..100:
+
dataPath = os.path.normpath(slicer.Application.GetBinDir().. + '/../share/Slicer3/Modules/AtlasCreator/TestData/')
  
        python atlascreator.py -i TestData/originals/ -s TestData/segmentations/ -o /tmp/acout --dynamic --meanIterations 5 -w -l "3 4 5 6 7 8 9" --normalize --normalizeTo 100
+
# create a new Atlas Creator MRML Node
 +
n = slicer.vtkMRMLAtlasCreatorNode()
  
-----------------------------------------------------------------------------------------------
+
# Initialize with a default configuration
4. Run dynamic registration with the testdata on a cluster (scheduler command "qsub -l centos5"):
+
n.InitializeByDefault()
  
        python atlascreator.py -i TestData/originals/ -s TestData/segmentations/ -o /tmp/acout --dynamic --meanIterations 5 -w -l "3 4 5 6 7 8 9" --normalize --cluster --schedulerCommand "qsub -l centos5"
+
# set the original images by specifying the absolute filepaths for all cases divided by space
 +
n.SetOriginalImagesFilePathList(dataPath + '/originals/case60.nrrd ' + dataPath + '/originals/case61.nrrd ' + dataPath + '/originals/case62.nrrd')
 +
# set the segmentations by specifying the absolute filepaths for all cases divided by space
 +
n.SetSegmentationsFilePathList(dataPath + '/segmentations/case60.nrrd ' + dataPath + '/segmentations/case61.nrrd ' + dataPath + '/segmentations/case62.nrrd')
  
-----------------------------------------------------------------------------------------------
+
# configure an output directory
5. Use existing registrations and just re-sample
+
n.SetOutputDirectory('/tmp/acout/')
  
        python atlascreator.py --skipRegistration --transforms /tmp/acout --existingTemplate TestData/segmentations/case62.nrrd -s TestData/segmentations/ -o /tmp/acout -l "3 4 5 6 7 8 9" --normalize --outputCast 3
+
# set the default case
 +
n.SetFixedTemplateDefaultCaseFilePath(dataPath + '/originals/case62.nrrd')
  
 +
# add the MRML node to the scene
 +
slicer.MRMLScene.AddNode(n)
  
 +
# start the computation by firing the launch event
 +
n.Launch()
 
</pre>
 
</pre>
  
== Development ==
+
==== Architecture of the Atlas Creator ====
  
===Notes from the Developer(s)===
+
{|
 
+
|[[Image:AcFlowNew.png|thumb|280px|The '''computational steps''' of the Atlas Creator]]
Separate notes on the development are available [[Modules:AtlasCreator:Development|on a separate page]].
+
|[[Image:AcComponentsNew.png|thumb|360px|'''Different Components''' work together in the Atlas Creator and create a very heterogeneous environment.]]
 +
|[[Image:AtlasCreatorClassDiagramm.png|thumb|360px|The '''class diagram of the Python Scripted Module''' which is the central unit of the Atlas Creator.]]
 +
|}
  
 
===Dependencies===
 
===Dependencies===
Line 347: Line 283:
  
 
===Known bugs===
 
===Known bugs===
 +
The AtlasCreator is currently ''not'' supported on Windows machines.
  
 
===Usability issues===
 
===Usability issues===
Line 363: Line 300:
  
 
== More Information ==  
 
== More Information ==  
 +
 +
''Please cite this work as:''
 +
 +
L. Zöllei, M. Shenton, W.M. Wells III, K.M. Pohl. The Impact of Atlas Formation Methods on Atlas-Guided Brain Segmentation, Statistical Registration. In ''Pair-wise and Group-wise Alignment and Atlas Formation Workshop at MICCAI 2007: Tenth International Conference on Medical Image Computing and Computer-Assisted Intervention'', pp. 39 - 46, Brisbane, Australia, 2007
  
 
===Acknowledgment===
 
===Acknowledgment===
 
The research was funded by an ARRA supplement to NIH NCRR (P41 RR13218).
 
The research was funded by an ARRA supplement to NIH NCRR (P41 RR13218).
  
The Atlas Creator module benefits from several different Toolkits: Thank you to Hans Johnson et al. for BRAINSFit, Torsten Rolfing et al. for CMTK and Jeremy De Bonet et al. for Congeal.
+
The Atlas Creator module benefits from several different Toolkits: Thank you for [[Modules:BRAINSFit|BRAINSTools]] (Hans Johnson et al.), for [[Modules:CMTK|CMTK]] (Torsten Rolfing et al.) and for [[Modules:AtlasCreator:CongealingCLI|Congeal]] (J. De Bonet, L. Zöllei and W.M. Wells III).
 +
 
 +
Thank you to Dominique Belhachemi and Steve Pieper for their support!
  
 
===References===
 
===References===

Latest revision as of 17:09, 21 July 2011

Home < Modules:AtlasCreator

Return to Slicer 3.6 Documentation


AtlasCreator

Atlas Creator User Interface in simple mode
Example of generated Atlases
Comparison of the alignment of two cases before and after Atlas Creation

General Information

Module Type & Category

Type: Built-in Loadable Module

Category: Registration

Authors, Collaborators & Contact

  • Daniel Haehn, University of Pennsylvania
  • Kilian Pohl, University of Pennsylvania
  • Contact: Daniel Haehn (haehn@bwh.harvard.edu)

Module Description

The Atlas Creator module aligns images paired with segmentations to generate statistical atlases for several segmented structures.

Features:

  • Support for BRAINSFit/CMTK/Congeal toolkits for Registration and Resampling
  • Fixed Registration against a template or Dynamic Registration against a mean image
  • Normalization of output atlases to a given value
  • auto-detection of Structures (labels)
  • different Output Casts
  • Principal Component Analysis
  • Cluster Computation Mode
  • using existing Transforms and skipping the Registration (f.e. to re-run a previous generation)

Usage

This module supports different usage types and interfaces:

  1. Simple Atlas Creation (HowTo)
  2. The extended graphical user interface
  3. The command line interface
  4. External invocation using the Atlas Creator MRML Node

Use Cases, Examples

Input Data Requirements

The Atlas Creator expects input data to be structured the following way:

  • In general each original image is accompanied by a manual segmentation.
  • The images and the segmentations have to be in two different folders but have matching filenames.
  • All images and segmentations have to be in Slicer-readable format.
  • For Example:
    • ./originals/case1.nrrd
    • ./originals/case2.nrrd
    • ./originals/case3.nrrd
    • ./segmentations/case1.nrrd
    • ./segmentations/case2.nrrd
    • ./segmentations/case3.nrrd


HowTo: Simple Atlas Creation
The following steps perform a Pair Fixed Registration against an automatic chosen template for automatically detected structures.
1. Select the directories containing the Original Images and the Segmentations in the Input/Output panel.
2. Select an Output Directory in the Input/Output panel. It makes sense to create a new directory to use for the Output.
3. Hit Start!
4. After some wait (minutes or hours!, depending on the number of input cases), the generated atlases and the used template will be loaded into 3D Slicer.


Output Directory Structure

The Output Directory contains the following content after the Atlas Creator finished.

  • ./template.nrrd - The fixed or dynamic template
  • ./normalizedIntensityMapOfAligned.nrrd - An intensity map of all aligned cases, divided by the number of cases.
  • ./registered/ - A directory containing the registered Original Images, if Delete Aligned Images is off.
  • ./resampled/ - A directory containing the resampled Segmentations used for the Atlas Creation, if Delete Aligned Segs. is off.
  • ./transforms/ - A directory containing the generated transforms as a result of the registration
  • ./atlasX.nrrd - Atlas for label X, if Activate PCA is off.
  • ./atlasY.nrrd - Atlas for label Y, if Activate PCA is off.
  • ./atlasZ.nrrd - Atlas for label Z, if Activate PCA is off.
  • ./PCA/PCAX/ - A directory containing generated PCA data for label X, if Activate PCA is on.
  • ./PCA/PCAY/ - A directory containing generated PCA data for label Y, if Activate PCA is on.
  • ./PCA/PCAZ/ - A directory containing generated PCA data for label Z, if Activate PCA is on.
  • ... more atlases depending on which structures were used

Quick Tour of Features and Use

The Extended Graphical User Interface

Atlas Creator User Interface in extended mode

The Atlas Creator module is organized in panels from which only the Input/Output panel is expanded by default. Additional features are provided through an extended interface. This extended interface is divided into the Parameters panel and the Advanced panels which are collapsed by default.


Input/Output Panel

The Input/Output panel reflects the required settings for any atlas creation, simple or extended.

The Input/Output panel

  • Original Images: The folder containing the original images Required
  • Segmentations: The folder containing the segmentations Required
  • Output directory: The output folder - if it does not exist or is not empty, a new output folder with a similar name will be created Required
  • Registration Type: The type of alignment used during registration stage
    • Pair Fixed: Register all other cases against a fixed template. By default, the Atlas Creator chooses this template.
    • Pair Online: Register all cases against a mean image of all cases which will be generated automatically.
    • Group Online: Register all cases using the un-biased groupwise registration provided by the Congeal tool.


Parameters Panel

The Parameters panel

  • Toolkit for Pair Fixed and Pair Online: By default BRAINSFit are used for registration and resampling. If the CMTK extensions are installed, it be used as an alternative. If CMTK was chosen but not installed, the Atlas Creator falls back to BRAINSFit.
  • Deformation: Choose the deformation model for the registration stage.
    • Affine: Use linear transformations (faster, less flexible)
    • Non-rigid: Use non-rigid transformations on top of linear transformations (slower, more flexible)
  • Alignment iterations, for Pair Online: The number of iterations for generating a mean image and registering against it in Pair Online mode.
  • Default case, for Pair Fixed: The default case to use as the fixed template in Pair Fixed mode. This gets chosen automatically when selecting Original Images and Segmentations but can be modified for convenience.



Advanced Panels


Cluster Configuration Panel

The Atlas Creator supports distributing all computations among a Grid Environment. This includes using a scheduler to start all computation jobs (registration, resampling, computing mean images, combine to atlases). All submitted jobs will be monitored for completion and will be re-started up to 4 times on failure. The atlas creation will continue if the failure is not critical but will notify of all failures.

The advanced Cluster Configuration panel

  • Use Cluster: If activated, all computation jobs will be submitted using the Scheduler Command.
  • Scheduler Command: This command will be used to submit all jobs. For example, if the Scheduler Command is bsub < , the computation jobs will be run as bsub < script1.sh instead of just running script1.sh.



Principal Component Analysis Panel

Beside generating statistical atlases, the Atlas Creator module supports a Principal Component Analysis (PCA) to incorporate shape information.

The advanced Principal Component Analysis panel

  • Activate PCA: Use Principal Component Analysis instead of statistical atlas generation.
  • Max. Eigenvectors: The maximal number of eigenvectors to analyze during the PCA computation. Should be equal to the number of input cases but can be restricted for convenience. The Atlas Creator will detect if the number exceeds the number of cases.
  • Combine PCAs: If activated, all structures (labels) will be defined in one PCA model instead of defining a PCA model for each structure.



Use Existing Transforms Panel

It is possible to skip the registration stage and directly resample segmentations using existing transforms. This can be used to modify existing atlases.

The advanced Use Existing Transforms panel

  • Skip Registration: If activated, the registration stage will be skipped and existing transforms are used for resampling the input segmentations.
  • Transforms directory: The directory containing existing transformations. In order to be valid, these transformations must have been generated by the same toolkit (CMTK or BRAINSFit) as configured now.
  • Existing Template:: The existing template which was used in the previous atlas generation (template.nrrd).



Misc. Panel

Miscellaneous settings can be specified using this panel.

The advanced Misc. panel

  • Labels: The list of structures for which to generate the different atlases. Each structure has to be represented by a label number. By default, the Atlas Creator reads this list from the default case - if specified - or from the first segmentation automatically.
  • Save Transforms: If activated, the generated transforms of the registration stage will be saved. (Default setting)
  • Normalize Atlases: The generated statistical atlases can be normalized to a value range from 0..X where X is the Normalize to value.
  • Normalize to: If Normalize Atlases is activated, this value is the upper boundary of the range to which the atlases are normalized to. By default, this is 1.
  • Output cast for Atlases: The output cast for the generated atlases can be specified. Default is short.
  • Delete aligned Images: If activated, the aligned images will be deleted after atlas generation. If not activated, a sub-directory registered containing the aligned images will be available in the output directory.
  • Delete aligned Segs.: If activated, the aligned images will be deleted after atlas generation. If not activated, a sub-directory resampled containing the aligned segmentations will be available in the output directory.
  • Debug Output: This switch enables extra debug and verbose output during all computations.
  • Dry-Run (Simulaton): If activated, no actual computation is performed and the atlas creation will be simulated. This might be helpful to test a long-run computation before actually performing it.



The Command Line Interface

Beside using the graphical user interface in 3D Slicer, the Atlas Creator can be accessed using the commandline interface.

$ cd Slicer3-release/lib/Slicer3/Modules/AtlasCreator/
$ python atlascreator.py --help
AtlasCreator for 3D Slicer
Version v0.4

Usage:

-h, --help
        Show this information.

-i, --images DIR
        Directory containing original images.

-s, --segmentations DIR
        Directory containing segmentations.

-o, --output DIR
        Output directory.

[....]

The full documentation of the commandline interface is available on a separate page.

Development

Notes from the Developer(s)

External invocation using the Atlas Creator MRML Node

It is easy to include the Atlas Creator in third-party 3D Slicer modules (C++, Tcl and Python are supported) or run it via the Tcl or Python consoles. To do so, one has to configure the vtkMRMLAtlasCreatorNode and fire a launch event.

The following example outlines the procedure by configuring a Pair fixed computation against a defaultCase (Python was chosen for this example):

from Slicer import slicer
import os

# we use the testdata which is shipped with the Atlas Creator
dataPath = os.path.normpath(slicer.Application.GetBinDir().. + '/../share/Slicer3/Modules/AtlasCreator/TestData/')

# create a new Atlas Creator MRML Node
n = slicer.vtkMRMLAtlasCreatorNode()

# Initialize with a default configuration
n.InitializeByDefault()

# set the original images by specifying the absolute filepaths for all cases divided by space
n.SetOriginalImagesFilePathList(dataPath + '/originals/case60.nrrd ' + dataPath + '/originals/case61.nrrd ' + dataPath + '/originals/case62.nrrd')
# set the segmentations by specifying the absolute filepaths for all cases divided by space
n.SetSegmentationsFilePathList(dataPath + '/segmentations/case60.nrrd ' + dataPath + '/segmentations/case61.nrrd ' + dataPath + '/segmentations/case62.nrrd')

# configure an output directory
n.SetOutputDirectory('/tmp/acout/')

# set the default case
n.SetFixedTemplateDefaultCaseFilePath(dataPath + '/originals/case62.nrrd')

# add the MRML node to the scene
slicer.MRMLScene.AddNode(n)

# start the computation by firing the launch event
n.Launch()

Architecture of the Atlas Creator

The computational steps of the Atlas Creator
Different Components work together in the Atlas Creator and create a very heterogeneous environment.
The class diagram of the Python Scripted Module which is the central unit of the Atlas Creator.

Dependencies

At least BRAINSFit, CMTK or Congeal have to be installed. BRAINSFit is deployed via Slicer, VMTK and Congeal are available as Slicer extensions.

Tests

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

Known bugs

The AtlasCreator is currently not supported on Windows machines.

Usability issues

  • Congeal support is still Under Construction.

Source code & documentation

Source code:

Doxygen documentation:

More Information

Please cite this work as:

L. Zöllei, M. Shenton, W.M. Wells III, K.M. Pohl. The Impact of Atlas Formation Methods on Atlas-Guided Brain Segmentation, Statistical Registration. In Pair-wise and Group-wise Alignment and Atlas Formation Workshop at MICCAI 2007: Tenth International Conference on Medical Image Computing and Computer-Assisted Intervention, pp. 39 - 46, Brisbane, Australia, 2007

Acknowledgment

The research was funded by an ARRA supplement to NIH NCRR (P41 RR13218).

The Atlas Creator module benefits from several different Toolkits: Thank you for BRAINSTools (Hans Johnson et al.), for CMTK (Torsten Rolfing et al.) and for Congeal (J. De Bonet, L. Zöllei and W.M. Wells III).

Thank you to Dominique Belhachemi and Steve Pieper for their support!

References