Automatic Processing Using Command-Line
To process multiple scans at once and/or run BrainSuite on a remote machine, it is often easier to run CSE via the command-line. The Bash script cortical_extraction.sh is provided with the BrainSuite program from our download site to make this process easier.
Note that
cortical_extraction.sh assumes that BrainSuite has been installed in the user’s home directory. If this is not the case, be sure to either set the BRAINSUITEPATH environment variable or edit cortical_extraction.sh to look in the right place for the files.Assuming that you’re in the directory with the scan you wish to process, run the script with:
~/brainsuite/cortical_extraction.sh subject_mri.nii.gzwhere subject_mri.nii.gz is the filename of the scan you wish to process. If you’re not in the same directory as the scan (e.g. if you’re writing a script to process many scans at once), include the full path to the file with the file name. Running cortical_extraction.sh this way produces the same result as automatically processing a scan with the GUI (i.e. it uses the same default parameters as the GUI version). After it finishes running, check out the results in BrainSuite or the viewer of your choice.
Manual Processing Using Command-Line
The command-line version of CSE also allows manual adjustment of each module’s parameters, similar to the manual adjustments available via the GUI. To do so, edit the cortical_extraction.sh file.
-
Copy the
cortical_extraction.shfile to a new working directory (such as the directory with the scans you wish to process).
Since you will be editing the file, it is usually helpful to keep a copy of the original, in case you want to use the default parameters for another study later. There is no need to copy the bin or atlas directories as well. -
Open the copied
cortical_extraction.shfile in your favorite text editor -
Edit the parameters you wish to change
- VERBOSE: verbosity level and timer flag
- BSEFILES: mask file
- BSEOPTIONS: parameters for skull stripping (BSE)
- BFCOPTIONS: parameters for bias field correction (BFC)
- PVCOPTIONS: parameters for tissue classification (PVC)
- PVCFILES: filename for saving the partial volume fraction file
- CEREBROOPTIONS: parameters for cerebrum/cerebellum labeling tool
- ATLAS: atlas file for cerebrum extraction
- ATLASLABELS: label file for cerebrum extraction
- ATLASES: sets up ATLAS and ATLASLABELS for cerebrum/cerebellum labeling
- WARPS: filenames for saving cerebrum extraction affine and warp transforms
- PIALINPUT: filename of inner cortical surface used for generating pial surface
- PIAL: filename of generated pial surface
- GMSINPUTS: input files for pial surface generation
- GMSOUTPUTS: output file of pial surface generation
- LEFTINRCTX: filename for left inner cortical generated by hemisphere splitting
- RIGHTINRCTX: filename for right inner cortical surface generated by hemisphere splitting
- LEFTPIAL: filename for left pial surface generated by hemisphere splitting
- RIGHTPIAL: filename for right pial surface generated by hemisphere splitting
- INNERHEMI: inner cortical surface files output by hemisphere splitting
- OUTERHEMI: pial surface files output by hemisphere splitting
Other parameters can be changed using the flags explained below.
- Save and run
cortical_extraction.sh. Assuming that you’re in the directory with the cortical_extraction script, you run it with:./cortical_extraction.sh subject_mri.nii.gzwhere subject_mri.nii.gz is the filename of the scan you wish to process. If you’re not in the same directory as the scan (e.g. if you’re writing a script to process many scans at once), include the full path to the file with the file name.
- Check the results. Open up the results in BrainSuite or the viewer of your choice to make sure everything worked
Command-Line Parameters
[ bse | bfc | pvc | cerebro | cortex | scrubmask | tca | dewisp | dfs | dfsmooth | topocheck | gms | hemisplit ]
bse : brain surface extractor (BSE)^top
This program automatically skull-strips a T1-weighted image.
This program automatically skull-strips a T1-weighted image.
usage: bse [settings]
Required Settings
| Flags | Description |
|---|---|
-i <input filename> |
input MRI volume |
Optional Settings
| Flags | Description |
|---|---|
-d <float> |
diffusion constant [default: 25] |
-o <output filename> |
output brain-masked MRI volume |
-n <iterations> |
diffusion iterations [default: 3] |
-s <edge sigma> |
edge detection constant [default: 0.62] |
-r <size> |
radius of erosion/dilation filter [default: 1] |
-p |
dilate final mask |
--trim |
trim brainstem |
--noneck |
remove neck (assumes LPI orientation) |
--mask <filename> |
save smooth brain mask |
--adf <filename> |
diffusion filter output |
--edge <filename> |
edge map output |
--hires <filename> |
save detailed brain mask |
--cortex <filename> |
cortex file |
-v <number> |
verbosity level (0=silent) [default: 1] |
--norotate |
retain original orientation (default behavior will auto-rotate input NII files to LPI orientation |
--timer |
show timing |
example:
bse -i input_mri.img -o skull_stripped_mri.img
bfc : bias field corrector (BFC)^top
This program corrects gain variation in T1-weighted MRI.
This program corrects gain variation in T1-weighted MRI.
usage: bfc [settings]
required settings:
| Flags | Description |
|---|---|
-i <input filename> |
input skull-stripped MRI volume |
-o <output filename> |
output bias-corrected MRI volume |
optional settings:
| Flags | Description |
|---|---|
-m <mask filename> |
mask file |
--bias <output filename> |
save bias field estimate |
--maskedbias <output filename> |
save bias field estimate (masked) |
-r <radius> |
histogram radius (voxels) [default: 12] |
-s <spacing> |
bias sample spacing (voxels) [default: 16] |
-c <spacing> |
control point spacing (voxels) [default: 64] |
-w <strength> |
spline stiffness weighting parameter [default: 0.0001] |
--ellipse |
use ellipsoid for ROI histogram |
--block |
use block for ROI histogram |
--iterate |
iterative mode (overrides -r, -s, -c, -w settings) |
--schedule <schedule_file> |
list of parameters |
--biasprefix <prefix> |
save iterative bias field estimates as <prefix>.n.field.nii.gz |
--prefix <prefix> |
save iterative corrected images as <prefix>.n.bfc.nii.gz |
--extrapolate |
apply correction field to entire volume |
-L <lower> |
minimum allowed bias value [default: 0.5] |
-U <upper> |
maximum allowed bias value [default: 1.5] |
--low |
small bias model [0.95,1.05] |
--medium |
medium bias model [0.90,1.10] |
--high |
high bias model [0.80,1.20] |
--analyze |
generate intermediate files in Analyze format |
--nifti |
generate intermediate files in Nifti format |
--analyzegz |
generate intermediate files in gzipped Analyze format |
--niftigz |
generate intermediate files in gzipped Nifti format |
--eps <epsilon> |
convergence threshold [default: 1e-06] |
--beps <bias_epsilon> |
bias estimate convergence threshold (values > 0.1 disable) [default: 0] |
-v <number> |
verbosity level (0=silent) [default: 1] |
--timer |
display timing information |
notes:
For anisotropic voxels, distances are scaled based on the smallest dimension.
Iterative mode will run multiple passes of BFC using a range of settings to correct for severe artifacts.
pvc : partial volume classifier (PVC) tool.^top
This program performs voxel-wise tissue classification T1-weighted MRI.
Image should be skull-stripped and bias-corrected before tissue classification.
This program performs voxel-wise tissue classification T1-weighted MRI.
Image should be skull-stripped and bias-corrected before tissue classification.
usage: pvc [settings]
required settings:
| Flags | Description |
|---|---|
-i <input MRI> |
MRI file |
optional settings:
| Flags | Description |
|---|---|
-m <mask file> |
brain mask file |
-o <label file> |
output label file |
-f <fraction file> |
output tissue fraction file |
-l <lambda> |
spatial prior strength [default: 0.1] |
-v <level> |
verbosity level (0 = silent) [default: 1] |
-3 |
use a three-class (CSF=0,GM=1,WM=2) labeling |
--timer |
time processing |
example:
pvc -i mri.img -o mri.label.img -f mri.frac.img
notes:
Input MRI should be skull stripped or a mask should be specified.
Output tissue label volume is an 8-bit label file using the values:
0 (CSF), 1 (GM), 2 (WM), 3 (GM/CSF), 4 (GM/WM), 5 (CSF/Other), 8 (Background)
Tissue fractions are saved as a 32-bit floating point volume:
0 (BKG) 1 (CSF) <-> 2 (GM) <-> 3 (WM)
cerebro : Cerebrum/cerebellum labeling tool^top
This program performs automated labeling of cerebellum and cerebrum in T1 MRI.
Input MRI should be skull-stripped or a brain-only mask should be provided.
This program performs automated labeling of cerebellum and cerebrum in T1 MRI.
Input MRI should be skull-stripped or a brain-only mask should be provided.
usage: cerebro [settings]
required settings:
| Flags | Description |
|---|---|
-i <input MRI> |
input 3D MRI volume |
--atlas <atlas MRI file> |
atlas MRI volume |
--atlaslabels <label file> |
atlas labeling |
optional settings:
| Flags | Description |
|---|---|
-m <mask file> |
brain mask file* |
-o <output mask> |
output cerebrum mask volume* |
-l <label file> |
output labeled hemisphere/cerebrum volume |
-c <cost function> |
0,1,2 [default: 1] |
--air <output air file> |
save affine transform to file. |
--warp <output warp file> |
save warp transform to file. |
-v <level> |
verbosity level (0=silent) [default: 1] |
--linconv <value> |
linear convergence [default: 0.1] |
--warplevel <order> |
warp order (2,3,4,5,6,7,8) [default: 5] |
--warpconv <warpconv> |
warp convergence [default: 100] |
--keep |
don't remove temporary files |
--tempdir <directory> |
specify directory to use for temporary files |
--tempdirbase <directory> |
create a temporary directory within this directory |
notes:
The input MRI should be skull-stripped or a brain mask file should be used.
The atlas is also expected to be skull stripped.
(*) either an output mask file or an output label file is required.
Cerebro makes use of the AIR5.2.5 library, developed by Roger P Woods, MD
cortex : cortex extractor^top
This program produces a cortical mask using tissue fraction estimates and a co-registered cerebellum/hemisphere mask.
This program produces a cortical mask using tissue fraction estimates and a co-registered cerebellum/hemisphere mask.
usage: cortex [settings]
required settings:
| Flags | Description |
|---|---|
-h <label file> |
hemisphere / lobe label volume |
-o <mask file> |
output structure mask |
-f <fraction file> |
tissue fraction file (32-bit float) |
optional settings:
| Flags | Description |
|---|---|
-p <percentage> |
tissue fraction threshold (percentage) [default: 50] |
-w |
compute WM/GM boundary |
-g |
compute GM/CSF boundary |
-v <verbosity> |
verbosity level [default: 1] |
--timer |
timing function |
scrubmask : ScrubMask tool.^top
This program filters binary masks to trim loosely connected voxels that may result from segmentation errors and produce bumps on tessellated surfaces.
This program filters binary masks to trim loosely connected voxels that may result from segmentation errors and produce bumps on tessellated surfaces.
usage: scrubmask [settings]
required settings:
| Flags | Description |
|---|---|
-i <mask file> |
input structure mask file |
-o <mask file> |
output structure mask file |
optional settings:
| Flags | Description |
|---|---|
-b <threshold> |
background fill threshold [default: 1] |
-f <threshold> |
foreground trim threshold [default: 1] |
-n <iterations> |
number of iterations [default: 10] |
-v <level> |
verbosity (0=silent) [default: 1] |
--timer |
timing function |
tca : topological correction algorithm (TCA)^top
This program removes topological handles from a binary object.
Algorithm created by David W Shattuck and Richard M Leahy
This program removes topological handles from a binary object.
Algorithm created by David W Shattuck and Richard M Leahy
usage: tca [settings]
required settings:
| Flags | Description |
|---|---|
-i <input filename> |
input mask volume |
-o <output filename> |
output mask volume |
optional settings:
| Flags | Description |
|---|---|
-m <n> |
maximum correction size [default: 200] |
-n <n> |
minimum correction size [default: 1] |
--delta <delta> |
foreground delta [default: 0] |
-v <level> |
verbosity (0 = quiet) [default: 1] |
--timer |
timing function |
dewisp : Dewisp^top
This program removes wispy tendril structures from cortex model binary masks. It does so based on graph theoretic analysis of connected components, similar to TCA. Each branch of the structure graph is analyzed to determine pinch points that indicate a likely error in segmentation that attaches noise to the image. The pinch threshold determines how many voxels the cross-section can be before it is considered part of the image.
This program removes wispy tendril structures from cortex model binary masks. It does so based on graph theoretic analysis of connected components, similar to TCA. Each branch of the structure graph is analyzed to determine pinch points that indicate a likely error in segmentation that attaches noise to the image. The pinch threshold determines how many voxels the cross-section can be before it is considered part of the image.
usage: dewisp [settings]
required settings:
| Flags | Description |
|---|---|
-i <file> |
input file |
-o <file> |
output file |
optional settings:
| Flags | Description |
|---|---|
-g |
debug |
-v <level> |
verbosity [default: 0] |
-t <threshold> |
size threshold [default: 15] |
-n <iterations> |
maximum number of iterations [default: 10] |
--timer |
time processing |
dfs : Surface Generator^top
This program generates mesh surfaces using an isosurface algorithm.
This program generates mesh surfaces using an isosurface algorithm.
usage: dfs [settings]
required settings:
| Flags | Description |
|---|---|
-i <input volume> |
input 3D volume |
-o <output surface> |
output surface mesh file |
optional settings:
| Flags | Description |
|---|---|
-c <image volume> |
shade surface model with data from image volume |
-n <value> |
number of smoothing iterations [default: 10] |
-a <value> |
smoothing constant [default: 0.5] |
-f <value> |
scaling percentile [default: 0.999] |
-nz |
tessellate non-zero voxels |
-gt <threshold> |
tessellate voxels greater than <threshold> |
-lt <threshold> |
tessellate voxels less than <threshold> |
-eq <value> |
tessellate voxels equal to <value> |
-z |
zero-pad volume (avoids clipping at edges) |
--nonormals |
do not compute vertex normals |
--postsmooth |
smooth vertices after coloring |
-v <level> |
verbosity (0 = quiet) [default: 1] |
--timer |
timing function |
notes:
if the -c option is specified, a set of vertex colors is generated within the file.
dfsmooth : DFSSmooth^top
This program is an alternate surface smoother.
This program is an alternate surface smoother.
usage: dfsmooth [settings]
required settings:
| Flags | Description |
|---|---|
-i <file> |
input file |
-o <file> |
output file |
optional settings:
| Flags | Description |
|---|---|
-g |
debug |
-v <level> |
verbosity [default: 0] |
-n <iterations> |
number of smoothing iterations [default: 10] |
-a <alpha> |
smoothing constant [default: 0.5] |
-c <weighting> |
curvature weighting [default: 5] |
--timer |
timer function |
topocheck : Topology Check^top
This program tests the topological properties of a surface file.
This program tests the topological properties of a surface file.
usage: topocheck [settings]
required settings:
| Flags | Description |
|---|---|
-i <input_file> |
input surface file |
optional settings:
| Flags | Description |
|---|---|
-o <output_file> |
output surface file with colors indicating border points |
notes:
input formats: surface files (.dfs, .obj)
gms11a : Pial Surface Generation^top
This program computes a pial surface model using an inner WM/GM mesh and a tissue fraction map.
This program computes a pial surface model using an inner WM/GM mesh and a tissue fraction map.
usage: gms11a [settings]
required settings:
| Flags | Description |
|---|---|
-i <file> |
input file |
-o <file> |
output file |
-f <fraction file> |
floating point (32) tissue fraction image |
-m <mask file> |
restrict growth to mask file region |
optional settings:
| Flags | Description |
|---|---|
-g |
debug |
-v <level> |
verbosity [default: 0] |
-n <n> |
number of iterations [default: 10] |
-r <radius> |
search radius [default: 2] |
-s <step size> |
step size [default: 0.1] |
--max <thickness> |
maximum allowed tissue thickness [default: 10] |
-t <threshold> |
tissue threshold [default: 1.1] |
--interval <n> |
output interval [default: 0] |
--prefix <prefix> |
prefix for exporting surfaces if interval is set |
--smooth <smoothing constant> |
apply Laplacian smoothing [default: 0.1] |
--timer |
show timing |
--norm |
recompute normals at each iteration |
--nc <normal_constant> |
strength of normal smoother. [default: 0] |
--tc <tangential_constant> |
strength of tangential smoother. [default: 0] |
hemisplit11a : Hemisphere splitter.^top
usage: hemisplit11a [settings]
required settings:
| Flags | Description |
|---|---|
-i <surface> |
input surface |
-l <volume> |
input hemisphere label volume |
--left <surface> |
output surface file, left hemisphere |
--right <surface> |
output surface file, right hemisphere |
optional settings:
| Flags | Description |
|---|---|
-p <input_pial_surface> |
pial surface file—must have same geometry as input surface |
-pl <surface> |
output pial surface file, left hemisphere |
-pr <surface> |
output pial surface file, right hemisphere |
-v <level> |
verbosity (0 = silent) [default: 1] |
--timer |
timing function |
notes:
Splits a surface object into two separate surfaces given an input label volume.
Each vertex is labeled left or right based on the labels being odd (left) or even (right).
The largest contour on the split surface is then found and used as the separation between
left and right.