napari.layers.Vectors#

class napari.layers.Vectors(data=None, *, affine=None, axis_labels=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, units=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.
axis_labels (tuple of str, optional) – Dimension names of the layer data. If not provided, axis_labels will be set to (…, ‘axis -2’, ‘axis -1’).
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.
units (tuple of str or pint.Unit, optional) – Units of the layer data in world coordinates. If not provided, the default units are assumed to be pixels.
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

axis_labels#

Dimension names of the layer data.

Type:: tuple of str

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

units#

Units of the layer data in world coordinates.

Type:: tuple of pint.Unit

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.

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, thumbnail, data_displayed, ...])	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`()
`update_transform_box_visibility`(visible)
`world_to_data`(position)	Convert from world coordinates to data coordinates.

Attributes

`ModeCallable`	alias of `Callable`[[`Layer`, `Event`], `None` \| `Generator`[`None`, `None`, `None`]]
`affine`	Extra affine transform to go from physical to world coordinates.
`axis_labels`	tuple of axis labels for the layer.
`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.
`unique_id`	Unique ID of the layer.
`units`	List of units for the layer.
`vector_style`	Determines how vectors are displayed.
`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 axis_labels: tuple[str, ...]#: tuple of axis labels for the layer.

bind_key(key_bind: ~app_model.types._keys._keybindings.KeyBinding | str | int | ellipsis, func=<object object>, *, overwrite=False)#

Bind a key combination to a keymap.

Parameters:

keymap (dict of str: callable) – Keymap to modify.
key_bind (keybinding-like 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: 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]#

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#

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

property data: ndarray#

start point and projections of vectors.

Type:: (N, 2, D) array

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

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

get_ray_intersections(position: npt.ArrayLike, view_direction: npt.ArrayLike, dims_displayed: list[int], world: bool = True) → tuple[np.ndarray | None, np.ndarray | 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 (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#

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#

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 length: float#

Multiplicative factor for length of all vectors.

Type:: float

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

property out_of_slice_display: bool#

renders vectors slightly out of slice.

Type:: bool

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#

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.

property properties: dict[str, ndarray]#

Annotations for each point

Type:: dict {str
Type:: array (N,)}, DataFrame

refresh(event: Event | None = None, *, thumbnail: bool = True, data_displayed: bool = True, highlight: bool = True, extent: bool = True, force: bool = False) → None#: Refresh all layer data based on current view slice.

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 rotate: npt.NDArray#

Rotation matrix in world coordinates.

Type:: array

save(path: str, plugin: str | None = 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: 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 unique_id: Hashable#

Unique ID of the layer.

This is guaranteed to be unique to this specific layer instance over the lifetime of the program.

property units: tuple[Unit, ...]#: List of units for the layer.

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

property visible: bool#

Whether the visual is currently being displayed.

Type:: bool

world_to_data(position: npt.ArrayLike) → npt.NDArray#

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