## Note: This page was created with the CommandTemplate
##
## If you're modifying this page please take a look at the
## latest version of CommandTemplate to ensure that you're
## using the latest version of the CommandTemplate
##
## See HelpOnCommandTemplate for description of formatting
'''Index''' <<TableOfContents>>

= Name =
mri_binarize

= Description =
Program to binarize a volume (or volume-encoded surface file). Can also
be used to merge with other binarizations. Binarization can be done
based on threshold or on matched values.

= Synopsis =
mri_binarize --i <invol> --o <outvol> 

= Arguments =
== Required Flagged Arguments ==
||--i <invol>|| input volume to be binarized ||
||--o <outvol>|| path to output volume ||

== Optional Flagged Arguments ==
||--min || Minimum voxel threshold (default is -infinity) || Cannot be used with --match ||
||--max || Maximum voxel threshold (default is infinity) || Cannot be used with --match ||
||--pct P || Set threshold to capture top P% (in mask or total volume) || Set min threshold so that the top P percent of the voxels are captured in the output mask. The percent will be computed based on the number of voxels in the volume (if not input mask is specified) or within the input mask. ||
||--rimin rmin || Compute minimum based on rmin*globalmean || ||
||--rmax rmax || Compute maximum based on rmax*globalmean || ||
||--fdr fdrthres || Compute min based on FDR assuming -log10(p) input. --fdr-pos, -fdr-neg, fdr-abs (use only pos, neg, or abs). Abs is the default. || Set min threshold to achieve a given FDR. By default, it uses the absolute value but this can be changed with --fdr-pos and --fdr-neg. If a mask is passed, it will compute the voxel-wise threshold only with in the places where mask > 0.5.  The mask threshold will be ignored. ||
||--match matchval <matchval2 ...> || Use match instead of threshold || Binarize based on matching volumes. Any number of match values can be specified. Cannot be used with --min/--max. ||
||--replaceonly V1 V2 || Replace voxels equal to V1 with V2 and propagate other src voxels instead of binarizing || ||
||--replace V1 V2 || Replace voxels equal to V1 with V2 || Replace every occurrence of (int) value V1 with value V2. Multiple --replace args are possible. ||
||--ctx-wm || Set match vals to 2, 41, 77, 251-255 (aseg for cerebral WM) || ||
||--all-wm || Set match vals to 2, 41, 77, 251-255, 7, and 46 (aseg for all WM) || ||
||--ventricles || Set match vals those for aseg ventricles+choroid (not 4th) || ||
||--wm+vcsf || WM and ventricular CSF, including choroid (not 4th) || ||
||--gm || Match for all Wm and VCSF and background, then invert || ||
||--subcort-gm || Subcortical gray matter || ||
||--count countfile|| Save number of hits in ascii file || Four numbers are saved: the number of voxels that match(nhits), the volume of the voxels that match, the total number of voxels in the volume (nvoxtot), and the percent matching (100*nhits/nvoxtot). ||
||-no-count || Turn off counting number of voxels in the first frame (good for large volumes) || ||
||--binval val || Set voxels within threshold to val (default is 1) || Value to use for those voxels that are in the threshold/match (--binval) or out of the range (--binvalnot). These must be integer values. ||
||--binvalnot notval || Set voxels outside range to notval (default is 0) || Value to use for those voxels that are in the threshold/match (--binval) or out of the range (--binvalnot). These must be integer values. Only applies when a merge volume is NOT specified. ||
||--inv || set binval=0, binvalnot=1 || ||
||--frame frame# || Use 0-based frame of input (default is 0) || ||
||--frame-sum || Sum frames together before binarizing || Sum the frames together before applying threshold ||
||--frame-and || Take intersection (AND) of frames || You do not need to specify a --min (the min will be set to nframes-0.5). Treat the multi-frame volume as binary 'AND' the frames together. This takes an intersection of the individual frames ||
||--frameno || Use give frame of the input, 0-based, default is 0. || ||
||--merge mergevol || Merge with mergevolume || mergevol must be the same dimension as the input volume. Merge binarization with the mergevol. If the voxel is within the threshold range (or matches), then its value will be binval. If not, then it will inherit its value from the value at that voxel in mergevol. mergevol must be the same dimension as the input volume. Combining this with --binval allows you to construct crude segmentations. ||
||--mask maskvol || Mask input with maskvol || Mask input with mask. The mask volume is itself binarized at thresh (default is 0.5). If a voxel is not in the mask, then it will be assigned binvalnot or the value from the merge volume. ||
||--mask-thresh thresh || Set threshold for mask (default is 0.5) || Mask input with mask. The mask volume is itself binarized at thresh (default is 0.5). If a voxel is not in the mask, then it will be assigned binvalnot or the value from the merge volume. ||
||--abs || Take abs of invol first (ie, make unsigned) || ||
||--bincol || Set binarized voxel value to its column number || ||
||--zero-edges || Set edge voxels to zero || Set the first and last planes in all dimensions to zero (or --binvalnot_. This makes sure that all the voxels on the edge of the imaging volume are zero. ||
||--zero-slice-edges || Set edge slice voxels to zero || Same as --zero-edge, but only for slices ||
||--dilate ndilate || Dilate binarization in 3D || ||
||--erode nerode || Erode binarization in 3D (after any dilation) || ||
||--erode2d nerode2d || Erode binarization in 2D (after any 3D erosion) || ||
||--erode-face nerode || Erode binarization using 'face' nearest neighbor || ||
||--erode-edge nerode || Erode binarizaiton using 'edge' nearest neighbor || ||
||--erode-corner nerode || Erode binarization using 'corner' nearest neighbor, same as --erode || ||
||--bb npad || Reduce dim of output to the minimum volume of non-zero voxels with npad boundary || ||
||--surf surfname || Create a surface mesh from the binarization || ||
||--surf-smooth niteration || Iteratively smooth the surface mesh || ||
||--noverbose || Default is verbose || ||
||--uchar || Save output file in 'uchar' format || ||
||--checkopts || Don't run anything, just check options and exit || ||
||--help || Print out information on how to use this program || ||
||--version || Print out version and exit || ||
||--debug || Turns on debugging || ||

== Notes ==
{{{
--min min
--max max
--rmin rmin
--rmax rmax
}}}

Minimum and maximum thresholds. If the value at a voxel is >= min and <= max, then its value in the output will be 1 (or --binval), otherwise it is 0 (or --binvalnot) or the value of the merge volume at that voxel.  By default, min = -infinity and max = +infinity, but you must set one of the thresholds. Cannot be used with --match. If --rmin or --rmax are specified, then min (or max) is computed as rmin (or rmax) times the global mean of the input.


= Examples =
== Example 1 ==
{{{
mri_binarize --i aseg.mgz --o left_hippocampus.mgz --match 17
}}}

Creates a binary mask (.nii) of the left hippocampus from the subject's aseg.mgz

= Bugs =
None

= See Also =
[[mri_extract_label]]

= Links =
FreeSurfer, FsFast


= Reporting Bugs =
Report bugs to < analysis-bugs@nmr.mgh.harvard.edu >