napari viewer tutorial

Welcome to the tutorial on the napari viewer!

This tutorial assumes you have already installed napari and know how to launch the viewer. For help with installation see our installation tutorial. For help getting started with the viewer see our getting started tutorial.

This tutorial will teach you about the napari viewer, including how to use its graphical user interface (GUI) and how the data within it is organized. At the end of the tutorial you should understand the both the layout of the viewer on the screen and the data inside of it.

Launching the viewer

As discussed in getting started tutorial the napari viewer can be launched from the command-line, a python script, an IPython console, or a jupyter notebook. All four methods launch the same viewer, and anything related to the interacting with the viewer on the screen applies equally to all of them. We will use the syntax inside python scripts so you can copy and paste these examples into scripts and run them.

Let’s get stated by launching a viewer with a simple 2D image.

The fastest way to get the viewer open and throw an image up on the screen is using the napari.view_image method:

import napari
from skimage import data

viewer = napari.view_image(data.astronaut(), rgb=True)

Calling napari.view_image will return a Viewer object that is the main object inside napari. All the data you add to napari will be stored inside the Viewer object and will be accessible from it. This command will also open the viewer to create a GUI that you can interact with.

You can also create an empty Viewer directly and then start adding images to it. For example:

viewer = napari.Viewer()
new_layer = viewer.add_image(data.astronaut(), rgb=True)

add_image accepts the same arguments as view_image but returns a layer rather than a Viewer, (as you must already have a viewer to use it).

After running either of those two commands you should now be able to see the photograph of the astronaut in the napari viewer as shown below

Hide code cell source
from napari.utils import nbscreenshot

nbscreenshot(viewer, alt_text="photograph of an astronaut in napari viewer")
photograph of an astronaut in napari viewer

Both the view_image and the add_image methods accept any numpy-array like object as an input, including n-dimensional arrays. For more information on adding images to the viewer see the image layer guide. Now we will continue exploring the rest of the viewer.

Layout of the viewer

The viewer is organized into a few key areas:

image: viewer layout

We’ll go through each of these in the next sections.

Main canvas

The main canvas is in the center of the viewer and contains the visual display of the data passed to napari, including images, point, shapes, and our other supported data types. Under the hood the canvas is a vispy.scene.SceneCanvas object which has built-in support for features such as zooming and panning. As vispy uses OpenGL and your graphics card, panning and zooming are highly performant. You can also return to the original zoom level by clicking the home button in the viewer buttons panel.

Layer list

One of the basic napari objects are layers. There are different layer types for Image, Points, Shapes, and other basic data types. They can be added to the viewer either programmatically or through the GUI. Once added they start to populate the layer list located on the bottom lefthand side of the main canvas.

The layer list contains one widget for each of the layers that have been added to the viewer and includes a thumbnail which shows a miniaturized version of the currently viewed data, a name that is an editable text box, visibility button that can be toggled on or off to show or hide the layer, and an icon for the layer type.

Adding the following three image layers using the code below adds three-layer widgets to the layer list as follows:

viewer = napari.Viewer()
viewer.add_image(data.astronaut(), name='astronaut')
viewer.add_image(data.moon(), name='moon')
viewer.add_image(, name='camera')
Hide code cell source
nbscreenshot(viewer, alt_text="3 image layers shown in napari viewer with the canvas displaying a photograph of a man looking through a camcorder")