Modules:EM-Segmenter-Documentation:FAQ

From SlicerWiki

Jump to: navigation, search

Contents

About this FAQ

This FAQ is intended to answer questions about the EMSegmenter implementations in Slicer3. It also covers some related topics like how to create surfaces from your segmentation results. It is not intended to be a complete description or tutorial for the EMSegmenter algorithm; see the Getting More Information and Help section of the FAQ for other EMSegmenter resources.

If you have a question that you would like answered or added to this FAQ please email the Slicer users' list.

Getting More Information or Help

The EMSegmenter must be configured properly to work on new data; the configuration process can be complicated and require a number of steps. Improper configuration will lead to poor results. Here are some links to resources that will get you started:

  • Read the Frequently Asked Questions from this page
  • Read the scientific papers that describe the EMSegmenter algorithm and its use on medical data [TODO: add link]
  • Post a query to the Slicer users' list
  • Add a bug or feature request to the bug tracker (or browse current issues); note that there is a special EMSegmenter bug category
  • Work through the EMSegmenter tutorials linked from the Slicer3 training page

How Do I Get Started?

Would you like to try out the EMSegmenter? Follow these instructions to create your first segmentation. Once you've completed these steps, you will be able to explore further by modifying segmentation parameters and/or segmenting new images.

  1. Start with a computer that has at least 2GB of RAM. 4GB or better is preferred.
  2. Get a copy of Slicer3 and the EMSegmenter brain segmentation tutorial
    1. Build or download a recent copy of Slicer3 [TODO: link] (we'll call the Slicer3 build directory $SLICER_BUILD_DIR)
    2. Download and unzip a copy of the brain segmentation tutorial [TODO: link] (we'll call the directory $EM_TUTORIAL_DIR)
    3. Create a playpen directory on your computer for segmentation results and intermediate files (we'll call it $PLAYPEN_DIR)
  3. Start Slicer3 and load the tutorial dataset (TODO break out to new FAQ: NOTE: the tutorial dataset contains image data, atlas data, and segmentation parameters)
    1. From Slicer3 choose File->Import Scene
    2. Browse to the $EM_TUTORIAL_DIR and select the MRML scene that contains the tutorial data and parameters: TODO: what is the filename
    3. Click OK; once the data is loaded you should be able to view the images in Slicer's 2D and 3D visualization widows
  4. Load the EMSegmenter Template Builder and run the Segmentation
    1. From the modules directory select Segmentation->EMSegmenter Template Builder
    2. The template builder contains a number of steps; at each step segmentation parameters can be modified. For now, don't modify the parameters; they are already set up to work for the tutorial dataset because you loaded the tutorial data MRML scene. Instead, read the description of each step and look at the parameters so that you can begin to get used to them. Click Next to move from step to step until you are at the last step labeled TODO.
    3. On the last step you should choose a volume that you want to contain the segmentation results. Click on the pull-down labeled TODO and select TODO. You will be able to rename the volume later if you wish.
    4. Now click TODO start the segmentation process. It will take approximately TODO minutes to complete on a TODO machine.
  5. View the segmentation results


  1. Locate tutorial parameter file and data on disk (e.g., $EM_TUTORIAL_DIR=/playpen/EMSegmentTutorial)
  2. Locate EMSegmenterCommandLine executable (e.g., $SLICER_BUILD_DIR/bin/EMSegmenterCommandLine)
  3. Locate your target image data (volumes to be segmented) on disk (e.g., $MY_DATA_DIR/T1Volume.mhd)

Preprocessing Questions

Should I use the default preprocessing?

If you want to use intensity normalization or image registration within your segmentation pipeline, it is best if you do this outside of the EMSegmenter tool. Default intensity normalization and registration methods are available. However, these steps are highly dependent on the type of data used---what will work for some applications will fail miserably for others.

Visualization

How do I view the tutorial input data?

  1. Start Slicer3
  2. File->Import Scene...; Select $EM_TUTORIAL_DIR/Data/EMSegmenterTutorial_New.mrml
  3. Use Slicer3 visualization tools to inspect images


How do I view segmentation results?

  1. Be sure to run the segmenter first to produce results (e.g., a volume named TutorialSegmentation)
  2. Select the first target volume for display
  3. Select the segmentation results volume in the Labelmap chooser
  4. Adjust opacity of the labelmap
  5. (Optional) Generate and display surfaces from the segmentation results
    1. Select the "Model Generation" -> "Model Maker" module
    2. For "Input Volume", select the TutorialSegmentation (or whatever the segmentation results are called) volume
    3. For "Output Directory", create and select $PLAYPEN_DIR/Models
    4. For "Model Scene File", select $PLAYPEN_DIR/Models.mrml
    5. Enable "Generate All Models"
    6. Set "End Label" to the highest label that you produced (e.g., 8 fro the tutorial)
    7. Enable "Joint Smoothing"
    8. Click on Apply (this will generate the models and will take approximately 5 minutes)
    9. Load the models into Slicer (File->Import Scene; select $PLAYPEN_DIR/Models.mrml)
    10. Use The Models module to manipulate display attributes


EMSegment Simple Module

How do I segment my target images using the tutorial parameters?

  1. Load Slicer
  2. Import the tutorial parameters (File->Import Scene...)
  3. Load your target volumes (File->Add Volumes...)
  4. Choose the Segmentation->EMSegment Simple Module
  5. Select the tutorial parameter set
  6. Select your images as the first two input channels (the tutorial is specifically for exactly two input channels)
  7. Click 'Run'

Note that the target volumes must be specified in the same order as they are specified in the parameter set.


Template Builder Module

Command Line Interface

How do I segment the tutorial data from the command line?

Segmenting the tutorial data is a good way to test that you have everything setup properly. It is also a good way to experiment with viewing segmentation results.

  1. Change to your playpen directory and run the segmentation. Specify the tutorial parameters using the mrmlSceneFileName flag. By default use the tutorial data. Specify the name of the segmentation result volume. (This step takes approximately 10 minutes on a dual-core 3GHz computer). 
cd $PLAYPEN_DIR
$SLICER_BUILD_DIR/bin/EMSegmenterCommandLine                                  \
  --mrmlSceneFileName $EM_TUTORIAL_DIR/Data/EMSegmentTutorialTemlate_New.mrml \
  --resultVolumeFileName TutorialSegmentation.mhd
  1. Visualize the results
    1. Start Slicer3
    2. Import the tutorial MRML scene (File->Import Scene...)
    3. Load segmentation result (File->AddVolume; Select $PLAYPEN_DIR/TutorialSegmentation.mhd; Check "LabelMap")
    4. Use slicer visualization tools to compare first input channel with segmentation

How do I save and view intermediate results?

Saving intermediate results is a good way to troubleshoot image normalization and registration problems. To save intermediate results, simply add a flag to the command line specifying the output directory. 

cd $PLAYPEN_DIR
mkdir IntermediateResults
$SLICER_BUILD_DIR/bin/EMSegmenterCommandLine                                  \
  --mrmlSceneFileName $EM_TUTORIAL_DIR/Data/EMSegmentTutorialTemlate_New.mrml \
  --resultVolumeFileName TutorialSegmentation.mhd                             \
  --intermediateResultsDirectory IntermediateResults

You can view the intermediate results by starting Slicer3 and loading the $PLAYPEN_DIR/IntermediateResults/EMSegmenterScene.mrml.

How do I segment my target images using the tutorial parameters?

By default, if you specify the tutorial parameters then the tutorial data is used. To use new data, specify your target input images on the command line. 

cd $PLAYPEN_DIR
mkdir IntermediateResults
$SLICER_BUILD_DIR/bin/EMSegmenterCommandLine                                  \
  --mrmlSceneFileName $EM_TUTORIAL_DIR/Data/EMSegmentTutorialTemlate_New.mrml \
  --resultVolumeFileName TutorialSegmentation.mhd                             \
  --targetVolumeFileNames $MY_DATA_DIR/T1Volume.mhd,$MY_DATA_DIR/T2Volume.mhd

Note that the target volumes must be specified in the same order as they are specified in the parameter set.

How do I specify pre-aligned atlas (spatial prior) volumes?

The EMSegmenter can register the tutorial atlas to your data. If you do not want to use this default registration but instead use a specialized registration method to align the atlas (or use a new atlas that is already aligned), you can specify the aligned atlas images on the command line. 

cd $PLAYPEN_DIR
mkdir IntermediateResults
$SLICER_BUILD_DIR/bin/EMSegmenterCommandLine                                  \
  --mrmlSceneFileName $EM_TUTORIAL_DIR/Data/EMSegmentTutorialTemlate_New.mrml \
  --resultVolumeFileName TutorialSegmentation.mhd                             \
  --targetVolumeFileNames $MY_DATA_DIR/T1Volume.mhd,$MY_DATA_DIR/T2Volume.mhd \
  --atlasVolumeFileNames                                                      \
    atlasBackgroundReg.mhd,atlasBackgroundReg.mhd,atlasCSFReg.mhd,atlasGreymatterReg.mhd,atlasWhitematterReg.mhd

Note that the atlas volumes must be specified in the same order as they are specified in the parameter set.

How do I change segmentation parameters from the command line?

You can specify full parameter sets on the command line using the --mrmlSceneFileName flag. The command line interface is not designed to allow changes of individual algorithm parameters. Use the EMSegment template builder if you want to alter individual parameters. After the parameters are fixed in the template builder, you can save the MRML scene and use this new parameter set from the command line.

The segmentation results are compressed but I wanted an uncompressed volume, what should I do?

Add the --disableCompression flag.

Retrieved from "http://www.slicer.org/slicerWiki/index.php/Modules:EM-Segmenter-Documentation:FAQ"
Personal tools
Toolbox