Events reference

The following tables contain events that you may connect to. For example, to have a specific function called whenever the users changes the number of dimensions displayed in the viewer (e.g. from 2D to 3D), you can use <event>.connect(your_callback):

from napari.utils.events import Event
from napari import Viewer

def my_callback(event: Event):
    print("The number of dims shown is now:", event.value)

viewer = Viewer()
viewer.dims.events.ndim.connect(my_callback)

Viewer events

Event

Description

Event.value type

viewer.axes.events.visible

If axes are visible or not.

bool

viewer.axes.events.labels

If axes labels are visible or not. Not the actual axes labels are stored in viewer.dims.axes_labels.

bool

viewer.axes.events.colored

If axes are colored or not. If colored then default coloring is x=cyan, y=yellow, z=magenta. If not colored than axes are the color opposite of the canvas background.

bool

viewer.axes.events.dashed

If axes are dashed or not. If not dashed then all the axes are solid. If dashed then x=solid, y=dashed, z=dotted.

bool

viewer.axes.events.arrows

If axes have arrowheads or not.

bool

viewer.camera.events.center

Center of rotation for the camera. In 2D viewing the last two values are used.

Tuple[float, float, float]

viewer.camera.events.zoom

Scale from canvas pixels to world pixels.

float

viewer.camera.events.angles

Euler angles of camera in 3D viewing (rx, ry, rz), in degrees. Only used during 3D viewing. Note that Euler angles’s intrinsic degeneracy means different sets of Euler angles may lead to the same view.

Tuple[float, float, float]

viewer.camera.events.perspective

Perspective (aka “field of view” in vispy) of the camera (if 3D).

float

viewer.camera.events.interactive

If the camera interactivity is enabled or not.

bool

viewer.cursor.events.position

Position of the cursor in world coordinates. None if outside the world.

float

viewer.cursor.events.scaled

Flag to indicate whether cursor size should be scaled to zoom. Only relevant for circle and square cursors which are drawn with a particular size.

bool

viewer.cursor.events.size

Size of the cursor in canvas pixels.Only relevant for circle and square cursors which are drawn with a particular size.

int

viewer.cursor.events.style

Style of the cursor. Must be one of * square: A square * circle: A circle * cross: A cross * forbidden: A forbidden symbol * pointing: A finger for pointing * standard: The standard cursor # crosshair: A crosshair

CursorStyle

viewer.dims.events.ndim

Number of dimensions.

int

viewer.dims.events.ndisplay

Number of displayed dimensions.

Literal[2, 3]

viewer.dims.events.last_used

Dimension which was last used.

int

viewer.dims.events.range

List of tuples (min, max, step), one for each dimension. In a world coordinates space. As with Python’s range and slice, max is not included.

Tuple[float, float, float]

viewer.dims.events.current_step

Tuple of the slider position for each dims slider, in slider coordinates.

int

viewer.dims.events.order

Tuple of ordering the dimensions, where the last dimensions are rendered.

int

viewer.dims.events.axis_labels

Tuple of labels for each dimension.

str

viewer.grid.events.stride

Number of layers to place in each grid square before moving on to the next square. The default ordering is to place the most visible layer in the top left corner of the grid. A negative stride will cause the order in which the layers are placed in the grid to be reversed.

ConstrainedIntValue

viewer.grid.events.shape

Number of rows and columns in the grid. A value of -1 for either or both of will be used the row and column numbers will trigger an auto calculation of the necessary grid shape to appropriately fill all the layers at the appropriate stride.

Tuple[napari.utils.events.custom_types.ConstrainedIntValue, napari.utils.events.custom_types.ConstrainedIntValue]

viewer.grid.events.enabled

If grid is enabled or not.

bool

viewer.scale_bar.events.visible

If scale bar is visible or not.

bool

viewer.scale_bar.events.colored

If scale bar are colored or not. If colored then default color is magenta. If not colored than scale bar color is the opposite of the canvas background or the background box.

bool

viewer.scale_bar.events.color

Scalebar and text color. See ColorValue.validate for supported values.

ColorValue

viewer.scale_bar.events.ticks

If scale bar has ticks at ends or not.

bool

viewer.scale_bar.events.position

Position of the scale bar in the canvas. Must be one of ‘top left’, ‘top right’, ‘bottom right’, ‘bottom left’. Default value is ‘bottom right’.

Position

viewer.scale_bar.events.font_size

The font size (in points) of the text.

float

viewer.scale_bar.events.box

If background box is visible or not.

bool

viewer.scale_bar.events.box_color

Background box color. See ColorValue.validate for supported values.

ColorValue

viewer.scale_bar.events.unit

Unit to be used by the scale bar. The value can be set to None to display no units.

str

viewer.text_overlay.events.visible

If text overlay is visible or not.

bool

viewer.text_overlay.events.color

A (4,) color array of the text overlay.

ColorValue

viewer.text_overlay.events.font_size

The font size (in points) of the text.

float

viewer.text_overlay.events.position

Position of the text overlay in the canvas. Must be one of ‘top left’, ‘top right’, ‘top center’, ‘bottom right’, ‘bottom left’, ‘bottom_center’. Default value is ‘top left’

TextOverlayPosition

viewer.text_overlay.events.text

Text to be displayed in the canvas.

str

viewer.tooltip.events.visible

If tooltip is visible or not.

bool

viewer.tooltip.events.text

text of tooltip

str

viewer.events.help

str

viewer.events.status

Union[str, Dict]

viewer.events.theme

str

viewer.events.title

The title of the viewer window.

str

viewer.events.mouse_over_canvas

bool

viewer.events.help

str

viewer.events.status

Union[str, Dict]

viewer.events.theme

str

viewer.events.title

The title of the viewer window. By default ‘napari’.

str

viewer.events.mouse_over_canvas

bool

LayerList events

Event

Description

Event.value type

layers.events.inserting

layers.events.inserted

layers.events.removing

layers.events.removed

layers.events.moving

layers.events.moved

layers.events.changed

layers.events.reordered

layers.selection.events.active

layers.selection.events.changed

Layer events

Events listed for the base class Layer are present on all layer types.

Class

Event

Description

Event.value type

Layer

layer.events.source

source of the layer (such as a plugin or widget)

Layer

layer.events.refresh

Layer

layer.events.set_data

Layer

layer.events.blending

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’, ‘translucent_no_depth’, ‘additive’, and ‘minimum’}.

Layer

layer.events.opacity

Opacity of the layer visual, between 0.0 and 1.0.

Layer

layer.events.visible

Whether the layer visual is currently being displayed.

Layer

layer.events.scale

Scale factors for the layer.

Layer

layer.events.translate

Translation values for the layer.

Layer

layer.events.rotate

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.

Layer

layer.events.shear

Either a vector of upper triangular values, or an nD shear matrix with ones along the main diagonal.

Layer

layer.events.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 length N translation vector and a 1 or a napari Affine transform object. Applied as an extra transform on top of the provided scale, rotate, and shear values.

Layer

layer.events.data

Layer

layer.events.name

Name of the layer.

Layer

layer.events.thumbnail

Array of thumbnail data for the layer.

Layer

layer.events.status

Displayed in status bar bottom left.

Layer

layer.events.help

Displayed in status bar bottom right.

Layer

layer.events.interactive

Determine if canvas pan/zoom interactivity is enabled.

Layer

layer.events.cursor

String identifying which cursor displayed over canvas.

Layer

layer.events.cursor_size

Size of cursor if custom. None yields default size

Layer

layer.events.editable

Layer

layer.events.loaded

Layer

layer.events._ndisplay

Layer

layer.events.select

Layer

layer.events.deselect

Image, Labels, Surface

layer.events.contrast_limits

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.

Image, Labels, Surface

layer.events.contrast_limits_range

Range for the color limits for luminance images. If the image is rgb the contrast_limits_range is ignored.

Image, Labels, Surface

layer.events.gamma

Gamma correction for determining colormap linearity. Defaults to 1.

Image, Labels, Surface

layer.events.colormap

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 Colormap.

Image, Labels

layer.events.mode

Interactive mode. The normal, default mode is PAN_ZOOM, which allows for normal interactivity with the canvas. In TRANSFORM mode the image can be transformed interactively.

Image, Labels, Surface

layer.events.interpolation

Interpolation mode used by vispy. Must be one of our supported modes.

Image, Labels

layer.events.interpolation2d

Image, Labels

layer.events.interpolation3d

Image, Labels, Surface

layer.events.rendering

Rendering mode used by vispy. Must be one of our supported modes.

Image, Labels

layer.events.depiction

3D Depiction mode. Must be one of {‘volume’, ‘plane’}. The default value is ‘volume’.

Image, Labels

layer.events.iso_threshold

Threshold for isosurface.

Image, Labels

layer.events.attenuation

Attenuation rate for attenuated maximum intensity projection.

Labels

layer.events.preserve_labels

Labels

layer.events.properties

Properties for each label. Each property should be an array of length N, where N is the number of labels, and the first property corresponds to background.

Labels

layer.events.n_edit_dimensions

The number of dimensions across which labels will be edited.

Labels

layer.events.contiguous

If True, the fill bucket changes only connected pixels of same label.

Labels

layer.events.brush_size

Size of the paint brush in data coordinates.

Labels

layer.events.selected_label

Index of selected label. Can be greater than the current maximum label.

Labels

layer.events.color_mode

Labels

layer.events.brush_shape

Labels

layer.events.contour

If greater than 0, displays contours of labels instead of shaded regions with a thickness equal to its value.

Labels

layer.events.features

Features table where each row corresponds to a label and each column is a feature. The first row corresponds to the background label.

Labels

layer.events.paint

Points

layer.events.mode

Interactive mode. The normal, default mode is PAN_ZOOM, which allows for normal interactivity with the canvas. In ADD mode clicks of the cursor add points at the clicked location. In SELECT mode the cursor can select points by clicking on them or by dragging a box around them. Once selected points can be moved, have their properties edited, or be deleted.

Points

layer.events.size

Size of the point marker in data pixels. If given as a scalar, all points are made the same size. If given as an array, size must be the same or broadcastable to the same shape as the data.

Points

layer.events.edge_width

Width of the symbol edge in pixels.

Points

layer.events.edge_width_is_relative

If enabled, edge_width is interpreted as a fraction of the point size.

Points

layer.events.face_color

Color of the point marker body. Numeric color values should be RGB(A).

Points

layer.events.current_face_color

Face color of the marker edge for the next point to be added or the currently selected point.

Points

layer.events.edge_color

Color of the point marker border. Numeric color values should be RGB(A).

Points

layer.events.current_edge_color

Edge color of the marker edge for the next point to be added or the currently selected point.

Points

layer.events.properties

Properties for each point. Each property should be an array of length N, where N is the number of points.

Points

layer.events.current_properties

Points

layer.events.symbol

Symbol to be used for the point markers. Must be one of the following: arrow, clobber, cross, diamond, disc, hbar, ring, square, star, tailed_arrow, triangle_down, triangle_up, vbar, x.

Points

layer.events.out_of_slice_display

If True, renders points not just in central plane but also slightly out of slice according to specified point marker size.

Points

layer.events.n_dimensional

This property will soon be deprecated in favor of ‘out_of_slice_display’. Use that instead.

Points

layer.events.highlight

Points

layer.events.shading

Render lighting and shading on points. Options are: * ‘none’ No shading is added to the points. * ‘spherical’ Shading and depth buffer are changed to give a 3D spherical look to the points

Points

layer.events.antialiasing

Points

layer.events.canvas_size_limits

Lower and upper limits for the size of points in canvas pixels.

Points

layer.events.features

Features table where each row corresponds to a point and each column is a feature.

Points

layer.events.feature_defaults

Stores the default value of each feature in a table with one row.

Vectors

layer.events.length

Multiplicative factor on projections for length of all vectors.

Vectors

layer.events.edge_width

Width for all vectors in pixels.

Vectors

layer.events.edge_color

Color of all of the vectors.

Vectors

layer.events.edge_color_mode

Vectors

layer.events.properties

Properties for each vector. Each property should be an array of length N, where N is the number of vectors.

Vectors

layer.events.out_of_slice_display

If True, renders vectors not just in central plane but also slightly out of slice according to specified point marker size.

Vectors

layer.events.features

Features table where each row corresponds to a vector and each column is a feature.

Vectors

layer.events.feature_defaults

Stores the default value of each feature in a table with one row.

Shapes

layer.events.mode

Interactive mode. The normal, default mode is PAN_ZOOM, which allows for normal interactivity with the canvas. The SELECT mode allows for entire shapes to be selected, moved and resized. The DIRECT mode allows for shapes to be selected and their individual vertices to be moved. The VERTEX_INSERT and VERTEX_REMOVE modes allow for individual vertices either to be added to or removed from shapes that are already selected. Note that shapes cannot be selected in this mode. The ADD_RECTANGLE, ADD_ELLIPSE, ADD_LINE, ADD_PATH, and ADD_POLYGON modes all allow for their corresponding shape type to be added.

Shapes

layer.events.edge_width

Thickness of lines and edges. If a list is supplied it must be the same length as the length of data and each element will be applied to each shape otherwise the same value will be used for all shapes.

Shapes

layer.events.edge_color

If string can be any color name recognized by vispy or hex value if starting with #. If array-like must be 1-dimensional array with 3 or 4 elements. If a list is supplied it must be the same length as the length of data and each element will be applied to each shape otherwise the same value will be used for all shapes.

Shapes

layer.events.face_color

If string can be any color name recognized by vispy or hex value if starting with #. If array-like must be 1-dimensional array with 3 or 4 elements. If a list is supplied it must be the same length as the length of data and each element will be applied to each shape otherwise the same value will be used for all shapes.

Shapes

layer.events.properties

Properties for each shape. Each property should be an array of length N, where N is the number of shapes.

Shapes

layer.events.current_edge_color

Color of the edge of the next shape to be added or the currently selected shape.

Shapes

layer.events.current_face_color

Color of the face of the next shape to be added or the currently selected shape.

Shapes

layer.events.current_properties

Shapes

layer.events.highlight

Shapes

layer.events.features

Features table where each row corresponds to a shape and each column is a feature.

Shapes

layer.events.feature_defaults

Stores the default value of each feature in a table with one row.

Surface

layer.events.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'.

Tracks

layer.events.tail_width

Width of the track tails in pixels.

Tracks

layer.events.tail_length

Length of the positive (backward in time) tails in units of time.

Tracks

layer.events.head_length

Length of the positive (forward in time) tails in units of time.

Tracks

layer.events.display_id

display the track id

Tracks

layer.events.display_tail

display the track tail

Tracks

layer.events.display_graph

display the graph edges

Tracks

layer.events.color_by

Track property (from property keys) by which to color vertices.

Tracks

layer.events.colormap

Default colormap to use to set vertex colors. Specialized colormaps, relating to specified properties can be passed to the layer via colormaps_dict.

Tracks

layer.events.properties

Properties for each point. Each property should be an array of length N, where N is the number of points.

Tracks

layer.events.rebuild_tracks

Tracks

layer.events.rebuild_graph