mri_label2vol - creates mgz volume from a label or set of labels


mri_label2vol [--flag argument] Also, run mri_label2vol --help for more information


Positional Arguments


Required Flagged Arguments

--label, --annot, or --seg are not to be used together.

--label labelfile

Label file

For multiple labels, use multiple --label flags.

--annot annotfile

Annotation file

--seg segpath

Path to segmentation

--temp tempvolid

Template volume

The output volume will have the same size and geometry as the template.

Optional Flagged Arguments

--reg regmatfile

tkregister-style registration matrix

Maps the XYZ of the label to the XYZ of the template volume. If not specified, then the identity is assumed.

--fillthresh thresh

Relative threshold value

Relative threshold which the number hits in a voxel must exceed for the voxel to be considered a candidate for membership in the label. (See mri_label2vol --help for more information)

--proj type start stop delta

Project the label along the surface normal

Type can be either abs or frac. abs means that the start, stop, and delta are measured in mm. frac means that start, stop, and delta are relative to the thickness at each vertex. The label definition is changed to fill in label points in increments of delta from start to stop. Uses the white surface. The label MUST have been defined on the surface.

--subject subjectid

Subject identifier

Required when using --proj

--hemi hemi

lh or rh

Hemisphere to use loading the surface for --proj. Required when using --proj


Identity matrix

Use the identity matrix as the registration.


--o volid

Single frame output volume (any mri_convert format accepted)




Converts a label or a set of labels into a volume. For a single label, the volume will be binary: 1 where the label is and 0 where it is not. For multiple labels, the volume will be 0 where no labels were found otherwise the value will be the label number. For a voxel to be declared part of a label, it must have enough hits in the voxel and it must have more hits than any other label.


Example 1

Convert a label into a binary mask in the functional space; require that a functional voxel be filled at least 50% by the label:

  --label lh-avg_central_sulcus.label 
  --temp f.nii.gz 
  --reg register.dat 
  --fillthresh .5 
  --o cent-lh.nii.gz

To see how well the label is mapped into the functional volume, run

tkmedit bert orig 
  -overlay ./cent-lh.nii.gz 
  -overlay-reg ./register.dat -fthresh .5 -fmid 1

Then load the label with File->Label->LoadLabel. The label should overlap with the overlay. The overlap will not be perfect but it should be very close.

Example 2

  --label lh-avg_central_sulcus.label 
  --temp f.nii.gz 
  --reg register.dat 
  --fillthresh .3 
  --proj frac 0 1 .1 
  --subject bert --hemi lh
  --o cent-lh.nii.gz

Convert a surface label into a binary mask in the functional space. Fill in all the cortical gray matter. Require that a functional voxel be filled at least 30% by the label.

Example 3

  --label lh-avg_central_sulcus.label 
  --temp f.nii 
  --reg register.dat 
  --proj abs -3 -2 .1 
  --subject bert --hemi lh
  --o cent-lh.nii

Convert a surface label into a binary mask in the functional space. Sample a 1mm ribbon 2mm below the gray/white surface. Do not require a fill threshold.

Example 4

  --label lh-avg_central_sulcus.label 
  --label lh-avg_calcarine_sulcus.label 
  --temp $SUBJECTS_DIR/bert/orig
  --o cent_calc.img

Convert two labels into a volume in the same space as the labels. The voxels corresponding to lh-avg_central_sulcus.label will have a of value of 1 whereas those assigned to lh-avg_calcarine_sulcus.label will have a value of 2.

Checking your Results

It is very important to check that the conversion of the label to the volume was done correctly. It may be that it is way off or it could be off around the edges. This is particularly true for surface-based labels or when converting a label to a low-resolution space. To check the result, load the orig volume into tkmedit. The orig volume should be in the label space. Load the mri_label2vol output volume as an overlay; this makes the labeled voxels appear as 'activity'. Finally, load the label itself. You should see the label (in green) sitting on top of the 'activity' of the labeled volume.


When the output type is COR, all the voxels will be zero. The work-around is to save it as some other type, then use mri_convert with -no_rescale 1 to convert it to COR.

Cannot convert surface labels with different hemispheres.

See Also

mri_label2label, mri_vol2label, mri_annotation2label, mri_mergelabels, tkregister2, mri_convert, tkmedit, tksurfer


FreeSurfer, FsFast

Methods Description




Reporting Bugs

Report bugs to <>



mri_label2vol (last edited 2017-11-30 11:34:02 by MorganFogarty)