Difference between revisions of "Projects:ARRA:SlicerEM:AtlasCreator"

From NAMIC Wiki
Jump to: navigation, search
 
(46 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
The Atlas Creator combines existing segmentations to an anatomical atlas based on robust statistics.
 
The Atlas Creator combines existing segmentations to an anatomical atlas based on robust statistics.
  
== Examples ==
+
== Examples and Tests ==
  
The following example was created using 6 different cases, aligned against a Fixed Template. It took about 25 Mins on a 4 Core Xeon System with 3 GHz and visualized using the default labelMap colors.
+
Now available at [[Projects:ARRA:SlicerEM:AtlasCreator:Tests]].
 
 
[[File:FixedTemplateCase3_6Cases_25mins.png|600px]]
 
  
 
== GUI ==
 
== GUI ==
Line 19: Line 17:
 
The priority list reflects the open issues.
 
The priority list reflects the open issues.
  
 +
Version 0.4 (current version in Trunk and 3.6Branch)
 
# <strike>Re-structure Atlas Creator code according to the Design specified below</strike>
 
# <strike>Re-structure Atlas Creator code according to the Design specified below</strike>
 
# <strike>Implement dynamic registration</strike>
 
# <strike>Implement dynamic registration</strike>
#* Watch out for overflows
+
#* <strike>Watch out for overflows</strike>
 
# <strike>Implement support for parallel Computation</strike>
 
# <strike>Implement support for parallel Computation</strike>
# <strike>Add Help</strike> and Online Documentation
+
# <strike>Add Help</strike>
# check how to include C++ code in AtlasCreator
+
# <strike>check how to include C++ code in AtlasCreator</strike>
#* create concept
+
#* <strike>create concept</strike>
# make KilisSandbox work with PCA
+
# <strike>make KilisSandbox work with PCA</strike>
# create AtlasCreator MRML Node
+
# <strike>include CMTK as alternative (affine) to BRAINSFit</strike>
# update documentation page
+
# <strike>create outputDir automatically</strike>
# include CMTK as alternative to BRAINSFit
+
# <strike>Solve Double/Float Problem</strike>
# Include PCA functionality in AtlasCreator
+
# <strike>refactor cluster mode to be based on a script</strike>
 +
# <strike>cluster script template is configurable for individual needs</strike>
 +
# <strike>add support for CMTK non-rigid</strike>
 +
# <strike>de-activate CMTK multi-threading in cluster-mode</strike>
 +
# <strike>different wait time for cluster mode for observing finished jobs</strike>
 +
# <strike>don't use Slicer temp dir anymore, use a temp dir in the output dir instead</strike>
 +
# <strike>adding date to print timestamps</strike>
 +
# <strike>return as output as well the normalized intensity maps of aligned cases in the static mode</strike>
 +
# <strike>only resample filenames which exist in registration and vice versa</strike>
 +
# <strike>add the ability to normalize to 0..X instead of only 0..1</strike>
 +
# <strike>create AtlasCreator MRML Node and use a converter to create configuration objects</strike>
 +
# <strike>output status in notify loop</strike>
 +
# <strike>change last step from VTK to ITK</strike>
 +
# <strike>test invokation from EMSegmenter</strike>
 +
# <strike>Include PCA functionality in AtlasCreator</strike>
 +
# <strike>change GUI to use AtlasCreator MRML Node</strike>
 +
# <strike>finish advanced panel in the GUI</strike>
 +
# <strike>replace configuration objects by MRML Node</strike>
 +
# <strike>add watching of submitted jobs (check if job returns 0)</strike>
 +
# <strike>tests!!</strike>
 +
# <strike>Congeal wrapper</strike>
 +
# <strike>added check if Congeal was installed and deactivate the group online mode if not</strike>
 +
# <strike>solve issue in CongealingCLI when running on Windows</strike>
 +
# <strike>downsample testdata</strike>
 +
# <strike>add flag to ignore the templates segmentation in atlascreation</strike>
 +
# <strike>update documentation page</strike>
 +
 
 +
Nice to have in the future:
 +
# include group online mode
 +
# simplify and reduce command line arguments
 +
## save all outputs by default and add flags to specify to not save
 +
# enhance performance of ComputeMeanImage ITK code
  
 
== Design ==
 
== Design ==
  
The following State Machine diagram shows the flow of the Atlas Creator logic. It can be run in two modes:
+
The following State Machine diagram (slightly outdated) shows the flow of the Atlas Creator logic. It can be run in two modes:
 
* Normal mode, all computations on one machine
 
* Normal mode, all computations on one machine
 
* Cluster mode, parallelized computations
 
* Cluster mode, parallelized computations
Line 41: Line 71:
  
  
The following class diagram shows the structure of the module.
+
The following class diagram (slightly outdated) shows the structure of the module.
  
 
[[File:AtlasCreatorClassDiagramm.png|600px]]
 
[[File:AtlasCreatorClassDiagramm.png|600px]]
Line 80: Line 110:
  
 
The module immediately recognizes if the parallelized registration jobs are complete and then continues the pipeline on the node where the it was first started.
 
The module immediately recognizes if the parallelized registration jobs are complete and then continues the pipeline on the node where the it was first started.
 
==== Input for Parallelized Computation ====
 
* Optional: Command for scheduling the generated bash scripts. This command will be run with the generated bash scripts as individual arguments.
 
* Optional: Path to 3D Slicer (must be a network installation reachable by each node)
 
* Optional: The temporary directory to be used by the 3D Slicer launch mechanism
 
* Optional: The config file directory to be used by the 3D Slicer launch mechanism
 
* The number of different computation nodes. The Atlas Creator will use this number to distribute the parallelized registration among the input images.
 
  
 
=== The Atlas Creator Command Line Interface ===
 
=== The Atlas Creator Command Line Interface ===
Line 107: Line 130:
 
21:42:17 daniel@sbia-pc66:~/SLICER/TRUNK/Slicer3/Modules/AtlasCreator$ python atlascreator.py --help
 
21:42:17 daniel@sbia-pc66:~/SLICER/TRUNK/Slicer3/Modules/AtlasCreator$ python atlascreator.py --help
 
AtlasCreator for 3D Slicer
 
AtlasCreator for 3D Slicer
Version v0.1
+
Version v0.22
  
 
Usage:
 
Usage:
Line 122: Line 145:
 
-o, --output DIR
 
-o, --output DIR
 
         Output directory.
 
         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
 
--skipRegistration
Line 155: Line 182:
 
-w, --writeTransforms
 
-w, --writeTransforms
 
         Write transforms to output directory.
 
         Write transforms to output directory.
 +
 +
--keepAligned
 +
        Keep the aligned images and segmentations.
  
 
-l, --labels STRING
 
-l, --labels STRING
Line 161: Line 191:
 
--normalize
 
--normalize
 
         Normalize Atlases to 0..1.
 
         Normalize Atlases to 0..1.
         If activated, the output cast will be set to Float.
+
         If activated, the output cast will be set to Double.
  
 
--outputCast INT
 
--outputCast INT
Line 183: Line 213:
  
 
         --schedulerCommand EXECUTABLE
 
         --schedulerCommand EXECUTABLE
                 The executable to use as a scheduler in cluster mode, f.e. "qsub-run".
+
                 The executable to use as a scheduler in cluster mode, f.e. "qsub".
  
 
--slicer FILEPATH
 
--slicer FILEPATH
Line 209: Line 239:
 
21:42:13 daniel@sbia-pc66:~/SLICER/TRUNK/Slicer3/Modules/AtlasCreator$ python atlascreator.py --examples
 
21:42:13 daniel@sbia-pc66:~/SLICER/TRUNK/Slicer3/Modules/AtlasCreator$ python atlascreator.py --examples
 
AtlasCreator for 3D Slicer
 
AtlasCreator for 3D Slicer
Version v0.1
+
Version v0.22
  
 
Examples:
 
Examples:
Line 218: Line 248:
  
 
-----------------------------------------------------------------------------------------------
 
-----------------------------------------------------------------------------------------------
2. Run dynamic registration with the testdata:
+
2. Run fixed registration with the testdata and use CMTK instead of BRAINSFit:
 +
 
 +
        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 --cmtk
 +
 
 +
-----------------------------------------------------------------------------------------------
 +
3. Run dynamic registration with the 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
 
         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
  
 
-----------------------------------------------------------------------------------------------
 
-----------------------------------------------------------------------------------------------
3. Run dynamic registration with the testdata on a cluster (scheduler command "qsub-run"):
+
4. Run dynamic registration with the testdata on a cluster (scheduler command "qsub"):
  
         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-run
+
         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 -b y"
  
 
-----------------------------------------------------------------------------------------------
 
-----------------------------------------------------------------------------------------------
4. Use existing registrations and just re-sample
+
5. Use existing registrations and just re-sample
  
 
         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
 
         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
Line 265: Line 300:
 
logic.Start(configuration)
 
logic.Start(configuration)
 
</pre>
 
</pre>
 +
 +
By the upcoming release v0.3 it will be possible to configure a vtkMRMLAtlasCreatorNode instead of a configuration object and then invoke a ''vtkMRMLAtlasCreatorNode::LaunchEvent'' to start the calculation.
 +
 +
By release v0.4 the configuration objects will be fully replaced by the MRML node.
 +
 +
== Further Information ==
 +
=== PCA ===
 +
 +
The PCA features are under heavy development. Notes are [[Projects:ARRA:SlicerEM:AtlasCreator:PCA|here]].
 +
 +
=== Groupwise Registration ===
 +
 +
It is planned to integrate groupwise registration. Notes are [[Projects:ARRA:SlicerEM:AtlasCreator:Groupwise|here]].

Latest revision as of 15:33, 15 April 2011

Home < Projects:ARRA:SlicerEM:AtlasCreator

Atlas Creator

The Atlas Creator combines existing segmentations to an anatomical atlas based on robust statistics.

Examples and Tests

Now available at Projects:ARRA:SlicerEM:AtlasCreator:Tests.

GUI

The following screenshot shows the graphical user interface of the Atlas Creator module in 3D Slicer Version 3.

Atlascreator.png

Priority List

The priority list reflects the open issues.

Version 0.4 (current version in Trunk and 3.6Branch)

  1. Re-structure Atlas Creator code according to the Design specified below
  2. Implement dynamic registration
    • Watch out for overflows
  3. Implement support for parallel Computation
  4. Add Help
  5. check how to include C++ code in AtlasCreator
    • create concept
  6. make KilisSandbox work with PCA
  7. include CMTK as alternative (affine) to BRAINSFit
  8. create outputDir automatically
  9. Solve Double/Float Problem
  10. refactor cluster mode to be based on a script
  11. cluster script template is configurable for individual needs
  12. add support for CMTK non-rigid
  13. de-activate CMTK multi-threading in cluster-mode
  14. different wait time for cluster mode for observing finished jobs
  15. don't use Slicer temp dir anymore, use a temp dir in the output dir instead
  16. adding date to print timestamps
  17. return as output as well the normalized intensity maps of aligned cases in the static mode
  18. only resample filenames which exist in registration and vice versa
  19. add the ability to normalize to 0..X instead of only 0..1
  20. create AtlasCreator MRML Node and use a converter to create configuration objects
  21. output status in notify loop
  22. change last step from VTK to ITK
  23. test invokation from EMSegmenter
  24. Include PCA functionality in AtlasCreator
  25. change GUI to use AtlasCreator MRML Node
  26. finish advanced panel in the GUI
  27. replace configuration objects by MRML Node
  28. add watching of submitted jobs (check if job returns 0)
  29. tests!!
  30. Congeal wrapper
  31. added check if Congeal was installed and deactivate the group online mode if not
  32. solve issue in CongealingCLI when running on Windows
  33. downsample testdata
  34. add flag to ignore the templates segmentation in atlascreation
  35. update documentation page

Nice to have in the future:

  1. include group online mode
  2. simplify and reduce command line arguments
    1. save all outputs by default and add flags to specify to not save
  3. enhance performance of ComputeMeanImage ITK code

Design

The following State Machine diagram (slightly outdated) shows the flow of the Atlas Creator logic. It can be run in two modes:

  • Normal mode, all computations on one machine
  • Cluster mode, parallelized computations

AtlasCreatorStateMachine.png


The following class diagram (slightly outdated) shows the structure of the module.

AtlasCreatorClassDiagramm.png

Proposal: Configuration of the Atlas Creator logic

The Atlas Creator supports different modes of operation. For now, we focus on Skip Registration Mode, Normal Mode and Cluster Mode.

To configure an Atlas Creator operation, we introduce configuration containers. The following example shows how to create the configuration:

# configuration for a Normal Mode operation
configuration = AtlasCreatorConfiguration()
# define the parameters
configuration.SetTemplateType("fixed")
...
self._logic.Start(configuration)

# configuration for a Cluster Mode operation
gridConfiguration = AtlasCreatorGridConfiguration()
# define the same parameters as above
gridConfiguration.SetTemplateType("fixed")
...
# and also additional cluster specific parameters
gridConfiguration.SetSchedulerCommand("stageClusterJob.sh")
...
self._logic.Start(configuration)

The logic detects which operation scenario was configured and then adjusts the workflow accordingly. This concept can be easily extended for future operation modes.

Proposal: Running the Atlas Creator in a Grid Environment

The Atlas Creator concept supports parallelized computations. An existing grid environment can be leveraged during the Registration phase as shown in the diagram above.

Only the Registration can be performed parallelized since it is the most time-consuming task in the Atlas Creator pipeline.

The Atlas Creator module runs on one node in the cluster (most likely the head node) and then generates bash scripts which start the registration using the 3D Slicer launch mechanism. These scripts can be run using an existing scheduler or a similar mechanism and use the Python invokation method shown in the section below. An existing $DISPLAY environment is not necessary for using the 3D Slicer launch mechanism.

The module immediately recognizes if the parallelized registration jobs are complete and then continues the pipeline on the node where the it was first started.

The Atlas Creator Command Line Interface

The Atlas Creator comes with a command line interface. This interface can be used by invoking the following command.

# in the source directory
cd Slicer3/Modules/AtlasCreator/

# or in the build directory
cd Slicer3-build/lib/Slicer3/Modules/AtlasCreator/

# start the command line interface
python atlascreator.py

A detailed help system is available by calling python atlascreator.py --help:

21:42:17 daniel@sbia-pc66:~/SLICER/TRUNK/Slicer3/Modules/AtlasCreator$ python atlascreator.py --help
AtlasCreator for 3D Slicer
Version v0.22

Usage:

-h, --help
        Show this information.

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

-s, --segmentations DIR
        Directory containing segmentations.

-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:

        --transforms DIR
                Directory containing existing transforms.

        --existingTemplate FILEPATH
                Filepath to an existing template used for resampling only.

--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
        Use a fixed template for registration.

        The following arguments have to be specified if fixed registration is chosen:

        --template FILEPATH
                Filepath to an image used as a template for fixed registration.

-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
        List of labels to include for the atlases, f.e. "3 4 5 6 8 10".

--normalize
        Normalize Atlases to 0..1.
        If activated, the output cast will be set to Double.

--outputCast INT
        Output cast for the atlases. Possible values:
        0: Char
        1: Unsigned Char
        2: Double
        3: Float
        4: Int
        5: Unsigned Int
        6: Long
        7: Unsigned Long
        8: Short
        9: Unsigned Short
        DEFAULT: 8

-c, --cluster
        Use the cluster mode.

        The following arguments have to be specified if cluster mode is chosen:

        --schedulerCommand EXECUTABLE
                The executable to use as a scheduler in cluster mode, f.e. "qsub".

--slicer FILEPATH
        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
        Enable debug information.

--dryrun
        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!

Usage examples can be displayed by calling python atlascreator.py --examples:

21:42:13 daniel@sbia-pc66:~/SLICER/TRUNK/Slicer3/Modules/AtlasCreator$ python atlascreator.py --examples
AtlasCreator for 3D Slicer
Version v0.22

Examples:
-----------------------------------------------------------------------------------------------
1. Run fixed registration with the testdata:

        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:

        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 --cmtk

-----------------------------------------------------------------------------------------------
3. Run dynamic registration with the 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

-----------------------------------------------------------------------------------------------
4. Run dynamic registration with the testdata on a cluster (scheduler command "qsub"):

        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 -b y"

-----------------------------------------------------------------------------------------------
5. Use existing registrations and just re-sample

        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

Invoking the Atlas Creator logic externally

The Atlas Creator logic can be invoked via Python, f.e. from another 3D Slicer module or the 3D Slicer Python console.

To access the Atlas Creator logic, the following snippet is useful:

from Slicer import slicer

# get the path to the Atlas Creator module
pathToAtlasCreator = str(slicer.Application.GetModulePaths()) + '/AtlasCreator'

# add it to the python sys path
sys.path.append(pathToAtlasCreator)

# import the Atlas Creator module
from AtlasCreatorGUI import *

# instantiate the Atlas Creator gui, needed for debug statements on the console
# and automatically creates the logic
gui = AtlasCreatorGUI()

# get the Atlas Creator logic
logic = gui.GetMyLogic()

# create configuration
configuration = AtlasCreatorConfiguration()
# configure now using the setters...

# work with the logic
logic.Start(configuration)

By the upcoming release v0.3 it will be possible to configure a vtkMRMLAtlasCreatorNode instead of a configuration object and then invoke a vtkMRMLAtlasCreatorNode::LaunchEvent to start the calculation.

By release v0.4 the configuration objects will be fully replaced by the MRML node.

Further Information

PCA

The PCA features are under heavy development. Notes are here.

Groupwise Registration

It is planned to integrate groupwise registration. Notes are here.