napari.layers.Surface#

class napari.layers.Surface(data, *, affine=None, blending='translucent', cache=True, colormap='gray', contrast_limits=None, experimental_clipping_planes=None, feature_defaults=None, features=None, gamma=1.0, metadata=None, name=None, normals=None, opacity=1.0, projection_mode='none', rotate=None, scale=None, shading='flat', shear=None, texcoords=None, texture=None, translate=None, vertex_colors=None, visible=True, wireframe=None)[source]#

Bases: IntensityVisualizationMixin, 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.

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

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

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

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

  • feature_defaults (dict[str, Any] or Dataframe-like) – The default value of each feature in a table with one row.

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

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

  • metadata (dict) – Layer metadata.

  • name (str) – Name of the layer.

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

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

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

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

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

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

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

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

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

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

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

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

features#

Features table where each row corresponds to a vertex 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

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.

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.

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

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

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

feature_defaults

Dataframe-like with one row of feature default values.

features

Dataframe-like features table.

gamma

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.

normals

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.

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.

vertex_colors

vertex_values

vertices

visible

Whether the visual is currently being displayed.

wireframe

Details

property feature_defaults: DataFrame#

Dataframe-like with one row of feature default values.

See features for more details on the type of this property.

property features: DataFrame#

Dataframe-like features table.

It is an implementation detail that this is a pandas.DataFrame. In the future, we will target the currently-in-development Data API dataframe protocol [1]. This will enable us to use alternate libraries such as xarray or cuDF for additional features without breaking existing usage of this.

If you need to specifically rely on the pandas API, please coerce this to a pandas.DataFrame using features_to_pandas_dataframe.

References