mri_vol2roi - extracts ROI from volume




Positional Arguments


Required Flagged Arguments

--srcvol srcvolstem

input stem

Bfloat/bshort stem of the volume from which the ROI is to be extracted.

--srcreg regfile

source registration (SrcXYZ = R*AnatXYZ)

Registration between src volume and subject's anatomical (ie, a register.dat). This is only needed when using a label.

--label labelfile

path to label file

Path to FreeSurfer label file. Make sure to give full path. The label file has, among other things, xyz coorindates of the points in the label. Each point has an extent of 1mm^3. These xyz coorindates have to be mapped into the source volume. This is done with the registration matrix (--srcreg) and (possibly) with the label registration (see --labelreg and --labeltal).

--labelreg labelregfile

label registration (LabelXYZ = L*AnatXYZ). See warning before using this option.

File with matrix that maps label xyz coordinates to subject's anatomical coordinates. Note: this matrix should map to the subject's anatomical coordinates in 'tkregister' space. IMPORTANT: passing the talairach.xfm file with this option can result in a MISINTERPRETATION of the transform.


use tal xfm for labelreg.

The label is in talairach space. In this case, the talairach.xfm file for the subject in the register.dat (--srcreg) is loaded. This matrix is modified to make it appropriate for use with the register.dat (ie, it will be interpreted correctly). See also --talxfm and --labelreg.

--talxfm xfmfile

use talxfm intead of talairach.xfm

Use xfmfile in subject/mri/transforms for talairach transfrom instead of talairach.xfm. This forces --labeltal.

--labelfillthresh thresh

fraction of voxel.

Each label point represents 1mm^3, so it is possible that a source voxel is not entirely filled by label points. This option allows the user to choose the extent to which a voxel must be filled for it to be considered part of the label. thresh is a number between 0 and 1 and represents the fraction of the volume of a voxel that must be filled in order for that voxel to be part of the label. Setting thresh=0 will force all voxels to be in the label regardless of what's in the label file. Default is a small value just above 0.

--mskvol maskstem

mask volume path.

Stem of the bshort/bfloat mask volume. This volume should be the same dimension as the source volume (the number of frames can differ). The mask volume will be thresholded to determine which voxels will be included in the ROI. See --mskthresh, --msktail, --mskframe, and --mskinvert for thresholding criteria.

--mskthresh mskthresh

threshold (0.5) mask threshold.

Voxels value magnitude must be above mskthresh to be included. Default is 0.5.

--msktail tail

'<abs>', pos, or neg (mask tail).

Tail is the sign that a voxel must have in order to be included. Tail can be abs, pos, or neg. Abs means that the sign should be ignored (the default), pos means that the sign must be positive, neg means that the sign must be negative.

--mskframe nthframe

0-based mask frame <0>.

Use the nthframe in the mask volume to derive the mask. nthframe is 0-based (ie, --mskframe 5 indicates the 6th frame). Default is 0 (ie, the first frame).


invert the mask.

After selecting voxels based on the threshold criteria (ie, mskthresh, msktail, mskframe), invert the mask (ie, the non-selected voxels become selected and vise versa).

--roiavgtxt fname

Output text file for ROI average.

Save output in text format. See introduction.

--roiavg stem

Output bfloat stem for ROI average.

Save output as a bfloat 'volume'. This flag is actually necessary even if you are not going to use this output.

--finalmskvol finalmaskstem

path in which to save final mask.

Save the final set of voxels selected for the ROI in this volume. See introduction for more info.

--finalmskcrs fname

save col,row,slice in text fname.

Save the column, row, and slice of the voxels in the mask in a text file. The indicies are zero-based.

Optional Flagged Arguments







mri_vol2roi extracts a region-of-interest (ROI) from a volume. The ROI can be defined in one of three ways: (1) as set of voxels in a mask volume the same size as the source volume, (2) as a set of label points (defined in a label file), or (3) the intersection of (1) and (2). mri_vol2roi can also be used to create a binary mask volume from a label; see CREATING A BINARY MASK VOLUME FROM A LABEL below.

The result is a text file (argument of --roiavgtxt) with the following rows of information. (1) The number of source voxels in the label (0 if no label is used). (2) The number of voxels in the final ROI. (3) the average of the ROI voxels in the source volume. If the source volume has multiple frames, then there will be a row for each frame.

In addition, a final ROI mask volume can be saved. This volume is the same size as the source volume (one frame only). The value of a voxel is 1 if it was in the final ROI or 0 if it was out.

mri_vol2roi can be used to create a binary mask volume, ie, a volume with 1s where the label is and 0s everywhere else. Use something like:

This will create a bshort volume with stem labelbinmask. This will be the same size/geometry as the srcvol f. register.dat is the registration matrix between the label space and srcvol space. mri_vol2roi requires an output for the ROI information (--roiavg), but in this application the user typically does not want this information (still has to be there on the command line).


Example 1

mri_vol2roi foo -i f -o out

Example 2

mri_vol2roi foo -i f -o out -f fvalue


The matrix used with --labelreg must map to the subject's anatomical coordinates in 'tkregister' space. IMPORTANT: passing the talairach.xfm file with this option can result in a MISINTERPRETATION of the transform.

The source, mask, and finalmask volumes must be in bshort/bfloat format.

A roiavgstem must be specified even if you do not want this format. The roiavgtxt can be specified independently.

See Also

othercommand1, othercommand2


FreeSurfer, FsFast, ROI

Methods Description




Reporting Bugs

Report bugs to <>



mri_vol2roi (last edited 2008-04-29 11:46:24 by localhost)