cse: command line

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.gz

where 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.

  1. Copy the cortical_extraction.sh file 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.
  2. Open the copied cortical_extraction.sh file in your favorite text editor
  3. 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.

  4. 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.gz

    where 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.

  5. Check the results. Open up the results in BrainSuite or the viewer of your choice to make sure everything worked

Command-Line Parameters

bse : brain surface extractor (BSE)^top
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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.