napari.view_layers.Viewer

class napari.view_layers.Viewer(*, title='napari', ndisplay=2, order=(), axis_labels=(), show=True)[source]

Bases: napari.components.viewer_model.ViewerModel

Napari ndarray viewer.

Parameters

  • title (string, optional) – The title of the viewer window. by default ‘napari’.

  • ndisplay ({2, 3}, optional) – Number of displayed dimensions. by default 2.

  • order (tuple of int, optional) – Order in which dimensions are displayed where the last two or last three dimensions correspond to row x column or plane x row x column if ndisplay is 2 or 3. by default None

  • axis_labels (list of str, optional) – Dimension names. by default they are labeled with sequential numbers

  • show (bool, optional) – Whether to show the viewer after instantiation. by default True.

Methods

add_image([data, channel_axis, rgb, ...])

Add an image layer to the layer list.

add_labels(data, *[, num_colors, features, ...])

Add a Labels layer to the layer list.

add_layer(layer)

Add a layer to the viewer.

add_points([data, ndim, features, ...])

Add a Points layer to the layer list.

add_shapes([data, ndim, features, ...])

Add a Shapes layer to the layer list.

add_surface(data, *[, colormap, ...])

Add a Surface layer to the layer list.

add_tracks(data, *[, features, properties, ...])

Add a Tracks layer to the layer list.

add_vectors([data, ndim, features, ...])

Add a Vectors layer to the layer list.

bind_key(key[, func, overwrite])

Bind a key combination to a keymap.

close()

Close the viewer window.

close_all()

Class metod, Close all existing viewer instances.

construct([_fields_set])

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data.

copy(*[, include, exclude, update, deep])

Duplicate a model, optionally choose which fields to include, exclude and change.

dict(**kwargs)

Convert to a dictionary.

enums_as_values([as_values])

Temporarily override how enums are retrieved.

from_orm(obj)

json(**kwargs)

Serialize to json.

open(path, *[, stack, plugin, layer_type])

Open a path or list of paths with plugins, and add layers to viewer.

open_sample(plugin, sample[, reader_plugin])

Open sample from plugin and add it to the viewer.

parse_file(path, *[, content_type, ...])

parse_obj(obj)

parse_raw(b, *[, content_type, encoding, ...])

reset()

Reset the state of the model to default values.

reset_view()

Reset the camera view.

rounded_division(min_val, max_val, precision)

schema([by_alias, ref_template])

schema_json(*[, by_alias, ref_template])

screenshot([path, canvas_only, flash])

Take currently displayed screen and convert to an image array.

show(*[, block])

Resize, show, and raise the viewer window.

update(values[, recurse])

Update a model in place.

update_console(variables)

Update console's namespace with desired variables.

update_forward_refs(**localns)

Try to update ForwardRefs on fields based on this Model, globalns and localns.

validate(value)

Attributes

class_keymap

events

experimental

Experimental commands for IPython console.

window

Details

add_image(data=None, *, channel_axis=None, rgb=None, colormap=None, contrast_limits=None, gamma=1, interpolation='nearest', rendering='mip', depiction='volume', iso_threshold=0.5, attenuation=0.05, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=1, blending=None, visible=True, multiscale=None, cache=True, plane=None, experimental_clipping_planes=None) → Union[napari.layers.image.image.Image, List[napari.layers.image.image.Image]]

Add an image layer to the layer list.

Parameters

  • data (array or list of array) – Image data. Can be N >= 2 dimensional. If the last dimension has length 3 or 4 can be interpreted as RGB or RGBA if rgb is True. If a list and arrays are decreasing in shape then the data is treated as a multiscale image. Please note multiscale rendering is only supported in 2D. In 3D, only the lowest resolution scale is displayed.

  • channel_axis (int, optional) – Axis to expand image along. If provided, each channel in the data will be added as an individual image layer. In channel_axis mode, all other parameters MAY be provided as lists, and the Nth value will be applied to the Nth channel in the data. If a single value is provided, it will be broadcast to all Layers.

  • rgb (bool or list) – Whether the image is rgb RGB or RGBA. If not specified by user and the last dimension of the data has length 3 or 4 it will be set as True. If False the image is interpreted as a luminance image. If a list then must be same length as the axis that is being expanded as channels.

  • colormap (str, napari.utils.Colormap, tuple, dict, list) – Colormaps 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. If a list then must be same length as the axis that is being expanded as channels, and each colormap is applied to each new image layer.

  • contrast_limits (list (2,)) – 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. If list of lists then must be same length as the axis that is being expanded and then each colormap is applied to each image.

  • gamma (list, float) – Gamma correction for determining colormap linearity. Defaults to 1. If a list then must be same length as the axis that is being expanded as channels.

  • interpolation (str or list) – Interpolation mode used by vispy. Must be one of our supported modes. If a list then must be same length as the axis that is being expanded as channels.

  • rendering (str or list) – Rendering mode used by vispy. Must be one of our supported modes. If a list then must be same length as the axis that is being expanded as channels.

  • depiction (str) –

    Selects a preset volume depiction mode in vispy

    • volume: images are rendered as 3D volumes.

    • plane: images are rendered as 2D planes embedded in 3D.

  • iso_threshold (float or list) – Threshold for isosurface. If a list then must be same length as the axis that is being expanded as channels.

  • attenuation (float or list) – Attenuation rate for attenuated maximum intensity projection. If a list then must be same length as the axis that is being expanded as channels.

  • name (str or list of str) – Name of the layer. If a list then must be same length as the axis that is being expanded as channels.

  • metadata (dict or list of dict) – Layer metadata. If a list then must be a list of dicts with the same length as the axis that is being expanded as channels.

  • scale (tuple of float or list) – Scale factors for the layer. If a list then must be a list of tuples of float with the same length as the axis that is being expanded as channels.

  • translate (tuple of float or list) – Translation values for the layer. If a list then must be a list of tuples of float with the same length as the axis that is being expanded as channels.

  • rotate (float, 3-tuple of float, n-D array or list.) – 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. If a list then must have same length as the axis that is being expanded as channels.

  • shear (1-D array or list.) – A vector of shear values for an upper triangular n-D shear matrix. If a list then must have same length as the axis that is being expanded as channels.

  • affine (n-D array or napari.utils.transforms.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.

  • opacity (float or list) – Opacity of the layer visual, between 0.0 and 1.0. If a list then must be same length as the axis that is being expanded as channels.

  • blending (str or list) – 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’, and ‘additive’}. If a list then must be same length as the axis that is being expanded as channels.

  • visible (bool or list of bool) – Whether the layer visual is currently being displayed. If a list then must be same length as the axis that is being expanded as channels.

  • multiscale (bool) – Whether the data is a multiscale image or not. Multiscale data is represented by a list of array like image data. If not specified by the user and if the data is a list of arrays that decrease in shape then it will be taken to be multiscale. The first image in the list should be the largest. Please note multiscale rendering is only supported in 2D. In 3D, only the lowest resolution scale is displayed.

  • cache (bool) – Whether slices of out-of-core datasets should be cached upon retrieval. Currently, this only applies to dask arrays.

  • plane (dict or SlicingPlane) – Properties defining plane rendering in 3D. Properties are defined in data coordinates. Valid dictionary keys are {‘position’, ‘normal’, ‘thickness’, and ‘enabled’}.

  • experimental_clipping_planes (list of dicts, list of ClippingPlane, or ClippingPlaneList) – Each dict defines a clipping plane in 3D in data coordinates. Valid dictionary keys are {‘position’, ‘normal’, and ‘enabled’}. Values on the negative side of the normal are discarded if the plane is enabled.

Returns

layer – The newly-created image layer or list of image layers.

Return type

napari.layers.Image or list

add_labels(data, *, num_colors=50, features=None, properties=None, color=None, seed=0.5, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=0.7, blending='translucent', rendering='iso_categorical', depiction='volume', visible=True, multiscale=None, cache=True, plane=None, experimental_clipping_planes=None) → napari.layers.labels.labels.Labels

Add a Labels layer to the layer list.

Parameters

  • data (array or list of array) – Labels data as an array or multiscale. Must be integer type or bools. Please note multiscale rendering is only supported in 2D. In 3D, only the lowest resolution scale is displayed.

  • num_colors (int) – Number of unique colors to use in colormap.

  • features (dict[str, array-like] or DataFrame) – Features table where each row corresponds to a label and each column is a feature. The first row corresponds to the background label.

  • properties (dict {str: array (N,)} or DataFrame) – 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.

  • color (dict of int to str or array) – Custom label to color mapping. Values must be valid color names or RGBA arrays.

  • seed (float) – Seed for colormap random generator.

  • name (str) – Name of the layer.

  • metadata (dict) – Layer metadata.

  • scale (tuple of float) – Scale factors for the layer.

  • translate (tuple of float) – Translation values for the layer.

  • rotate (float, 3-tuple of float, or n-D array.) – 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.

  • shear (1-D array or n-D array) – Either a vector of upper triangular values, or an nD shear matrix with ones along the main diagonal.

  • affine (n-D array or napari.utils.transforms.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.

  • opacity (float) – Opacity of the layer visual, between 0.0 and 1.0.

  • blending (str) – 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’, and ‘additive’}.

  • rendering (str) – 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’.

  • depiction (str) – 3D Depiction mode. Must be one of {‘volume’, ‘plane’}. The default value is ‘volume’.

  • visible (bool) – Whether the layer visual is currently being displayed.

  • multiscale (bool) – Whether the data is a multiscale image or not. Multiscale data is represented by a list of array like image data. If not specified by the user and if the data is a list of arrays that decrease in shape then it will be taken to be multiscale. The first image in the list should be the largest. Please note multiscale rendering is only supported in 2D. In 3D, only the lowest resolution scale is displayed.

  • cache (bool) – Whether slices of out-of-core datasets should be cached upon retrieval. Currently, this only applies to dask arrays.

  • plane (dict or SlicingPlane) – Properties defining plane rendering in 3D. Properties are defined in data coordinates. Valid dictionary keys are {‘position’, ‘normal’, ‘thickness’, and ‘enabled’}.

  • experimental_clipping_planes (list of dicts, list of ClippingPlane, or ClippingPlaneList) – Each dict defines a clipping plane in 3D in data coordinates. Valid dictionary keys are {‘position’, ‘normal’, and ‘enabled’}. Values on the negative side of the normal are discarded if the plane is enabled.

data

Integer label data as an array or multiscale. Can be N dimensional. Every pixel contains an integer ID corresponding to the region it belongs to. The label 0 is rendered as transparent. Please note multiscale rendering is only supported in 2D. In 3D, only the lowest resolution scale is displayed.

Type

array or list of array

multiscale

Whether the data is a multiscale image or not. Multiscale data is represented by a list of array like image data. The first image in the list should be the largest. Please note multiscale rendering is only supported in 2D. In 3D, only the lowest resolution scale is displayed.

Type

bool

metadata

Labels metadata.

Type

dict

num_colors

Number of unique colors to use in colormap.

Type

int

features

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

Type

Dataframe-like

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.

Type

dict {str: array (N,)}, DataFrame

color

Custom label to color mapping. Values must be valid color names or RGBA arrays.

Type

dict of int to str or array

seed

Seed for colormap random generator.

Type

float

opacity

Opacity of the labels, must be between 0 and 1.

Type

float

contiguous

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

Type

bool

n_edit_dimensions

The number of dimensions across which labels will be edited.

Type

int

contour

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

Type

int

brush_size

Size of the paint brush in data coordinates.

Type

float

selected_label

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

Type

int

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.

Type

str

plane

Properties defining plane rendering in 3D.

Type

SlicingPlane

experimental_clipping_planes

Clipping planes defined in data coordinates, used to clip the volume.

Type

ClippingPlaneList

Notes

_selected_color4-tuple or None

RGBA tuple of the color of the selected label, or None if the background label 0 is selected.

Returns

layer – The newly-created labels layer.

Return type

napari.layers.Labels

add_layer(layer: napari.layers.base.base.Layer) → napari.layers.base.base.Layer

Add a layer to the viewer.

Parameters

layer (napari.layers.Layer) – Layer to add.

Returns

layer – The layer that was added (same as input).

Return type

napari.layers.Layer or list

add_points(data=None, *, ndim=None, features=None, properties=None, text=None, symbol='o', size=10, edge_width=0.1, edge_width_is_relative=True, edge_color='black', edge_color_cycle=None, edge_colormap='viridis', edge_contrast_limits=None, face_color='white', face_color_cycle=None, face_colormap='viridis', face_contrast_limits=None, out_of_slice_display=False, n_dimensional=None, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=1, blending='translucent', visible=True, cache=True, property_choices=None, experimental_clipping_planes=None, shading='none', experimental_canvas_size_limits=(0, 10000), shown=True) → napari.layers.points.points.Points

Add a Points layer to the layer list.

Parameters

  • data (array (N, D)) – Coordinates for N points in D dimensions.

  • ndim (int) – Number of dimensions for shapes. When data is not None, ndim must be D. An empty points layer can be instantiated with arbitrary ndim.

  • features (dict[str, array-like] or DataFrame) – Features table where each row corresponds to a point and each column is a feature.

  • properties (dict {str: array (N,)}, DataFrame) – Properties for each point. Each property should be an array of length N, where N is the number of points.

  • property_choices (dict {str: array (N,)}) – possible values for each property.

  • text (str, dict) – Text to be displayed with the points. If text is set to a key in properties, the value of that property will be displayed. Multiple properties can be composed using f-string-like syntax (e.g., ‘{property_1}, {float_property:.2f}). A dictionary can be provided with keyword arguments to set the text values and display properties. See TextManager.__init__() for the valid keyword arguments. For example usage, see /napari/examples/add_points_with_text.py.

  • symbol (str) – 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.

  • size (float, array) – 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.

  • edge_width (float, array) – Width of the symbol edge in pixels.

  • edge_width_is_relative (bool) – If enabled, edge_width is interpreted as a fraction of the point size.

  • edge_color (str, array-like, dict) – Color of the point marker border. Numeric color values should be RGB(A).

  • edge_color_cycle (np.ndarray, list) – Cycle of colors (provided as string name, RGB, or RGBA) to map to edge_color if a categorical attribute is used color the vectors.

  • edge_colormap (str, napari.utils.Colormap) – Colormap to set edge_color if a continuous attribute is used to set face_color.

  • edge_contrast_limits (None, (float, float)) – clims for mapping the property to a color map. These are the min and max value of the specified property that are mapped to 0 and 1, respectively. The default value is None. If set the none, the clims will be set to (property.min(), property.max())

  • face_color (str, array-like, dict) – Color of the point marker body. Numeric color values should be RGB(A).

  • face_color_cycle (np.ndarray, list) – Cycle of colors (provided as string name, RGB, or RGBA) to map to face_color if a categorical attribute is used color the vectors.

  • face_colormap (str, napari.utils.Colormap) – Colormap to set face_color if a continuous attribute is used to set face_color.

  • face_contrast_limits (None, (float, float)) – clims for mapping the property to a color map. These are the min and max value of the specified property that are mapped to 0 and 1, respectively. The default value is None. If set the none, the clims will be set to (property.min(), property.max())

  • out_of_slice_display (bool) – If True, renders points not just in central plane but also slightly out of slice according to specified point marker size.

  • n_dimensional (bool) – This property will soon be deprecated in favor of ‘out_of_slice_display’. Use that instead.

  • name (str) – Name of the layer.

  • metadata (dict) – Layer metadata.

  • scale (tuple of float) – Scale factors for the layer.

  • translate (tuple of float) – Translation values for the layer.

  • rotate (float, 3-tuple of float, or n-D array.) – 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.

  • shear (1-D array or n-D array) – Either a vector of upper triangular values, or an nD shear matrix with ones along the main diagonal.

  • affine (n-D array or napari.utils.transforms.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.

  • opacity (float) – Opacity of the layer visual, between 0.0 and 1.0.

  • blending (str) – 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’, and ‘additive’}.

  • visible (bool) – Whether the layer visual is currently being displayed.

  • cache (bool) – Whether slices of out-of-core datasets should be cached upon retrieval. Currently, this only applies to dask arrays.

  • shading (str, 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

  • experimental_canvas_size_limits (tuple of float) – Lower and upper limits for the size of points in canvas pixels.

  • shown (1-D array of bool) – Whether to show each point.

data

Coordinates for N points in D dimensions.

Type

array (N, D)

features

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

Type

DataFrame-like

feature_defaults

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

Type

DataFrame-like

properties

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

Type

dict {str: array (N,)} or DataFrame

text

Text to be displayed with the points. If text is set to a key in properties, the value of that property will be displayed. Multiple properties can be composed using f-string-like syntax (e.g., ‘{property_1}, {float_property:.2f}). For example usage, see /napari/examples/add_points_with_text.py.

Type

str

symbol

Symbol used for all point markers.

Type

str

size

Array of sizes for each point in each dimension. Must have the same shape as the layer data.

Type

array (N, D)

edge_width

Width of the marker edges in pixels for all points

Type

array (N,)

edge_width

Width of the marker edges for all points as a fraction of their size.

Type

array (N,)

edge_color

Array of edge color RGBA values, one for each point.

Type

Nx4 numpy array

edge_color_cycle

Cycle of colors (provided as string name, RGB, or RGBA) to map to edge_color if a categorical attribute is used color the vectors.

Type

np.ndarray, list

edge_colormap

Colormap to set edge_color if a continuous attribute is used to set face_color.

Type

str, napari.utils.Colormap

edge_contrast_limits

clims for mapping the property to a color map. These are the min and max value of the specified property that are mapped to 0 and 1, respectively. The default value is None. If set the none, the clims will be set to (property.min(), property.max())

Type

None, (float, float)

face_color

Array of face color RGBA values, one for each point.

Type

Nx4 numpy array

face_color_cycle

Cycle of colors (provided as string name, RGB, or RGBA) to map to face_color if a categorical attribute is used color the vectors.

Type

np.ndarray, list

face_colormap

Colormap to set face_color if a continuous attribute is used to set face_color.

Type

str, napari.utils.Colormap

face_contrast_limits

clims for mapping the property to a color map. These are the min and max value of the specified property that are mapped to 0 and 1, respectively. The default value is None. If set the none, the clims will be set to (property.min(), property.max())

Type

None, (float, float)

current_size

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

Type

float

current_edge_width

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

Type

float

current_edge_color

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

Type

str

current_face_color

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

Type

str

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.

Type

bool

selected_data

Integer indices of any selected points.

Type

set

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.

Type

str

face_color_mode

Face color setting mode.

DIRECT (default mode) allows each point to be set arbitrarily

CYCLE allows the color to be set via a color cycle over an attribute

COLORMAP allows color to be set via a color map over an attribute

Type

str

edge_color_mode

Edge color setting mode.

DIRECT (default mode) allows each point to be set arbitrarily

CYCLE allows the color to be set via a color cycle over an attribute

COLORMAP allows color to be set via a color map over an attribute

Type

str

shading

Shading mode.

Type

Shading

experimental_canvas_size_limits

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

Type

tuple of float

shown

Whether each point is shown.

Type

1-D array of bool

Notes

_view_dataarray (M, 2)

2D coordinates of points in the currently viewed slice.

_view_sizearray (M, )

Size of the point markers in the currently viewed slice.

_view_edge_widtharray (M, )

Edge width of the point markers in the currently viewed slice.

_indices_viewarray (M, )

Integer indices of the points in the currently viewed slice and are shown.

_selected_view :

Integer indices of selected points in the currently viewed slice within the _view_data array.

_selected_boxarray (4, 2) or None

Four corners of any box either around currently selected points or being created during a drag action. Starting in the top left and going clockwise.

_drag_startlist or None

Coordinates of first cursor click during a drag action. Gets reset to None after dragging is done.

_antialiasfloat

The amount of antialiasing pixels for both the marker and marker edge.

Returns

layer – The newly-created points layer.

Return type

napari.layers.Points

add_shapes(data=None, *, ndim=None, features=None, properties=None, property_choices=None, text=None, shape_type='rectangle', edge_width=1, edge_color='#777777', edge_color_cycle=None, edge_colormap='viridis', edge_contrast_limits=None, face_color='white', face_color_cycle=None, face_colormap='viridis', face_contrast_limits=None, z_index=0, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=0.7, blending='translucent', visible=True, cache=True, experimental_clipping_planes=None) → napari.layers.shapes.shapes.Shapes

Add a Shapes layer to the layer list.

Parameters

  • data (list or array) – List of shape data, where each element is an (N, D) array of the N vertices of a shape in D dimensions. Can be an 3-dimensional array if each shape has the same number of vertices.

  • ndim (int) – Number of dimensions for shapes. When data is not None, ndim must be D. An empty shapes layer can be instantiated with arbitrary ndim.

  • features (dict[str, array-like] or Dataframe-like) – Features table where each row corresponds to a shape and each column is a feature.

  • properties (dict {str: array (N,)}, DataFrame) – Properties for each shape. Each property should be an array of length N, where N is the number of shapes.

  • property_choices (dict {str: array (N,)}) – possible values for each property.

  • text (str, dict) – Text to be displayed with the shapes. If text is set to a key in properties, the value of that property will be displayed. Multiple properties can be composed using f-string-like syntax (e.g., ‘{property_1}, {float_property:.2f}). A dictionary can be provided with keyword arguments to set the text values and display properties. See TextManager.__init__() for the valid keyword arguments. For example usage, see /napari/examples/add_shapes_with_text.py.

  • shape_type (string or list) – String of shape shape_type, must be one of “{‘line’, ‘rectangle’, ‘ellipse’, ‘path’, ‘polygon’}”. 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.

  • edge_width (float or list) – 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.

  • edge_color (str, array-like) – 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.

  • edge_color_cycle (np.ndarray, list) – Cycle of colors (provided as string name, RGB, or RGBA) to map to edge_color if a categorical attribute is used color the vectors.

  • edge_colormap (str, napari.utils.Colormap) – Colormap to set edge_color if a continuous attribute is used to set face_color.

  • edge_contrast_limits (None, (float, float)) – clims for mapping the property to a color map. These are the min and max value of the specified property that are mapped to 0 and 1, respectively. The default value is None. If set the none, the clims will be set to (property.min(), property.max())

  • face_color (str, array-like) – 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.

  • face_color_cycle (np.ndarray, list) – Cycle of colors (provided as string name, RGB, or RGBA) to map to face_color if a categorical attribute is used color the vectors.

  • face_colormap (str, napari.utils.Colormap) – Colormap to set face_color if a continuous attribute is used to set face_color.

  • face_contrast_limits (None, (float, float)) – clims for mapping the property to a color map. These are the min and max value of the specified property that are mapped to 0 and 1, respectively. The default value is None. If set the none, the clims will be set to (property.min(), property.max())

  • z_index (int or list) – Specifier of z order priority. Shapes with higher z order are displayed ontop of others. 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.

  • name (str) – Name of the layer.

  • metadata (dict) – Layer metadata.

  • scale (tuple of float) – Scale factors for the layer.

  • translate (tuple of float) – Translation values for the layer.

  • rotate (float, 3-tuple of float, or n-D array.) – 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.

  • shear (1-D array or n-D array) – Either a vector of upper triangular values, or an nD shear matrix with ones along the main diagonal.

  • affine (n-D array or napari.utils.transforms.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.

  • opacity (float) – Opacity of the layer visual, between 0.0 and 1.0.

  • blending (str) – 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’, and ‘additive’}.

  • visible (bool) – Whether the layer visual is currently being displayed.

  • cache (bool) – Whether slices of out-of-core datasets should be cached upon retrieval. Currently, this only applies to dask arrays.

data

List of shape data, where each element is an (N, D) array of the N vertices of a shape in D dimensions.

Type

(N, ) list of array

features

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

Type

Dataframe-like

feature_defaults

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

Type

DataFrame-like

properties

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

Type

dict {str: array (N,)}, DataFrame

text

Text to be displayed with the shapes. If text is set to a key in properties, the value of that property will be displayed. Multiple properties can be composed using f-string-like syntax (e.g., ‘{property_1}, {float_property:.2f}). For example usage, see /napari/examples/add_shapes_with_text.py.

Type

str, dict

shape_type

Name of shape type for each shape.

Type

(N, ) list of str

edge_color

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

Type

str, array-like

face_color

Color of the shape face. Numeric color values should be RGB(A).

Type

str, array-like

edge_width

Edge width for each shape.

Type

(N, ) list of float

z_index

z-index for each shape.

Type

(N, ) list of int

current_edge_width

Thickness of lines and edges of the next shape to be added or the currently selected shape.

Type

float

current_edge_color

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

Type

str

current_face_color

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

Type

str

selected_data

List of currently selected shapes.

Type

set

nshapes

Total number of shapes.

Type

int

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.

Type

Mode

Notes

_data_dictDict of ShapeList

Dictionary containing all the shape data indexed by slice tuple

_data_viewShapeList

Object containing the currently viewed shape data.

_selected_data_historyset

Set of currently selected captured on press of <space>.

_selected_data_storedset

Set of selected previously displayed. Used to prevent rerendering the same highlighted shapes when no data has changed.

_selected_boxNone | np.ndarray

None if no shapes are selected, otherwise a 10x2 array of vertices of the interaction box. The first 8 points are the corners and midpoints of the box. The 9th point is the center of the box, and the last point is the location of the rotation handle that can be used to rotate the box.

_drag_startNone | np.ndarray

If a drag has been started and is in progress then a length 2 array of the initial coordinates of the drag. None otherwise.

_drag_boxNone | np.ndarray

If a drag box is being created to select shapes then this is a 2x2 array of the two extreme corners of the drag. None otherwise.

_drag_box_storedNone | np.ndarray

If a drag box is being created to select shapes then this is a 2x2 array of the two extreme corners of the drag that have previously been rendered. None otherwise. Used to prevent rerendering the same drag box when no data has changed.

_is_movingbool

Bool indicating if any shapes are currently being moved.

_is_selectingbool

Bool indicating if a drag box is currently being created in order to select shapes.

_is_creatingbool

Bool indicating if any shapes are currently being created.

_fixed_aspectbool

Bool indicating if aspect ratio of shapes should be preserved on resizing.

_aspect_ratiofloat

Value of aspect ratio to be preserved if _fixed_aspect is True.

_fixed_vertexNone | np.ndarray

If a scaling or rotation is in progress then a length 2 array of the coordinates that are remaining fixed during the move. None otherwise.

_fixed_indexint

If a scaling or rotation is in progress then the index of the vertex of the bounding box that is remaining fixed during the move. None otherwise.

_update_propertiesbool

Bool indicating if properties are to allowed to update the selected shapes when they are changed. Blocking this prevents circular loops when shapes are selected and the properties are changed based on that selection

_allow_thumbnail_updatebool

Flag set to true to allow the thumbnail to be updated. Blocking the thumbnail can be advantageous where responsiveness is critical.

_clipboarddict

Dict of shape objects that are to be used during a copy and paste.

_colorslist

List of supported vispy color names.

_vertex_sizefloat

Size of the vertices of the shapes and bounding box in Canvas coordinates.

_rotation_handle_lengthfloat

Length of the rotation handle of the bounding box in Canvas coordinates.

_input_ndimint

Dimensions of shape data.

_thumbnail_update_threshint

If there are more than this number of shapes, the thumbnail won’t update during interactive events

Returns

layer – The newly-created shapes layer.

Return type

napari.layers.Shapes

add_surface(data, *, colormap='gray', contrast_limits=None, gamma=1, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=1, blending='translucent', shading='flat', visible=True, cache=True, experimental_clipping_planes=None, wireframe=None, normals=None) → napari.layers.surface.surface.Surface

Add a Surface layer to the layer list.

Parameters

  • data (2-tuple or 3-tuple of array) – The first element of the tuple is an (N, D) array of vertices of mesh triangles. The second is an (M, 3) array of int of indices of the mesh triangles. The optional third element is the (K0, …, KL, N) array of values used to color vertices where the additional L dimensions are used to color the same mesh with different values. If not provided, it defaults to ones.

  • colormap (str, napari.utils.Colormap, tuple, dict) – 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.

  • contrast_limits (list (2,)) – 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.

  • gamma (float) – Gamma correction for determining colormap linearity. Defaults to 1.

  • name (str) – Name of the layer.

  • metadata (dict) – Layer metadata.

  • scale (tuple of float) – Scale factors for the layer.

  • translate (tuple of float) – Translation values for the layer.

  • rotate (float, 3-tuple of float, or n-D array.) – 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.

  • shear (1-D array or n-D array) – Either a vector of upper triangular values, or an nD shear matrix with ones along the main diagonal.

  • affine (n-D array or napari.utils.transforms.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.

  • opacity (float) – Opacity of the layer visual, between 0.0 and 1.0.

  • blending (str) – 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’, and ‘additive’}.

  • shading (str, 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’.

  • visible (bool) – Whether the layer visual is currently being displayed.

  • cache (bool) – Whether slices of out-of-core datasets should be cached upon retrieval. Currently, this only applies to dask arrays.

  • wireframe (dict or SurfaceWireframe) – Whether and how to display the edges of the surface mesh with a wireframe.

  • normals (dict or SurfaceNormals) – Whether and how to display the face and vertex normals of the surface mesh.

data

The first element of the tuple is an (N, D) array of vertices of mesh triangles. The second is an (M, 3) array of int of indices of the mesh triangles. The third element is the (K0, …, KL, N) array of values used to color vertices where the additional L dimensions are used to color the same mesh with different values.

Type

3-tuple of array

vertices

Vertices of mesh triangles.

Type

(N, D) array

faces

Indices of mesh triangles.

Type

(M, 3) array of int

vertex_values

Values used to color vertices.

Type

(K0, …, KL, N) array

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.

Type

str, napari.utils.Colormap, tuple, dict

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.

Type

list (2,)

shading

One of a list of preset shading modes that determine the lighting model using when rendering the surface.

  • ‘none’

  • ‘flat’

  • ‘smooth’

Type

str

gamma

Gamma correction for determining colormap linearity.

Type

float

wireframe

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

Type

SurfaceWireframe

normals

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

Type

SurfaceNormals

Notes

_data_view(M, 2) or (M, 3) array

The coordinates of the vertices given the viewed dimensions.

_view_faces(P, 3) array

The integer indices of the vertices that form the triangles in the currently viewed slice.

_colorbararray

Colorbar for current colormap.

Returns

layer – The newly-created surface layer.

Return type

napari.layers.Surface

add_tracks(data, *, features=None, properties=None, graph=None, tail_width=2, tail_length=30, head_length=0, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=1, blending='additive', visible=True, colormap='turbo', color_by='track_id', colormaps_dict=None, cache=True, experimental_clipping_planes=None) → napari.layers.tracks.tracks.Tracks

Add a Tracks layer to the layer list.

Parameters

  • data (array (N, D+1)) – Coordinates for N points in D+1 dimensions. ID,T,(Z),Y,X. The first axis is the integer ID of the track. D is either 3 or 4 for planar or volumetric timeseries respectively.

  • features (Dataframe-like) – Features table where each row corresponds to a point and each column is a feature.

  • properties (dict {str: array (N,)}, DataFrame) – Properties for each point. Each property should be an array of length N, where N is the number of points.

  • graph (dict {int: list}) – Graph representing associations between tracks. Dictionary defines the mapping between a track ID and the parents of the track. This can be one (the track has one parent, and the parent has >=1 child) in the case of track splitting, or more than one (the track has multiple parents, but only one child) in the case of track merging. See examples/tracks_3d_with_graph.py

  • color_by (str) – Track property (from property keys) by which to color vertices.

  • tail_width (float) – Width of the track tails in pixels.

  • tail_length (float) – Length of the positive (backward in time) tails in units of time.

  • head_length (float) – Length of the positive (forward in time) tails in units of time.

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

  • colormaps_dict (dict {str: napari.utils.Colormap}) – Optional dictionary mapping each property to a colormap for that property. This allows each property to be assigned a specific colormap, rather than having a global colormap for everything.

  • name (str) – Name of the layer.

  • metadata (dict) – Layer metadata.

  • scale (tuple of float) – Scale factors for the layer.

  • translate (tuple of float) – Translation values for the layer.

  • rotate (float, 3-tuple of float, or n-D array.) – 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.

  • shear (1-D array or n-D array) – Either a vector of upper triangular values, or an nD shear matrix with ones along the main diagonal.

  • affine (n-D array or napari.utils.transforms.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.

  • opacity (float) – Opacity of the layer visual, between 0.0 and 1.0.

  • blending (str) – 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’, and ‘additive’}.

  • visible (bool) – Whether the layer visual is currently being displayed.

  • cache (bool) – Whether slices of out-of-core datasets should be cached upon retrieval. Currently, this only applies to dask arrays.

Returns

layer – The newly-created tracks layer.

Return type

napari.layers.Tracks

add_vectors(data=None, *, ndim=None, features=None, properties=None, property_choices=None, edge_width=1, edge_color='red', edge_color_cycle=None, edge_colormap='viridis', edge_contrast_limits=None, out_of_slice_display=False, length=1, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=0.7, blending='translucent', visible=True, cache=True, experimental_clipping_planes=None) → napari.layers.vectors.vectors.Vectors

Add a Vectors layer to the layer list.

Parameters

  • data ((N, 2, D) or (N1, N2, ..., ND, D) array) – An (N, 2, D) array is interpreted as “coordinate-like” data and a list of N vectors with start point and projections of the vector in D dimensions. An (N1, N2, …, ND, D) array is interpreted as “image-like” data where there is a length D vector of the projections at each pixel.

  • ndim (int) – Number of dimensions for vectors. When data is not None, ndim must be D. An empty vectors layer can be instantiated with arbitrary ndim.

  • features (dict[str, array-like] or DataFrame) – Features table where each row corresponds to a vector and each column is a feature.

  • properties (dict {str: array (N,)}, DataFrame) – Properties for each vector. Each property should be an array of length N, where N is the number of vectors.

  • property_choices (dict {str: array (N,)}) – possible values for each property.

  • edge_width (float) – Width for all vectors in pixels.

  • length (float) – Multiplicative factor on projections for length of all vectors.

  • edge_color (str) – Color of all of the vectors.

  • edge_color_cycle (np.ndarray, list) – Cycle of colors (provided as string name, RGB, or RGBA) to map to edge_color if a categorical attribute is used color the vectors.

  • edge_colormap (str, napari.utils.Colormap) – Colormap to set vector color if a continuous attribute is used to set edge_color.

  • edge_contrast_limits (None, (float, float)) – clims for mapping the property to a color map. These are the min and max value of the specified property that are mapped to 0 and 1, respectively. The default value is None. If set the none, the clims will be set to (property.min(), property.max())

  • out_of_slice_display (bool) – If True, renders vectors not just in central plane but also slightly out of slice according to specified point marker size.

  • name (str) – Name of the layer.

  • metadata (dict) – Layer metadata.

  • scale (tuple of float) – Scale factors for the layer.

  • translate (tuple of float) – Translation values for the layer.

  • rotate (float, 3-tuple of float, or n-D array.) – 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.

  • shear (1-D array or n-D array) – Either a vector of upper triangular values, or an nD shear matrix with ones along the main diagonal.

  • affine (n-D array or napari.utils.transforms.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.

  • opacity (float) – Opacity of the layer visual, between 0.0 and 1.0.

  • blending (str) – 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’, and ‘additive’}.

  • visible (bool) – Whether the layer visual is currently being displayed.

  • cache (bool) – Whether slices of out-of-core datasets should be cached upon retrieval. Currently, this only applies to dask arrays.

data

The start point and projections of N vectors in D dimensions.

Type

(N, 2, D) array

features

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

Type

Dataframe-like

feature_defaults

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

Type

DataFrame-like

properties

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

Type

dict {str: array (N,)}, DataFrame

edge_width

Width for all vectors in pixels.

Type

float

length

Multiplicative factor on projections for length of all vectors.

Type

float

edge_color

Color of all of the vectors.

Type

str

edge_color_cycle

Cycle of colors (provided as string name, RGB, or RGBA) to map to edge_color if a categorical attribute is used color the vectors.

Type

np.ndarray, list

edge_colormap

Colormap to set vector color if a continuous attribute is used to set edge_color.

Type

str, napari.utils.Colormap

edge_contrast_limits

clims for mapping the property to a color map. These are the min and max value of the specified property that are mapped to 0 and 1, respectively. The default value is None. If set the none, the clims will be set to (property.min(), property.max())

Type

None, (float, float)

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.

Type

bool

Notes

_view_data(M, 2, 2) array

The start point and projections of N vectors in 2D for vectors whose start point is in the currently viewed slice.

_view_face_color(M, 4) np.ndarray

colors for the M in view vectors

_view_indices(1, M) array

indices for the M in view vectors

_view_vertices(4M, 2) or (8M, 2) np.ndarray

the corner points for the M in view faces. Shape is (4M, 2) for 2D and (8M, 2) for 3D.

_view_faces(2M, 3) or (4M, 3) np.ndarray

indices of the _mesh_vertices that form the faces of the M in view vectors. Shape is (2M, 2) for 2D and (4M, 2) for 3D.

_view_alphas(M,) or float

relative opacity for the M in view vectors

_property_choicesdict {str: array (N,)}

Possible values for the properties in Vectors.properties.

_mesh_vertices(4N, 2) array

The four corner points for the mesh representation of each vector as as rectangle in the slice that it starts in.

_mesh_triangles(2N, 3) array

The integer indices of the _mesh_vertices that form the two triangles for the mesh representation of the vectors.

_max_vectors_thumbnailint

The maximum number of vectors that will ever be used to render the thumbnail. If more vectors are present then they are randomly subsampled.

Returns

layer – The newly-created vectors layer.

Return type

napari.layers.Vectors

bind_key(key, func=<object object>, *, overwrite=False)

Bind a key combination to a keymap.

Parameters

  • keymap (dict of str: callable) – Keymap to modify.

  • key (str or ...) – Key combination. ... acts as a wildcard if no key combinations can be matched in the keymap (this will overwrite all key combinations further down the lookup chain).

  • func (callable, None, or ...) – Callable to bind to the key combination. If None is passed, unbind instead. ... acts as a blocker, effectively unbinding the key combination for all keymaps further down the lookup chain.

  • overwrite (bool, keyword-only, optional) – Whether to overwrite the key combination if it already exists.

Returns

unbound – Callable unbound by this operation, if any.

Return type

callable or None

Notes

Key combinations are represented in the form [modifier-]key, e.g. a, Control-c, or Control-Alt-Delete. Valid modifiers are Control, Alt, Shift, and Meta.

Letters will always be read as upper-case. Due to the native implementation of the key system, Shift pressed in certain key combinations may yield inconsistent or unexpected results. Therefore, it is not recommended to use Shift with non-letter keys. On OSX, Control is swapped with Meta such that pressing Command reads as Control.

Special keys include Shift, Control, Alt, Meta, Up, Down, Left, Right, PageUp, PageDown, Insert, Delete, Home, End, Escape, Backspace, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, Space, Enter, and Tab

Functions take in only one argument: the parent that the function was bound to.

By default, all functions are assumed to work on key presses only, but can be denoted to work on release too by separating the function into two statements with the yield keyword:

@viewer.bind_key('h')
def hello_world(viewer):
    # on key press
    viewer.status = 'hello world!'

    yield

    # on key release
    viewer.status = 'goodbye world :('

To create a keymap that will block others, bind_key(..., ...)`.

close()[source]

Close the viewer window.

classmethod close_all() → int[source]

Class metod, Close all existing viewer instances.

This is mostly exposed to avoid leaking of viewers when running tests. As having many non-closed viewer can adversely affect performances.

It will return the number of viewer closed.

Returns

number of viewer closed.

Return type

int

classmethod construct(_fields_set: Optional[SetStr] = None, **values: Any) → Model

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy(*, include: Union[AbstractSetIntStr, MappingIntStrAny] = None, exclude: Union[AbstractSetIntStr, MappingIntStrAny] = None, update: DictStrAny = None, deep: bool = False) → Model

Duplicate a model, optionally choose which fields to include, exclude and change.

Parameters

  • include – fields to include in new model

  • exclude – fields to exclude from new model, as with values this takes precedence over include

  • update – values to change/add in the new model. Note: the data is not validated before creating the new model: you should trust this data

  • deep – set to True to make a deep copy of the model

Returns

new model instance

dict(**kwargs)

Convert to a dictionary.

enums_as_values(as_values: bool = True)

Temporarily override how enums are retrieved.

Parameters

as_values (bool, optional) – Whether enums should be shown as values (or as enum objects), by default True

property experimental

Experimental commands for IPython console.

For example run “viewer.experimental.cmds.loader.help”.

json(**kwargs)

Serialize to json.

open(path: Union[str, pathlib.Path, Sequence[Union[str, pathlib.Path]]], *, stack: bool = False, plugin: Optional[str] = None, layer_type: Optional[str] = None, **kwargs) → List[napari.layers.base.base.Layer]

Open a path or list of paths with plugins, and add layers to viewer.

A list of paths will be handed one-by-one to the napari_get_reader hook if stack is False, otherwise the full list is passed to each plugin hook.

Parameters

  • path (str or list of str) – A filepath, directory, or URL (or a list of any) to open.

  • stack (bool, optional) – If a list of strings is passed and stack is True, then the entire list will be passed to plugins. It is then up to individual plugins to know how to handle a list of paths. If stack is False, then the path list is broken up and passed to plugin readers one by one. by default False.

  • plugin (str, optional) – Name of a plugin to use. If provided, will force path to be read with the specified plugin. If the requested plugin cannot read path, an exception will be raised.

  • layer_type (str, optional) – If provided, will force data read from path to be passed to the corresponding add_<layer_type> method (along with any additional) kwargs provided to this function. This may result in exceptions if the data returned from the path is not compatible with the layer_type.

  • **kwargs – All other keyword arguments will be passed on to the respective add_layer method.

Returns

layers – A list of any layers that were added to the viewer.

Return type

list

open_sample(plugin: str, sample: str, reader_plugin: Optional[str] = None, **kwargs) → List[napari.layers.base.base.Layer]

Open sample from plugin and add it to the viewer.

To see all available samples registered by plugins, use napari.plugins.available_samples()

Parameters

  • plugin (str) – name of a plugin providing a sample

  • sample (str) – name of the sample

  • reader_plugin (str, optional) – reader plugin to pass to viewer.open (only used if the sample data is a string). by default None.

  • **kwargs – additional kwargs will be passed to the sample data loader provided by plugin. Use of **kwargs may raise an error if the kwargs do not match the sample data loader.

Returns

layers – A list of any layers that were added to the viewer.

Return type

list

Raises

KeyError – If plugin does not provide a sample named sample.

reset()

Reset the state of the model to default values.

reset_view()

Reset the camera view.

screenshot(path=None, *, canvas_only=True, flash: bool = True)[source]

Take currently displayed screen and convert to an image array.

Parameters

  • path (str) – Filename for saving screenshot image.

  • canvas_only (bool) – If True, screenshot shows only the image display canvas, and if False include the napari viewer frame in the screenshot, By default, True.

  • flash (bool) – Flag to indicate whether flash animation should be shown after the screenshot was captured. By default, True.

Returns

image – Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region.

Return type

array

show(*, block=False)[source]

Resize, show, and raise the viewer window.

update(values: Union[napari.utils.events.evented_model.EventedModel, dict], recurse: bool = True) → None

Update a model in place.

Parameters

  • values (dict, napari.utils.events.EventedModel) – Values to update the model with. If an EventedModel is passed it is first converted to a dictionary. The keys of this dictionary must be found as attributes on the current model.

  • recurse (bool) – If True, recursively update fields that are EventedModels. Otherwise, just update the immediate fields of this EventedModel, which is useful when the declared field type (e.g. Union) can have different realized types with different fields.

update_console(variables)[source]

Update console’s namespace with desired variables.

Parameters

variables (dict, str or list/tuple of str) – The variables to inject into the console’s namespace. If a dict, a simple update is done. If a str, the string is assumed to have variable names separated by spaces. A list/tuple of str can also be used to give the variable names. If just the variable names are give (list/tuple/str) then the variable values looked up in the callers frame.

classmethod update_forward_refs(**localns: Any) → None

Try to update ForwardRefs on fields based on this Model, globalns and localns.

previous

napari.view_layers.Dims

next

napari.types