2. Exploring the napari GUI

Goal: Navigate the viewer confidently, adjust how images look, try the napari gallery, and understand image metadata.

Instructor-guided GUI Walkthrough (25 min)¶

Follow along as the instructor walks through the major parts of the napari interface using the Cells (3D + 2Ch) sample image.

Check out the napari viewer documentation for a full walkthrough.

import napari
from napari.utils import nbscreenshot
viewer = napari.Viewer()
viewer.open_sample('napari', 'cells3d')

/home/runner/work/workshops/workshops/.pixi/envs/default/lib/python3.14/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

Downloading file 'data/cells3d.tif' from 'https://gitlab.com/scikit-image/data/-/raw/2cdc5ce89b334d28f06a58c9f0ca21aa6992a5ba/cells3d.tif' to '/home/runner/.cache/scikit-image/0.26.0'.

nbscreenshot(viewer)

The Viewer Layout¶

Key Interactions¶

• Zoom: right-click and drag or scroll wheel (or two-finger scroll on trackpad)

• Pan: click and drag on the canvas, hold Shift to pan in 3D mode

• Reset view: click the home button (bottom-right row of viewer buttons)

Dimension Sliders¶

When a layer has more dimensions than the viewer can display, sliders appear at the bottom of the canvas. Drag a slider to move through z-slices, time points, or channels.

viewer.dims.ndisplay = 2
viewer.dims.current_step = (23, 100, 100)

nbscreenshot(viewer)

You can rename the slider labels! Right click on the roll dimensions button and double-click on the axis label to edit it.

viewer.dims.axis_labels = ['Z', 'Y', 'X']
viewer.axes.visible = True
viewer.dims.ndisplay = 3

nbscreenshot(viewer)

2D ↔ 3D Toggle¶

Click the 2D/3D button in the viewer button row to switch rendering modes. In 3D mode you can click-drag to rotate the volume.

viewer.dims.ndisplay = 3
viewer.camera.angles = (-27, 8, -58)

nbscreenshot(viewer)

Overlays¶

There are viewer overlays that can be added to the canvas. In this case we will add the Axes overlay to show the Axis Labels attached to the data. Go to View > Axes > Axes Visible to turn it on.

Try also to visualize the Color Bar (LUT) overlay for each layer by right clicking on the layer(s) that you want to visualize or toggle the color bar from the navbar menu Layers > Measure > Color Bar.

We can also enable the scale bar with View > Scale Bar > Visible from the navbar. If all layers have consistent units, then the scalebar displays the physical scale. If not, it defaults to pixels.

Layer Controls¶

With a layer selected, layer controls at the top-left let you change:

• Contrast limits — adjust brightness/darkness and auto-contrast

• Colormap — the colour used to display intensity values

• Blending — how layers are composited

• Opacity — layer transparency

viewer.axes.visible = False
viewer.dims.ndisplay = 2
viewer.dims.current_step = (29, 100, 100)
nuclei = viewer.layers['nuclei']
nuclei.contrast_limits = (0, 40000)
nuclei.colormap = 'cyan'

membrane = viewer.layers['membrane']
membrane.contrast_limits = (0, 40000)
membrane.colormap = 'orange'

nbscreenshot(viewer)

viewer.dims.ndisplay = 3
membrane.rendering = 'attenuated_mip'
membrane.visible = False
nuclei.rendering = 'attenuated_mip'

nbscreenshot(viewer)

viewer.close()

Grid View¶

Grid Mode allows you to view multiple layers in separate panels at the same time. This is especially useful for comparing channels in a multi-channel image. You can enable it with the grid button in the viewer buttons (bottom row, second from the right). You can right-click the grid button to adjust the number of rows and columns in the grid, including how many layers are shown in each panel (i.e. stride).

viewer = napari.Viewer()
viewer.open_sample('napari', 'lily')
viewer.grid.enabled = True

Downloading file 'data/lily.tif' from 'https://gitlab.com/scikit-image/data/-/raw/2cdc5ce89b334d28f06a58c9f0ca21aa6992a5ba/lily-of-the-valley-fluorescence.tif' to '/home/runner/.cache/scikit-image/0.26.0'.

nbscreenshot(viewer)

Console Peek¶

napari has a built-in Python console that allows you to interact with the viewer programmatically. Some features that are not yet exposed through the GUI can be used via the console.

Open it from the menu with Window > Console, or click the leftmost viewer button.

As an example, here we change the viewer scale bar units (you can’t do this through the GUI yet):

viewer.grid.stride = 2
for l in viewer.layers:
    l.colorbar.visible = True
viewer.scale_bar.visible = True

viewer.scale_bar.unit = 'micrometer'

nbscreenshot(viewer)

The console lets you access the viewer directly to programmatically change different properties. You can also access individual layers using viewer.layers — the starting point for scripting napari in your own workflows.

Layer Metadata with napari-metadata (5 min)¶

The napari-metadata plugin lets you view and edit layer metadata, including axis labels, scale, and physical units of your layers — essential for making measurements in real units.

Open the widget: Plugins > Layer metadata: Layer metadata

There are three parts to the widget:

1. File metadata — read-only metadata from the file

2. Axes metadata — axis labels, physical scale, units, and more

3. Copy metadata — copy metadata from one layer to another

Gallery Exploration Breakout (15 min)¶

Recommended Examples¶

1. 3D Layer Bounding Box Overlay

2. 3D vector field and image across time

3. Add labels with features

4. Add points 3D

5. Add vectors color by angle

6. Anisotropic data with scale

7. Annotate segmentation with text

8. Colorbars and auto-tiling of overlays in grid mode

9. Displaying xarray data in napari

10. Features table widget

11. Heart with multiple annotations

12. Image points 3D

13. Labels 3D

14. Minimum blending

15. Show points based on feature

16. Surface with texture and vertex_oolors

17. Tracks 3D

Sharing Time (5 min)¶

• What did you find in the gallery? (check the Zulip stream for screenshots!)

• Any surprising layer types or visualizations?

• Questions about the interface?