napari.layers.Tracks#

class napari.layers.Tracks(data, *, affine=None, blending='additive', cache=True, color_by='track_id', colormap='turbo', colormaps_dict=None, experimental_clipping_planes=None, features=None, graph=None, head_length: int = 0, metadata=None, name=None, opacity=1.0, projection_mode='none', properties=None, rotate=None, scale=None, shear=None, tail_length: int = 30, tail_width: int = 2, translate=None, visible=True)[source]#

Bases: Layer

Tracks layer.

Parameters:
  • data (array (N, D+1)) – Coordinates for N points in D+1 dimensions. ID,T,(Z),Y,X. The first axis is the integer ID of the track. D is either 3 or 4 for planar or volumetric timeseries respectively.

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

  • color_by (str) – Track property (from property keys) by which to color vertices.

  • colormap (str) – Default colormap to use to set vertex colors. Specialized colormaps, relating to specified properties can be passed to the layer via colormaps_dict.

  • colormaps_dict (dict {str: napari.utils.Colormap}) – Optional dictionary mapping each property to a colormap for that property. This allows each property to be assigned a specific colormap, rather than having a global colormap for everything.

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

  • features (Dataframe-like) – Features table where each row corresponds to a point and each column is a feature.

  • graph (dict {int: list}) – Graph representing associations between tracks. Dictionary defines the mapping between a track ID and the parents of the track. This can be one (the track has one parent, and the parent has >=1 child) in the case of track splitting, or more than one (the track has multiple parents, but only one child) in the case of track merging. See examples/tracks_3d_with_graph.py

  • head_length (float) – Length of the positive (forward in time) tails in units of time.

  • metadata (dict) – Layer metadata.

  • name (str) – Name of the layer.

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

  • properties (dict {str: array (N,)}, DataFrame) – Properties for each point. Each property should be an array of length N, where N is the number of points.

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

  • tail_length (float) – Length of the positive (backward in time) tails in units of time.

  • tail_width (float) – Width of the track tails in pixels.

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

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

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.

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

colomaps_dict

color_by

colormap

colormaps_dict

current_time

current time according to the first dimension

cursor

String identifying cursor displayed over canvas.

cursor_size

Size of cursor if custom.

data

Coordinates for N points in D+1 dimensions.

display_graph

display the graph edges

display_id

display the track id

display_tail

display the track tail

editable

Whether the current layer data is editable from the viewer.

experimental_clipping_planes

extent

Extent of layer in data and world coordinates.

features

Dataframe-like features table.

graph

Graph representing associations between tracks.

graph_connex

vertex connections for drawing the graph

graph_times

time points associated with each graph vertex

head_length

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.

opacity

Opacity value between 0.0 and 1.0.

projection_mode

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

properties

Properties for each track.

properties_to_color_by

track properties that can be used for coloring etc...

rotate

Rotation matrix in world coordinates.

scale

Anisotropy factors to scale data into world coordinates.

shear

Shear matrix in world coordinates.

source

tail_length

Width for all vectors in pixels.

tail_width

Width for all vectors in pixels.

thumbnail

Integer array of thumbnail for the layer

track_colors

return the vertex colors according to the currently selected property

track_connex

vertex connections for drawing track lines

track_labels

return track labels at the current time

track_times

time points associated with each track vertex

translate

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

use_fade

toggle whether we fade the tail of the track, depending on whether the time dimension is displayed

visible

Whether the visual is currently being displayed.

Details

property current_time#

current time according to the first dimension

property data: ndarray#

Coordinates for N points in D+1 dimensions.

Type:

array (N, D+1)

property display_graph: bool#

display the graph edges

property display_id: bool#

display the track id

property display_tail: bool#

display the track tail

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 graph: dict[int, list[int]] | None#

Graph representing associations between tracks.

Type:

dict {int

Type:

list}

property graph_connex: ndarray#

vertex connections for drawing the graph

property graph_times: ndarray | None#

time points associated with each graph vertex

property properties: dict[str, ndarray]#

Properties for each track.

Type:

dict {str

Type:

np.ndarray (N,)}

property properties_to_color_by: list[str]#

track properties that can be used for coloring etc…

property tail_length: int#

Width for all vectors in pixels.

Type:

float

property tail_width: float#

Width for all vectors in pixels.

Type:

float

property track_colors: ndarray | None#

return the vertex colors according to the currently selected property

property track_connex: ndarray | None#

vertex connections for drawing track lines

property track_labels: tuple#

return track labels at the current time

property track_times: ndarray | None#

time points associated with each track vertex

property use_fade: bool#

toggle whether we fade the tail of the track, depending on whether the time dimension is displayed