napari.layers.Surface

class napari.layers.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, texture=None, texcoords=None, vertex_colors=None)[source]

Bases: napari.layers.intensity_mixin.IntensityVisualizationMixin, napari.layers.base.base.Layer

Surface layer renders meshes onto the canvas.

Surfaces may be colored by:
  • setting vertex_values, which colors the surface with the selected colormap (default is uniform ones)

  • setting vertex_colors, which replaces/overrides any color from vertex_values

  • setting both texture and texcoords, which blends a the value from a texture (image) with the underlying color from vertex_values or vertex_colors. Blending is achieved by multiplying the texture color by the underlying color - an underlying value of “white” will result in the unaltered texture color.

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

  • texture ((I, J) or (I, J, C) array) – A 2D texture to be mapped onto the mesh using texcoords. C may be 3 (RGB) or 4 (RGBA) channels for a color texture.

  • texcoords ((N, 2) array) – 2D coordinates for each vertex, mapping into the texture. The number of texture coords must match the number of vertices (N). Coordinates should be in [0.0, 1.0] and are scaled to sample the 2D texture. Coordinates outside this range will wrap, but this behavior should be considered an implementation detail: there are no plans to change it, but it’s a feature of the underlying vispy visual.

  • vertex_colors ((N, C) or (K0, ..., KL, N, C) array of color values) – Take care that the (optional) L additional dimensions match those of vertex_values for proper slicing. C may be 3 (RGB) or 4 (RGBA) channels.

  • 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 (None, dict or SurfaceWireframe) – Whether and how to display the edges of the surface mesh with a wireframe.

  • normals (None, 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.

Methods

as_layer_data_tuple()

bind_key(key[, 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.

reset_contrast_limits([mode])

Scale contrast limits to data range

reset_contrast_limits_range([mode])

Scale contrast limits range to data type if dtype is an integer, or use the current maximum data range otherwise.

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

affine

Extra affine transform to go from physical to world coordinates.

blending

Determines how RGB and alpha values get mixed.

bounding_box

class_keymap

colormap

colormap for luminance images.

colormaps

names of available colormaps.

contrast_limits

Limits to use for the colormap.

contrast_limits_range

The current valid range of the contrast limits.

cursor

String identifying cursor displayed over canvas.

cursor_size

Size of cursor if custom.

data

dtype

editable

Whether the current layer data is editable from the viewer.

experimental_clipping_planes

extent

Extent of layer in data and world coordinates.

faces

gamma

help

displayed in status bar bottom right.

interactive

loaded

Return True if this layer is fully loaded in memory.

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.

normals

opacity

Opacity value between 0.0 and 1.0.

rotate

Rotation matrix in world coordinates.

scale

Anisotropy factors to scale data into world coordinates.

shading

shear

Shear matrix in world coordinates.

source

texcoords

texture

thumbnail

Integer array of thumbnail for the layer

translate

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

translate_grid

vertex_colors

vertex_values

vertices

visible

Whether the visual is currently being displayed.

wireframe

Details

property affine

Extra affine transform to go from physical to world coordinates.

Type

napari.utils.transforms.Affine

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(..., ...)`.

property 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 mode

click_plane_from_click_data(click_position: numpy.ndarray, view_direction: numpy.ndarray, dims_displayed: List) Tuple[numpy.ndarray, numpy.ndarray]

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) – 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]

property colormap

colormap for luminance images.

Type

napari.utils.Colormap

property colormaps

names of available colormaps.

Type

tuple of str

property contrast_limits

Limits to use for the colormap.

Type

list of float

property contrast_limits_range

The current valid range of the contrast limits.

classmethod create(data, meta: Optional[dict] = None, layer_type: Optional[str] = None) napari.layers.base.base.Layer

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

String identifying cursor displayed over canvas.

Type

str

property cursor_size

Size of cursor if custom. None yields default size.

Type

int | None

data_to_world(position)

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: napari.layers.base.base.Extent

Extent of layer in data and world coordinates.

get_ray_intersections(position: List[float], view_direction: numpy.ndarray, dims_displayed: List[int], world: bool = True) Union[Tuple[numpy.ndarray, numpy.ndarray], Tuple[None, None]]

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 – 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: Optional[Tuple[float, ...]] = None, *, view_direction: Optional[numpy.ndarray] = None, dims_displayed: Optional[List[int]] = None, world=False)

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: Tuple[float], *, view_direction: Optional[numpy.ndarray] = None, dims_displayed: Optional[List[int]] = None, world=False)

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

displayed in status bar bottom right.

Type

str

property loaded: bool

Return True if this layer is fully loaded in memory.

This base class says that layers are permanently in the loaded state. Derived classes that do asynchronous loading can override this.

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

Unique name of the layer.

Type

str

property ndim

Number of dimensions in the data.

Type

int

property opacity

Opacity value between 0.0 and 1.0.

Type

float

projected_distance_from_mouse_drag(start_position: numpy.ndarray, end_position: numpy.ndarray, view_direction: numpy.ndarray, vector: numpy.ndarray, dims_displayed: Union[List, numpy.ndarray])

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 (Union[List, np.ndarray]) – (3,) list of currently displayed dimensions

Returns

projected_distance

Return type

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

refresh(event=None)

Refresh all layer data based on current view slice.

reset_contrast_limits(mode=None)

Scale contrast limits to data range

reset_contrast_limits_range(mode=None)

Scale contrast limits range to data type if dtype is an integer, or use the current maximum data range otherwise.

property rotate

Rotation matrix in world coordinates.

Type

array

save(path: str, plugin: Optional[str] = None) List[str]

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

Anisotropy factors to scale data into world coordinates.

Type

list

property shear

Shear matrix in world coordinates.

Type

array

property thumbnail

Integer array of thumbnail for the layer

Type

array

property translate

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

Type

list

property visible: bool

Whether the visual is currently being displayed.

Type

bool

world_to_data(position)

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