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.


nilearn.plotting.view_img_on_surf(stat_map_img, surf_mesh='fsaverage5', threshold=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, black_bg=False, vmax=None, vmin=None, symmetric_cmap=True, bg_on_data=False, darkness=0.7, colorbar=True, colorbar_height=0.5, colorbar_fontsize=25, title=None, title_fontsize=25, vol_to_surf_kwargs=None)[source]

Insert a surface plot of a statistical map into an HTML page.

stat_map_imgNiimg-like object, 3D

See Input and output: neuroimaging data representation.

surf_meshstr or dict, default=’fsaverage5’

If a string, it should be one of the following values:

  • “fsaverage3”: the low-resolution fsaverage3 mesh (642 nodes)

  • “fsaverage4”: the low-resolution fsaverage4 mesh (2562 nodes)

  • “fsaverage5”: the low-resolution fsaverage5 mesh (10242 nodes)

  • “fsaverage6”: the medium-resolution fsaverage6 mesh (40962 nodes)

  • “fsaverage7”: same as “fsaverage”

  • “fsaverage”: the high-resolution fsaverage mesh (163842 nodes)


    The high-resolution fsaverage will result in more computation time and memory usage

If a dictionary, it should have the same structure as those returned by nilearn.datasets.fetch_surf_fsaverage, i.e. keys should be ‘infl_left’, ‘pial_left’, ‘sulc_left’, ‘infl_right’, ‘pial_right’, and ‘sulc_right’, containing inflated and pial meshes, and sulcal depth values for left and right hemispheres.

thresholdstr, number or None, optional

If None, no thresholding. If it is a number only values of amplitude greater than threshold will be shown. If it is a string it must finish with a percent sign, e.g. “25.3%”, and only values of amplitude above the given percentile will be shown.

cmapstr or matplotlib colormap, default=cm.cold_hot

Colormap to use.

black_bgbool, default=False

If True, image is plotted on a black background. Otherwise on a white background.

bg_on_databool, default=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 jointly visible with surf_data. Otherwise, the background image will only be visible where there is no surface data (either because surf_data contains nans or because is was thresholded).


This non-uniformly changes the surf_data values according to e.g the sulcal depth.

darknessfloat between 0 and 1, optional

Specifying the darkness of the background image:

  • 1 indicates that the original values of the background are used

  • 0.5 indicates that the background values are reduced by half before being applied.


vmaxfloat or None, optional

upper bound for the colorbar. if None, use the absolute max of the brain map.

vminfloat or None, optional

min value for mapping colors. If symmetric_cmap is True, vmin is always equal to -vmax and cannot be chosen. If symmetric_cmap is False, vmin is equal to the min of the image, or 0 when a threshold is used.

symmetric_cmapbool, default=True

Make colormap symmetric (ranging from -vmax to vmax). You can set it to False if you are plotting only positive values.

colorbarbool, default=True

Add a colorbar or not.

colorbar_heightfloat, default=0.5

Height of the colorbar, relative to the figure height

colorbar_fontsizeint, default=25

Fontsize of the colorbar tick labels.

titlestr, optional

Title for the plot.

title_fontsizeint, default=25

Fontsize of the title.

vol_to_surf_kwargsdict, default=None

Dictionary of keyword arguments that are passed on to nilearn.surface.vol_to_surf when extracting a surface from the input image. See the function documentation for details.This parameter is especially useful when plotting an atlas. See Will default to {} if None is passed.

SurfaceViewplot of the stat map.

It can be saved as an html page or rendered (transparently) by the Jupyter notebook. Useful methods are :

  • ‘resize’ to resize the plot displayed in a Jupyter notebook

  • ‘save_as_html’ to save the plot to a file

  • ‘open_in_browser’ to save the plot and open it in a web browser.

See also


plot from a surface map on a cortical mesh.

Examples using nilearn.plotting.view_img_on_surf

Making a surface plot of a 3D statistical map

Making a surface plot of a 3D statistical map

Making a surface plot of a 3D statistical map

Making a surface plot of a 3D statistical map