Using the points layer

In this document, you will learn about the napari Points layer, including displaying spots over an image that have been found in an automated fashion, or manually annotating an image with points. You will also understand how to add a points layer and edit it from the GUI and from the console.

When to use the points layer

The points layer allows you to display an NxD array of N points in D coordinates. You can adjust the size, face color, and edge color of all the points independently. You can also adjust the opactiy, edge width, and symbol representing all the points simultaneously.

Each data point can have annotations associated with it using the Points.properties dictionary. These properties can be used to set the face and edge colors of the points. For example, when displaying points of different classes/types, one could automatically set color the individual points by their respective class/type. For more details on point properties, see the “setting point edge and face color with properties” below or the point annotation tutorial.

A simple example

You can create a new viewer and add a set of points in one go using the napari.view_points method, or if you already have an existing viewer, you can add points to it using viewer.add_points. The api of both methods is the same. In these examples we’ll mainly use add_points to overlay points onto on an existing image.

In this example, we will overlay some points on the image of an astronaut:

import napari
import numpy as np
from skimage import data

viewer = napari.view_image(data.astronaut(), rgb=True)
points = np.array([[100, 100], [200, 200], [300, 100]])

points_layer = viewer.add_points(points, size=30)
from napari.utils import nbscreenshot

nbscreenshot(viewer, alt_text="3 points overlaid on an astronaut image")
3 points overlaid on an astronaut image

Arguments of view_points and add_points

view_points() and add_points() accept the same layer-creation parameters.

help(napari.view_points)
Help on function view_points in module napari.view_layers:

view_points(data=None, *, ndim=None, features=None, properties=None, text=None, symbol='o', size=10, edge_width=0.1, edge_width_is_relative=True, 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, out_of_slice_display=False, n_dimensional=None, name=None, metadata=None, scale=None, translate=None, rotate=None, shear=None, affine=None, opacity=1, blending='translucent', visible=True, cache=True, property_choices=None, experimental_clipping_planes=None, shading='none', experimental_canvas_size_limits=(0, 10000), shown=True, title='napari', ndisplay=2, order=(), axis_labels=(), show=True) -> napari.viewer.Viewer
    Create a viewer and add a 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.
    features : dict[str, array-like] or DataFrame
        Features table where each row corresponds to a point and each column
        is a feature.
    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 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.
    edge_width : float, array
        Width of the symbol edge in pixels.
    edge_width_is_relative : bool
        If enabled, edge_width is interpreted as a fraction of the point size.
    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())
    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.
    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.
    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
        `Affine` transform object. Applied as an extra transform on top of the
        provided scale, rotate, and shear values.
    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.
    cache : bool
        Whether slices of out-of-core datasets should be cached upon retrieval.
        Currently, this only applies to dask arrays.
    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
    experimental_canvas_size_limits : tuple of float
        Lower and upper limits for the size of points in canvas pixels.
    shown : 1-D array of bool
        Whether to show each point.
        title : string, optional
        The title of the viewer window. by default 'napari'.
    ndisplay : {2, 3}, optional
        Number of displayed dimensions. by default 2.
    order : tuple of int, optional
        Order in which dimensions are displayed where the last two or last
        three dimensions correspond to row x column or plane x row x column if
        ndisplay is 2 or 3. by default None
    axis_labels : list of str, optional
        Dimension names. by default they are labeled with sequential numbers
    show : bool, optional
        Whether to show the viewer after instantiation. by default True.
    
    
    Returns
    -------
    viewer : :class:`napari.Viewer`
        The newly-created viewer.

Points data

The input data to the points layer must be an NxD numpy array containing the coordinates of N points in D dimensions. The ordering of these dimensions is the same as the ordering of the dimensions for image layers. This array is always accessible through the layer.data property and will grow or shrink as new points are either added or deleted.

Using the points properties dictionary

The Points layer can contain properties that annotate each point. Points.properties stores the properties in a dictionary where each key is the name of the property and the values are numpy arrays with a value for each point (i.e., length N for N points in Points.data). As we will see below, we can use the values in a property to set the display properties of the points (e.g., face color or edge color). To see the points properties in action, please see the point annotation tutorial.

Creating a new points layer

As you can add new points to a points layer using the add points tool, it is possible to create a brand new empty points layers by clicking the new points layer button above the layers list. The shape of the points layer is defined by the points inside it, and so as you add new points the shape will adjust as needed. The dimension of the new points layer will default to the largest dimension of any layer currently in the viewer, or to 2 if no other layers are present in the viewer.

Non-editable mode

If you want to disable editing of the points layer you can set the editable property of the layer to False.

As note in the section on 3D rendering, when using 3D rendering the points layer is not editable.

3D rendering of points

All our layers can be rendered in both 2D and 3D mode, and one of our viewer buttons can toggle between each mode. The number of dimensions sliders will be 2 or 3 less than the total number of dimensions of the layer. See for example these points overlaid on an image in both 2D and 3D:

Note though that when entering 3D rendering mode the point add, delete, and select tools are all disabled. Those options are only supported when viewing a layer using 2D rendering.

Pan and zoom mode

The default mode of the points layer is to support panning and zooming, as in the image layer. This mode is represented by the magnifying glass in the layers control panel, and while it is selected editing the layer is not possible. Continue reading to learn how to use some of the editing modes. You can always return to pan and zoom mode by pressing the Z key when the points layer is selected.

Adding, deleting, and selecting points

New points can be added using the point adding tool. This tool can be selected from layer controls panel. Points can then be added by clicking in the canvas. If you have a multidimensional points layer then the coordinates of the new point will keep track of the currently viewed slice that you added the point too. You can quickly select the add points tool by pressing the P key when the points layer is selected. The point adding tool also supports panning and zooming.

You can select a point by selecting the select points tool and then clicking on that point. You can select multiple points by continuing to shift click on additional points, or by dragging a bounding box around the points you want to select. You can quickly select the select points tool by pressing the S key when the points layer is selected.

You can select all the points in the currently viewed slice by clicking the A key if you are in select mode.

Once selected you can delete the selected points by clicking on the delete button in the layer controls panel or pressing the delete key.

When using the point selection tool the pan and zoom functionality of the viewer canvas is disabled and you are able to select points the layer. You can temporarily re-enable pan and zoom by pressing and holding the spacebar. This feature can be useful if you want to move around the points layer as you create your selection.

Changing points size

Each point can have a different size. You can pass a list or 1-dimensional array of points through the size keyword argument to initialize the layer with points of different sizes. These sizes are then accessible through the size property. If you pass a single size then all points will get initialized with that size. Points can be pseudo-visualized as n-dimensional if the out_of_slice_display property is set to True or the out of slice checkbox is checked. In this setting when viewing different slices of the layer points will appear in the neighbouring slices to the ones in which they are located with a size scaled by the distance from their center to that slice. This feature can be especially useful when visualizing 2D slices of points that are located in a 3D volume.

Points can also be resized within the GUI by first selecting them and then adjusting the point size slider. If no points are selected, then adjusting the slider value will only serve to initialize the size for new points that are about to be added. The value of the size of the next point to be added can be found in the layer.current_size property. Note this property is different from layer.size which contains the current sizes of all the points.

Changing points edge and face color

Individual points can each have different edge and face colors. You can initially set these colors by providing a list of colors to the edge_color or face_color keyword arguments respectively, or you can edit them from the GUI. The colors of each of the points are available as lists under the layer.edge_color and layer.face_color properties. Similar to the size and current_size properties these properties are different from the layer.current_edge_color and layer.current_face_color properties that will determine the color of the next point to be added or any currently selected points.

To change the point color properties from the GUI you must first select the points whose properties you want to change, otherwise you will just be initializing the property for the next point you add.

Setting point edge and face color with properties

Point edge and face colors can be set as a function of a property in Points.properties. There are two ways that the values in properties can be mapped to colors: (1) color cycles and (2) colormaps.

Color cycles are sets of colors that are mapped to categorical properties. The colors are repeated if the number of unique property values is greater than the number of colors in the color cycle.

Colormaps are a continuum of colors that are mapped to a continuous property value. The available colormaps are listed below (colormaps are from vispy). For some guidance on choosing colormaps, see the matplotlib colormap docs.

list(napari.utils.colormaps.AVAILABLE_COLORMAPS)
['PiYG',
 'blue',
 'bop blue',
 'bop orange',
 'bop purple',
 'cyan',
 'gist_earth',
 'gray',
 'gray_r',
 'green',
 'hsv',
 'inferno',
 'magenta',
 'magma',
 'plasma',
 'red',
 'turbo',
 'twilight',
 'twilight_shifted',
 'viridis',
 'yellow']

Setting edge or face color with a color cycle

Here we will set the edge color of the markers with a color cycle on a property. To do the same for a face color, substitute face_color for edge_color in the example snippet below.

viewer = napari.view_image(data.astronaut(), rgb=True)
points = np.array([[100, 100], [200, 200], [300, 100]])
point_properties = {
    'good_point': np.array([True, True, False]),
    'confidence': np.array([0.99, 0.8, 0.2]),
}

points_layer = viewer.add_points(
    points,
    properties=point_properties,
    edge_color='good_point',
    edge_color_cycle=['magenta', 'green'],
    edge_width=0.5,
)
nbscreenshot(viewer, alt_text="3 points overlaid on an astronaut image, where the edge color of the points has been changed to a color cycle")