download .ipynb

surface layer tutorial

Welcome to the tutorial on the napari Surface layer!

This tutorial assumes you have already installed napari, know how to launch the viewer, and are familiar with its layout. For help with installation see our installation tutorial. For help getting started with the viewer see our getting started tutorial. For help understanding the organisation of the viewer, including things like the layers list, the layer properties widgets, the layer control panels, and the dimension sliders see our napari viewer tutorial.

This tutorial will teach you about the napari Surface layer, including how to display surface data and edit the properties of surfaces like the contrast, opacity, colormaps and blending mode. At the end of the tutorial you should understand how to add and manipulate surfaces both from the GUI and from the console.

The surface layer allows you to display a precomputed surface mesh that is defined by an NxD array of N vertices in D coordinates, an Mx3 integer array of the indices of the triangles making up the faces of the surface, and a length N list of values to associate with each vertex to use alongside a colormap.

a simple example

You can create a new viewer and add a surface in one go using the napari.view_surface method, or if you already have an existing viewer, you can add an image to it using viewer.add_surface. The api of both methods is the same. In these examples we’ll mainly use view_surface.

A simple example of viewing a surface is as follows:

import napari
import numpy as np

vertices = np.array([[0, 0], [0, 20], [10, 0], [10, 10]])
faces = np.array([[0, 1, 2], [1, 2, 3]])
values = np.linspace(0, 1, len(vertices))
surface = (vertices, faces, values)

viewer = napari.view_surface(surface)  # add the surface
WARNING: QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-runner'
/opt/hostedtoolcache/Python/3.8.11/x64/lib/python3.8/site-packages/napari/_vispy/ UserWarning: Alternative shading modes are only available in 3D, defaulting to none
/opt/hostedtoolcache/Python/3.8.11/x64/lib/python3.8/site-packages/napari/_vispy/ RuntimeWarning: divide by zero encountered in true_divide
  zoom = np.min(canvas_size / scale)
from napari.utils import nbscreenshot


arguments of view_surface and add_surface

view_surface() and add_surface() accept the same layer-creation parameters.

Help on function view_surface in module napari.view_layers:

view_surface(data, *, colormap='gray', contrast_limits=None, gamma=1, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=1, blending='translucent', shading='flat', visible=True, title='napari', ndisplay=2, order=(), axis_labels=(), show=True) -> napari.viewer.Viewer
    Create a viewer and add a surface layer.
    data : 2-tuple or 3-tuple of array
        The first element of the tuple is an (N, D) array of vertices of
        mesh triangles. The second is an (M, 3) array of int of indices
        of the mesh triangles. The optional third element is the
        (K0, ..., KL, N) array of values used to color vertices where the
        additional L dimensions are used to color the same mesh with
        different values. If not provided, it defaults to ones.
    colormap : str, napari.utils.Colormap, tuple, dict
        Colormap to use for luminance images. If a string must be the name
        of a supported colormap from vispy or matplotlib. If a tuple the
        first value must be a string to assign as a name to a colormap and
        the second item must be a Colormap. If a dict the key must be a
        string to assign as a name to a colormap and the value must be a
    contrast_limits : list (2,)
        Color limits to be used for determining the colormap bounds for
        luminance images. If not passed is calculated as the min and max of
        the image.
    gamma : float
        Gamma correction for determining colormap linearity. Defaults to 1.
    name : str
        Name of the layer.
    metadata : dict
        Layer metadata.
    scale : tuple of float
        Scale factors for the layer.
    translate : tuple of float
        Translation values for the layer.
    rotate : float, 3-tuple of float, or n-D array.
        If a float convert into a 2D rotation matrix using that value as an
        angle. If 3-tuple convert into a 3D rotation matrix, using a yaw,
        pitch, roll convention. Otherwise assume an nD rotation. Angles are
        assumed to be in degrees. They can be converted from radians with
        np.degrees if needed.
    shear : 1-D array or n-D array
        Either a vector of upper triangular values, or an nD shear matrix with
        ones along the main diagonal.
    affine : n-D array or napari.utils.transforms.Affine
        (N+1, N+1) affine transformation matrix in homogeneous coordinates.
        The first (N, N) entries correspond to a linear transform and
        the final column is a lenght N translation vector and a 1 or a napari
        AffineTransform object. If provided then translate, scale, rotate, and
        shear values are ignored.
    opacity : float
        Opacity of the layer visual, between 0.0 and 1.0.
    blending : str
        One of a list of preset blending modes that determines how RGB and
        alpha values of the layer visual get mixed. Allowed values are
        {'opaque', 'translucent', and 'additive'}.
    shading: str, Shading
        One of a list of preset shading modes that determine the lighting model
        using when rendering the surface in 3D.
            * Shading.NONE
                Corresponds to shading='none'.
            * Shading.FLAT
                Corresponds to shading='flat'.
            * Shading.SMOOTH
                Corresponds to shading='smooth'.
    visible : bool
        Whether the layer visual is currently being displayed.
        title : string, optional
            The title of the viewer window. by default 'napari'.
        ndisplay : {2, 3}, optional
            Number of displayed dimensions. by default 2.
        order : tuple of int, optional
            Order in which dimensions are displayed where the last two or last
            three dimensions correspond to row x column or plane x row x column if
            ndisplay is 2 or 3. by default None
        axis_labels : list of str, optional
            Dimension names. by default they are labeled with sequential numbers
        show : bool, optional
            Whether to show the viewer after instantiation. by default True.
    viewer : :class:`napari.Viewer`
        The newly-created viewer.

surface data

The data for a surface layer is defined by a 3-tuple of its vertices, faces, and vertex values. The vertices are an NxD array of N vertices in D coordinates. The faces are an Mx3 integer array of the indices of the triangles making up the faces of the surface. The vertex values are a length N list of values to associate with each vertex to use alongside a colormap. This 3-tuple is accessible through the property.

3D rendering of images

All our layers can be rendered in both 2D and 3D mode, and one of our viewer buttons can toggle between each mode. The number of dimensions sliders will be 2 or 3 less than the total number of dimensions of the layer. See for example these brain surfaces rendered in 3D:

image: brain surface

working with colormaps

The same colormaps available for the Image layer are also available for the Surface layer. napari supports any colormap that is created with vispy.color.Colormap. We provide access to some standard colormaps that you can set using a string of their name.

 'bop blue',
 'bop orange',
 'bop purple',

Passing any of these as follows as keyword arguments will set the colormap of that surface. You can also access the current colormap through the layer.colormap property which returns a tuple of the colormap name followed by the vispy colormap object. You can list all the available colormaps using layer.colormaps.

It is also possible to create your own colormaps using vispy’s vispy.color.Colormap object, see it’s full documentation here. For more detail see the image layer tutorial.

adjusting contrast limits

The vertex values of the surface layer get mapped through its colormap according to values called contrast limits. These are a 2-tuple of values defining how what values get applied the minimum and maximum of the colormap and follow the same principles as the contrast_limits described in the image layer tutorial. They are also accessible through the same keyword arguments, properties, and range slider as in the image layer.

layer visibility

All our layers support a visibility toggle that allows you to set the visible property of each layer. This property is located inside the layer widget in the layers list and is represented by an eye icon.

layer opacity

All our layers support an opacity slider and opacity property that allow you to adjust the layer opacity between 0, fully invisible, and 1, fully visible.

blending layers

All our layers support three blending modes translucent, additive, and opaque that determine how the visuals for this layer get mixed with the visuals from the other layers.

An opaque layer renders all the other layers below it invisible and will fade to black as you decrease its opacity.

The translucent setting will cause the layer to blend with the layers below it if you decrease its opacity but will fully block those layers if its opacity is 1. This is a reasonable default, useful for many applications.

The final blending mode additive will cause the layer to blend with the layers below even when it has full opacity. This mode is especially useful for visualizing multiple layers at the same time.

naming layers

All our layers support a name property that can be set inside a text box inside the layer widget in the layers list. The name of each layer is forced into being unique so that you can use the name to index into viewer.layers to retrieve the layer object.

scaling layers

All our layers support a scale property and keyword argument that will rescale the layer multiplicatively according to the scale values (one for each dimension). This property can be particularly useful for viewing anisotropic data where the size of the voxel in the z dimension might be different then the size in the x and y dimensions.

translating layers

All our layers support a translate property and keyword argument that you can use to offset a layer relative to the other layers, which could be useful if you are trying to overlay two layers for image registration purposes.

layer metadata

All our layers also support a metadata property and keyword argument that you can use to store an arbitrary metadata dictionary on the layer.

next steps

Hopefully, this tutorial has given you a detailed understanding of the Vectors layer, including how to create one and control its properties. To learn more about some of the other layer types that napari supports checkout some more of our tutorials listed below. The vectors layer tutorial is a great one to try next as it describes rendering lots of lines.