Skip to content

Commit 94cf061

Browse files
MMathisLabMMathisLab
authored
Adding demos to Docs (#3029)
* Update _toc.yml * doc header formatting * headers * polishing * Update config.yaml * Update config.yaml * Update config.yaml
1 parent a310260 commit 94cf061

31 files changed

Lines changed: 236 additions & 215 deletions

‎README.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -67,17 +67,16 @@ DeepLabCut with the PyTorch engine
6767
- [1] [Install PyTorch](https://pytorch.org/get-started/locally/) (**install and then select the desired
6868
CUDA version if you want to use a GPU**): `pip install torch torchvision`.
6969
Or as an example for GPU support (please check pytorch docs to get the perfect version for your CUDA):
70-
```python
71-
# GPU version of pytorch for CUDA 11.3
70+
```bash
7271
conda install pytorch cudatoolkit=11.3 -c pytorch
7372
```
7473
- [2] Then, [install `pytables`](https://www.pytables.org/usersguide/installation.html):
75-
```python
74+
```bash
7675
conda install -c conda-forge pytables==3.8.0
7776
```
7877
- [3] Finally, install `DeepLabCut` (with all functions + the GUI):
79-
```python
80-
pip install --pre "deeplabcut[gui]"`
78+
```bash
79+
pip install --pre "deeplabcut[gui]"
8180
```
8281
or `pip install --pre "deeplabcut"` (headless
8382
version with PyTorch)!
@@ -99,7 +98,7 @@ For a deeper understanding and more resources for you to get started with Python
9998
<img src="https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1609244903687-US1SN063QIFJS4BP4IJD/ke17ZwdGBToddI8pDm48kFG9xAYub2PPnmh56PTVg7gUqsxRUqqbr1mOJYKfIPR7LoDQ9mXPOjoJoqy81S2I8N_N4V1vUb5AoIIIbLZhVYxCRW4BPu10St3TBAUQYVKcAju5e7u9RZJEVbVQPZRu9xb_m-kUO2M3I1IeDqD4l8YcGqu2nZPx1UhKV8wc1ELN/dlc_overview_whitebkgrnd.png?format=2500w" width="95%">
10099
</p>
101100

102-
# [DEMO the code](/examples)
101+
# [DEMO the code](examples/README.md)
103102

104103
🐭 pose tracking of single animals demo [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_DEMO_mouse_openfield.ipynb)
105104

‎_toc.yml‎

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,14 @@ parts:
1010
- file: docs/installation
1111
- file: docs/recipes/installTips
1212
- file: docs/docker
13+
1314
- caption: Main User Guides
1415
chapters:
1516
- file: docs/standardDeepLabCut_UserGuide
1617
- file: docs/maDLC_UserGuide
1718
- file: docs/Overviewof3D
1819
- file: docs/HelperFunctions
20+
1921
- caption: Graphical User Interfaces (GUIs)
2022
chapters:
2123
- file: docs/gui/PROJECT_GUI
@@ -36,16 +38,28 @@ parts:
3638
- file: docs/beginner-guides/labeling
3739
- file: docs/beginner-guides/Training-Evaluation
3840
- file: docs/beginner-guides/video-analysis
39-
- caption: Hardware Tips
41+
- caption: 🚀 Main Demo Notebooks
4042
chapters:
41-
- file: docs/recipes/TechHardware
42-
- caption: DeepLabCut-Live!
43+
- file: examples/COLAB/COLAB_DEMO_SuperAnimal
44+
- file: examples/COLAB/COLAB_DEMO_mouse_openfield
45+
- file: examples/COLAB/COLAB_3miceDemo
46+
- file: examples/COLAB/COLAB_HumanPose_with_RTMPose
47+
48+
49+
50+
- caption: 🚀 Notebooks For Your Data
4351
chapters:
44-
- file: docs/deeplabcutlive
45-
- caption: 🦄 DeepLabCut Model Zoo
52+
- file: examples/COLAB/COLAB_YOURDATA_SuperAnimal
53+
- file: examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis
54+
- file: examples/COLAB/COLAB_YOURDATA_maDLC_TrainNetwork_VideoAnalysis
55+
56+
- caption: 🚀 Special Feature Demos
4657
chapters:
47-
- file: docs/ModelZoo
48-
- file: docs/recipes/UsingModelZooPupil
58+
- file: examples/COLAB/COLAB_transformer_reID
59+
- file: examples/COLAB/COLAB_BUCTD_and_CTD_tracking
60+
- file: examples/JUPYTER/Demo_3D_DeepLabCut
61+
- file: examples/COLAB/COLAB_DLC_ModelZoo
62+
4963
- caption: 🧑‍🍳 Cookbook (detailed helper guides)
5064
chapters:
5165
- file: docs/convert_maDLC
@@ -60,15 +74,30 @@ parts:
6074
- file: docs/recipes/flip_and_rotate
6175
- file: docs/recipes/pose_cfg_file_breakdown
6276
- file: docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook
77+
78+
- caption: Hardware Tips
79+
chapters:
80+
- file: docs/recipes/TechHardware
81+
- caption: DeepLabCut-Live!
82+
chapters:
83+
- file: docs/deeplabcutlive
84+
- caption: 🦄 DeepLabCut Model Zoo
85+
chapters:
86+
- file: docs/ModelZoo
87+
- file: docs/recipes/UsingModelZooPupil
88+
6389
- caption: DeepLabCut Benchmarking
6490
chapters:
6591
- file: docs/benchmark
6692
- file: docs/pytorch/Benchmarking_shuffle_guide
93+
6794
- caption: Mission & Contribute
6895
chapters:
6996
- file: docs/MISSION_AND_VALUES
7097
- file: docs/roadmap
7198
- file: docs/Governance
99+
- file: CONTRIBUTING
100+
72101
- caption: Citations for DeepLabCut
73102
chapters:
74103
- file: docs/citation

‎conda-environments/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
### Please head over to [Installation](/docs/installation.md) to see how to utilize our supplied conda envs!
1+
# Please head over to [Installation](/docs/installation.md) to see how to utilize our supplied conda envs!

‎deeplabcut/gui/tabs/label_frames.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ def label_frames(
6363
├── ...
6464
├── 2025-01-01-experiment7 # folder containing the images to label
6565
└── ...
66+
6667
>>> deeplabcut.label_frames(
6768
>>> "C:\\myproject\\reaching-task\\config.yaml",
6869
>>> "2025-01-01-experiment7",

‎deeplabcut/pose_estimation_pytorch/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ print(deeplabcut.pose_estimation_pytorch.available_models())
4646
print(deeplabcut.pose_estimation_pytorch.available_detectors())
4747
```
4848

49-
#### Model Configuration Files
49+
### Model Configuration Files
5050

5151
Model architectures are built according to a configuration specified in a `yaml` file.
5252
This file (named `pytorch_cfg.yaml`) describes the architecture of the model you want to
@@ -77,7 +77,7 @@ model_cfg = dlc_torch.config.make_pytorch_pose_config(
7777
)
7878
```
7979

80-
#### Adding Models
80+
### Adding Models
8181

8282
If you want to add a novel model, you'll ideally build them from the following
8383
implemented parts:
@@ -94,7 +94,7 @@ You can either use existing classes and only replace some elements, or rewrite
9494
everything you need for your model. We use Model Registries to simplify the process of
9595
adding models.
9696

97-
#### Model Registry
97+
### Model Registry
9898

9999
Registries are created for all model building blocks to make it easy to add new models.
100100
All you need to do is add the decorator `REGISTRY.register_module` to be able to load

‎docker/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ DLC_VERSION=3.0.0 CUDA_VERSION=12.1 deeplabcut-docker bash --gpus all
6262
*Note: Advanced users can also directly download and use the `deeplabcut-docker.sh`
6363
script if this is preferred over a python helper script.*
6464

65-
#### Jupyter Notebooks Running on Remote Servers
65+
### Jupyter Notebooks Running on Remote Servers
6666

6767
Sometimes, we want to run Jupyter Notebooks on remote servers but connect to them
6868
through the browser on our local machine. To do so, port forwarding needs to be used.

‎docs/HelperFunctions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Or perhaps you sort of know the name of the function, but not fully, then you ca
1919

2020
Now, for any of these functions, you type ``deeplabcut.analyze_videos_converth5_to_csv?`` you get:
2121

22-
```python
22+
```text
2323
Signature: deeplabcut.analyze_videos_converth5_to_csv(videopath, videotype='.avi')
2424
Docstring:
2525
By default the output poses (when running analyze_videos) are stored as MultiIndex Pandas Array, which contains the name of the network, body part name, (x, y) label position in pixels, and the likelihood for each frame per body part. These arrays are stored in an efficient Hierarchical Data Format (HDF) in the same directory, where the video is stored. If the flag save_as_csv is set to True, the data is also exported as comma-separated value file. However, if the flag was *not* set, then this function allows the conversion of all h5 files to csv files (without having to analyze the videos again)!

‎docs/ModelZoo.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ To provide the community with easy access to such high performance models across
6868
![SA-TVM](https://user-images.githubusercontent.com/28102185/209957260-c0db72e0-4fdf-434c-8579-34bc5f27f907.png)
6969

7070

71-
#### Practical example: Using SuperAnimal models for inference without training.
71+
### Practical example: Using SuperAnimal models for inference without training.
7272

7373
You can simply call the model and run video inference.
7474

@@ -87,7 +87,7 @@ deeplabcut.video_inference_superanimal([video_path],
8787
```
8888

8989

90-
#### Practical example: Using SuperAnimal model bottom up, considering video/animal size.
90+
### Practical example: Using SuperAnimal model bottom up, considering video/animal size.
9191

9292
In our work we introduced a spatial-pyramid for smartly rescaling images. Imagine if you frames are much larger than what we trained on, it would be hard for the model to find the animal! Here, you can simply guide the model with the `scale_list`:
9393

@@ -107,7 +107,7 @@ deeplabcut.video_inference_superanimal([video_path],
107107
video_adapt = False)
108108
```
109109

110-
#### Practical example: Using transfer learning with superanimal weights.
110+
### Practical example: Using transfer learning with superanimal weights.
111111
In the `deeplabcut.train_network` function, the `superanimal_transfer_learning` option plays a pivotal role. If it's set to __True__, it uses a new decoding layer and allows you to use superanimal weights in any project, no matter the number of keypoints. However, if it's set to __False__, you are doing fine-tuning. So, make sure your dataset has the right number of keypoints.
112112

113113
Specifically:

‎docs/UseOverviewGuide.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ Getting Started: [a video tutorial on navigating the documentation!](https://www
7171
</p>
7272

7373
### Overview of the workflow:
74-
This page contains a list of the essential functions of DeepLabCut as well as demos. There are many optional parameters with each described function, which you can find [here](functionDetails.md). For additional assistance, you can use the [help](UseOverviewGuide.md#help) function to better understand what each function does.
74+
This page contains a list of the essential functions of DeepLabCut as well as demos. There are many optional parameters with each described function. For detailed function documentation, please refer to the main user guides or API documentation. For additional assistance, you can use the [help](UseOverviewGuide.md#help) function to better understand what each function does.
7575

7676
<p align="center">
7777
<img src="https://static1.squarespace.com/static/57f6d51c9f74566f55ecf271/t/5cca272524a69435c3251c40/1556752170424/flowfig.jpg?format=1000w" width=95%>
@@ -81,7 +81,7 @@ This page contains a list of the essential functions of DeepLabCut as well as de
8181
</em>
8282
</p>
8383

84-
You can have as many projects on your computer as you wish. You can have DeepLabCut installed in an [environment](/conda-environments) and always exit and return to this environment to run the code. You just need to point to the correct ``config.yaml`` file to [jump back in](/docs/UseOverviewGuide.md#tips-for-daily-use)! The documentation below will take you through the individual steps.
84+
You can have as many projects on your computer as you wish. You can have DeepLabCut installed in an [environment](../conda-environments/README.md) and always exit and return to this environment to run the code. You just need to point to the correct ``config.yaml`` file to [jump back in](/docs/UseOverviewGuide.md#tips-for-daily-use)! The documentation below will take you through the individual steps.
8585

8686
<p align="center">
8787
<img src= https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1559758477126-B9PU1EFA7L7L1I24Z2EH/ke17ZwdGBToddI8pDm48kH6mtUjqMdETiS6k4kEkCoR7gQa3H78H3Y0txjaiv_0fDoOvxcdMmMKkDsyUqMSsMWxHk725yiiHCCLfrh8O1z5QPOohDIaIeljMHgDF5CVlOqpeNLcJ80NK65_fV7S1UQf4d-kVja3vCG3Q_2S8RPAcZTZ9JxgjXkf3-Un9aT84H3bqxw7fF48mhrq5Ulr0Hg/howtouseDLC2d_3d-01.png?format=500w width="60%">
@@ -100,7 +100,7 @@ We recommend first using **DeepLabCut for a single animal scenario** to understa
100100

101101
We highly recommend using it first in the Project Manager GUI ([Option 3](docs/functionDetails.md#deeplabcut-project-manager-gui)). This will allow you to get used to the additional steps by being walked through the process. Then, you can always use all the functions in your favorite IDE, notebooks, etc.
102102

103-
#### *What scenario do you have?*
103+
### *What scenario do you have?*
104104

105105
- **I have single animal videos:**
106106
- quick start: when you `create_new_project` (and leave the default flag to False in `multianimal=False`). This is the typical work path for many of you.
@@ -141,7 +141,7 @@ with the terminal interface you get the most versatility and options.
141141
[VIDEO TUTORIAL AVAILABLE!](https://www.youtube.com/watch?v=DRT-Cq2vdWs)
142142

143143
We provide Jupyter and COLAB notebooks for using DeepLabCut on both a pre-labeled dataset, and on the end user's
144-
own dataset. See all the demo's [here!](/examples) Please note that GUIs are not easily supported in Jupyter in MacOS, as you need a framework build of python. While it's possible to launch them with a few tweaks, we recommend using the Project Manager GUI or terminal, so please follow the instructions below.
144+
own dataset. See all the demo's [here!](../examples/README.md) Please note that GUIs are not easily supported in Jupyter in MacOS, as you need a framework build of python. While it's possible to launch them with a few tweaks, we recommend using the Project Manager GUI or terminal, so please follow the instructions below.
145145

146146
(using-project-manager-gui)=
147147
## Option 2: using the Project Manager GUI:

‎docs/beginner-guides/beginners-guide.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Now, we are going to install the core dependencies. The way this works is that t
3737

3838
**(1) Install PyTorch**
3939

40-
`PyTorch` is the backend deep-learning language we wrote DLC3 in. To select the right version, head to the [“Install PyTorch”](https://pytorch.org/get-started/locally/) instructions in the official PyTorch Docs. Select your desired PyTorch build, operating system, select conda as your package manager and Python as the language. Select your compute platform (either a CUDA version or CPU only). Then, use the command to install the PyTorch package. Below are a few possible examples:
40+
`PyTorch` is the backend deep-learning language we wrote DLC3 in. To select the right version, head to the ["Install PyTorch"](https://pytorch.org/get-started/locally/) instructions in the official PyTorch Docs. Select your desired PyTorch build, operating system, select conda as your package manager and Python as the language. Select your compute platform (either a CUDA version or CPU only). Then, use the command to install the PyTorch package. Below are a few possible examples:
4141

4242
- **GPU version of pytorch for CUDA 12.4**
4343
```
@@ -88,7 +88,7 @@ When you first launch the GUI, you'll find three primary main options:
8888
2. **Load Project:** Use this to resume your on-hold or past work.
8989
3. **Model Zoo:** Best suited for those who want to explore Model Zoo.
9090

91-
#### Commencing Your Work:
91+
### Commencing Your Work:
9292

9393
- For a first-time or new user, please click on **`Start New Project`**.
9494

0 commit comments

Comments
 (0)