You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
DeepLabStream is a python based multi-purpose tool that enables the realtime tracking of animals and manipulation of experiments.
7
14
Our toolbox is adapted from the previously published [DeepLabCut](https://github.com/AlexEMG/DeepLabCut) ([Mathis et al., 2018](https://www.nature.com/articles/s41593-018-0209-y)) and expands on its core capabilities.
@@ -10,12 +17,17 @@ DeepLabStreams core feature is the real-time analysis using any type of camera-b
10
17
11
18
12
19
### Quick Reference:
20
+
21
+
### Read the preprint: [Schweihoff et al, 2019](https://doi.org/10.1101/2019.12.20.884478).
### 2. [Introduction to experiments](https://github.com/SchwarzNeuroconLab/DeepLabStream/wiki/Introduction)
15
26
16
-
### 2. [Introduction to experiments](docs/Introduction.md)
27
+
### 3. [Design your first experiment](https://github.com/SchwarzNeuroconLab/DeepLabStream/wiki/My-first-experiment)
28
+
29
+
### 4. [Adapting an existing experiment to your own needs](https://github.com/SchwarzNeuroconLab/DeepLabStream/wiki/Adapting-an-existing-experiment-to-your-own-needs)
17
30
18
-
### 3. [Design your first experiment](docs/MyFirstExperiment.md)
19
31
20
32
### How does this work
21
33
@@ -26,44 +38,6 @@ and to end, prolong or modify parts of experimental protocol.
26
38
27
39
28
40
29
-
## Installation
30
-
31
-
See [Installation](utils/Installation.md).
32
-
33
-
## Testing
34
-
35
-
To properly test your DeepLabStream installation, we included a testing script that you can run in three different modes. ```DeepLabStream.py``` allows you to test your cameras, your DeepLabcut installation,
36
-
and to benchmark your DeepLabStream performance.
37
-
38
-
1. Run the following command to test your cameras:
39
-
```bash
40
-
python DeepLabStream.py
41
-
```
42
-
43
-
2. Next, you can test how your DeepLabCut installation behaves and if you did correctly set the DeepLabCut path in the config:
44
-
```bash
45
-
python DeepLabStream.py --dlc-enabled
46
-
```
47
-
48
-
3. And finally you can benchmark your system automatically:
The stream would run until it gets 3000 analyzed frames (you can always stop it manually at any point, just press 'Q' while the stream window is in focus).
53
-
Then it will show you a detailed statistic of the overall performance timings, analysis timings, percentage of frames where it did lose tracking and your average FPS.
54
-
55
-
#### Recording testing
56
-
57
-
Additionally, you can test and see the results of the build-in video recorder. Run the following command to test it:
58
-
```bash
59
-
python DeepLabStream.py --recording-enabled
60
-
```
61
-
62
-
This will record the videofeed from the camera to your `OUTPUT_DIRECTORY`. You can also add this flag to any of the previously mentioned tests to check performance with recording enabled.
63
-
64
-
Important note: **recording will always save only "raw" video, without analysis, with framerate as close to specified as possible**
65
-
66
-
67
41
## Usage
68
42
69
43
### How to use DeepLabStream
@@ -109,37 +83,18 @@ As a visual representation of this event, the border of the ROI will turn green.
109
83
110
84
All experimental output will be stored to a .csv file for easy postprocessing.
111
85
112
-
Look at the [Introduction to experiments](docs/Introduction.md) to get an idea how to design your own experiment in DeepLabStream.
86
+
Look at the [Introduction to experiments](https://github.com/SchwarzNeuroconLab/DeepLabStream/wiki/Introduction) to get an idea how to design your own experiment in DeepLabStream or learn how to adapt one of the already published experiments at [Adapting an existing experiment](https://github.com/SchwarzNeuroconLab/DeepLabStream/wiki/Adapting-an-existing-experiment-to-your-own-needs).
113
87
114
88
### Known issues
115
89
116
-
#### Error when stopping the analysis:
117
-
```
118
-
BrokenPipeError: [Errno 32] Broken pipe
119
-
```
90
+
If you encounter any issues or errors, you can check out the wiki article ([Help there is an error!](https://github.com/SchwarzNeuroconLab/DeepLabStream/wiki/Help-there-is-an-error!)). If your issue is not listed yet, please refer to the issues and either submit a new issue or find a reported issue (which might be already solved) there. Thank you!
120
91
121
-
This is an `multiprocessing.Queue` closing error, when some items are still in the Queue.
122
-
This should not affect the app in any meaningful way.
123
-
124
-
#### Tensorflow not releasing GPU memory
125
-
Sometimes Tensorflow session will not release all allocated GPU memory when you stop the analysis. This will result in OOM (out of memory) error.
126
-
See more on that issue on [tensorflow github](https://github.com/tensorflow/tensorflow/issues/19731)
127
-
128
-
The error itself looks like this:
129
-
```
130
-
2020-02-10 13:44:49.972600: E tensorflow/stream_executor/cuda/cuda_driver.cc:806] failed to allocate 635,29M (666146048 bytes) from device: CUDA_ERROR_OUT_OF_MEMORY: out of memory
131
-
```
132
-
133
-
The issue can be resolved by closing and opening the app. If not, manually kill all python processes
134
-
```
135
-
killall -9 python
136
-
```
137
92
## References:
138
93
139
94
If you use this code or data please cite [Schweihoff et al, 2019](https://doi.org/10.1101/2019.12.20.884478).
140
95
141
96
## License
142
-
This project is licensed under the GNU Lesser General Public License v3.0. Note that the software is provided "as is", without warranty of any kind, express or implied.
97
+
This project is licensed under the GNU General Public License v3.0. Note that the software is provided "as is", without warranty of any kind, expressed or implied.
0 commit comments