Using the `points` layer#

DEPRECATED ATTRIBUTES

As of napari 0.5.0, edge_* attributes are being renamed to border_* attributes. We have yet to update the images and/or videos in this tutorial. Please use border in place of edge for all Points attributes moving forward.

The code in this tutorial uses the latest API. Only images and videos may be out of date.

In this document, you will learn about the napari Points layer, including displaying points 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.

For more information about layers, refer to Layers at a glance.

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 border color of all the points independently. You can also adjust opacity and symbol representing all the points simultaneously.

Each data point can have annotations associated with it using the Points.features table. These features can be used to set the face and border 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 features, see Setting point border and face color with features or point annotation tutorial.

Creating and editing the `points` layer using the GUI#

The GUI contains following tools in the layer controls panel for the points layer:

Buttons
- Delete selected points
- Add points
- Select points
- Pan/zoom
- Transform
Controls
- Opacity
- Point size
- Blending
- Symbol
- Face color
- Border color
- Display text
- Out of slice
Other tools
- New points layer button
- 2D/3D button

Buttons#

Deleting points

Points can be deleted after they have been selected. First select the point or points to delete, then click on the delete button in the layer controls panel or press the delete key on your keyboard.
Adding points

New points can be added using the point adding tool, shown above, from the layer controls panel. Points can then be added by clicking in the canvas.

Note: Clicking and dragging moves the image, just as pan/zoom does. Just click where you want the point to go. You cannot adjust the point by clicking and dragging. Use the point size control to make it larger or smaller.

If you have a multidimensional points layer then the coordinates of the new point will keep track of the currently viewed slice the point has been added to.

Quickly select the add points tool by pressing the 2 key when the points layer is selected. The add points tool supports panning and zooming.

Additionally, you can select all the points in the currently viewed slice by pressing the a key and all the points in the layer (across all slices) using Shift-a.

Note: Pressing either keybinding again will toggle the selection, so you can select all points in a layer and the deselect points from a slice.
Selecting points

Select a point using the tool (shown above) 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 switch to the select points tool by pressing the 3 key when the points layer is selected. Select all the points in the currently viewed slice by clicking the a key while in select mode.

Using the select points tool disables pan and zoom functionality. This allows you to select points on the layer. 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.
Pan/zoom

The default mode of the points layer supports 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, the Add point, Delete selected points, and Select points tools are all disabled. Those options are supported only when viewing a layer using 2D rendering. Return to pan and zoom mode by pressing the 4 key when the points layer is selected.
Transform

Use this tool to rotate, scale, or translate the layer. Note: at present this feature is limited to 2D viewer display mode. To reset the transformation, you can Option/Alt-click the transform button (a confirmation dialog will open to confirm the reset). Enable this mode by pressing the 5 key when the points layer is selected.

Controls#

Opacity

The opacity slider adjusts the opacity of a point or points from 0 (transparent) to 1.00 (completely opaque).
Point size

Point size can be adjusted from 1 to 100 using the point size slider.
Blending

Select translucent, translucent no depth, additive, minimum, or opaque from the dropdown. Refer to the Blending layers section of Layers at a glance for an explanation of each type of blending.
Symbol

Select one of the symbol types from the dropdown menu. This will be the shape of a new point or will change the shape of all points on the current points layer. The symbol property applies to all the points on a layer so you don’t need to have any points selected for it to have an effect. In fact, you cannot change the symbol for a single point on a layer and leave the rest the same.
Face and border colors

To change the point color properties from the GUI first select the points whose properties you want to change, otherwise you will just be initializing the property for the next point to add. Select the point you want to change, then click the thumbnail next to face color: or border color: to select or create a color from the pallette.
Display text

Check this box to turn display text on or off. Currently, text can be added to the points only programmatically and not through the GUI. Refer to the example Add points with multicolor text for more information.
Out of slice

If this box is checked, out of slice is on or true. If this box is not checked, out of slice is off or false. If it is on or true, points slightly out of slice are rendered. Refer to Changing points size below for more information.

Other tools#

New points layer button

Create a brand new empty points layer by clicking the New points layer button at the top of the layers list panel. The shape of the points layer is defined by the points inside it, 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.
2D/3D button or Toggle ndisplay button

All layers can be rendered in both 2D and 3D. The Toggle ndisplay button at the bottom of the left panel toggles between these 2 modes. When in 2D, the button looks like this: , ready to switch to 3D mode. When in 3D, the button looks like this: , ready to switch to 2D mode. You can also switch modes by pressing Ctrl+y.

Note that when entering 3D rendering mode the GUI Add point, Delete selected points, and Select points tools are all disabled. Those options are supported only when viewing a layer using 2D rendering.
ctrl-c and ctrl-v (copying and pasting points)

Copy and paste any selected points using ctrl-c and ctrl-v, respectively. If you have a multidimensional Points layer you can copy points from one slice to another by pasting them into the new slice. The coordinates of the points in the visible dimensions will be in the same place on the new slice as in the old slice, but the rest of the coordinates will be updated with the new slice values.

Controlling the `points` layer programmatically#

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.

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

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)

Arguments of `view_points` and `add_points`#

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

help(napari.view_points)

Show code cell output Hide code cell output

Help on function view_points in module napari.view_layers:

view_points(data=None, ndim=None, *, affine=None, antialiasing=1, 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, title='napari', ndisplay=2, order=(), show=True, camera: napari.components.camera.Camera = None, cursor: napari.components.cursor.Cursor = None, dims: napari.components.dims.Dims = None, grid: napari.components.grid.GridCanvas = None, layers: napari.components.layerlist.LayerList = None, help: str = '', status: Union[str, dict] = 'Ready', tooltip: napari.components.tooltip.Tooltip = None, theme: str = None, mouse_over_canvas: bool = False) -> 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.
    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.
        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 features table#

The Points layer can contain features that annotate each point. Points.features stores the features in a table or data frame where each column represents a feature and each row represents a point. Therefore, the table has N rows for the N points in Points.data. This table can be provided as a dictionary that maps from feature names to the columns of feature values. For example, the following dictionary can be used as the value for the features parameter in Viewer.add_points

features = {
    'good_point': [True, True, False],
    'confidence': [0.99, 0.8, 0.2],
}

and corresponds to the following features table

point index	good_point	confidence
0	True	0.99
1	True	0.8
2	False	0.2

where the point index is the index for a point in both data and its corresponding row in the features table.

As we will see below, we can use feature values to determine the display properties of the points (e.g., face color or border color). To see the points features in action, please see the Point annotation tutorial.

Non-editable mode#

To disable editing the points layer, set the editable property of the layer to False.

When using 3D rendering the points layer cannot be edited.

3D rendering#

The number of dimensions sliders will be 2 or 3 less than the total number of dimensions of the layer, allowing you to browse volumetric timeseries data and other high dimensional data. See for example these points overlaid on an image in both 2D and 3D:

Adding, deleting, and selecting points#

To do this in the console, use code something like the example in Add points on nD shapes.

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. When True and 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.

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 border and face color#

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

Setting point border and face color with features#

Point border and face colors can be set as a function of a feature in Points.features. There are two ways that these feature values can be mapped to colors: (1) color cycles and (2) colormaps.

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

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

list(napari.utils.colormaps.AVAILABLE_COLORMAPS)

['blue',
 'bop blue',
 'bop orange',
 'bop purple',
 'cyan',
 'gist_earth',
 'gray',
 'gray_r',
 'green',
 'hsv',
 'I Blue',
 'I Bordeaux',
 'I Forest',
 'I Orange',
 'I Purple',
 'inferno',
 'magenta',
 'magma',
 'PiYG',
 'plasma',
 'red',
 'turbo',
 'twilight',
 'twilight_shifted',
 'viridis',
 'yellow']

Setting border or face color with a color cycle#

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

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

points_layer = viewer.add_points(
    points,
    features=point_features,
    border_color='good_point',
    border_color_cycle=['magenta', 'green'],
    border_width=0.5,
)

3 points overlaid on an astronaut image, where the border color of the points has been changed to a color cycle

In the example above, the point_features table was provided as a dictionary with two keys or features: good_point and confidence as described in Using the points features table. The values of each feature are stored in a list of length 3 since there were three coordinates provided in points. We set the border color as a function of the good_point feature by providing the keyword argument border_color='good_point' to the viewer.add_points() method. The color cycle is set via the border_color_cycle keyword argument, border_color_cycle=['magenta', 'green']. The color cycle can be provided as a list of colors (a list of strings or a (M x 4) array of M RGBA colors).

Setting border or face color with a colormap#

In the example snippet below, we set the face color of the markers with a colormap on a feature. To do the same for a border color, substitute face for border.

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

points_layer = viewer.add_points(
    points,
    features=point_features,
    face_color='confidence',
    face_colormap='viridis',
)

3 points overlaid on an astronaut image, where the face color of the points has been changed to a colormap

In the example above, the point_features table was provided as a dictionary with two keys or features: good_point and confidence as described in Using the points features table. The values of each feature are stored in a list of length 3 since there were three coordinates provided in points. We set the face color as a function of the confidence feature by providing the keyword argument face_color='confidence' to the viewer.add_points() method. We set the colormap to viridis using the face_colormap keyword argument as face_colormap='viridis'.

Changing the points symbol#

The symbol for the points layer is a global property for the layer. All points on a layer must have the same symbol. You can set the symbol when loading the layer using the symbol keyword argument.

Putting it all together#

Here you can see an example of adding, selecting, deleting points, and changing their features:

Selecting and changing points color, size and symbol in napari.

Using the points layer#

When to use the points layer#

Creating and editing the points layer using the GUI#