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.	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.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.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.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. 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.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.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.extent
Layer	layer.events._overlays
Layer	layer.events.select
Layer	layer.events.deselect
Layer	layer.events.mode
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, Surface	layer.events.interpolation	Interpolation mode used by vispy. Must be one of our supported modes. ‘custom’ is a special mode for 2D interpolation in which a regular grid of samples are 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.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.plane	Properties defining plane rendering in 3D. Properties are defined in data coordinates. Valid dictionary keys are {‘position’, ‘normal’, ‘thickness’, and ‘enabled’}.
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.
Image, Labels	layer.events.custom_interpolation_kernel_2d	Convolution kernel used with the ‘custom’ interpolation mode in 2D rendering.
Labels	layer.events.preserve_labels
Labels	layer.events.show_selected_label
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. 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.paint
Labels	layer.events.labels_update
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.edge_width	Width of the symbol edge in pixels.
Points	layer.events.current_edge_width	Edge width of the marker for the next point to be added or the currently selected point.
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	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.
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	Stores 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.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
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