Skip to content

Commit d28c3da

Browse files
C-AchardC-Achard
committed
Add documentation site skeleton
Add initial documentation site for the DeepLabCut Live GUI: new MyST/Jupyter Book config (myst.yml, _toc.yml), site assets (logo, custom.css), top-level docs (index.md, quickstart/install.md), and a build log (_build/logs/myst.build.json). Rename existing camera docs into docs/cameras_backends/ to better organize backends. Also add a "docs" extra to pyproject.toml (jupyter-book>=2.0) to support building the docs.
1 parent 791b021 commit d28c3da

File tree

10 files changed

+409
-0
lines changed

10 files changed

+409
-0
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,3 +113,6 @@ venv.bak/
113113
!dlclivegui/config.py
114114
# uv package files
115115
uv.lock
116+
117+
# Built jupyter-book
118+
docs/_build/

‎docs/_static/custom.css‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
/* ------------- Header background + text ------------- */
2+
:root {
3+
--dlc-header-bg: rgba(149, 72, 156, 0.85); /* #de6be8 with alpha */
4+
}
5+
html.dark {
6+
--dlc-header-bg: rgba(69, 83, 100, 0.85); /* #455364 with alpha */
7+
}
8+
/* Header background (frosted) */
9+
.myst-top-nav {
10+
background-color: var(--dlc-header-bg) !important;
11+
backdrop-filter: blur(8px) !important;
12+
-webkit-backdrop-filter: blur(8px) !important;
13+
}
14+
15+
/* Dark mode (Tailwind-style: .dark on an ancestor is common in MyST themes) */
16+
html.dark .myst-top-nav {
17+
background-color: var(--dlc-header-bg) !important;
18+
backdrop-filter: blur(8px) !important;
19+
-webkit-backdrop-filter: blur(8px) !important;
20+
}
21+
22+
/* Make header links inherit header text color */
23+
.myst-top-nav a {
24+
color: inherit !important;
25+
}
26+
27+
28+
29+
/* 1) Keep header as-is; only fix logo container */
30+
html.dark .myst-top-nav nav a > div {
31+
background: transparent !important;
32+
box-shadow: none !important;
33+
}
34+
35+
/* Optional: also remove padding/border-radius if the wrapper looks like a badge */
36+
html.dark .myst-top-nav nav a > div {
37+
border: 0 !important;
38+
}
39+
40+
41+
/* =========================================================
42+
MyST code blocks (global)
43+
Targets the exact structure you pasted:
44+
div.myst-code > pre.myst-code-body.hljs > code.language-*
45+
========================================================= */
46+
47+
:root {
48+
/* Light mode */
49+
--dlc-code-bg: rgba(149, 72, 156, 0.05);
50+
--dlc-code-fg: #111827;
51+
--dlc-code-border: #e5e7eb;
52+
--dlc-code-shadow: 0 1px 3px rgba(0,0,0,0.08);
53+
54+
/* Accents */
55+
--dlc-code-accent: #95489c;
56+
--dlc-code-radius: 12px;
57+
}
58+
59+
html.dark {
60+
/* Dark mode */
61+
--dlc-code-bg: rgba(69, 83, 100, 0.45);
62+
--dlc-code-fg: #e5e7eb;
63+
--dlc-code-border: rgba(229,231,235,0.14);
64+
--dlc-code-shadow: 0 8px 30px rgba(0,0,0,0.45);
65+
66+
--dlc-code-accent: #c77dd1;
67+
}
68+
69+
/* The outer wrapper (controls spacing + frame) */
70+
.myst-code {
71+
border: 1px solid var(--dlc-code-border);
72+
border-radius: var(--dlc-code-radius);
73+
background: var(--dlc-code-bg);
74+
box-shadow: var(--dlc-code-shadow);
75+
overflow: hidden; /* makes rounded corners clip */
76+
}
77+
78+
/* The <pre> element you showed: pre.myst-code-body.hljs */
79+
.myst-code-body.hljs {
80+
background-color: var(--dlc-code-bg) !important; /* overrides inline style "unset" */
81+
color: var(--dlc-code-fg) !important;
82+
83+
margin: 0 !important;
84+
padding: 0.9rem 1rem !important;
85+
line-height: 1.45;
86+
tab-size: 4;
87+
88+
/* Horizontal scroll for long lines */
89+
overflow: auto;
90+
}
91+
92+
/* Avoid any extra styling on the <code> tag */
93+
.myst-code-body code {
94+
background: transparent !important;
95+
color: inherit !important;
96+
padding: 0 !important;
97+
}
98+
99+
/* Base text inside code blocks */
100+
/* .myst-code-body.hljs {
101+
color: var(--dlc-code-fg) !important;
102+
} */
103+
104+
/* Token colors (HLJS) */
105+
/* .myst-code-body .hljs-built_in,
106+
.myst-code-body .hljs-keyword,
107+
.myst-code-body .hljs-selector-tag,
108+
.myst-code-body .hljs-literal {
109+
color: #95489c;
110+
}
111+
112+
113+
.myst-code-body .hljs-string,
114+
.myst-code-body .hljs-title,
115+
.myst-code-body .hljs-attr,
116+
.myst-code-body .hljs-attribute {
117+
color: #059669;
118+
}
119+
120+
121+
122+
.myst-code-body .hljs-number,
123+
.myst-code-body .hljs-symbol,
124+
.myst-code-body .hljs-bullet {
125+
color: #f59e0b;
126+
}
127+
128+
.myst-code-body .hljs-comment,
129+
.myst-code-body .hljs-quote {
130+
color: rgba(100,116,139,0.85);
131+
font-style: italic;
132+
}
133+
134+
html.dark .myst-code-body .hljs-comment,
135+
html.dark .myst-code-body .hljs-quote {
136+
color: rgba(148,163,184,0.75);
137+
}
138+
*/

‎docs/_static/images/logo.png‎

159 KB
Loading

‎docs/_toc.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
format: jb-book
2+
root: index
3+
4+
parts:
5+
- caption: Quickstart
6+
chapters:
7+
- file: quickstart/install
8+
# - file: quickstart/camera_setup
9+
# - file: quickstart/inference_setup
10+
# - file: quickstart/first_run
11+
12+
# - caption: User Guide
13+
# chapters:
14+
# - file: user_guide/overview
15+
16+
# - file: user_guide/cameras/index
17+
# sections:
18+
# - file: user_guide/cameras/configure_dialog
19+
# - file: user_guide/cameras/supported_backends
20+
21+
# - file: user_guide/inference/index
22+
# sections:
23+
# - file: user_guide/inference/model_selection
24+
# - file: user_guide/inference/inference_camera
25+
# - file: user_guide/inference/processor_plugins
26+
27+
# - file: user_guide/visualization/index
28+
# sections:
29+
# - file: user_guide/visualization/preview_and_overlays
30+
31+
# - file: user_guide/recording/index
32+
# sections:
33+
# - file: user_guide/recording/output_structure
34+
35+
# - caption: Limitations
36+
# chapters:
37+
# - file: limitations/current_limitations

docs/aravis_backend.md renamed to docs/cameras_backends/aravis_backend.md

File renamed without changes.

docs/camera_support.md renamed to docs/cameras_backends/camera_support.md

File renamed without changes.

‎docs/index.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# DeepLabCut Live GUI
2+
3+
A graphical application for **real-time pose estimation with DeepLabCut** using one or more cameras.
4+
5+
This GUI is designed for **scientists and experimenters** who want to preview, run inference, and record synchronized video with pose overlays—without writing code.
6+
7+
## Table of Contents
8+
9+
:::{toc}
10+
:::
11+
12+
---
13+
14+
## What this software does
15+
16+
- **Live camera preview** from one or multiple cameras
17+
- **Real-time pose inference** using DeepLabCut Live models
18+
- **Multi-camera support** with tiled display
19+
- **Video recording** (raw or with pose and bounding-box overlays)
20+
- **Session-based data organization** with reproducible naming
21+
- **Optional processor plugins** to extend behavior (e.g. remote control, triggers)
22+
23+
The application is built with **PySide6 (Qt)** and is intended for interactive experimental use rather than offline batch processing.
24+
25+
---
26+
27+
## Typical workflow
28+
29+
1. **Install** the application and required camera backends
30+
2. **Configure cameras** (single or multi-camera)
31+
3. **Select a DeepLabCut Live model**
32+
4. **Start preview** and verify frame rate
33+
5. **Run pose inference** on a selected camera
34+
6. **Record video** (optionally with overlays)
35+
7. **Organize results** by session and run
36+
37+
Each of these steps is covered in the *Quickstart* and *User Guide* sections of this documentation.
38+
39+
---
40+
41+
## Who this is for
42+
43+
- Neuroscience and behavior labs
44+
- Experimentalists running real-time tracking
45+
- Users who want a **GUI-first** workflow for DeepLabCut Live
46+
47+
You do **not** need to be a software developer to use this tool.
48+
49+
---
50+
51+
## What this documentation covers
52+
53+
- Installation and first-run setup
54+
- Camera configuration and supported backends
55+
- Pose inference settings and visualization
56+
- Recording options and file organization
57+
- Known limitations of the current release
58+
59+
This documentation intentionally focuses on **end-user operation**.
60+
Developer-oriented material (APIs, internals, extension points) is out of scope for now.
61+
62+
---
63+
64+
## Current limitations (high-level)
65+
66+
Before getting started, be aware of the following constraints:
67+
68+
- Pose inference runs on **one selected camera at a time** (even in multi-camera mode)
69+
- Camera synchronization depends on backend capabilities and hardware
70+
- DeepLabCut Live models must be **exported and compatible** with the selected backend
71+
- Performance depends on camera resolution, frame rate, GPU availability, and codec choice
72+
73+
A detailed and up-to-date list is maintained in the **Limitations** section.
74+
75+
76+
---
77+
78+
## About DeepLabCut Live
79+
80+
DeepLabCut Live enables low-latency, real-time pose estimation using models trained with DeepLabCut.
81+
This GUI provides an accessible interface on top of that ecosystem for interactive experiments.
82+
83+
---
84+
85+
*This project is under active development. Feedback from real experimental use is highly valued.*

‎docs/myst.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# See: https://mystmd.org/guide/frontmatter
2+
version: 1
3+
4+
project:
5+
title: DeepLabCut Live GUI
6+
description: PySide6-based GUI for real-time DeepLabCut experiments
7+
authors:
8+
- name: A. & M. Mathis Labs
9+
license: LGPL-3.0
10+
github: DeepLabCut/DeepLabCut-live-GUI
11+
toc:
12+
- file: index.md
13+
- title: Quickstart
14+
children:
15+
- file: quickstart/install
16+
# - file: quickstart/camera_setup
17+
# - file: quickstart/inference_setup
18+
# - file: quickstart/first_run
19+
20+
# - title: User Guide
21+
# children:
22+
# - file: user_guide/overview
23+
# - file: user_guide/cameras/index
24+
# children:
25+
# - file: user_guide/cameras/configure_dialog
26+
# - file: user_guide/cameras/supported_backends
27+
28+
# - file: user_guide/inference/index
29+
# children:
30+
# - file: user_guide/inference/model_selection
31+
# - file: user_guide/inference/inference_camera
32+
# - file: user_guide/inference/processor_plugins
33+
34+
# - file: user_guide/visualization/index
35+
# children:
36+
# - file: user_guide/visualization/preview_and_overlays
37+
38+
# - file: user_guide/recording/index
39+
# children:
40+
# - file: user_guide/recording/output_structure
41+
42+
# - title: Limitations
43+
# children:
44+
# - file: limitations/current_limitations
45+
46+
site:
47+
template: book-theme
48+
options:
49+
logo: _static/images/logo.png
50+
style: _static/custom.css

0 commit comments

Comments
 (0)