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

previous

napari’s application model

next

Glossary