napari-deeplabcut v0.4.0

A maintenance release, covering compatibility and data integrity.

Highlights

• A keypoints layer can no longer save its annotations into a folder it does not belong to (#246, closes #245)
  • The keypoints layer is reported and locked for editing instead; saving it works as previously (#246)
• Re-opening the same extracted frames folder no longer loads a duplicate keypoints layer (#246)
• Less use of napari internals, for compatibility with upcoming napari releases (#242)
• The numpy<2 upper bound is lifted, following DeepLabCut 3.0.2 (#241)

What you should know

Files written by earlier versions are not repaired

0.4.0 does not undo writes that already happened. If you labeled several extracted frames folders in one session with 0.3.x, check that each CollectedData_<ScorerName> file holds only frames from its own folder.

In the .csv next to it, the first column lists one frame per row; every row should name the folder the file sits in.

If any row names another folder, the napari plugin troubleshooting guide covers repairing the file.

New dialogs while labeling, and locked layers

Three situations are now handled differently:

• When a leftover keypoints layer belongs to a different folder than the frames you just opened
• When an annotated frame was renamed or deleted, so it is no longer in the folder
• When the same folder is opened twice; the duplicate keypoints layer is closed for you

In the first two, the keypoints layer is locked for editing until it matches the viewer's Image layer again.

Your annotations are untouched and saving still works, writing to the layer's own folder.
No file on disk is rewritten.

napari UI compatibility

Two situations now notify you once per session: napari's point size slider staying visible where the plugin means to hide it, and Ctrl+V not pasting keypoints. Both mean the plugin does not recognize your napari version's layer controls. Labeling still works; please report either.

Bug fixes

• #246 — Fix a keypoints layer adopting an unrelated dataset and saving into it (#245)
• #243 — Fix the config placeholder dialog's choice being forgotten when closing was cancelled, so a later config drop fell back to the default action
• #246 — Reject a folder whose frames match only by filename, which any two dataset folders in a DLC project do
• #246 — Stop keypoints on a deleted frame being re-keyed onto another frame
• #246 — Lock a keypoints layer for editing while it does not match the Image layer in the viewer

For developers

NumPy 2 (#241, #247)

The core numpy<2 bound is removed, following DeepLabCut#3499. DeepLabCut's TensorFlow extras still cap NumPy below 2 on some Python versions, so the NumPy resolved inside a deeplabcut[gui] environment depends on which extras are installed, not on this plugin alone.

napari compatibility canary (#239, #249)

A weekly job now runs the suite against napari --pre and against the declared 0.6.6 floor and latest stable, and opens a tracking issue on failure. The release path builds the distribution once and publishes the artifact that was installed and tested.

Faster test suite (#237)

The suite runs under pytest-xdist (-n auto --dist loadfile), roughly 290s to 60s locally.

Layer lifecycle (#243)

Keypoints layers kept bindings to a previous store after reattachment, and a recycled layer id was refused registration because a collected layer had left it behind. Both are fixed.

Please report any issue with this release, particularly around the NumPy 2 and napari compatibility work and the new locking behavior. Thanks for using the plugin!

What's Changed

• Run tests in parallel with pytest-xdist by @C-Achard in #237
• Detect napari and packaging breakage with a weekly job; centralize release workflow by @C-Achard in #239
• Release numpy<2 pin by @C-Achard in #241
• Update uv.lock by @C-Achard in #247
• Fix remaining napari private API usage by @C-Achard in #242
• Simplify layer lifecycle management by @C-Achard in #243
• Additional weekly CI fixes & improvements by @C-Achard in #249
• Fix: leftover Points layer leaking save info into newly loaded image layers by @C-Achard in #246

Full Changelog: v0.3.1.3...v0.4.0

napari-deeplabcut v0.3.1.3

Hotfix release: restores compatibility with napari 0.9, which prevented the plugin from starting.
Also applies the plugin's point size to newly added keypoints, and fixes labeling a keypoint after selecting one.

Changed

• The point size set in the plugin panel now applies to newly added keypoints, not only to keypoints already placed.
• napari's own point size slider is hidden in the layer controls. The plugin's point size panel is now the intended control for keypoint size.

Fixed

• Fixed the plugin failing to import on napari 0.9 and later (#235).
• Fixed being unable to add a point label after selecting a keypoint (#234).
• Fixed an invalid point size resizing keypoints before the error was reported, leaving the layer changed.

What's Changed

• Fix: cannot add point label after selecting a keypoint by @C-Achard in #234
• Fix napari 0.9+ import failure and apply point size to new keypoints by @C-Achard in #236

Full Changelog: v0.3.1.2...v0.3.1.3

napari-deeplabcut v0.3.1.2

Maintenance release: improves compatibility with recent napari versions, adds more ergonomic keyboard navigation, and fixes two issues affecting layer lifecycle and machine labels saves.

Added

• Added WASD keyboard shortcuts to navigate frames and select keypoints, for more ergonomic labeling.

Changed

• Added compatibility with napari 0.7 and later.

Fixed

• Fixed a crash caused by removing a Points layer while its trajectory plot was only partially initialized.
• Fixed a data-loss issue where saving machine labels for a disjoint set of frames could delete existing ground-truth keypoints.

What's Changed

• Add CI concurrency guards by @C-Achard in #229
• Relax napari version pin by @C-Achard in #217
• Fix crash when deleting Points layer immediately after loading by @C-Achard in #226
• Fix disjoint machine labels merge with GT being interpreted as deletion by @C-Achard in #228
• Add more ergonomic keybindings for navigation by @C-Achard in #225
• Minor UX tweaks by @C-Achard in #232

Full Changelog: v0.3.1.1...v0.3.1.2

napari-deeplabcut v0.3.1.1

What's Changed

This minor release focuses on faster video loading and navigation, more robust saving, and clearer visualization of machine labels.

Improvements

• Improved video reading performance, resulting in faster frame navigation especially for large videos.
• Made machine-generated labels visually distinct from other point layers, improving readability when multiple annotation layers are displayed.

Fixes

• Fixed handling of project configs containing duplicate bodyparts, preventing delayed failures during saves.
• Fixed saving behavior when keypoints that already exist in an .h5 file are deleted.
  • Added a clearer message when existing keypoints are deleted.
  • Ensured keypoint deletions are correctly propagated and persisted on disk.

Relevant PRs

• Improve video reader speed by @C-Achard in #215
• Add centralized layer display settings and make machine labels visually distinct by @C-Achard in #216
• Prevent loading duplicate body parts from config by @C-Achard in #220
• Fix overwrite conflict report generation to correctly handle deletions by @C-Achard in #223

Full Changelog: v0.3.1.0...v0.3.1.1

napari-deeplabcut v0.3.1.0

What's New

Automated annotation with point tracking

We're happy to introduce automated annotation with point tracking to help accelerate DeepLabCut annotation workflows in napari.

With the new Tracking Controls widget, you can now:

• Manually annotate keypoints on a reference frame
• Use a point tracking model to propagate those keypoints forward and/or backward in time
• Review, refine, delete, and merge tracked results before exporting them back into DeepLabCut

We currently support CoTracker3, please let us know if you would like to see more models added.

In more details:

• New Tracking Controls widget in napari
• Support for forward, backward, and bidirectional tracking
• Tracking results are created as separate Points layers, leaving the original annotation layer unchanged
• New refinement workflow for:
  • Deleting selected tracked points in future frames
  • Merging tracked results into annotation layers
  • Merge modes include:
    • Fill missing only
    • Overwrite existing target points
• Extensible point tracking model registry for future additions

Tracking is intended to accelerate annotation and does not replace manual review. The current workflow is still new, we welcome all feedback, improvement suggestions and feature requests.

Bug Fixes

Trajectory plotting robustness and tracking-layer support

Refactored trajectory plotting to use a more explicit internal render state and fixed issues affecting tracking layers.

Trajectory plot boundary handling

Fixed an issue where the trajectory plot window would compress to half the window size near the start or end of a video. The slider value is now more faithful to what is shown.

Config placeholder layer handling

Refactored and clarified the logic for handling config placeholder keypoint layers.

Changes include:

• Improved user prompts when new keypoints are detected in a config file
• Clearer choices for resolving placeholder layers:
  • Apply to current
  • Keep both
  • Cancel
• Fixed a segfault caused by premature layer deletion (see below)

Premature layer removal fix

Fixed a bug caused by placeholder layers being removed too early.

Color scheme legend text synchronization

Fixed an issue where legend color boxes updated when changing colormaps, but legend text did not.

This caused:

• Mismatch between legend text and color boxes
• Incorrect colors for newly added bodyparts
• Incorrect reset behavior after hover/unhover

Legend rendering is now more consistent with the selected colormap behavior.

Tracking widget and viewer synchronization

Fixed several issues in the tracking workflow:

• Fixed the viewer resetting to the first frame after adding tracking results
• Fixed the tracking widget not syncing to the current frame on startup
• Updated tracking progress behavior to use an indeterminate progress bar while preserving CoTracker-native batching
• Fixed the info button color so it follows napari settings instead of system theme settings (also affects layer stats)

We hope these fixes and improvements make the plugin more comfortable to use. Please let us know if you have any feedback!

Bug fixes

• Fixed an incorrect saving issue with machine labels causing likelihood columns to be retained
  • Affected projects will currently have to be saved again in napari-deeplabcut in order to allow shuffle creation to succeed in DLC.
  • Affected project will once more work as expected after DeepLabCut/DeepLabCut#3323 is merged.
  • Please open an issue if your project is affected and you cannot recover!

Full changelog

See v0.3.0.0...v0.3.0.1

napari-deeplabcut v0.3.0.0

This release brings a nearly-complete rewrite of the plugin, keeping a familiar UI and workflow but adding many new safety improvements around data loading/saving, improved user experience including more informative dialogs and issue reporting tools, and many quality-of-life improvements.

New features

UI additions

New status panel with folder, progress estimate, and point size slider

• New tooltip showing currently opened folder
• New "progress estimate" widget, showing the estimated % frames labeled in the current folder.

• Global point size slider:
  • Updates the size of all keypoints in the viewer
  • Saved to config.yaml automatically, and loaded on startup
  • One can still use the native napari point size slider for individual points, but this will not be persisted.

New color scheme display interactions

• Color scheme display improvements:

  • Now only shows entries for keypoints on the current frame
  • Added a toggle to show all keypoints from config.yaml, even if they are not visible on the current frame
  • Clicking an entry now selects all matching keypoints in the frame
  • Clicking an entry in "Show all keypoints" mode will jump to the first frame where that keypoint is visible, and select all matching keypoints in that frame, if any.
  • Also works for multi-animal data:
    • Clicking an individual's entry will select all keypoints for that individual
    • Clicking on a bodypart entry will select all keypoints for that bodypart across all individuals

• Fixed & improved trails:

  • Trails now work properly in multi-animal data, showing trails for all individuals of the proper color
  • Basic visualization settings for trails are persisted across sessions

New trajectory plot interactions

• Fixed and improved trajectory plot:
  • Colors are now dynamically updated to match individuals/bodyparts in the viewer
  • Selecting points automatically filters the plot to the selected individuals/bodyparts
  • Fixed Y coordinates to match napari viewer coordinates (top-left origin)

New tutorial

New keyboard shortcuts

• Improved tutorial and keyboard shortcuts dialogs
  • Keybinds are now dynamically shown if available, and document why they are enabled/disabled based on context
    • e.g. No Points layer -> Points navigation shortcuts are disabled
  • Updated tutorial visuals

New video frame extraction and cropping menu

• Improved video frame extraction and cropping
  • Loading a video opens the usual Video Controls panel, now with additional contextual information
  • Checking "Crop with rectangle" immediately creates a Shapes layer and selects the rectangle drawing tool
  • Safer method for selecting which rectangle to use for cropping when multiple are present, and better handling of edge cases
  • Shows the crop coordinates as they will appear in config.yaml

New debug log generation utility

• Debug log generation utility
  • Opening a Keypoint Controls dialog now adds a Help > Generate napari-dlc log option
  • Generates a copy-pastable log of relevant information about the plugin and napari environment, as well as latest debug messages, to help with debugging and issue reporting

Data loading/saving fixes and improvements

• Drag & drop loading is fixed!
  • Now auto-opens Keypoint Controls on folder load
  • When saving "project-less" annotations, the plugin may ask for a config.yaml if relevant, which will write annotations relative to the specified project. Users should then move the resulting annotations folder back to the specified project.

• Copy-paste is fixed!
• Any save that would overwrite data now shows a confirmation dialog
  • Can be disabled with the "Warn on overwrite" option in the Keypoint Controls, if one is labeling from scratch and requires faster saves
  • Saving machine labels now clearly shows that the CollectedData file will be modified, and warns about overwriting existing data if there are conflicts with existing labels
• Improved data loading checks and remapping of frames
  • Moving data between folders or machines should cause less issues with frame remapping, and the plugin should be able to recover from more types of data loading issues without crashing or incorrectly loading data.
• Loading a video and adding the config.yaml for the placeholder Points layer, and attempting to save, now warns about the missing frame extraction step, and offers a procedure to follow the DLC workflow more closely.
• Fixed several issues around config updates when refreshing by loading the config.yaml
• Attempting to open several labeled data folders at once now warns about only supporting one folder at a time, attempts to load annotations, and skips images/video frames from the new project, rather than ending up in an inconsistent state.

Bug fixes

• Several bugs, edge cases and unsafe data handling have been fixed, and the plugin should be much more stable and less likely to crash or lose data.
• Reduced reliance on specific napari versions, and introduced a compatibility layer for any code that is closer to napari internals
  • Greatly reduced napari internals monkeypatching and API-specific code
• Better handling of moved paths, missing config, broken or partial HDF5 files, and other common issues that may arise when moving data around or working with multiple machines

Code quality improvements

• Nearly complete rewrite of the plugin codebase, with a focus on modularity, readability, and maintainability
• Better separation of operations, vastly expanded testing, better documentation of plugin invariants and assumptions
  • Introduce pydantic models for various data structures, with validation and type checking to ensure data integrity and catch issues earlier
  • Better boundaries around UI updates, I/O operations and layer lifecycle management.
• Introduced a minimal deprecation system
• New debug contexts for monitoring performance and automated log generation

Updated documentation

The newly updated documentation can be found here.

Future directions

The codebase remains in a transitory state, with many improvements but still several areas that could use more consolidated logic, centralization around validated data models, and better abstraction of I/O formats to account for future changes in DLC projects.

As always, we welcome contributions and suggestions for improvements, and will continue to work on improving the plugin in future releases!

Feel free to add to #184 if you have any refactor-specific thoughts or suggestions.

Expect a focus on fixes and improvements shortly after this major update, followed by more features and improvements, such a automated point tracking for faster and more robust labeling.

What's Changed

• Fix _extract_single_frame() hdf key by @maximpavliv in #149
• Upgrade & refactor plugin by @C-Achard in #153
• Improve CI/CD and Compatibility Across Python Versions, Suppress RuntimeWarnings by @maximpavliv in #150
• Expand test coverage (writer and widgets) by @C-Achard in #156
• Add lazy_imread function to read list of images with mismatched extensions by @C-Achard in #154
• Fix & improve frame matching behavior by @C-Achard in #157
• Migrate to pyproject.toml (PEP 518/621) by @C-Achard in #165

New Contributors

• @maximpavliv made their first contribution in #149

Full Changelog: v0.2.1.7...v0.2.1.8