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', visible=True)[source]¶

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

Surface layer renders meshes onto the canvas.

Parameters

data (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 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.
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 lenght N translation vector and a 1 or a napari AffineTransform object. If provided then translate, scale, rotate, and shear values are ignored.
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.

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,)

gamma¶

Gamma correction for determining colormap linearity.

Type: float

Extended Summary

----------

_data_view¶

The coordinates of the vertices given the viewed dimensions.

Type: (M, 2) or (M, 3) array

_view_faces¶

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

Type: (P, 3) array

_colorbar¶

Colorbar for current colormap.

Type: array

Methods

Attributes

property affine¶

Affine transform.

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’).
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’).

Type: Blending mode

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.

property coordinates¶: Cursor position in data coordinates.

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

property displayed_coordinates¶

List of currently displayed coordinates.

Type: list

property editable¶

Whether the current layer data is editable from the viewer.

Type: bool

property extent¶

Extent of layer in data and world coordinates.

Return type: Extent

get_message()¶

Generate a status message based on the coordinates and value

Returns: msg – String containing a message that can be used as a status update.
Return type: string

get_status(position=None, *, world=False)¶

Status message of the data at a coordinate position.

Parameters

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

Returns

msg – String containing a message that can be used as a status update.

Return type

string

get_value(position=None, *, world=False)¶

Value of the data at a position.

Parameters

position (tuple) – Position in either data or world coordinates.
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.

Return type

tuple, None

property help¶

displayed in status bar bottom right.

Type: str

property interactive¶

Determine if canvas pan/zoom interactivity is enabled.

Type: bool

property loaded¶

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.

Return 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

property position¶

Cursor position in world slice coordinates.

Type: tuple

refresh(event=None)¶: Refresh all layer data based on current view slice.

reset_contrast_limits()¶: Scale contrast limits to data range

reset_contrast_limits_range()¶

Scale contrast limits range to data type.

Currently, this only does something if the data type is an unsigned integer… otherwise it’s unclear what the full range should be.

property rotate¶

Rotation matrix in world coordinates.

Type: array

save(path, plugin=None)¶

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 selected¶

Whether this layer is selected or not.

Type: bool

property shear¶

Sheer matrix in world coordinates.

Type: array

property status¶

displayed in status bar bottom left.

Type: str

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 translate_grid¶

Factors to shift the layer by.

Type: list

property visible¶

Whether the visual is currently being displayed.

Type: bool