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.camera.events.center

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

Union

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

viewer.camera.events.perspective

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

float

viewer.camera.events.mouse_pan

If the camera interactive panning with the mouse is enabled or not.

bool

viewer.camera.events.mouse_zoom

If the camera interactive zooming with the mouse 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.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.cursor.events.size

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

float

viewer.dims.events.ndim

Number of dimensions.

int

viewer.dims.events.ndisplay

Number of displayed dimensions.

Literal

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.dims.events.rollable

Tuple of axis roll state. If True the axis is rollable.

bool

viewer.dims.events.range

List of tuples (min, max, step), one for each dimension in world coordinates space. Lower and upper bounds are inclusive.

RangeTuple

viewer.dims.events.margin_left

Left margin in world pixels of the slice for each dimension.

float

viewer.dims.events.margin_right

Right margin in world pixels of the slice for each dimension.

float

viewer.dims.events.point

Dims position in world coordinates for each dimension.

float

viewer.dims.events.last_used

Dimension which was last interacted with.

int

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

viewer.grid.events.enabled

If grid is enabled or not.

bool

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

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

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

Dimension names of the layer data. If not provided, axis_labels will be set to (…, ‘axis -2’, ‘axis -1’).

Layer

layer.events.data

Data that the layer is visualizing. Can be N-dimensional.

Layer

layer.events.metadata

Layer metadata.

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

Layer

layer.events.help

Displayed in status bar bottom right.

Layer

layer.events.loaded

Layer

layer.events.mode

Layer

layer.events.mouse_pan

Determine if canvas interactive panning is enabled with the mouse.

Layer

layer.events.mouse_zoom

Determine if canvas interactive zooming is enabled with the mouse.

Layer

layer.events.name

Name of the layer. If not provided then will be guessed using heuristics.

Layer

layer.events.opacity

Opacity of the layer visual, between 0.0 and 1.0.

Layer

layer.events.projection_mode

How data outside the viewed dimensions but inside the thick Dims slice will be projected onto the viewed dimensions. Must fit to cls._projectionclass.

Layer

layer.events.refresh

Layer

layer.events.reload

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

Scale factors for the layer.

Layer

layer.events.set_data

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

Displayed in status bar bottom left.

Layer

layer.events.thumbnail

Array of thumbnail data for the layer.

Layer

layer.events.translate

Translation values for the layer.

Layer

layer.events.units

Units of the layer data in world coordinates. If not provided, the default units are assumed to be pixels.

Layer

layer.events.visible

Whether the layer visual is currently being displayed.

Layer

layer.events.interactive

Determine if canvas pan/zoom interactivity is enabled. This attribute is deprecated since 0.5.0 and should not be used. Use the mouse_pan and mouse_zoom attributes instead.

Layer

layer.events._extent_augmented

Layer

layer.events._overlays

Image, Labels

layer.events.attenuation

Attenuation rate for attenuated maximum intensity projection.

Image, Labels

layer.events.custom_interpolation_kernel_2d

Convolution kernel used with the ‘custom’ interpolation mode in 2D rendering.

Image, Labels

layer.events.depiction

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

Image, Labels, Surface

layer.events.interpolation

Image, Labels

layer.events.interpolation2d

Interpolation mode used by vispy for rendering 2d data. Must be one of our supported modes. (for list of supported modes see Interpolation enum) ‘custom’ is a special mode for 2D interpolation in which a regular grid of samples is taken from the texture around a position using ‘linear’ interpolation before being multiplied with a custom interpolation kernel (provided with ‘custom_interpolation_kernel_2d’).

Image, Labels

layer.events.interpolation3d

Same as ‘interpolation2d’ but for 3D rendering.

Image, Labels

layer.events.iso_threshold

Threshold for isosurface.

Image, Labels

layer.events.plane

Properties defining plane rendering in 3D. Properties are defined in data coordinates. Valid dictionary keys are {‘position’, ‘normal’, ‘thickness’, and ‘enabled’}.

Image, Labels, Surface

layer.events.rendering

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

Image

layer.events.contrast_limits

Intensity value limits to be used for determining the minimum and maximum colormap bounds for luminance images. If not passed, they will be calculated as the min and max intensity value of the image.

Image

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

layer.events.gamma

Gamma correction for determining colormap linearity; defaults to 1.

Image, Labels, Surface

layer.events.colormap

Colormaps to use for luminance images. If a string, it can be the name of a supported colormap from vispy or matplotlib or the name of a vispy color or a hexadecimal RGB color representation. 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.

Labels

layer.events.brush_shape

Labels

layer.events.brush_size

Size of the paint brush in data coordinates.

Labels

layer.events.contiguous

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

Labels

layer.events.contour

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

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

Method for calulating the gradient (used to get the surface normal) in the ‘iso_categorical’ rendering mode. Must be one of {‘fast’, ‘smooth’}. ‘fast’ uses a simple finite difference gradient in x, y, and z. ‘smooth’ uses an isotropic Sobel gradient, which is smoother but more computationally expensive. The default value is ‘fast’.

Labels

layer.events.labels_update

Labels

layer.events.n_edit_dimensions

The number of dimensions across which labels will be edited.

Labels

layer.events.paint

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

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

Labels

layer.events.show_selected_label

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

Size of the marker for the next point to be added or the currently selected point.

Points

layer.events.border_width

Width of the symbol border in pixels.

Points

layer.events.current_border_width

Border width of the marker for the next point to be added or the currently selected point.

Points

layer.events.border_width_is_relative

If enabled, border_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 border for the next point to be added or the currently selected point.

Points

layer.events.border_color

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

Points

layer.events.current_border_color

Border color of the marker border 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

Symbols 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.current_symbol

Symbol for the next point to be added or the currently selected points.

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

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

Points

layer.events.edge_width

Points

layer.events.current_edge_width

Points

layer.events.edge_width_is_relative

Points

layer.events.edge_color

Points

layer.events.current_edge_color

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

One of a list of preset display modes that determines how vectors are displayed. Allowed values are {‘line’, ‘triangle’, and ‘arrow’}.

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

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

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

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

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.

Surface

layer.events.contrast_limits_range

Surface

layer.events.gamma

Gamma correction for determining colormap linearity. Defaults to 1.

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

Surface

layer.events.wireframe

Whether and how to display the edges of the surface mesh with a wireframe.

Surface

layer.events.normals

Whether and how to display the face and vertex normals of the surface mesh.

Surface

layer.events.texture

Surface

layer.events.texcoords

Surface

layer.events.features

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

Surface

layer.events.feature_defaults

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

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