napari.layers.Vectors#

class napari.layers.Vectors(data=None, *, affine=None, blending='translucent', cache=True, edge_color='red', edge_color_cycle=None, edge_colormap='viridis', edge_contrast_limits=None, edge_width=1, experimental_clipping_planes=None, feature_defaults=None, features=None, length=1, metadata=None, name=None, ndim=None, opacity=0.7, out_of_slice_display=False, projection_mode='none', properties=None, property_choices=None, rotate=None, scale=None, shear=None, translate=None, vector_style='triangle', visible=True)[source]#

Bases: Layer

Vectors layer renders lines onto the canvas.

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.

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

  • 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())

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

  • 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) – The default value of each feature in a table with one row.

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

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

  • metadata (dict) – Layer metadata.

  • name (str) – Name of the layer.

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

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

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

  • projection_mode (str) – How data outside the viewed dimensions but inside the thick Dims slice will be projected onto the viewed dimenions.

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

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

  • vector_style (str) – One of a list of preset display modes that determines how vectors are displayed. Allowed values are {‘line’, ‘triangle’, and ‘arrow’}.

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

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

vector_style#

Determines how vectors are displayed.

  • VectorStyle.LINE:

    Vectors are displayed as lines.

  • VectorStyle.TRIANGLE:

    Vectors are displayed as triangles.

  • VectorStyle.ARROW:

    Vectors are displayed as arrows.

Type:

VectorStyle

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

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

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.

refresh_colors([update_color_mapping])

Calculate and update edge colors if using a cycle or color map

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

start point and projections of vectors.

edge_color

Array of RGBA edge colors (applied to all vectors)

edge_color_cycle

Color cycle for edge_color.

edge_color_mode

Edge color setting mode

edge_colormap

Return the colormap to be applied to a property to get the edge color.

edge_contrast_limits

contrast limits for mapping the edge_color colormap property to 0 and 1

edge_width

Width for all vectors in pixels.

editable

Whether the current layer data is editable from the viewer.

experimental_clipping_planes

extent

Extent of layer in data and world coordinates.

feature_defaults

Dataframe-like with one row of feature default values.

features

Dataframe-like features table.

help

displayed in status bar bottom right.

interactive

keymap

length

Multiplicative factor for length of all vectors.

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.

out_of_slice_display

renders vectors slightly out of slice.

projection_mode

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

properties

Annotations for each point

property_choices

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.

vector_style

Determines how vectors are displayed.

visible

Whether the visual is currently being displayed.

Details

property data: ndarray#

start point and projections of vectors.

Type:

(N, 2, D) array

property edge_color: ndarray#

Array of RGBA edge colors (applied to all vectors)

Type:

(1 x 4) np.ndarray

property edge_color_cycle: ndarray#

Color cycle for edge_color. Can be a list of colors defined by name, RGB or RGBA

Type:

list, np.ndarray

property edge_color_mode: ColorMode#

Edge color setting mode

DIRECT (default mode) allows each vector 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

property edge_colormap: Colormap#

Return the colormap to be applied to a property to get the edge color.

Returns:

colormap – The Colormap object.

Return type:

napari.utils.Colormap

property edge_contrast_limits: tuple[float, float]#

contrast limits for mapping the edge_color colormap property to 0 and 1

Type:

None, (float, float)

property edge_width: float#

Width for all vectors in pixels.

Type:

float

property feature_defaults#

Dataframe-like with one row of feature default values.

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

property features#

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

property length: float#

Multiplicative factor for length of all vectors.

Type:

float

property out_of_slice_display: bool#

renders vectors slightly out of slice.

Type:

bool

property properties: dict[str, ndarray]#

Annotations for each point

Type:

dict {str

Type:

array (N,)}, DataFrame

refresh_colors(update_color_mapping: bool = False)[source]#

Calculate and update edge colors if using a cycle or color map

Parameters:

update_color_mapping (bool) – If set to True, the function will recalculate the color cycle map or colormap (whichever is being used). If set to False, the function will use the current color cycle map or color map. For example, if you are adding/modifying vectors and want them to be colored with the same mapping as the other vectors (i.e., the new vectors shouldn’t affect the color cycle map or colormap), set update_color_mapping=False. Default value is False.

property vector_style: str#

Determines how vectors are displayed.

VectorStyle.LINE

Displays vectors as rectangular lines.

VectorStyle.TRIANGLE

Displays vectors as triangles.

VectorStyle.ARROW

Displays vectors as arrows.

Type:

Vectors display mode