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.

bool

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

Array

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

str

viewer.events.theme

str

viewer.events.title

The title of the viewer window.

str

viewer.events.help

str

viewer.events.status

str

viewer.events.theme

str

viewer.events.title

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

str

Layer events

Event

Description

Event.value type

layer.events.source

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

layer.events.refresh

layer.events.set_data

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

layer.events.opacity

Opacity of the layer visual, between 0.0 and 1.0.

layer.events.visible

Whether the layer visual is currently being displayed.

layer.events.scale

Scale factors for the layer.

layer.events.translate

Translation values for the 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.events.shear

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

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.events.data

layer.events.name

Name of the layer.

layer.events.thumbnail

Array of thumbnail data for the layer.

layer.events.status

Displayed in status bar bottom left.

layer.events.help

Displayed in status bar bottom right.

layer.events.interactive

Determine if canvas pan/zoom interactivity is enabled.

layer.events.cursor

String identifying which cursor displayed over canvas.

layer.events.cursor_size

Size of cursor if custom. None yields default size

layer.events.editable

layer.events.loaded

layer.events._ndisplay

layer.events.select

layer.events.deselect

layer.events.contrast_limits

list of float: Limits to use for the colormap.

layer.events.gamma

layer.events.colormap

napari.utils.Colormap: colormap for luminance images.

layer.events.mode

str: Interactive mode Interactive mode. The normal, default mode is PAN_ZOOM, which allows for normal interactivity with the canvas. TRANSFORM allows for manipulation of the layer transform.

layer.events.interpolation

Return current interpolation mode. Selects a preset interpolation mode in vispy that determines how volume is displayed. Makes use of the two Texture2D interpolation methods and the available interpolation methods defined in vispy/gloo/glsl/misc/spatial_filters.frag Options include: ‘bessel’, ‘bicubic’, ‘bilinear’, ‘blackman’, ‘catrom’, ‘gaussian’, ‘hamming’, ‘hanning’, ‘hermite’, ‘kaiser’, ‘lanczos’, ‘mitchell’, ‘nearest’, ‘spline16’, ‘spline36’ Returns ——- str The current interpolation mode

layer.events.rendering

Return current rendering mode. Selects a preset rendering mode in vispy that determines how volume is displayed. Options include: * translucent: voxel colors are blended along the view ray until the result is opaque. * mip: maximum intensity projection. Cast a ray and display the maximum value that was encountered. * minip: minimum intensity projection. Cast a ray and display the minimum value that was encountered. * attenuated_mip: attenuated maximum intensity projection. Cast a ray and attenuate values based on integral of encountered values, display the maximum value that was encountered after attenuation. This will make nearer objects appear more prominent. * additive: voxel colors are added along the view ray until the result is saturated. * iso: isosurface. Cast a ray until a certain threshold is encountered. At that location, lighning calculations are performed to give the visual appearance of a surface. * average: average intensity projection. Cast a ray and display the average of values that were encountered. Returns ——- str The current rendering mode

layer.events.iso_threshold

float: threshold for isosurface.

layer.events.attenuation

float: attenuation rate for attenuated_mip rendering.

layer.events.contrast_limits

layer.events.gamma

layer.events.colormap

layer.events.mode

Interactive mode. The normal, default mode is PAN_ZOOM, which allows for normal interactivity with the canvas. In PICK mode the cursor functions like a color picker, setting the clicked on label to be the current label. If the background is picked it will select the background label 0. In PAINT mode the cursor functions like a paint brush changing any pixels it brushes over to the current label. If the background label 0 is selected than any pixels will be changed to background and this tool functions like an eraser. The size and shape of the cursor can be adjusted in the properties widget. In FILL mode the cursor functions like a fill bucket replacing pixels of the label clicked on with the current label. It can either replace all pixels of that label or just those that are contiguous with the clicked on pixel. If the background label 0 is selected than any pixels will be changed to background and this tool functions like an eraser. In ERASE mode the cursor functions similarly to PAINT mode, but to paint with background label, which effectively removes the label.

layer.events.interpolation

layer.events.rendering

3D Rendering mode used by vispy. Must be one {‘translucent’, ‘iso_categorical’}. ‘translucent’ renders without lighting. ‘iso_categorical’ uses isosurface rendering to calculate lighting effects on labeled surfaces. The default value is ‘iso_categorical’.

layer.events.iso_threshold

layer.events.attenuation

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

layer.events.n_edit_dimensions

The number of dimensions across which labels will be edited.

layer.events.contiguous

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

layer.events.brush_size

Size of the paint brush in data coordinates.

layer.events.selected_label

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

layer.events.color_mode

layer.events.brush_shape

layer.events.contour

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

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.

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.

layer.events.edge_width

Width of the symbol edge in pixels.

layer.events.face_color

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

layer.events.current_face_color

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

layer.events.edge_color

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

layer.events.current_edge_color

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

layer.events.properties

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

layer.events.current_properties

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.

layer.events.n_dimensional

If True, renders points not just in central plane but also in all n-dimensions according to specified point marker size.

layer.events.highlight

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

layer.events._antialias

layer.events.experimental_canvas_size_limits

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

layer.events.length

Multiplicative factor on projections for length of all vectors.

layer.events.edge_width

Width for all vectors in pixels.

layer.events.edge_color

Color of all of the vectors.

layer.events.edge_color_mode

layer.events.properties

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

layer.events.n_dimensional

If True, renders vectors not just in central plane but also in all n-dimensions according to vectors lengths.

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.

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.

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.

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.

layer.events.properties

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

layer.events.current_edge_color

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

layer.events.current_face_color

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

layer.events.current_properties

layer.events.highlight

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.

layer.events.gamma

Gamma correction for determining colormap linearity. Defaults to 1.

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.

layer.events.interpolation

layer.events.rendering

layer.events.shading

layer.events.tail_width

Width of the track tails in pixels.

layer.events.tail_length

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

layer.events.head_length

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

layer.events.display_id

display the track id

layer.events.display_tail

display the track tail

layer.events.display_graph

display the graph edges

layer.events.color_by

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.

layer.events.properties

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

layer.events.rebuild_tracks

layer.events.rebuild_graph