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_surf(surf_mesh, surf_map=None, bg_map=None, threshold=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, black_bg=False, vmax=None, vmin=None, bg_on_data=False, darkness=0.7, symmetric_cmap=True, colorbar=True, colorbar_height=0.5, colorbar_fontsize=25, title=None, title_fontsize=25)[source]#

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

surf_meshstr 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_mapstr 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, .area, .curv, .sulc, .annot, .label) or a Numpy array

bg_mapstr or numpy.ndarray, default=None

Background image to be plotted on the mesh underneath the surf_data in greyscale, most likely a sulcal depth map for realistic shading. If the map contains values outside [0, 1], it will be rescaled such that all values are in [0, 1]. Otherwise, it will not be modified.

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.


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

You might want to change it to ‘gnist_ncar’ if plotting a surface atlas.

black_bgbool, default=False

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

symmetric_cmapbool, default=True

Make colormap symmetric (ranging from -vmax to vmax). Set it to False if you are plotting a surface atlas.

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.

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.

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


Surface plot from a 3D statistical map.