napari.layers.Points

class napari.layers.Points(data=None, ndim=None, *, affine=None, antialiasing=1, axis_labels=None, blending='translucent', border_color='dimgray', border_color_cycle=None, border_colormap='viridis', border_contrast_limits=None, border_width=0.05, border_width_is_relative=True, cache=True, canvas_size_limits=(2, 10000), experimental_clipping_planes=None, face_color='white', face_color_cycle=None, face_colormap='viridis', face_contrast_limits=None, feature_defaults=None, features=None, metadata=None, n_dimensional=None, name=None, opacity=1.0, out_of_slice_display=False, projection_mode='none', properties=None, property_choices=None, rotate=None, scale=None, shading='none', shear=None, shown=True, size=10, symbol='o', text=None, translate=None, units=None, visible=True)

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

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

• antialiasing (float) – Amount of antialiasing in canvas pixels.

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

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

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

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

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

• border_width (float, array) – Width of the symbol border in pixels.

• border_width_is_relative (bool) – If enabled, border_width is interpreted as a fraction of the point size.

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

• canvas_size_limits (tuple of float) – Lower and upper limits for the size of points in canvas 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.

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

• 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 point and each column is a feature.

• metadata (dict) – Layer metadata.

• n_dimensional (bool) – This property will soon be deprecated in favor of ‘out_of_slice_display’. Use that instead.

• name (str) – Name of the layer. If not provided then will be guessed using heuristics.

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

• out_of_slice_display (bool) – If True, renders points 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 dimensions. Must fit to cls._projectionclass.

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

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

  Render lighting and shading on points. Options are:

  • ’none’ No shading is added to the points.

  • ’spherical’ Shading and depth buffer are changed to give a 3D spherical look to the points

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

• shown (1-D array of bool) – Whether to show each point.

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

• symbol (str, array) – Symbols 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.

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

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

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

data

Coordinates for N points in D dimensions.

Type:

array (N, D)

axis_labels

Dimension names of the layer data.

Type:

tuple of str

features

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

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

Array of symbols for each point.

Type:

array of str

size

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

Type:

array (N,)

border_width

Width of the marker borders in pixels for all points

Type:

array (N,)

border_width

Width of the marker borders for all points as a fraction of their size.

Type:

array (N,)

border_color

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

Type:

Nx4 numpy array

border_color_cycle

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

Type:

np.ndarray, list

border_colormap

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

Type:

str, napari.utils.Colormap

border_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_symbol

Symbol for the next point to be added or the currently selected points.

Type:

Symbol

current_size

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

Type:

float

current_border_width

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

Type:

float

current_border_color

Border color of the marker border for the next point to be added or the currently selected point.

Type:

str

current_face_color

Face color of the marker border for the next point to be added or the currently selected point.

Type:

str

out_of_slice_display

If True, renders points not just in central plane but also slightly out of slice according to specified point marker size.

Type:

bool

selected_data

Integer indices of any selected points.

Type:

Selection

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

border_color_mode

Border 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

shading

Shading mode.

Type:

Shading

antialiasing

Amount of antialiasing in canvas pixels.

Type:

float

canvas_size_limits

Lower and upper limits for the size of points in canvas pixels.

Type:

tuple of float

shown

Whether each point is shown.

Type:

1-D array of bool

units

Units of the layer data in world coordinates.

Type:

tuple of pint.Unit

Notes

_view_dataarray (M, D)

coordinates of points in the currently viewed slice.

_view_sizearray (M, )

Size of the point markers in the currently viewed slice.

_view_symbolarray (M, )

Symbols of the point markers in the currently viewed slice.

_view_border_widtharray (M, )

Border width of the point markers in the currently viewed slice.

_indices_viewarray (M, )

Integer indices of the points in the currently viewed slice and are shown.

_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

add(coords)	Adds points at coordinates.
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 displayed 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.
interaction_box(index)	Create the interaction box around a list of points in view.
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 face and border colors if using a cycle or color map
refresh_text()	Refresh the text values.
remove_selected()	Removes selected points if any.
save(path[, plugin])	Save this layer to path with default (or specified) plugin.
set_view_slice()
to_mask(*, shape[, data_to_world, ...])	Return a binary mask array of all the points as balls.
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.
antialiasing	Amount of antialiasing in canvas pixels.
axis_labels	tuple of axis labels for the layer.
blending	Determines how RGB and alpha values get mixed.
border_color	Array of RGBA border colors for each point
border_color_cycle	Color cycle for border_color.
border_color_mode	border color setting mode
border_colormap	Return the colormap to be applied to a property to get the border color.
border_contrast_limits	contrast limits for mapping the border_color colormap property to 0 and 1
border_width	border_width of all N points.
border_width_is_relative	treat border_width as a fraction of point size.
bounding_box
canvas_size_limits	Limit the canvas size of points
class_keymap
current_border_color	border color of marker for the next added point or the selected point(s).
current_border_width	border_width of marker for the next added point.
current_edge_color
current_edge_width
current_face_color	Face color of marker for the next added point or the selected point(s).
current_properties	properties for the next added point.
current_size	size of marker for the next added point.
current_symbol	symbol of marker for the next added point.
cursor	String identifying cursor displayed over canvas.
cursor_size	Size of cursor if custom.
data	coordinates for N points in D dimensions.
edge_color
edge_color_cycle
edge_color_mode
edge_colormap
edge_contrast_limits
edge_width
edge_width_is_relative
editable	Whether the current layer data is editable from the viewer.
experimental_clipping_planes
extent	Extent of layer in data and world coordinates.
face_color	Array of RGBA face colors for each point
face_color_cycle	Color cycle for face_color Can be a list of colors defined by name, RGB or RGBA
face_color_mode	Face color setting mode
face_colormap	Return the colormap to be applied to a property to get the face color.
face_contrast_limits	clims for mapping the face_color colormap property to 0 and 1
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
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.
n_dimensional	This property will soon be deprecated in favor of out_of_slice_display.
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 points 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.
selected_data	set of currently selected points.
shading	shading mode.
shear	Shear matrix in world coordinates.
shown	Boolean array determining which points to show
size	size of all N points.
source
symbol	symbol used for all point markers.
text	the TextManager object containing containing the text properties
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.
visible	Whether the visual is currently being displayed.

Details

add(coords)

Adds points at coordinates.

Parameters:

coords (array) – Point or points to add to the layer data.

property affine: Affine

Extra affine transform to go from physical to world coordinates.

Type:

napari.utils.transforms.Affine

property antialiasing: float

Amount of antialiasing in canvas pixels.

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

property border_color: ndarray

Array of RGBA border colors for each point

Type:

(N x 4) np.ndarray

property border_color_cycle: ndarray

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

Type:

Union[list, np.ndarray]

property border_color_mode: str

border 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

property border_colormap: Colormap

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

Returns:

colormap – The Colormap object.

Return type:

napari.utils.Colormap

property border_contrast_limits: tuple[float, float]

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

Type:

None, (float, float)

property border_width: ndarray

border_width of all N points.

Type:

(N, D) array

property border_width_is_relative: bool

treat border_width as a fraction of point size.

Type:

bool

property canvas_size_limits: tuple[float, float]

Limit the canvas size of points

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 current_border_color: str

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

Type:

str

property current_border_width: int | float

border_width of marker for the next added point.

Type:

float

property current_face_color: str

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

property current_properties: dict[str, ndarray]

properties for the next added point.

Type:

dict{str

Type:

np.ndarray(1,)}

property current_size: int | float

size of marker for the next added point.

Type:

float

property current_symbol: int | float

symbol of marker for the next added point.

Type:

float

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

coordinates for N points in D dimensions.

Type:

(N, 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 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 face_color: ndarray

Array of RGBA face colors for each point

Type:

(N x 4) np.ndarray

property face_color_cycle: ndarray

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

Type:

Union[np.ndarray, cycle]

property face_color_mode: str

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

property face_colormap: 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: None | tuple[float, float]

clims for mapping the face_color colormap property to 0 and 1

Type:

None, (float, float)

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

get_ray_intersections(position: list[float], view_direction: ndarray, dims_displayed: list[int], world: bool = True) → tuple[ndarray, ndarray] | tuple[None, None]

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

This method overrides the base layer, replacing the bounding box used to calculate intersections with a larger one which includes the size of points in view.

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 – 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: tuple | None = None, *, view_direction: ndarray | 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 # 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 : dict # Dict containing information that can be used in a status update. #

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

interaction_box(index: list[int]) → ndarray | None

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

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

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 n_dimensional: bool

This property will soon be deprecated in favor of out_of_slice_display. Use that instead.

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 points 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:

np.ndarray (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) → None

Calculate and update face and border 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 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() → None

Refresh the text values.

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

remove_selected() → None

Removes selected points if any.

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 selected_data: Selection[int]

set of currently selected points.

Type:

set

property shading: Shading

shading mode.

property shear: npt.NDArray

Shear matrix in world coordinates.

Type:

array

property shown: ndarray[Any, dtype[ScalarType]]

Boolean array determining which points to show

property size: ndarray

size of all N points.

Type:

(N,) array

property symbol: ndarray

symbol used for all point markers.

Type:

str

property text: TextManager

the TextManager object containing containing the text properties

Type:

TextManager

property thumbnail: npt.NDArray[np.uint8]

Integer array of thumbnail for the layer

Type:

array

to_mask(*, shape: tuple, data_to_world: Affine | None = None, isotropic_output: bool = True) → ndarray[Any, dtype[ScalarType]]

Return a binary mask array of all the points as balls.

Parameters:

• shape (tuple) – The shape of the mask to be generated.

• data_to_world (Optional[Affine]) – The data-to-world transform of the output mask image. This likely comes from a reference image. If None, then this is the same as this layer’s data-to-world transform.

• isotropic_output (bool) – If True, then force the output mask to always contain isotropic balls in data/pixel coordinates. Otherwise, allow the anisotropy in the data-to-world transform to squash the balls in certain dimensions. By default this is True, but you should set it to False if you are going to create a napari image layer from the result with the same data-to-world transform and want the visualized balls to be roughly isotropic.

Returns:

The output binary mask array of the given shape containing this layer’s points as balls.

Return type:

np.ndarray

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