brainscdetector:Tutorial
From NITRC Wiki
Return to the BRAINS Constellation Detector main page.
Contents |
Introduction
BRAINS Constellation Detector is developed for registering human brain scans prior to all brain image processing and analysis, such as tissue classification, surface analysis, and diffusion tensor analysis, etc. It also serves as a powerful automated labeling tool to reliably find important landmarks, such as MPJ, AC, PC, etc.
This tutorial provides a practical usage for the software.
More information can be found at:
http://www.nitrc.org/plugins/mwiki/index.php?title=brainscdetector:MainPage or
http://www.nitrc.org/plugins/mwiki/index.php/brains:MainPage
System requirement
- Mac 10.5 or later
- Linux 64-bit
- Windows (TODO)
Prerequisites
To use the software, make sure the following tools are ready to go:
- SVN at http://subversion.apache.org/
- CMake 2.8 or later at http://www.cmake.org/
- Qt 4.6 or later at http://qt.nokia.com/ if GUI needs to be built (recommended)
Download the source code
The source code can be checked out by:
svn co https://www.nitrc.org/svn/brains/StandAloneApps/StandAloneBRAINSConstellationDetector
Build the project
Compile and set environment variables for the project
For Mac users
type:
mkdir bcd-build \ cd bcd-build \ cmake -C ../StandAloneBRAINSConstellationDetector/InitialCache-OSX64.cmake \ ../StandAloneBRAINSConstellationDetector
For Linux users
type:
mkdir bcd-build \ cd bcd-build \ cmake -C ../StandAloneBRAINSConstellationDetector/InitialCache-Linux64.cmake \ ../StandAloneBRAINSConstellationDetector
Build GUI
If GUI is needed (recommended), further run (Else, skip to the next step)
ccmake ../StandAloneBRAINSConstellationDetector
In ccmake GUI interface, make sure
- BUILD_WITH_GUI is set to ON.
- QT_QMAKE_EXECUTABLE is set correctly.
An example ccmake screenshot is shown below.
Build the project by make
make -j8
Practical usage
Run tests
One might want to ensure that the software was built correctly by running some tests
cd BRAINSConstellationDetector-build \ ctest -D Experimental
View help
To view detailed command line usage for the detector and GUI, type
cd ../bin/ \ ./BRAINSConstellationDetector -h \ ./BRAINSConstellationDetectorGUI -h
Use cases
Regular use
The following command will automatically detect some important landmarks for a test MRI T1 image, and generate an AC-PC aligned and resampled image
./BRAINSConstellationDetector \ --inputVolume ../../StandAloneBRAINSConstellationDetector/BRAINSConstellationDetector/tutorial/1.nii.gz \ --outputResampledVolume resampled-1.nii.gz \ --outputLandmarksInACPCAlignedSpace resampled-1.fcsv
A sample debug log is show as follows:
Verifying input parameters... Set modelFilename to default: ./T1.mdl Set llsModelFilename to default: ./llsModel.txt \ Reading in external files... \ Loading image... Processing: ../../StandAloneBRAINSConstellationDetector/BRAINSConstellationDetector/tutorial/1.nii.gz \ Finding center of head mass... ListSample TotalFrequency is 9830400 1329 ValidHistogramsEntries, 9830400 TotalFrequency 0.01 ---> 0 0.99 ---> 572 LowHigh Thresholds: [0,195,572] maxSIDirection = 144.462 Computing Sampled Distance Computations \ Finding eye centers with BRAINS Hough Eye Detector... The resulted interpupilary distance is 61.2361 mm \ Finding named points with BRAINS Constellation Detector... RP template size = 891 voxels AC template size = 891 voxels PC template size = 891 voxels VN4 template size = 891 voxels Search Radii [ RP, AC, PC, VN4 ] will be 5 5 10 5 \ Estimating MSP... Level 0 Quality Estimates -0.518051 0.51826 -1.62277 cc= -0.964529 iters= 608 Level 1 Quality Estimates -0.439915 0.51826 -1.50766 cc= -0.928358 iters= 763 Level 2 Quality Estimates -0.710796 0.409686 -1.496 cc= -0.861804 iters= 883 \ Performing local search... The estimated MSP error in LR direction: 0.777928 mm Local search radius in LR direction is set to 1 mm. \ Writing results to files... The resampled output volume is written. The landmarks file in the output space is written.
To view the result with the GUI tool, type
./BRAINSConstellationDetectorGUI \ --inputVolume resampled-1.nii.gz \ --inputLandmarks resampled-1.fcsv
Note, the user can also manipulate landmarks and save the result for further processing, but we will discuss these topics later. To see its usage, click the "Help" button.
In case the automated detection fails
Sometimes, the detector may fail due to various reasons. We will show how to deal with this situation step by step:
Run detector for another "bad" input image with normal process by
./BRAINSConstellationDetector \ --inputVolume ../../StandAloneBRAINSConstellationDetector/BRAINSConstellationDetector/tutorial/2.nii.gz \ --outputResampledVolume resampled-2.nii.gz \ --outputLandmarksInACPCAlignedSpace resampled-2.fcsv
You will find that the resampled output image is not generated because a problem has been detected by the detector. One might notice the debug information as follows:
... Finding eye centers with BRAINS Hough Eye Detector... The resulted adult interpupilary distance is 29.6966 mm The distance is abnormal! Get ready to use a GUI corrector next. ...
If you look at the original input image, you might notice that the part of the eye contents of the image is cut off.
Unfortunately, the current version must fail if similar thing happens to the input image due to its heavy reliance on eye centers information. However, we can use the GUI tool to correct any bad landmarks and ask the detector to load the information and skip any estimation steps for the enlisted landmarks (in our case, the eye centers). There are roughly two kinds of situations one might encounter:
- If the detector generates a bad output and it realize the problem (as in this tutorial example), skip to the next step.
- If the detector generates a bad output due to "missing eyes" in the scan and it
has not realize it (not in this example), we can force it to skip the eye detection step and stop right after the essential files for correction are written. To do this for our example, type
./BRAINSConstellationDetector \ --inputVolume ../../StandAloneBRAINSConstellationDetector/BRAINSConstellationDetector/tutorial/2.nii.gz \ -f
To correct the landmarks, first we need to load an image file named EMSP.nii.gz and a landmark file named EMSP.fcsv in the debug image directory that we requested in the previous step, which if is not specified will be in the current directory. So, in our example, we can correct the landmarks by running
./BRAINSConstellationDetectorGUI \ --inputVolume EMSP.nii.gz \ --inputLandmarks EMSP.fcsv
One should see the image in the estimated mid-sagittal plane aligned space along with two zero eye center landmarks.
Then we correct the landmarks manually in the GUI tool. Click a landmark in the list to pick its label in the viewer and then, move the corresponding label in the viewers to the right place (A rough position is good enough).
The user can also perform a zoom in/out to get a more accurate manipulation by a right click to a viewer and then drag upwards/downwards.
Click the save button to save the result to file when finished.
Finally, we are able to get a corrected resampled image and a corresponding landmarks file by adding an overriding landmarks argument (--loadLandmarksEMSPFilename) at the end of the command we normally use
./BRAINSConstellationDetector \ --inputVolume ../../StandAloneBRAINSConstellationDetector/BRAINSConstellationDetector/tutorial/2.nii.gz \ --outputResampledVolume resampled-2.nii.gz \ --outputLandmarksInACPCAlignedSpace resampled-2.fcsv --inputLandmarksEMSP EMSP.fcsv
Another thing one might be interested in is that the detector can actually skip any landmark estimation steps other than the two eye centers as long as the landmarks are enlisted in the landmarks file and the file is loaded with a --loadLandmarksEMSPFilename argument to the detector. Of course, the GUI tool provides the user with such a functionality to add/ remove/modify any landmarks for the input image. If for example, one pass the manually labeled file containing the position of AC, PC, and MPJ to the detector, it will directly use these three points to calculate the rigid transform to get a AC-PC aligned image. The following command will generate the correction "EMSP" files if at least the eye detection process succeeds:
./BRAINSConstellationDetector \ --inputVolume ../../StandAloneBRAINSConstellationDetector/BRAINSConstellationDetector/tutorial/2.nii.gz \ --outputResampledVolume resampled-2.nii.gz \ --outputLandmarksInACPCAlignedSpace resampled-2.fcsv -w 2
Then, use a similar "loading landmarks to GUI" command and a "overriding landmarks in the detector" command we mentioned before to obtain a correct result.
Return to the BRAINS Constellation Detector main page.
