mri_vol2surf - assigns values from a volume to each surface vertex


mri_vol2surf [<options>] --src inputfile --out outpufile --srcreg registrationfile --hemi hemisphere


Required Flagged Arguments


input volume path


output path

--srcreg registrationfile

source registration file

RegistrationFile as computed by tkregister, tkmedit, mri_make_register, or spmmat2register. The volume is mapped onto the surface of subject subjectname (unless --trgsubject is specified). There may or may not be another line with the method used to convert voxel indices from floating to integer during registration. If tkregiser was used to register the volume, the method should be blank or 'tkregister' (no quotes), otherwise it should be 'round'. This can be overridden with --float2int.


hemisphere (lh or rh)

Optional Flagged Arguments


input volume fileformat


float-to-int conversion method (<round>, tkregister )

override float2int method in registration file. See BUGS.


make make registration matrix round-compatible

Attempt to convert the registration matrix so that it is round (or nearest neighbor) compatible. Setting this flag will only have an effect if the float2int method is tkregister. It will 'fix' the matrix and change the float2int method to round. Don't use this flag unless you know what you are doing.

--fwhm FWHM

smooth input volume (mm)

Smooth input volume with a gaussian kernal with FWHM mm.


target subject (if different than reg)

resample volume onto this subject instead of the one found in the registration file. The target subject can be either a subject name (as found in $SUBJECTS_DIR) or ico (to map onto the sphere). If the target subject is not the source subject, then the surfaces are mapped using each subject's spherical surface registration (?h.sphere.reg or that specified with --surfreg). If the target subject is ico, then the volume is resampled onto an icosahedron, which is used to uniformly sample a sphere. This requires specifying the icosahedron order (see --icoorder).


target surface (white)

the surface on which to resample. The default is white. It will look for $SUBJECTS_DIR/subjectname/surf/?h.surfacenam

With --trgsubject



Default=sphere.reg. This is a representation of a subject's cortical surface after it has been registered/morphed with a template spherical surface.

--icoorder n

order of icosahedron when trgsubject=ico

specifies the order of the icosahedral tesselation. the number of vertices is given by the formula 10*2^n+2. In general, it is best to use the largest size available.

Surface Normal Proection

--projfrac fraction

(0->1) fractional projection along surface normal

fraction (0,1) of the cortical thickness at each vertex to project along the surface normal. Default=0. When set at 0.5 with the white surface, this should sample in the middle of the cortical surface. This requires that a ?h.thickness file exist for the source subject. Note, the faction can be less than zero, in which case it will project into the white matter. See also --projdist.

--projdist mmdist

distance projection along normal

Same as --projfrac but projects the given distance in mm at all points of the surface regardless of thickness.



output format

--frame frameno

save only nth frame (with paint format)

sample and save only the given frame from the source volume (needed when out_type = paint). Default=0


do not save output as multiple 'slices'

by default, mri_vol2surf will save the output as multiple 'slices'. This is for logistical purposes (eg, in the analyze format the size of a dimension cannot exceed 2^15). Use this flag to prevent this behavior. This has no effect when the output type is paint.

--rf R

integer reshaping factor, save as R 'slices'

Explicity set the reshaping factor to R. R must be an integer factor of the number of vertices.


volume to store the number of hits at each vox

Save a volume (the same size as the source) in which the value at each voxel is the number of surface vertices it maps to. The number of voxels hit at least once is printed to stdout as : 'Number of source voxels hit'


source hit volume format

--nvox nvoxfile

write number of voxels intersecting surface

Save the number of voxels intersecting the surface in the file nvoxfile.


--srcsynth seed

synthesize source volume

Synthesize the source volume with white gaussian noise. seed is the seed to the random generator. Use -1 to have the seed automatically chosen based on time-of-day. See also --seedfile

--seedfile fname

save synth seed to fname

Save random number generator seed in fname. Has no effect without --srcsynth. This is only useful for keeping track of the distribution of seeds for debugging purposes.


print out information on how to use this program


print out version and exit










Example 1

To paint the third frame of bfloat volume sig registered with tkregister onto a the left hemisphere of a surface

This will create sig-lh.w in the current directory, which can then be loaded into tksurfer

Example 2

To convert an analyze volume onto the sphere (right hemisphere)


When the output format is paint, the output file must be specified with a partial path (eg, ./data-lh.w) or else the output will be written into the subject's anatomical directory.

Currently no support for searching along the surface normal for a maximum value (as can be done with the paint program)

The ability to put the float2int conversion method in the registration file is new as of Fall 2001. Consequently, there may be some registration files that do not have a method string, which will force the method to be that of tkregister. This is can be overridden with --float2int.

See Also

othercommand1, othercommand2


FreeSurfer, FsFast

Methods Description

The data volume was projected onto the cortical surface.



Reporting Bugs

Report bugs to <>



mri_vol2surf (last edited 2008-04-29 11:45:40 by localhost)