diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 155b218b1..764dfe563 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -25,7 +25,7 @@ body: attributes: label: DeepLabCut version description: What version of DLC are you using? Please check with `import deeplabcut`, `deeplabcut.__version__` - placeholder: 3.0.0rc14 + placeholder: 3.0.0 validations: required: true - type: dropdown diff --git a/changelog/3_0_0/images/buctd_benchmarks.png b/changelog/3_0_0/images/buctd_benchmarks.png new file mode 100644 index 000000000..127b1d4f1 Binary files /dev/null and b/changelog/3_0_0/images/buctd_benchmarks.png differ diff --git a/changelog/3_0_0/images/openfield_benchmark_pr2613.png b/changelog/3_0_0/images/openfield_benchmark_pr2613.png new file mode 100644 index 000000000..0ebedddb4 Binary files /dev/null and b/changelog/3_0_0/images/openfield_benchmark_pr2613.png differ diff --git a/changelog/3_0_0/images/speed_tensorflow.avif b/changelog/3_0_0/images/speed_tensorflow.avif new file mode 100644 index 000000000..43dcf7444 Binary files /dev/null and b/changelog/3_0_0/images/speed_tensorflow.avif differ diff --git a/changelog/3_0_0/v3_0_0.md b/changelog/3_0_0/v3_0_0.md new file mode 100644 index 000000000..994a65958 --- /dev/null +++ b/changelog/3_0_0/v3_0_0.md @@ -0,0 +1,158 @@ +# DeepLabCut 3.0: familiar workflows, modern foundations, better performance + +DeepLabCut 3.0 introduces a PyTorch-first training and inference stack while keeping the core DeepLabCut workflow familiar. +Projects still follow the same labeling, training, evaluation, and video-analysis pipeline used throughout the 2.x series, but the underlying engine has been substantially modernized. + +For users who have already been following the release candidates, many of these changes will already feel familiar. +DeepLabCut 3.0 consolidates these incremental changes into a stable release. + +## Increased model performance and speed + + + + + + + + +
Benchmark tableOpenfield benchmark results
Pose estimation performance of the 3.0 PyTorch models compared against previous TensorFlow models on the DeepLabCut Openfield dataset (see PR #2613); RMSE: root mean squared error. *Values from Mathis et al. 2018.
+ + + + + + + + + +
Trimice datasetSpeed comparison: PyTorch vs TensorFlow
Speed of the current PyTorch implementation (ResNet50) compared to the TensorFlow implementation. Results were obtained using a NVIDIA GeForce RTX 2080 Ti with CUDA 12.2 on the DeepLabCut Trimice dataset.
+ + + + + + + + +
BUCTD benchmarks
Comparison of the new BUCTD model architectures with DLCRNet and DEKR on the Marmoset, Fish and Trimice dataset. From Zhou et al., ICCV 2023.
+ +## The journey to 3.0 + +A quick recap of some of the major milestones leading to this release: + +- #2613 - Full initial PyTorch backend implementation +- #2952 - New bottom-up conditional top-down (BUCTD) model architecture +- #2795 - New RTMPose top-down architecture +- #2868 - Updated notebooks and Colab examples for PyTorch workflows +- #2804 - PyTorch model export + +And more, find the full PR reference [on GitHub](https://github.com/DeepLabCut/DeepLabCut/pulls?page=1&q=is%3Apr+label%3ADLC3.0%F0%9F%94%A5)! + +## Notable features in 3.0.0 + +### PyTorch-first, TensorFlow-compatible + +DeepLabCut 3.0 adds a new PyTorch backend while retaining TensorFlow support for legacy workflows. +Project management remains the same and labeled datasets remain compatible. +PyTorch models can be trained alongside previous TensorFlow models on the same train/test splits for direct benchmarking and comparison. + + +### Expanded architecture support + +DeepLabCut 3.0 significantly broadens the supported model ecosystem beyond the classic ResNet-based workflows. The PyTorch stack includes: + +- ResNet and HRNet backbones +- Bottom-up multi-animal approaches such as DEKR and PAF/DLCRNet variants +- Top-down detector-plus-pose pipelines including RTMPose +- Hybrid architectures such as BUCTD and CTD variants +- SuperAnimal-related pretrained workflows + +The documentation now includes dedicated [architecture guides](https://deeplabcut.github.io/DeepLabCut/docs/pytorch/architectures.html) to help users choose models based on scene complexity and experimental needs. + +### Flexible PyTorch training configuration + +The PyTorch engine introduces a modern training stack with expanded augmentation options, training schedules, device management, and model architectures. For each training run, the settings are stored in a `pytorch_config.yaml`, enabling easy reproducibility. + +### Improved interoperability + +The new PyTorch data pipeline introduces loaders for both standard DeepLabCut projects and COCO-style datasets, making it easier to integrate DeepLabCut with broader computer-vision workflows and external annotation formats. + +### Model Zoo and SuperAnimal workflows + +DeepLabCut 3.0 continues to expand the Model Zoo and SuperAnimal ecosystem, making pretrained models and transfer learning more accessible. +Colab notebooks and updated GUI tooling make it easier to experiment with modern architectures without extensive setup. (see the [documentation](https://deeplabcut.github.io/DeepLabCut/README.html)) + +### Modernized installation and packaging + +The project has been moved to a newer packaging system, and is now based around pyproject.toml. This enables the use of modern package-managers & dependency resolvers, such as `uv` or `pdm`. +Users can still install only the components they require, be it GUI support, TensorFlow compatibility, ModelZoo features, and optional experimental integrations. + +### Labeling GUI + +DeepLabCut 3.0 is shipped with a new release of the napari-deeplabcut plugin. Our napari-based labeling GUI has undergone a major internal re-write and modernization: while preserving familiar UI and the DeepLabCut workflow, the update substantially improves stability, data handling, usability, visualization, and annotation workflows, now with automated point tracking for faster labeling. See the [release notes](https://github.com/DeepLabCut/napari-deeplabcut/releases) to find out about all improvements. + +### Upcoming: refreshed documentation + +We have updated and streamlined the documentation, with a focus on clarity and up-to-date information in core areas (installation, getting started guides, and more). +Expect the documentation to continue evolving soon after the release! + +## A major transition + +The jump from the final DeepLabCut 2.x releases to the current codebase is best understood as a transition to more recent Python & deep learning ecosystems rather than a routine update. +Taken together, the PyTorch backend, broader architecture support, ModelZoo integration, packaging modernization, updated labeling GUI, and documentation improvements represent a major evolution of DeepLabCut, which we are happy to release as 3.0. + + +## Closing thoughts + +We hope you enjoy this new version, and we aim to keep sharing many exciting improvements in the future in all areas, be it performance and speed, codebase quality improvements, foundation models integration, user experience and documentation. + +--- +## Changelog since 3.0.0rc14 + +- Add up-to-date uv.lock (#3242) +- Remove unnecessary imports (#3224) +- Add custom styling options for docs (custom.css) (#3207) +- Add internal helper for batched modelzoo inference from in-memory arrays (inference runner) (#3222) +- Implement intelligent test selection in CI (#3046) +- Revamp CONTRIBUTING.md (#3241) +- Update FMPose3D modelzoo integration (#3221) +- Add automated docs & notebooks freshness + normalization checks (#3228) +- Install from PyPI pre-release; add both-backends (#3238) +- Apply linting to entire codebase & add CI workflow to check linting (#3216) +- Bump requests from 2.32.5 to 2.33.0 (#3259) +- Refactor Analyze Videos tab (#3268) +- Consolidate test workflow infrastructure in CI (#3254) +- Move protobuf requirement to pyproject.toml (#3235) +- Use pinned ffmpeg version in CI (#3276) +- Docs versioning: Add glob support, better validation and reporting (#3278) +- Bump cryptography from 46.0.5 to 46.0.7 (#3277) +- Fix failing local Windows tests due to ruamel parsing (#3275) +- Update & de-duplicate skeleton builder (#3258) +- Bump pygments from 2.19.2 to 2.20.0 (#3262) +- update conda yaml: install pyside6 via conda instead of pip (#3253) +- Bump pyasn1 from 0.6.2 to 0.6.3 (#3249) +- Fix SuperAnimal / pretrained load for RTMPose: implement convert_weights on RTMCCHead (#3270) +- Use async update check in GUI (#3234) +- Update napari-DLC docs for refactor (#3280) +- Refactor/predict multianimal (#3220) +- Fix incorrect MultiLevel construction in outlier_frames.compute_deviations (#3247) +- Bump pillow from 12.1.1 to 12.2.0 (#3283) +- Bump pytest from 9.0.2 to 9.0.3 (#3284) +- CircleCI: disable hugginface xet (#3316) +- Update and diversify TensorFlow optional installations. (#3292) +- Bump urllib3 from 2.6.3 to 2.7.0 (#3325) +- Bump gitpython from 3.1.47 to 3.1.50 (#3322) +- make GenerativeSampler visibility-aware (#3305) +- Add isatty method to StreamWriter + eval GUI fix (#3314) +- Add conditional replacement of `@torch.inference_mode` for inference on AMD DirectML GPUs (#3295) +- Robustness fix: Annotation file not dropping likelihood column if present from machine labels (#3323) +- Remove trailing comma in models_to_framework.json (#3330) +- update `list_videos_in_folder` (#3303) +- Improve `TrainingDatasetMetadata` and `get_shuffle_engine` for incomplete projects (#3313) +- update RTMPose `SimCCPredictor`: expose `apply_softmax` and fix visibility thresholding (#3306) +- GUI: Add "Generate debug log" action (#3328) +- [Docker 1] Simplify and modernize Dockerfile (#3290) +- [Docker 2] Update deeplabcut-docker package (#3291) +- Add additional drop_likelihood_columns guards (#3333) +- Resolve inconsistent parameter names via aliasing + deprecationwarning (#3332) +- bump dlclibrary (v0.0.12) and napari-deeplabcut (v3.1.0) (#3338) diff --git a/deeplabcut/version.py b/deeplabcut/version.py index 150be4aa2..08022ce8d 100644 --- a/deeplabcut/version.py +++ b/deeplabcut/version.py @@ -9,5 +9,5 @@ # Licensed under GNU Lesser General Public License v3.0 # -__version__ = "3.0.0rc14" +__version__ = "3.0.0" VERSION = __version__ diff --git a/examples/test.sh b/examples/test.sh index c26419917..b9be0a511 100755 --- a/examples/test.sh +++ b/examples/test.sh @@ -6,7 +6,7 @@ rm -r OUT cd .. pip uninstall deeplabcut python3 setup.py sdist bdist_wheel -pip install dist/deeplabcut-3.0.0rc14-none-any.whl +pip install dist/deeplabcut-3.0.0-none-any.whl cd examples diff --git a/pyproject.toml b/pyproject.toml index 0dd1d9e8c..a578f17dd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ requires = [ "setuptools>=61" ] [project] name = "deeplabcut" -version = "3.0.0rc14" +version = "3.0.0" description = "Markerless pose-estimation of user-defined features with deep learning" readme = { file = "README.md", content-type = "text/markdown" } keywords = [ diff --git a/reinstall.sh b/reinstall.sh index 1483261a6..ec60dc6a8 100755 --- a/reinstall.sh +++ b/reinstall.sh @@ -1,4 +1,4 @@ pip uninstall deeplabcut rm -rf dist/ build/ *.egg-info python3 setup.py sdist bdist_wheel -pip install dist/deeplabcut-3.0.0rc14-py3-none-any.whl +pip install dist/deeplabcut-3.0.0-py3-none-any.whl diff --git a/uv.lock b/uv.lock index ac4b09485..b3d096b3f 100644 --- a/uv.lock +++ b/uv.lock @@ -1183,7 +1183,7 @@ wheels = [ [[package]] name = "deeplabcut" -version = "3.0.0rc14" +version = "3.0.0" source = { editable = "." } dependencies = [ { name = "albumentations" },