This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

7.12.3. nilearn.surface.vol_to_surf

nilearn.surface.vol_to_surf(img, surf_mesh, radius=3.0, interpolation='linear', kind='line', n_samples=None, mask_img=None)

Extract surface data from a Nifti image.

New in version 0.4.0.

imgNiimg-like object, 3d or 4d.


surf_meshstr or numpy.ndarray

Either a file containing surface mesh geometry (valid formats are .gii or Freesurfer specific files such as .orig, .pial, .sphere, .white, .inflated) or a list of two Numpy arrays, the first containing the x-y-z coordinates of the mesh vertices, the second containing the indices (into coords) of the mesh faces.

radiusfloat, optional (default=3.).

The size (in mm) of the neighbourhood from which samples are drawn around each node.

interpolation{‘linear’, ‘nearest’}

How the image intensity is measured at a sample point.

  • ‘linear’ (the default):

    Use a trilinear interpolation of neighboring voxels.

  • ‘nearest’:

    Use the intensity of the nearest voxel.

For one image, the speed difference is small, ‘linear’ takes about x1.5 more time. For many images, ‘nearest’ scales much better, up to x20 faster.

kind{‘line’, ‘ball’}

The strategy used to sample image intensities around each vertex.

  • ‘line’ (the default):

    samples are regularly spaced along the normal to the mesh, over the interval [- radius, + radius]. (sometimes called thickness sampling)

  • ‘ball’:

    samples are regularly spaced inside a ball centered at the mesh vertex.

n_samplesint or None, optional (default=None)

How many samples are drawn around each vertex and averaged. If None, use a reasonable default for the chosen sampling strategy (20 for ‘ball’ or 10 for ‘line’). For performance reasons, if using kind =”ball”, choose n_samples in [10, 20, 40, 80, 160] (default is 20), because cached positions are available.

mask_imgNiimg-like object or None, optional (default=None)

Samples falling out of this mask or out of the image are ignored. If None, don’t apply any mask.

texturenumpy.ndarray, 1d or 2d.

If 3D image is provided, a 1d vector is returned, containing one value for each mesh node. If 4D image is provided, a 2d array is returned, where each row corresponds to a mesh node.


This function computes a value for each vertex of the mesh. In order to do so, it selects a few points in the volume surrounding that vertex, interpolates the image intensities at these sampling positions, and averages the results.

Two strategies are available to select these positions.
  • ‘ball’ uses points regularly spaced in a ball centered at the mesh

    vertex. The radius of the ball is controlled by the parameter radius.

  • ‘line’ starts by drawing the normal to the mesh passing through this

    vertex. It then selects a segment of this normal, centered at the vertex, of length 2 * radius. Image intensities are measured at points regularly spaced on this normal segment.

You can control how many samples are drawn by setting n_samples.

Once the sampling positions are chosen, those that fall outside of the 3d image (or outside of the mask if you provided one) are discarded. If all sample positions are discarded (which can happen, for example, if the vertex itself is outside of the support of the image), the projection at this vertex will be numpy.nan.

The 3d image then needs to be interpolated at each of the remaining points. Two options are available: ‘nearest’ selects the value of the nearest voxel, and ‘linear’ performs trilinear interpolation of neighbouring voxels. ‘linear’ may give better results - for example, the projected values are more stable when resampling the 3d image or applying affine transformations to it. For one image, the speed difference is small, ‘linear’ takes about x1.5 more time. For many images, ‘nearest’ scales much better, up to x20 faster.

Once the 3d image has been interpolated at each sample point, the interpolated values are averaged to produce the value associated to this particular mesh vertex.

WARNING: This function is experimental and details such as the interpolation method are subject to change.