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.10.15. nilearn.plotting.plot_surf

nilearn.plotting.plot_surf(surf_mesh, surf_map=None, bg_map=None, hemi='left', view='lateral', cmap=None, colorbar=False, avg_method='mean', threshold=None, alpha='auto', bg_on_data=False, darkness=1, vmin=None, vmax=None, cbar_vmin=None, cbar_vmax=None, title=None, output_file=None, axes=None, figure=None, **kwargs)

Plotting of surfaces with optional background and data

New in version 0.3.

surf_mesh: str or list of two numpy.ndarray

Surface mesh geometry, can be a file (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.

surf_map: str or numpy.ndarray, optional.

Data to be displayed on the surface mesh. Can be a file (valid formats are .gii, .mgz, .nii, .nii.gz, or Freesurfer specific files such as .thickness, .curv, .sulc, .annot, .label) or a Numpy array with a value for each vertex of the surf_mesh.

bg_map: Surface data object (to be defined), optional,

Background image to be plotted on the mesh underneath the surf_data in greyscale, most likely a sulcal depth map for realistic shading.

hemi{‘left’, ‘right’}, default is ‘left’

Hemisphere to display.

view: {‘lateral’, ‘medial’, ‘dorsal’, ‘ventral’, ‘anterior’, ‘posterior’},

default is ‘lateral’ View of the surface that is rendered.

cmap: matplotlib colormap, str or colormap object, default is None

To use for plotting of the stat_map. Either a string which is a name of a matplotlib colormap, or a matplotlib colormap object. If None, matplotlib default will be chosen

colorbarbool, optional, default is False

If True, a colorbar of surf_map is displayed.

avg_method: {‘mean’, ‘median’}, default is ‘mean’

How to average vertex values to derive the face value, mean results in smooth, median in sharp boundaries.

thresholda number or None, default is None.

If None is given, the image is not thresholded. If a number is given, it is used to threshold the image, values below the threshold (in absolute value) are plotted as transparent.

alpha: float, alpha level of the mesh (not surf_data), default ‘auto’

If ‘auto’ is chosen, alpha will default to .5 when no bg_map is passed and to 1 if a bg_map is passed.

bg_on_data: bool, default is False

If True, and a bg_map is specified, the surf_data data is multiplied by the background image, so that e.g. sulcal depth is visible beneath the surf_data. NOTE: that this non-uniformly changes the surf_data values according to e.g the sulcal depth.

darkness: float, between 0 and 1, default is 1

Specifying the darkness of the background image. 1 indicates that the original values of the background are used. .5 indicates the background values are reduced by half before being applied.

vmin, vmax: lower / upper bound to plot surf_data values

If None , the values will be set to min/max of the data

titlestr, optional

Figure title.

output_file: str, or None, optional

The name of an image file to export plot to. Valid extensions are .png, .pdf, .svg. If output_file is not None, the plot is saved to a file, and the display is closed.

axes: instance of matplotlib axes, None, optional

The axes instance to plot to. The projection must be ‘3d’ (e.g., figure, axes = plt.subplots(subplot_kw={‘projection’: ‘3d’}), where axes should be passed.). If None, a new axes is created.

figure: instance of matplotlib figure, None, optional

The figure instance to plot to. If None, a new figure is created.

See also


For surface data object to be used as background map for this plotting function.


For plotting statistical maps on brain surfaces.


for plotting statistical maps on brain surfaces.