napari.layers.Layer#

class napari.layers.Layer(data, ndim, *, affine=None, blending='translucent', cache=True, experimental_clipping_planes=None, metadata=None, mode='pan_zoom', multiscale=False, name=None, opacity=1.0, projection_mode='none', rotate=None, scale=None, shear=None, translate=None, visible=True)[source]#

Bases: KeymapProvider, MousemapProvider, ABC

Base layer class.

Parameters:
  • data (array or list of array) – Data that the layer is visualizing. Can be N-dimensional.

  • ndim (int) – Number of spatial dimensions.

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

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

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

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

  • metadata (dict) – Layer metadata.

  • mode (str) – The layer’s interactive mode.

  • multiscale (bool) – Whether the data is multiscale or not. Multiscale data is represented by a list of data objects and should go from largest to smallest.

  • name (str, optional) – Name of the layer. If not provided then will be guessed using heuristics.

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

  • projection_mode (str) – How data outside the viewed dimensions but inside the thick Dims slice will be projected onto the viewed dimensions. Must fit to cls._projectionclass.

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

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

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

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

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

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.

Type:

n-D array or napari.utils.transforms.Affine

blending#

Determines how RGB and alpha values get mixed.

  • Blending.OPAQUE Allows for only the top layer to be visible and corresponds to depth_test=True, cull_face=False, blend=False.

  • Blending.TRANSLUCENT Allows for multiple layers to be blended with different opacity and corresponds to depth_test=True, cull_face=False, blend=True, blend_func=('src_alpha', 'one_minus_src_alpha'), and blend_equation=('func_add').

  • Blending.TRANSLUCENT_NO_DEPTH Allows for multiple layers to be blended with different opacity, but no depth testing is performed. Corresponds to depth_test=False, cull_face=False, blend=True, blend_func=('src_alpha', 'one_minus_src_alpha'), and blend_equation=('func_add').

  • Blending.ADDITIVE Allows for multiple layers to be blended together with different colors and opacity. Useful for creating overlays. It corresponds to depth_test=False, cull_face=False, blend=True, blend_func=('src_alpha', 'one'), and blend_equation=('func_add').

  • Blending.MINIMUM

    Allows for multiple layers to be blended together such that the minimum of each RGB component and alpha are selected. Useful for creating overlays with inverted colormaps. It corresponds to depth_test=False, cull_face=False, blend=True, blend_equation=('min').

Type:

Blending

cache#

Whether slices of out-of-core datasets should be cached upon retrieval. Currently, this only applies to dask arrays.

Type:

bool

corner_pixels#

Coordinates of the top-left and bottom-right canvas pixels in the data coordinates of each layer. For multiscale data the coordinates are in the space of the currently viewed data level, not the highest resolution level.

Type:

array

cursor#

String identifying which cursor displayed over canvas.

Type:

str

cursor_size#

Size of cursor if custom. None yields default size

Type:

int | None

help#

Displayed in status bar bottom right.

Type:

str

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.

Type:

bool

mouse_pan#

Determine if canvas interactive panning is enabled with the mouse.

Type:

bool

mouse_zoom#

Determine if canvas interactive zooming is enabled with the mouse.

Type:

bool

multiscale#

Whether the data is multiscale or not. Multiscale data is represented by a list of data objects and should go from largest to smallest.

Type:

bool

name#

Unique name of the layer.

Type:

str

ndim#

Dimensionality of the layer.

Type:

int

opacity#

Opacity of the layer visual, between 0.0 and 1.0.

Type:

float

projection_mode#

How data outside the viewed dimensions but inside the thick Dims slice will be projected onto the viewed dimenions.

Type:

str

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.

Type:

float, 3-tuple of float, or n-D array.

scale#

Scale factors for the layer.

Type:

tuple of float

scale_factor#

Conversion factor from canvas coordinates to image coordinates, which depends on the current zoom level.

Type:

float

shear#

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

Type:

1-D array or n-D array

source#

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

Type:

Source

status#

Displayed in status bar bottom left.

Type:

str

translate#

Translation values for the layer.

Type:

tuple of float

thumbnail#

Array of thumbnail data for the layer.

Type:

(N, M, 4) array

visible#

Whether the layer visual is currently being displayed.

Type:

bool

z_index#

Depth of the layer visual relative to other visuals in the scenecanvas.

Type:

int

Notes

Must define the following:

  • _extent_data: property

  • data property (setter & getter)

May define the following:

  • _set_view_slice(): called to set currently viewed slice

  • _basename(): base/default name of the layer

    inherited-members:

Methods

as_layer_data_tuple()

bind_key(key_bind[, func, overwrite])

Bind a key combination to a keymap.

block_update_properties()

click_plane_from_click_data(click_position, ...)

Calculate a (point, normal) plane parallel to the canvas in data coordinates, centered on the centre of rotation of the camera.

create(data[, meta, layer_type])

Create layer from data of type layer_type.

data_to_world(position)

Convert from data coordinates to world coordinates.

get_ray_intersections(position, ...[, world])

Get the start and end point for the ray extending from a point through the data bounding box.

get_source_str()

get_status([position, view_direction, ...])

Status message information of the data at a coordinate position.

get_value(position, *[, view_direction, ...])

Value of the data at a position.

projected_distance_from_mouse_drag(...)

Calculate the length of the projection of a line between two mouse clicks onto a vector (or array of vectors) in data coordinates.

refresh([event])

Refresh all layer data based on current view slice.

save(path[, plugin])

Save this layer to path with default (or specified) plugin.

set_view_slice()

world_to_data(position)

Convert from world coordinates to data coordinates.

Attributes

ModeCallable

alias of Callable[[Layer, Event], Union[None, Generator[None, None, None]]]

affine

Extra affine transform to go from physical to world coordinates.

blending

Determines how RGB and alpha values get mixed.

bounding_box

class_keymap

cursor

String identifying cursor displayed over canvas.

cursor_size

Size of cursor if custom.

data

editable

Whether the current layer data is editable from the viewer.

experimental_clipping_planes

extent

Extent of layer in data and world coordinates.

help

displayed in status bar bottom right.

interactive

keymap

loaded

True if this layer is fully loaded in memory, False otherwise.

metadata

Key/value map for user-stored data.

mode

Interactive mode

mouse_pan

Determine if canvas interactive panning is enabled with the mouse.

mouse_zoom

Determine if canvas interactive zooming is enabled with the mouse.

name

Unique name of the layer.

ndim

Number of dimensions in the data.

opacity

Opacity value between 0.0 and 1.0.

projection_mode

Mode of projection of the thick slice onto the viewed dimensions.

rotate

Rotation matrix in world coordinates.

scale

Anisotropy factors to scale data into world coordinates.

shear

Shear matrix in world coordinates.

source

thumbnail

Integer array of thumbnail for the layer

translate

Factors to shift the layer by in units of world coordinates.

visible

Whether the visual is currently being displayed.

Details

property affine: Affine#

Extra affine transform to go from physical to world coordinates.

Type:

napari.utils.transforms.Affine

property blending: str#

Determines how RGB and alpha values get mixed.

Blending.OPAQUE

Allows for only the top layer to be visible and corresponds to depth_test=True, cull_face=False, blend=False.

Blending.TRANSLUCENT

Allows for multiple layers to be blended with different opacity and corresponds to depth_test=True, cull_face=False, blend=True, blend_func=(‘src_alpha’, ‘one_minus_src_alpha’), and blend_equation=(‘func_add’).

Blending.TRANSLUCENT_NO_DEPTH

Allows for multiple layers to be blended with different opacity, but no depth testing is performed. Corresponds to depth_test=False, cull_face=False, blend=True, blend_func=(‘src_alpha’, ‘one_minus_src_alpha’), and blend_equation=(‘func_add’).

Blending.ADDITIVE

Allows for multiple layers to be blended together with different colors and opacity. Useful for creating overlays. It corresponds to depth_test=False, cull_face=False, blend=True, blend_func=(‘src_alpha’, ‘one’), and blend_equation=(‘func_add’).

Blending.MINIMUM

Allows for multiple layers to be blended together such that the minimum of each RGB component and alpha are selected. Useful for creating overlays with inverted colormaps. It corresponds to depth_test=False, cull_face=False, blend=True, blend_equation=(‘min’).

Type:

Blending mode

click_plane_from_click_data(click_position: npt.ArrayLike, view_direction: npt.ArrayLike, dims_displayed: list[int]) tuple[np.ndarray, np.ndarray][source]#

Calculate a (point, normal) plane parallel to the canvas in data coordinates, centered on the centre of rotation of the camera.

Parameters:
  • click_position (np.ndarray) – click position in world coordinates from mouse event.

  • view_direction (np.ndarray) – view direction in world coordinates from mouse event.

  • dims_displayed (List[int]) – dimensions of the data array currently in view.

Returns:

click_plane – tuple of (plane_position, plane_normal) in data coordinates.

Return type:

Tuple[np.ndarray, np.ndarray]

classmethod create(data: Any, meta: dict | None = None, layer_type: str | None = None) Layer[source]#

Create layer from data of type layer_type.

Primarily intended for usage by reader plugin hooks and creating a layer from an unwrapped layer data tuple.

Parameters:
  • data (Any) – Data in a format that is valid for the corresponding layer_type.

  • meta (dict, optional) – Dict of keyword arguments that will be passed to the corresponding layer constructor. If any keys in meta are not valid for the corresponding layer type, an exception will be raised.

  • layer_type (str) – Type of layer to add. Must be the (case insensitive) name of a Layer subclass. If not provided, the layer is assumed to be “image”, unless data.dtype is one of (np.int32, np.uint32, np.int64, np.uint64), in which case it is assumed to be “labels”.

Raises:
  • ValueError – If layer_type is not one of the recognized layer types.

  • TypeError – If any keyword arguments in meta are unexpected for the corresponding add_* method for this layer_type.

Examples

A typical use case might be to upack a tuple of layer data with a specified layer_type.

>>> data = (
...     np.random.random((10, 2)) * 20,
...     {'face_color': 'blue'},
...     'points',
... )
>>> Layer.create(*data)
property cursor: str#

String identifying cursor displayed over canvas.

Type:

str

property cursor_size: int#

Size of cursor if custom. None yields default size.

Type:

int

data_to_world(position)[source]#

Convert from data coordinates to world coordinates.

Parameters:

position (tuple, list, 1D array) – Position in data coordinates. If longer then the number of dimensions of the layer, the later dimensions will be used.

Returns:

Position in world coordinates.

Return type:

tuple

property editable: bool#

Whether the current layer data is editable from the viewer.

Type:

bool

property extent: Extent#

Extent of layer in data and world coordinates.

For image-like layers, these coordinates are the locations of the pixels in Layer.data which are treated like sample points that are centered in the rendered version of those pixels. For other layers, these coordinates are the points or vertices stored in Layer.data. Lower and upper bounds are inclusive.

get_ray_intersections(position: npt.ArrayLike, view_direction: npt.ArrayLike, dims_displayed: list[int], world: bool = True) tuple[np.ndarray | None, np.ndarray | None][source]#

Get the start and end point for the ray extending from a point through the data bounding box.

Parameters:
  • position – the position of the point in nD coordinates. World vs. data is set by the world keyword argument.

  • view_direction (np.ndarray) – a unit vector giving the direction of the ray in nD coordinates. World vs. data is set by the world keyword argument.

  • dims_displayed (List[int]) – a list of the dimensions currently being displayed in the viewer.

  • world (bool) – True if the provided coordinates are in world coordinates. Default value is True.

Returns:

  • start_point (np.ndarray) – The point on the axis-aligned data bounding box that the cursor click intersects with. This is the point closest to the camera. The point is the full nD coordinates of the layer data. If the click does not intersect the axis-aligned data bounding box, None is returned.

  • end_point (np.ndarray) – The point on the axis-aligned data bounding box that the cursor click intersects with. This is the point farthest from the camera. The point is the full nD coordinates of the layer data. If the click does not intersect the axis-aligned data bounding box, None is returned.

get_status(position: npt.ArrayLike | None = None, *, view_direction: npt.ArrayLike | None = None, dims_displayed: list[int] | None = None, world: bool = False) dict[source]#

Status message information of the data at a coordinate position.

Parameters:
  • position (tuple of float) – Position in either data or world coordinates.

  • view_direction (Optional[np.ndarray]) – A unit vector giving the direction of the ray in nD world coordinates. The default value is None.

  • dims_displayed (Optional[List[int]]) – A list of the dimensions currently being displayed in the viewer. The default value is None.

  • world (bool) – If True the position is taken to be in world coordinates and converted into data coordinates. False by default.

Returns:

source_info – Dictionary containing a information that can be used as a status update.

Return type:

dict

get_value(position: npt.ArrayLike, *, view_direction: npt.ArrayLike | None = None, dims_displayed: list[int] | None = None, world: bool = False) tuple | None[source]#

Value of the data at a position.

If the layer is not visible, return None.

Parameters:
  • position (tuple of float) – Position in either data or world coordinates.

  • view_direction (Optional[np.ndarray]) – A unit vector giving the direction of the ray in nD world coordinates. The default value is None.

  • dims_displayed (Optional[List[int]]) – A list of the dimensions currently being displayed in the viewer. The default value is None.

  • world (bool) – If True the position is taken to be in world coordinates and converted into data coordinates. False by default.

Returns:

value – Value of the data. If the layer is not visible return None.

Return type:

tuple, None

property help: str#

displayed in status bar bottom right.

Type:

str

property loaded: bool#

True if this layer is fully loaded in memory, False otherwise.

Layers that only support sync slicing are always fully loaded. Layers that support async slicing can be temporarily not loaded while slicing is occurring.

property metadata: dict#

Key/value map for user-stored data.

property mode: str#

Interactive mode

Interactive mode. The normal, default mode is PAN_ZOOM, which allows for normal interactivity with the canvas.

TRANSFORM allows for manipulation of the layer transform.

Type:

str

property mouse_pan: bool#

Determine if canvas interactive panning is enabled with the mouse.

Type:

bool

property mouse_zoom: bool#

Determine if canvas interactive zooming is enabled with the mouse.

Type:

bool

property name: str#

Unique name of the layer.

Type:

str

property ndim: int#

Number of dimensions in the data.

Type:

int

property opacity: float#

Opacity value between 0.0 and 1.0.

Type:

float

projected_distance_from_mouse_drag(start_position: npt.ArrayLike, end_position: npt.ArrayLike, view_direction: npt.ArrayLike, vector: np.ndarray, dims_displayed: list[int]) npt.NDArray[source]#

Calculate the length of the projection of a line between two mouse clicks onto a vector (or array of vectors) in data coordinates.

Parameters:
  • start_position (np.ndarray) – Starting point of the drag vector in data coordinates

  • end_position (np.ndarray) – End point of the drag vector in data coordinates

  • view_direction (np.ndarray) – Vector defining the plane normal of the plane onto which the drag vector is projected.

  • vector (np.ndarray) – (3,) unit vector or (n, 3) array thereof on which to project the drag vector from start_event to end_event. This argument is defined in data coordinates.

  • dims_displayed (List[int]) – (3,) list of currently displayed dimensions

Returns:

projected_distance

Return type:

(1, ) or (n, ) np.ndarray of float

property projection_mode#

Mode of projection of the thick slice onto the viewed dimensions.

The sliced data is described by an n-dimensional bounding box (“thick slice”), which needs to be projected onto the visible dimensions to be visible. The projection mode controls the projection logic.

refresh(event: Event | None = None) None[source]#

Refresh all layer data based on current view slice.

property rotate: npt.NDArray#

Rotation matrix in world coordinates.

Type:

array

save(path: str, plugin: str | None = None) list[str][source]#

Save this layer to path with default (or specified) plugin.

Parameters:
  • path (str) – A filepath, directory, or URL to open. Extensions may be used to specify output format (provided a plugin is available for the requested format).

  • plugin (str, optional) – Name of the plugin to use for saving. If None then all plugins corresponding to appropriate hook specification will be looped through to find the first one that can save the data.

Returns:

File paths of any files that were written.

Return type:

list of str

property scale: npt.NDArray#

Anisotropy factors to scale data into world coordinates.

Type:

array

property shear: npt.NDArray#

Shear matrix in world coordinates.

Type:

array

property thumbnail: npt.NDArray[np.uint8]#

Integer array of thumbnail for the layer

Type:

array

property translate: npt.NDArray#

Factors to shift the layer by in units of world coordinates.

Type:

array

property visible: bool#

Whether the visual is currently being displayed.

Type:

bool

world_to_data(position: npt.ArrayLike) npt.NDArray[source]#

Convert from world coordinates to data coordinates.

Parameters:

position (tuple, list, 1D array) – Position in world coordinates. If longer then the number of dimensions of the layer, the later dimensions will be used.

Returns:

Position in data coordinates.

Return type:

tuple