Napari-3D-Counter

A plugin for manually counting objects in 3D images

Statement of need

Despite the many high-quality automated methods for identifying objects in images, expert annotation is sometimes the most practical option. For example, training and optimizing a machine learning model may require more effort than manual annotation. In these cases, user-friendly software is especially important to save time for the expert annotator. User-friendliness includes both ergonomics (whether the software is intuitive and efficient to use) and stability (whether the software works as expected).

I introduce the package Napari-3D-Counter, which leverages the Python / napari ecosystem to create a user-friendly interface for manual cell counting. Napari is a user-friendly multidimensional image viewer that is open source and implemented in the Python programming language. Napari’s implementation language gives it the advantage of easily integrating with Python’s numerous scientific tools through a plugin system.

Because napari is under active development, upstream changes can affect plugins. To keep Napari-3D-Counter reliable, fixes are released promptly with the aid of unit tests, which cover over 90% of the code. These tests are automatically run before publication using a GitHub Action.

The functionality of the main widget provided by Napari-3D-Counter, Count3D, is similar to the FIJI cell counter plugin, with important differences: no macros are necessary for keyboard automation, locations can be saved in the CSV format instead of XML (enabling easier integration with GUI spreadsheet tools) and most importantly, integration with the Python / napari ecosystem. This integration is significant because napari provides advanced 3D visualization capabilities, while the Python ecosystem offers powerful packages such as scikit-image and SciPy for analysis.

Native napari Points layers can replicate many of the core features of Count3D. However, Count3D has the advantage of being specifically specialized to count cells of different types: it takes one keyboard shortcut to switch between various cell type counters, and there is a live display of how many cells of each type have been counted. Furthermore, saving and loading a single CSV file containing the coordinates of all cells from all types is preferable to creating separate files for each type. Overall, using Napari-3D-Counter is likely to save the expert annotator’s time over using native Napari Points.

Finally, Count3D’s functionality is also similar to the manual spots feature of Imaris. In addition to the ergonomic benefits of a bespoke cell counter listed above, a clear advantage of Count3D over Imaris is its availability under a free software license, while Imaris is proprietary software that requires a costly license.

Beyond Count3D’s core features, other functions related to manual cell counting are implemented in auxiliary plugins: IngressPoints, SplitOnShapes, and ReconstructSelected. IngressPoints takes a native napari points layer, perhaps created by automated labeling, and turns them into a counted cell type in Count3D. SplitOnShapes splits labels of cell types based on spatial information. For example, if a user wants to quantify the distribution of cells of multiple types across a tissue with multiple repeating segments (eg. spinal cord), they can use a napari Shapes layer to define all the segments in the X and Y axes, and SplitOnShapes will return a count of each cell type within each shape. Finally, ReconstructSelected can be used to aid in visualizing cells: if a user has a Label layer labeling all cells, but they only want to visualize a subset, ReconstructSelected will take those labels containing a Count3D cell and create an image layer contating only those cells, which can then be used to create 2D or 3D images. Overall, these auxiliary plugins help to integrate Count3D into more complex, semi-automated cell counting processes.

The utility of this plugin is also reflected in its use. It has been used in scientific publications and has over 15,000 downloads on conda-forge.

This napari plugin was generated with Cookiecutter using @napari’s cookiecutter-napari-plugin template.

Prerequisites

It is recommended to use conda to install Napari-3D-Counter and napari. Installation instructions for the miniconda distribution of conda can be found here:

https://www.anaconda.com/docs/getting-started/miniconda/install

Installation

You can install napari-3d-counter via conda

conda create -n n3dc-env -c conda-forge -y napari napari-3d-counter pyqt python=3.12
conda activate n3dc-env

pip

pip install napari-3d-counter

conda activate napari-env
pip install napari-3d-counter

Count3D Usage

1. First launch napari with the napari command.
2. Count3D can be launched from the plugin menu of napari, or through the command palette (Ctrl+Shift+P). Select Count3D.

This will spawn several Points Layers:

Point adder

This layer acts as the interface for napari-3d-counter. Any points added to this layer are dispatched into the appropriate data layer labeled by the GUI. Any other actions to this layer has no effects

Cell Type N

These are the data layers. The points actually live in these layers, and you can edit the style or delete individual points here.

out of slice

This contains the x and y of all points in all layers. This may be useful to keep track of what regions of the data have been annotated.

Adding a cell

You can add a cell of the currently selected cell type by clicking on the viewer. The counter on the current cell type’s button (on the right side of the screen) will be incremented.

Changing cell type

You can change the currently selected cell type by clicking on that cell type’s button. This change will be reflected in the the color and text of the first box in the GUI. Now any clicks to the canvas will be added to that type.

Additionally, the keyboard shortcut for that cell type can be used. Keyboard shortcuts are listed on the button, and are “q”, “w”, “e”, “r”, “t”, “y” by default

Undo last added cell

The undo button (shortcut u) will remove last added cell, regardless of cell type. This will change both remove the cell from the canvas and decrease the count in the appropriate type.

Remove a particular cell

To remove a particular cell, change to the layer containing the cell you would like to remove. Then select the select points tool (arrow) to select the points to delete, then use Delete selected points (x) to delete those points

This change will be reflected in the counts.

Change appearance of a cell type

Changes to the name or edge color of a points layer will be reflected in the previously added points, as well as the GUI. Features that are editable in this way include:

• face color
• edge color
• symbol
• point size

Save configuration

Use the Make launch_cell_count.py button to create a python script that will launch napari with 3DCounter added to the dock and with all cell type appearances. This functions to save any manual changes you made to the appearance of a cell type between sessions.

Save cells

Use the “Save cells” button to save the cell coordinates for all layers into a csv file. This saves the coordinates and the names of each of the cells.

Load cells

Use the “Load cells” button to load the cells from a csv file into new layers

Launch with saved configuration

To run Count3D with custom configuration, paste the following code into your napari ipython console

from napari_3d_counter import Count3D, CellTypeConfig

cell_type_config = [
    # The first cell type is called "cq+eve+" and should be green
    CellTypeConfig(
        name="cq+eve+",
        color="g"
    ),
    # The first cell type is called "cq+eve-" and should be cyan
    CellTypeConfig(
        name="cq+eve-",
        color="c"
    ),
    # The first cell type is called "cq-eve+" and should be red
    CellTypeConfig(
        name="cq-eve+",
        color="r"
    ),
]
# Launch the plugin with configuration
viewer.window.add_dock_widget(Count3D(viewer, cell_type_config=cell_type_config))

Usage example can be found in /example/launch_count_3d.py

Auxiliary plugins

Ingress Points

This plugin takes a points layer and adds the points to the selected cell type layer. This can be useful if you want to manually count cells after cell identification.

Usage example can be found in /example/launch_ingress_points.py

Split on Shapes

This plugin can be used to subset a cell type into several groups based on their x-y location. Simply draw a shape that surrounds your cells (perhaps in a segment of segmentaly repeating tissue) and run this plugin to get a list of cells of each type in each shape.

Usage example can be found in /example/launch_split_on_shapes.py

Reconstruct Selected

One use case of Napari 3D Counter is to visualize a subset of labeled cells. For example, automated process label your cells of interest as well as a set of off-target cells, and you would like to visualize only your cells of interest. This can be accomplished by using Napari 3D Counter to count your cells of interest, and some other process to create labels (perhaps nsbatwm) and using Reconstruct Selected to create a new image layer of those labels which have been counted as a particular cell type.

Usage example can be found in /example/launch_reconstruct_selected.py

Contributing

Contributions are very welcome. However, code written by LLMs is not welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

To contribute, first fork and clone the repository on GitHub: (GitHub docs)[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo]

Then install localy:

cd napari-3d-counter
pip install -e '.[testing]'

Run unit tests:

pytest

Run full test suite, ensuring it installs properly:

tox

License

Distributed under the terms of the GNU GPL v3.0 license, “napari-3d-counter” is free and open source software

Issues

If you encounter any problems, please file an issue along with a detailed description.