Skip to content

Commit fa89f7f

Browse files
n-poulsenMMathisLab
n-poulsen
and
MMathisLab
authored
Add PyTorch🔥 documentation (#2605)
* added initial pytorch docs * Update _toc.yml * Update user_guide.md * Update architectures.md * Update labelling.md * Update labelling.md * Update codespell.yml * Update README.md * Update installation.md * Delete conda-environments/DEEPLABCUT_M1.yaml * Update DEEPLABCUT.yaml * Update installation.md * Update maDLC_UserGuide.md * Update ModelZoo.md * Update standardDeepLabCut_UserGuide.md * Update standardDeepLabCut_UserGuide.md * Update standardDeepLabCut_UserGuide.md * Update Overviewof3D.md * Update PROJECT_GUI.md * Update UseOverviewGuide.md * Update beginners-guide.md * Update intro.md * Update architectures.md * Update architectures.md * Create course.md - updating and migration from workshop materials * Update _toc.yml * Update manage-project.md * Update beginners-guide.md * Update manage-project.md * Update _toc.yml * Rename labelling.md to labeling.md * Update Training-Evaluation.md * Update video-analysis.md * Update architectures.md * Update architectures.md * Update AUTHORS * Update architectures.md * doc clean up, tested local build * Update beginners-guide.md * Update ModelZoo.md * Update ModelZoo.md * Update ModelZoo.md * Update ModelZoo.md * Update README.md - small resize on homepage * Update ModelZoo.md * Update ModelZoo.md - link update * Update AUTHORS * Update README.md - add badge for python version supported * Update installation.md * Update DEEPLABCUT.yaml - this, for now, will install from branch source (assuming the branch is named "pytorch_dlc" * Update DEEPLABCUT.yaml * Update AUTHORS * fixed typos * Update python-package.yml * Update README.md * Update beginners-guide.md * Update user_guide.md * m1 for tf only * Update README.md --------- Co-authored-by: Mackenzie Mathis <[email protected]> Co-authored-by: Mackenzie Mathis <[email protected]>
1 parent 2d70052 commit fa89f7f

27 files changed

Lines changed: 1159 additions & 462 deletions

‎.github/workflows/codespell.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,5 @@ jobs:
1717
uses: actions/checkout@v3
1818
- name: Codespell
1919
uses: codespell-project/actions-codespell@v1
20+
with:
21+
ignore_words_list: bu,BU,td,TD,ctd,CTD, Wither

‎.github/workflows/python-package.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ jobs:
1414
fail-fast: false
1515
matrix:
1616
os: [ubuntu-latest, macos-13, windows-latest]
17-
python-version: [3.9, "3.10"]
17+
python-version: ["3.10"]
1818
include:
1919
- os: ubuntu-latest
2020
path: ~/.cache/pip

‎AUTHORS‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
DeepLabCut (www.deeplabcut.org) was initially developed by
2-
Alexander & Mackenzie Mathis in collaboration with Matthias Bethge.
2+
Alexander & Mackenzie Mathis in collaboration with Matthias Bethge in 2017.
33
It is actively developed by Alexander & Mackenzie Mathis (steering council and owners).
44

55
DeepLabCut is an open-source tool and has benefited from suggestions and edits by many
@@ -108,13 +108,32 @@ A Mathis, [email protected] | https://github.com/AlexEMG
108108
M Mathis, [email protected] | https://github.com/MMathisLab
109109
J Lauer, [email protected] | https://github.com/jeylau
110110
N Poulsen, [email protected] | https://github.com/n-poulsen
111-
S Ye, https://github.com/yeshaokai
111+
S Schneider, [email protected] | https://github.com/stes
112+
S Ye, [email protected] | https://github.com/yeshaokai
112113

113114
Preprint:
114-
Ye, S., Filippova, A., Lauer, J., Vidal, M., Schneider, S., Qiu, T., Mathis, A., & Mathis, M.W. (2022).
115+
Ye, S., Filippova, A., Lauer, J., Schneider, S., Vidal, M., Qiu, T., Mathis, A., & Mathis, M.W. (2023).
115116
SuperAnimal pretrained pose estimation models for behavioral analysis. https://arxiv.org/abs/2203.07436
116117

117118

118119
############################################################################################################
119-
DeepLabCut 3.0+ additions:
120-
staty tuned, but includes BUCTD!
120+
121+
DeepLabCut 3.0 Toolbox
122+
M Mathis, [email protected] | https://github.com/MMathisLab
123+
A Mathis, [email protected] | https://github.com/AlexEMG
124+
N Poulsen, [email protected] | https://github.com/n-poulsen
125+
S Ye, [email protected] | https://github.com/yeshaokai
126+
A Filippova, [email protected] | https://github.com/nastya236
127+
Q Macé | https://github.com/QuentinJGMace
128+
J Lauer, [email protected] | https://github.com/jeylau
129+
L Stoffl, [email protected] | https://github.com/LucZot
130+
131+
We also greatly thank the 2023 DeepLabCut AI Residents who contributed:
132+
Anna Teruel-Sanchis | https://github.com/anna-teruel
133+
Riza Rae Pineda | https://github.com/rizarae-p
134+
Konrad Danielewski | https://github.com/KonradDanielewski
135+
136+
Products:
137+
PyTorch backend for DeepLabCut
138+
Expanded SuperAnimal capabilities
139+
New model architectures (WIP: stay tuned, but includes BUCTD)

‎README.md‎

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,14 @@
66
</p>
77

88
<p align="center">
9-
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1665060917309-V0YVY2UKVLKSS6O18XDI/MousereachGIF.gif?format=1000w?format=250w" height="150">
9+
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1665060917309-V0YVY2UKVLKSS6O18XDI/MousereachGIF.gif?format=1000w?format=180w" height="150">
1010

11-
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/daed7f16-527f-4150-8bdd-cbb20e267451/cheetah-ezgif.com-video-to-gif-converter.gif?format=250w" height="150">
11+
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/daed7f16-527f-4150-8bdd-cbb20e267451/cheetah-ezgif.com-video-to-gif-converter.gif?format=180w" height="150">
1212

1313

14-
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1534797521117-EIEUED03C68241QZ4KCK/ke17ZwdGBToddI8pDm48kAx9qLOWpcHWRGxWsJQSczRZw-zPPgdn4jUwVcJE1ZvWQUxwkmyExglNqGp0IvTJZUJFbgE-7XRK3dMEBRBhUpwdr4GYy30vFzf31Oe7KAPZKkqgaiEgc5jBNdhZmDPlzxdkDSclo6ofuXZm6YCEhUo/MATHIS_2018_fly.gif?format=250w" height="150">
14+
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1534797521117-EIEUED03C68241QZ4KCK/ke17ZwdGBToddI8pDm48kAx9qLOWpcHWRGxWsJQSczRZw-zPPgdn4jUwVcJE1ZvWQUxwkmyExglNqGp0IvTJZUJFbgE-7XRK3dMEBRBhUpwdr4GYy30vFzf31Oe7KAPZKkqgaiEgc5jBNdhZmDPlzxdkDSclo6ofuXZm6YCEhUo/MATHIS_2018_fly.gif?format=180w" height="150">
1515

16-
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1619609897110-TKSTWKEM6HTGXID9D489/ke17ZwdGBToddI8pDm48kAvjv6tW_eojYQmNU0ncbllZw-zPPgdn4jUwVcJE1ZvWEtT5uBSRWt4vQZAgTJucoTqqXjS3CfNDSuuf31e0tVHBSTXHtjUKlhRtWJ1Vo6l1B2bxJtByvWSjL6Vz3amc5yb8BodarTVrzIWCp72ioWw/triMouseDLC.gif?format=250w" height="150">
16+
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1619609897110-TKSTWKEM6HTGXID9D489/ke17ZwdGBToddI8pDm48kAvjv6tW_eojYQmNU0ncbllZw-zPPgdn4jUwVcJE1ZvWEtT5uBSRWt4vQZAgTJucoTqqXjS3CfNDSuuf31e0tVHBSTXHtjUKlhRtWJ1Vo6l1B2bxJtByvWSjL6Vz3amc5yb8BodarTVrzIWCp72ioWw/triMouseDLC.gif?format=180w" height="150">
1717

1818

1919

@@ -34,6 +34,7 @@
3434
[👩🏾‍💻👨‍💻 DeepLabCut AI Residency](https://www.deeplabcutairesidency.org/)
3535

3636

37+
![Vesion](https://img.shields.io/badge/python_version-3.10-purple)
3738
[![Downloads](https://pepy.tech/badge/deeplabcut)](https://pepy.tech/project/deeplabcut)
3839
[![Downloads](https://pepy.tech/badge/deeplabcut/month)](https://pepy.tech/project/deeplabcut)
3940
[![PyPI version](https://badge.fury.io/py/deeplabcut.svg)](https://badge.fury.io/py/deeplabcut)
@@ -58,8 +59,15 @@
5859

5960
# [Installation: how to install DeepLabCut](https://deeplabcut.github.io/DeepLabCut/docs/installation.html)
6061

61-
Very quick start: `pip install "deeplabcut[gui,tf]"` that includes all functions plus GUIs, or `pip install deeplabcut[tf]` (headless version with PyTorch and TensorFlow).
62-
* We recommend using our conda file, see [here](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/README.md) or the new [`deeplabcut-docker` package](https://github.com/DeepLabCut/DeepLabCut/tree/main/docker). Please note that currently we support Python 3.9 (see conda files for guidance).
62+
Please click the link above for all the information you need to get started! Please note that currently we support only Python 3.10+ (see conda files for guidance).
63+
64+
Developers Stable Release:
65+
- Very quick start: You need to have TensorFlow installed (up to v2.10 supported across platforms) `pip install "deeplabcut[gui,tf]"` that includes all functions plus GUIs, or `pip install deeplabcut[tf]` (headless version with PyTorch and TensorFlow).
66+
67+
Developers Alpha Release:
68+
- We also have an alpha release of PyTorch DeepLabCut available! [Please see here for instructions and information](https://github.com/DeepLabCut/DeepLabCut/blob/pytorch_docs/docs/pytorch/user_guide.md).
69+
70+
We recommend using our conda file, see [here](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/README.md) or the new [`deeplabcut-docker` package](https://github.com/DeepLabCut/DeepLabCut/tree/main/docker).
6371

6472
# [Documentation: The DeepLabCut Process](https://deeplabcut.github.io/DeepLabCut)
6573

@@ -209,6 +217,8 @@ SuperAnimal models are provided for research use only (non-commercial use).
209217

210218
- For all versions, please see [here](https://github.com/DeepLabCut/DeepLabCut/releases).
211219

220+
VERSION 3.0: A whole new experience with PyTorch🔥. While the high-level API remains the same, the backend and developer friendliness have greatly improved, along with performance gains!
221+
212222
VERSION 2.3: Model Zoo SuperAnimals, and a whole new GUI experience.
213223

214224
VERSION 2.2: Multi-animal pose estimation, identification, and tracking with DeepLabCut is supported (as well as single-animal projects).
@@ -220,6 +230,8 @@ VERSION 1.0: The initial, Nature Neuroscience version of [DeepLabCut](https://ww
220230

221231
# News (and in the news):
222232

233+
:purple_heart: We released a major update, moving from 2.x --> 3.x with the backend change to PyTorch
234+
223235
:purple_heart: The DeepLabCut Model Zoo launches SuperAnimals, see more [here](http://www.mackenziemathislab.org/dlc-modelzoo/).
224236

225237
:purple_heart: **DeepLabCut supports multi-animal pose estimation!** maDLC is out of beta/rc mode and beta is deprecated, thanks to the testers out there for feedback! Your labeled data will be backwards compatible, but not all other steps. Please see the [new `2.2+` releases](https://github.com/DeepLabCut/DeepLabCut/releases) for what's new & how to install it, please see our new [paper, Lauer et al 2022](https://www.nature.com/articles/s41592-022-01443-0), and the [new docs]( https://deeplabcut.github.io/DeepLabCut) on how to use it!
@@ -228,6 +240,9 @@ VERSION 1.0: The initial, Nature Neuroscience version of [DeepLabCut](https://ww
228240

229241
:purple_heart: We have a **real-time** package available! http://DLClive.deeplabcut.org
230242

243+
244+
- June 2024: Our second DLC paper ['Using DeepLabCut for 3D markerless pose estimation across species and behaviors'](https://www.nature.com/articles/s41596-019-0176-0) in Nature Protocols has surpassed 1,000 Google Scholar citations!
245+
- May 2024: DeepLabCut was featured in Nature: ['DeepLabCut: the motion-tracking tool that went viral'](https://www.nature.com/articles/d41586-024-01474-x)
231246
- January 2024: Our original paper ['DeepLabCut: markerless pose estimation of user-defined body parts with deep learning'](https://www.nature.com/articles/s41593-018-0209-y) in Nature Neuroscience has surpassed 3,000 Google Scholar citations!
232247
- December 2023: DeepLabCut hit 600,000 downloads!
233248
- October 2023: DeepLabCut celebrates a milestone with 4,000 🌟 in Github!

‎_toc.yml‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ parts:
44
- caption: Getting Started
55
chapters:
66
- file: docs/UseOverviewGuide
7+
- file: docs/course
78
- caption: Installation
89
chapters:
910
- file: docs/installation
@@ -17,12 +18,24 @@ parts:
1718
- file: docs/HelperFunctions
1819
- caption: Graphical User Interfaces (GUIs)
1920
chapters:
20-
- file: docs/PROJECT_GUI
21-
- file: docs/napari_GUI
21+
- file: docs/gui/PROJECT_GUI
22+
- file: docs/gui/napari_GUI
23+
- caption: DLC3 PyTorch Specific Docs
24+
chapters:
25+
- file: docs/pytorch/user_guide.md
26+
- file: docs/pytorch/pytorch_config.md
27+
- file: docs/pytorch/architectures.md
2228
- caption: Quick Start Tutorials
2329
chapters:
24-
- file: docs/single_animal_quick_guide
25-
- file: docs/tutorial_maDLC
30+
- file: docs/quick-start/single_animal_quick_guide
31+
- file: docs/quick-start/tutorial_maDLC
32+
- caption: Beginner's Guide to DeepLabCut
33+
chapters:
34+
- file: docs/beginner-guides/beginners-guide
35+
- file: docs/beginner-guides/manage-project
36+
- file: docs/beginner-guides/labeling
37+
- file: docs/beginner-guides/Training-Evaluation
38+
- file: docs/beginner-guides/video-analysis
2639
- caption: Hardware Tips
2740
chapters:
2841
- file: docs/recipes/TechHardware
@@ -34,7 +47,7 @@ parts:
3447
- file: docs/ModelZoo
3548
- file: docs/recipes/UsingModelZooPupil
3649
- file: docs/recipes/MegaDetectorDLCLive
37-
- caption: Cookbook
50+
- caption: Cookbook (detailed helper guides)
3851
chapters:
3952
- file: docs/tutorial
4053
- file: docs/convert_maDLC
@@ -48,13 +61,6 @@ parts:
4861
- file: docs/recipes/flip_and_rotate
4962
- file: docs/recipes/pose_cfg_file_breakdown
5063
- file: docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook
51-
- caption: Beginner's Guide to DeepLabCut in the GUI
52-
chapters:
53-
- file: docs/beginners-guide
54-
- file: docs/manage-project
55-
- file: docs/labelling
56-
- file: docs/Training-Evaluation
57-
- file: docs/video-analysis
5864
- caption: DeepLabCut Benchmark
5965
chapters:
6066
- file: docs/benchmark

‎conda-environments/DEEPLABCUT.yaml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# DEEPLABCUT.yaml
22

3-
#DeepLabCut2.0 Toolbox (deeplabcut.org)
3+
#DeepLabCut Toolbox (deeplabcut.org)
44
#© A. & M.W. Mathis Labs
55
#https://github.com/DeepLabCut/DeepLabCut
66
#Please see AUTHORS for contributors.
77

8-
#https://github.com/DeepLabCut/DeepLabCut/blob/master/AUTHORS
8+
#https://github.com/DeepLabCut/DeepLabCut/blob/main/AUTHORS
99
#Licensed under GNU Lesser General Public License v3.0
1010
#
1111
# DeepLabCut environment
@@ -29,4 +29,4 @@ dependencies:
2929
- ffmpeg
3030
- pytables==3.8.0
3131
- pip:
32-
- "deeplabcut[gui,tf]"
32+
- "git+https://github.com/DeepLabCut/DeepLabCut.git@pytorch_dlc#egg=deeplabcut[gui,modelzoo,wandb]"

0 commit comments

Comments
 (0)