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.

8.10.27. nilearn.plotting.view_img_on_surf

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, colorbar=True, colorbar_height=0.5, colorbar_fontsize=25, title=None, title_fontsize=25, vol_to_surf_kwargs={})[source]

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

stat_map_imgNiimg-like object, 3D


surf_meshstr or dict, optional.

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)

  • ‘fsaverage5_sphere’: the low-resolution fsaverage5 spheres

    Deprecated since version 0.8.0: This option has been deprecated and will be removed in v0.9.0. fsaverage5 sphere coordinates can now be accessed through attributes sphere_{left, right} using mesh=’fsaverage5’

  • ‘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. Default=’fsaverage5’.

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, optional

Colormap to use. Default=cm.cold_hot.

black_bgbool, optional

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

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 defaults to the min of the image, or 0 when a threshold is used.

symmetric_cmapbool, optional

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

colorbarbool, optional

Add a colorbar or not. Default=True.

colorbar_heightfloat, optional

Height of the colorbar, relative to the figure height. Default=0.5.

colorbar_fontsizeint, optional

Fontsize of the colorbar tick labels. Default=25.

titlestr, optional

Title for the plot.

title_fontsizeint, optional

Fontsize of the title. Default=25.

vol_to_surf_kwargsdict, optional

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

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