napari + DeepLabCut annotation tool
A napari plugin for keypoint annotation with DeepLabCut
Start by installing PySide6 with
pip install "pyside6<6.3.2"; this is the library we now use to build GUIs.
You can then install
napari-deeplabcut via pip:
pip install napari-deeplabcut
Alternatively, to install the latest development version, run:
pip install git+https://github.com/DeepLabCut/napari-deeplabcut.git
To use the plugin, please run:
Then, activate the plugin in Plugins > napari-deeplabcut: Keypoint controls.
All accepted files (config.yaml, images, h5 data files) can be loaded either by dropping them directly onto the canvas or via the File menu.
The easiest way to get started is to drop a folder (typically a folder from within a DeepLabCut's
labeled-data directory), and, if labeling from scratch, drop the corresponding
config.yaml to automatically add a
Points layer and populate the dropdown menus.
Tools & shortcuts are:
3, to easily switch between labeling and selection mode
4, to enable pan & zoom (which is achieved using the mouse wheel or finger scrolling on the Trackpad)
M, to cycle through regular (sequential), quick, and cycle annotation mode (see the description here)
E, to enable edge coloring (by default, if using this in refinement GUI mode, points with a confidence lower than 0.6 are marked in red)
F, to toggle between animal and body part color scheme.
backspaceto delete a point.
- Check the box "display text" to show the label names on the canvas.
- To move to another folder, be sure to save (Ctrl+S), then delete the layers, and re-drag/drop the next folder.
Annotations and segmentations are saved with
File > Save Selected Layer(s)... (or its shortcut
Only when saving segmentation masks does a save file dialog pop up to name the destination folder;
keypoint annotations are otherwise automatically saved in the corresponding folder as
- As a reminder, DLC will only use the H5 file; so be sure if you open already labeled images you save/overwrite the H5.
- Note, before saving a layer, make sure the points layer is selected. If the user clicked on the image(s) layer first, does
Save As, then closes the window, any labeling work during that session will be lost!
Video frame extraction and prediction refinement¶
Since v0.0.4, videos can be viewed in the GUI.
Since v0.0.5, trailing points can be visualized; e.g., helping in the identification of swaps or outlier, jittery predictions.
Loading a video (and its corresponding output h5 file) will enable the video actions at the top of the dock widget: they offer the option to manually extract video frames from the GUI, or to define cropping coordinates. Note that keypoints can be displaced and saved, as when annotating individual frames.
Suggested workflows, depending on the image folder contents:
Labeling from scratch – the image folder does not contain
Open napari as described in Usage and open an image folder together with the DeepLabCut project's
config.yaml. The image folder creates an image layer with the images to label. Supported image formats are:
config.yamlfile creates a Points layer, which holds metadata (such as keypoints read from the config file) necessary for labeling. Select the Points layer in the layer list (lower left pane on the GUI) and click on the +-symbol in the layer controls menu (upper left pane) to start labeling. The current keypoint can be viewed/selected in the keypoints dropdown menu (right pane). The slider below the displayed image (or the left/right arrow keys) allows selecting the image to label.
To save the labeling progress refer to Save Layers.
Data successfully savedshould be shown in the status bar, and the image folder should now contain a
CollectedData_<ScorerName>.h5file. (Note: For convenience, a CSV file with the same name is also saved.)
Resuming labeling – the image folder contains a
Open napari and open an image folder (which needs to contain a
CollectedData_<ScorerName>.h5file). In this case, it is not necessary to open the DLC project's
config.yamlfile, as all necessary metadata is read from the
Saving works as described in 1.
Refining labels – the image folder contains a
The process is analog to 2.
Drawing segmentation masks
Drop an image folder as in 1, manually add a shapes layer. Then select the rectangle in the layer controls (top left pane), and start drawing rectangles over the images. Masks and rectangle vertices are saved as described in Save Layers. Note that masks can be reloaded and edited at a later stage by dropping the
vertices.csvfile onto the canvas.
Labeling multiple image folders¶
Labeling multiple image folders has to be done in sequence; i.e., only one image folder can be opened at a time. After labeling the images of a particular folder is done and the associated Points layer has been saved, all layers should be removed from the layers list (lower left pane on the GUI) by selecting them and clicking on the trashcan icon. Now, another image folder can be labeled, following the process described in 1, 2, or 3, depending on the particular image folder.
Defining cropping coordinates¶
Prior to defining cropping coordinates, two elements should be loaded in the GUI:
a video and the DLC project's
config.yaml file (into which the crop dimensions will be stored).
Then it suffices to add a
Shapes layer, draw a
rectangle in it with the desired area,
and hit the button
Store crop coordinates; coordinates are automatically written to the configuration file.
Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.
To locally install the code, please git clone the repo and then run
pip install -e .
Distributed under the terms of the BSD-3 license, "napari-deeplabcut" is free and open source software.
If you encounter any problems, please file an issue along with a detailed description.
- 06 December 2022
- 03 June 2022
- Information not submitted
- Stars: 31
- Forks: 8
- Issues + PRs: 9