DeepLabCut-live-GUI PySide6/multicamera documentation ("2.0")#3206
DeepLabCut-live-GUI PySide6/multicamera documentation ("2.0")#3206C-Achard wants to merge 24 commits intoDeepLabCut:mainfrom
Conversation
Add Sphinx exclude_patterns to _config.yml to ignore virtual environments, site-packages, and build directories during doc builds (".venv/**", "venv/**", "**/site-packages/**", "_build/**", "**/_build/**"). Reformat _toc.yml into a proper jb-book "parts:" structure with correctly nested captions and chapters, normalize emoji-bearing captions with quotes, and restore many documentation sections. Also add a placeholder "DLC-Live!" entry with nested chapters/sections for the dlc-live GUI documentation. These changes clean up the table of contents and prevent unrelated files from being included in the documentation build.
Add a complete documentation subtree for the DeepLabCut-live GUI. New files include index, README, features, user guide (with overview), quickstart/install, camera backends (aravis backend and camera support), timestamp format, and a myst.yml site config. Update _toc.yml to add a DLC-Live section and link the new index, install and overview pages. These docs provide installation steps, backend recommendations, feature descriptions, processor/plugin guidance, recording/timestamp formats, and camera configuration details for the GUI.
Move DLC-Live GUI docs from docs/gui/dlc-live/... into docs/dlc-live/dlc-live-gui, update the table of contents to include the GUI under DeepLabCut-Live!, and remove the old placeholder. Add the main_window screenshot to the new static path. Revise documentation pages (index, overview, install) to improve structure and wording, add cross-links to quickstart and user guide, insert caution/important notes, and reference the Model Zoo (file:model-zoo). Update install instructions to require cloning from GitHub, add venv/activation notes, and change pip extras names to live-latest-pytorch / live-latest-tensorflow. Include temporary TODO/myst comments in myst.yml.
Rename the environment heading to explicitly mention virtual environments, emphasize TensorFlow availability on Windows for Python >3.10, and add an "Alternative: Install with conda" section. The new section shows how to create and activate a conda environment and provides pip editable install commands for PyTorch and TensorFlow backends (with links to official install guides). Also update the run instruction to allow invoking dlclivegui directly (or via uv).
Rewrite the DeepLabCut-Live-GUI overview: rename the app to dlclivegui and add startup instructions (activate env / uv run). Restructure the Main Window and workflow sections, add a startup screenshot, and clarify DLCLive and processor functionality with a new footnote linking to DLCLive processors. Expand Recording and Encoding sections with tips, controls, and a stronger warning about irreversible overlay recording. Add menu bar actions, keyboard shortcuts, small UI/wording tweaks, and various notes/tips to improve usability and clarity.
Move camera backend docs into the user_guide subtree, add camera setup link to the DLC-Live GUI index and TOC, and tidy backend documentation. Renamed aravis_backend.md and camera_support.md into docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/, added an important note marking Aravis support as experimental, converted internal links to the {doc} role, and cleaned up the backend list (including a placeholder for GenTL). These changes surface camera setup in the GUI docs and improve clarity/structure.
Move camera backend docs into the user_guide TOC and update links; refresh dlc-live GUI docs to clarify backend behavior and installation. Key changes: fix TOC path and index reference for camera_support, add note about OpenCV resolution/FPS limitations, reorganize and reword camera_support.md (headings, supported backends, platform recommendations, installation steps, and comparison table), mark Aravis as experimental on macOS and update its docs with minor formatting, troubleshooting and platform notes. Small formatting and clarity improvements throughout.
Rename and relocate timestamp_format.md to docs/dlc-live/dlc-live-gui/user_guide/misc/timestamp_format.md and add the new file to _toc.yml so it appears in the documentation navigation. Also tidy up the page content: change the heading to "Video Timestamp Format" and pluralize "video(s)" in the introductory sentence.
Delete docs/dlc-live/dlc-live-gui/README.md and docs/dlc-live/dlc-live-gui/features.md as part of a documentation cleanup. Update any references or links pointing to these files if content was moved or consolidated elsewhere.
Correct the camera setup link path in the DLC Live GUI docs and add a note about OpenCV controls. The docs now warn that OpenCV resolution and FPS settings are best-effort and may be inconsistent depending on camera drivers and hardware.
There was a problem hiding this comment.
Pull request overview
Expands and reorganizes the documentation for DeepLabCut Live and the upcoming DeepLabCut Live GUI, adding user-facing guides (install, overview, camera backends, timestamps) and integrating them into the Jupyter Book navigation.
Changes:
- Added new DeepLabCut Live GUI docs (installation, GUI overview, camera backend guides, timestamp format).
- Reorganized
_toc.ymlto include the new DLC-live GUI section and improve navigation structure. - Updated Sphinx/Jupyter Book configuration to exclude common venv/build folders from documentation builds.
Reviewed changes
Copilot reviewed 12 out of 13 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/dlc-live/dlc-live-gui/user_guide/overview.md | New GUI walkthrough and workflow overview. |
| docs/dlc-live/dlc-live-gui/user_guide/misc/timestamp_format.md | Documents timestamp sidecar JSON format and usage. |
| docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/camera_support.md | Adds backend support matrix and platform guidance. |
| docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/aravis_backend.md | Adds detailed Aravis backend setup/config/troubleshooting. |
| docs/dlc-live/dlc-live-gui/user_guide.md | Adds a standalone user guide page (legacy-style / longform). |
| docs/dlc-live/dlc-live-gui/quickstart/install.md | Adds install instructions (uv/conda) and backend selection notes. |
| docs/dlc-live/dlc-live-gui/index.md | Adds DLC-live GUI landing page and navigation links. |
| docs/dlc-live/deeplabcutlive.md | Adds/relocates DLC-live overview and points to GUI docs. |
| docs/deeplabcutlive.md | Removes old DLC-live page from prior location. |
| docs/ModelZoo.md | Adds an anchor label for cross-referencing. |
| _toc.yml | Reorganizes book TOC and adds DLC-live GUI section. |
| _config.yml | Excludes venv/build paths from Sphinx builds. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/camera_support.md
Show resolved
Hide resolved
docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/aravis_backend.md
Outdated
Show resolved
Hide resolved
| # NOTE @C-Achard Please move if needed, but since it is downstream of DLC-live | ||
| # I think it makes sense to have it here for now. | ||
| # TODO remove this note before merging |
There was a problem hiding this comment.
The TOC includes an explicit TODO remove this note before merging. Since this file is user-facing release configuration, please remove these review notes before merging to avoid shipping internal commentary in the built docs.
| # NOTE @C-Achard Please move if needed, but since it is downstream of DLC-live | |
| # I think it makes sense to have it here for now. | |
| # TODO remove this note before merging |
There was a problem hiding this comment.
Leaving open as reminder
docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/camera_support.md
Show resolved
Hide resolved
Standardize product name to "DeepLabCut-live-GUI" across docs, update wording and links, and remove an obsolete top-level user guide. Changes include: rename occurrences in index, install and overview pages; fix the venv activation command in the install quickstart; replace an internal docs link with a Sphinx-friendly reference to the camera support anchor; add the (file:dlclivegui-camera-support) anchor in camera_support.md; and delete the now-redundant docs/dlc-live/dlc-live-gui/user_guide.md file. Minor UX text tweaks (e.g. selectable stats text) are also included.
Clarify and reorganize Aravis backend documentation: reword experimental note, introduce a file anchor for the page, and namespace Aravis-specific settings under an "aravis" key (nesting previous properties). Rename the property from `camera_id` to `device_id` in the table and examples, and update the camera support page to reference the Aravis doc anchor for details and troubleshooting.
Rework and expand the Aravis backend user guide: clarify installation steps for Ubuntu/Debian, Fedora, macOS and Windows; consolidate and rename configuration examples (use properties.aravis / device_id, show index vs device selection); expand features, pixel-format behavior (Mono12/16 scaling -> BGR8), exposure/gain/fps/resolution handling, and streaming/performance tuning. Add notes on auto-populated Aravis metadata, troubleshooting commands, and a cleaned example configuration. These changes aim to improve clarity, stability recommendations, and real-world guidance when using the Aravis backend.
Normalize heading capitalization and minor formatting in the camera backend docs. Add a reference link for the Aravis backend and reorganize the Quick installation guide into a tab-set with Aravis (Linux/macOS) and GenTL (Windows) installation instructions. Also adjust the 'Detailed Backend Documentation' heading to 'In more detail' and tidy related links and notes.
Tidy and expand documentation for DLC Live GUI recording timestamps and recorder behavior. Minor whitespace fix in camera backend doc. In timestamp_format.md: normalized heading capitalization, cleaned JSON example, clarified that frame timestamps use caller-provided FrameData.timestamp when available and fall back to time.time() at enqueue time, made avg_fps calculation safe against zero duration, and added notes about encoding timing, dropped frames, frame-size mismatch error handling, and automatic frame conversions for the encoder.
deruyter92
left a comment
There was a problem hiding this comment.
Great docs! Super useful. For the installation instructions I think we should converge on the same procedure for the whole DLC ecosystem, let's discuss.
| We **recommend `uv`** for most users because it is fast, reliable, and handles optional dependencies cleanly. | ||
| **Conda is also supported**, especially if you already use it for DeepLabCut or GPU workflows. | ||
|
|
There was a problem hiding this comment.
I think this is to be discussed. For those who download the repo, I would recommend uv, but for those who install it as a package from PyPI in combination with other packages, a global conda environment might still be more intuitive.
| ```{important} | ||
| Support for Aravis in the GUI is currently experimental. | ||
| Please report issues or feedback to help improve this backend. | ||
| ``` |
|
|
||
| ## File naming | ||
|
|
||
| For a video file named `recording_2025-10-23_143052.mp4`, the timestamp file will be: |
There was a problem hiding this comment.
this is now in the folder name right?
BTW, I really like how recordings are saved now
| ## Backend comparison | ||
|
|
||
| | Feature | OpenCV | GenTL | Aravis | Basler (pypylon) | | ||
| |---------|--------|-------|--------|------------------| | ||
| | Exposure control | No | Yes | Yes | Yes | | ||
| | Gain control | No | Yes | Yes | Yes | | ||
| | Windows | ✅ | ✅ | ❌ | ✅ | | ||
| | Linux | ✅ | ✅ | ✅ | ✅ | | ||
| | macOS | ✅ | ❌ | ⚠️ | ✅ | |
There was a problem hiding this comment.
great that you added this as well
Documentation for DLC-live-GUI
Adds a new section that fully documents the upcoming upgrade for the DLC-live-GUI package.
Scope
Adds :
Edits old DLC-live files for consistency as well, and uses a sligthly different way of defining TOC sections that take less space and contribute less to potential visual clutter.
Related
See:
#3201is irrelevantTODO
Feedback
Please comment on this PR or on the DeepLabCut/DeepLabCut-live-GUI#39 feedback thread.
Summary
This pull request significantly expands and reorganizes the documentation for DeepLabCut Live (a bit) and its GUI (mainly), providing clearer structure, improved navigation, and detailed guides for installation and usage. The changes include a major update of the table of contents, the introduction of new documentation sections for DeepLabCut Live GUI, and updates to exclude irrelevant files from Sphinx builds. The most important changes are grouped below:
Documentation Structure and Navigation
_toc.ymlfile to reorganize the documentation into clearer thematic sections,. Also standardized captions for consistency and clarity. [1] [2] [3] [4]DeepLabCut Live GUI Documentation
index.md), installation guide (quickstart/install.md), and a detailed user guide (user_guide.md). These guides cover system requirements, backend selection, camera setup, model configuration, inference, recording, and troubleshooting. [1] [2] [3]DeepLabCut Live Documentation Updates
deeplabcutlive.mdwith a new version underdocs/dlc-live/deeplabcutlive.md, clarifying the distinction between the SDK and GUI, and linking to relevant documentation sections. [1] [2]Model Zoo Documentation
Sphinx Configuration Improvements
_config.ymlto exclude virtual environment and build directories from documentation builds, preventing irrelevant files from being processed.