napari.layers.Points

class napari.layers.Points(data=None, *, ndim=None, properties=None, text=None, symbol='o', size=10, edge_width=1, edge_color='black', edge_color_cycle=None, edge_colormap='viridis', edge_contrast_limits=None, face_color='white', face_color_cycle=None, face_colormap='viridis', face_contrast_limits=None, n_dimensional=False, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=1, blending='translucent', visible=True, property_choices=None)[source]

Bases: napari.layers.base.base.Layer

Points layer.

Parameters
  • data (array (N, D)) – Coordinates for N points in D dimensions.

  • ndim (int) – Number of dimensions for shapes. When data is not None, ndim must be D. An empty points layer can be instantiated with arbitrary ndim.

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

  • property_choices (dict {str: array (N,)}) – possible values for each property.

  • text (str, dict) – Text to be displayed with the points. If text is set to a key in properties, the value of that property will be displayed. Multiple properties can be composed using f-string-like syntax (e.g., ‘{property_1}, {float_property:.2f}). A dictionary can be provided with keyword arguments to set the text values and display properties. See TextManager.__init__() for the valid keyword arguments. For example usage, see /napari/examples/add_points_with_text.py.

  • symbol (str) – Symbol to be used for the point markers. Must be one of the following: arrow, clobber, cross, diamond, disc, hbar, ring, square, star, tailed_arrow, triangle_down, triangle_up, vbar, x.

  • size (float, array) – Size of the point marker. If given as a scalar, all points are made the same size. If given as an array, size must be the same broadcastable to the same shape as the data.

  • edge_width (float) – Width of the symbol edge in pixels.

  • edge_color (str, array-like, dict) – Color of the point marker border. Numeric color values should be RGB(A).

  • 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 edge_color if a continuous attribute is used to set face_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())

  • face_color (str, array-like, dict) – Color of the point marker body. Numeric color values should be RGB(A).

  • face_color_cycle (np.ndarray, list) – Cycle of colors (provided as string name, RGB, or RGBA) to map to face_color if a categorical attribute is used color the vectors.

  • face_colormap (str, napari.utils.Colormap) – Colormap to set face_color if a continuous attribute is used to set face_color.

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

  • n_dimensional (bool) – If True, renders points not just in central plane but also in all n-dimensions according to specified point marker size.

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

Coordinates for N points in D dimensions.

Type

array (N, D)

properties

Annotations for each point. Each property should be an array of length N, where N is the number of points.

Type

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

text

Text to be displayed with the points. If text is set to a key in properties, the value of that property will be displayed. Multiple properties can be composed using f-string-like syntax (e.g., ‘{property_1}, {float_property:.2f}). For example usage, see /napari/examples/add_points_with_text.py.

Type

str

symbol

Symbol used for all point markers.

Type

str

size

Array of sizes for each point in each dimension. Must have the same shape as the layer data.

Type

array (N, D)

edge_width

Width of the marker edges in pixels for all points

Type

float

edge_color

Array of edge color RGBA values, one for each point.

Type

Nx4 numpy array

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 edge_color if a continuous attribute is used to set face_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)

face_color

Array of face color RGBA values, one for each point.

Type

Nx4 numpy array

face_color_cycle

Cycle of colors (provided as string name, RGB, or RGBA) to map to face_color if a categorical attribute is used color the vectors.

Type

np.ndarray, list

face_colormap

Colormap to set face_color if a continuous attribute is used to set face_color.

Type

str, napari.utils.Colormap

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

current_size

Size of the marker for the next point to be added or the currently selected point.

Type

float

current_edge_color

Size of the marker edge for the next point to be added or the currently selected point.

Type

str

current_face_color

Size of the marker edge for the next point to be added or the currently selected point.

Type

str

n_dimensional

If True, renders points not just in central plane but also in all n-dimensions according to specified point marker size.

Type

bool

selected_data

Integer indices of any selected points.

Type

set

mode

Interactive mode. The normal, default mode is PAN_ZOOM, which allows for normal interactivity with the canvas.

In ADD mode clicks of the cursor add points at the clicked location.

In SELECT mode the cursor can select points by clicking on them or by dragging a box around them. Once selected points can be moved, have their properties edited, or be deleted.

Type

str

face_color_mode

Face color setting mode.

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

edge_color_mode

Edge color setting mode.

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

Notes

_property_choicesdict {str: array (N,)}

Possible values for the properties in Points.properties.

_view_dataarray (M, 2)

2D coordinates of points in the currently viewed slice.

_view_sizearray (M, )

Size of the point markers in the currently viewed slice.

_indices_viewarray (M, )

Integer indices of the points in the currently viewed slice.

_selected_view :

Integer indices of selected points in the currently viewed slice within the _view_data array.

_selected_boxarray (4, 2) or None

Four corners of any box either around currently selected points or being created during a drag action. Starting in the top left and going clockwise.

_drag_startlist or None

Coordinates of first cursor click during a drag action. Gets reset to None after dragging is done.

Methods

Attributes

add(coord)[source]

Adds point at coordinate.

Parameters

coord (sequence of indices to add point at) –

property affine

Extra affine transform to go from physical to world coordinates.

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 coordinates

Cursor position in data coordinates.

classmethod create(data, meta=None, layer_type=None)

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)
Return type

Layer

property current_edge_color

Edge color of marker for the next added point or the selected point(s).

Type

str

Return type

str

property current_face_color

Face color of marker for the next added point or the selected point(s).

Return type

str

property current_properties

properties for the next added point.

Type

dict{str

Type

np.ndarray(1,)}

Return type

Dict[str, ndarray]

property current_size

size of marker for the next added point.

Type

float

Return type

Union[int, float]

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 data

coordinates for N points in D dimensions.

Type

(N, D) array

Return type

ndarray

property displayed_coordinates

List of currently displayed coordinates.

displayed_coordinates is deprecated and will be removed in version 0.4.9. It should no longer be used as layers should will soon not know which dimensions are displayed. Instead you should use `[layer.coordinates[d] for d in viewer.dims.displayed]

Type

list

property edge_color

Array of RGBA edge colors for each point

Type

(N x 4) np.ndarray

Return type

ndarray

property edge_color_cycle

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

Type

Union[list, np.ndarray]

Return type

ndarray

property edge_color_mode

Edge color setting mode

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

Return type

str

property edge_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

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

Type

None, (float, float)

Return type

Tuple[float, float]

property edge_width

width used for all point markers.

Type

float

Return type

Union[None, int, float]

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

property face_color

Array of RGBA face colors for each point

Type

(N x 4) np.ndarray

Return type

ndarray

property face_color_cycle

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

Type

Union[np.ndarray, cycle]

Return type

ndarray

property face_color_mode

Face color setting mode

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

Return type

str

property face_colormap

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

Returns

colormap – The Colormap object.

Return type

napari.utils.Colormap

property face_contrast_limits

clims for mapping the face_color colormap property to 0 and 1

Type

None, (float, float)

Return type

Optional[Tuple[float, float]]

get_ray_intersections(position, view_direction, dims_displayed, world=True)

Get the start and end point for the ray extending from a point through the data bounding box.

Parameters
  • position (List[float]) – 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.

Return type

Union[Tuple[ndarray, ndarray], Tuple[None, None]]

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, an emtpy numpy array is returned (i.e., np.empty([]).

  • 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, an emtpy numpy array is returned (i.e., np.empty([]).

get_status(position, *, view_direction=None, dims_displayed=None, world=False)

Status message of the data at a coordinate position.

Parameters
  • position (tuple) – 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

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

Return type

string

get_value(position, *, view_direction=None, dims_displayed=None, world=False)

Value of the data at a position.

If the layer is not visible, return None.

Parameters
  • position (tuple) – 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

displayed in status bar bottom right.

Type

str

interaction_box(index)[source]

Create the interaction box around a list of points in view.

Parameters

index (list) – List of points around which to construct the interaction box.

Returns

box – 4x2 array of corners of the interaction box in clockwise order starting in the upper-left corner.

Return type

np.ndarray or None

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 metadata

Key/value map for user-stored data.

Return type

dict

property mode

Interactive mode

Interactive mode. The normal, default mode is PAN_ZOOM, which allows for normal interactivity with the canvas.

In ADD mode clicks of the cursor add points at the clicked location.

In SELECT mode the cursor can select points by clicking on them or by dragging a box around them. Once selected points can be moved, have their properties edited, or be deleted.

Type

str

Return type

str

property n_dimensional

renders points as n-dimensionsal.

Type

bool

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

property properties

Annotations for each point

Type

dict {str

Type

np.ndarray (N,)}, DataFrame

Return type

Dict[str, ndarray]

refresh(event=None)

Refresh all layer data based on current view slice.

refresh_colors(update_color_mapping=False)[source]

Calculate and update face and edge colors if using a cycle or color map :type update_color_mapping: bool :param update_color_mapping: 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 points and want them to be colored with the same mapping as the other points (i.e., the new points shouldn’t affect the color cycle map or colormap), set update_color_mapping=False. Default value is False.

refresh_text()[source]

Refresh the text values.

This is generally used if the properties were updated without changing the data

remove_selected()[source]

Removes selected points if any.

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 selected_data

set of currently selected points.

Type

set

Return type

set

property shear

Shear matrix in world coordinates.

Type

array

property size

size of all N points in D dimensions.

Type

(N, D) array

Return type

Union[int, float, ndarray, list]

property symbol

symbol used for all point markers.

Type

str

Return type

str

property text

the TextManager object containing containing the text properties

Type

TextManager

Return type

TextManager

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

world_to_data(position)

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