Skip to content

DeepLabCut-live-GUI PySide6/multicamera documentation ("2.0")#3206

Draft
C-Achard wants to merge 24 commits intoDeepLabCut:mainfrom
C-Achard:cy/dlclivegui2.0-docs
Draft

DeepLabCut-live-GUI PySide6/multicamera documentation ("2.0")#3206
C-Achard wants to merge 24 commits intoDeepLabCut:mainfrom
C-Achard:cy/dlclivegui2.0-docs

Conversation

@C-Achard
Copy link
Collaborator

@C-Achard C-Achard commented Feb 10, 2026

Documentation for DLC-live-GUI

Adds a new section that fully documents the upcoming upgrade for the DLC-live-GUI package.

Scope

Adds :

  • Install instructions
  • Main GUI quick guide
  • Camera backends support

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.

⚠️ NOTE The install procedure is a placeholder while DLC-live 2.0 release is being finalized.

Related

See:

TODO

  • Main user docs (viable minimum)
  • Polish camera support
    • Add all backends
      • OpenCV (?)
      • Basler
      • Aravis
      • Gentl
  • Figure out install procedure instructions priority
  • Polish timestamp guide
    • Introduce the concept earlier in docs for clarity
  • Document DLC-live usage
    • Model zoo models
    • PyTorch model export
  • (Optional) Get Update docs TOC and Sphinx excludes #3201 merged first
  • (Optional) Change install method if/once relevant

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

  • Overhauled the _toc.yml file to reorganize the documentation into clearer thematic sections,. Also standardized captions for consistency and clarity. [1] [2] [3] [4]
  • Added a new section for DeepLabCut Live GUI documentation, including a multi-level structure for quickstart, user guide, camera backends, and advanced features.

DeepLabCut Live GUI Documentation

  • Introduced comprehensive documentation for DeepLabCut Live GUI, including an overview (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

  • Moved and expanded the previous deeplabcutlive.md with a new version under docs/dlc-live/deeplabcutlive.md, clarifying the distinction between the SDK and GUI, and linking to relevant documentation sections. [1] [2]

Model Zoo Documentation

  • Added a reference label to the Model Zoo documentation for easier cross-linking and navigation.

Sphinx Configuration Improvements

  • Updated the Sphinx configuration in _config.yml to exclude virtual environment and build directories from documentation builds, preventing irrelevant files from being processed.

C-Achard and others added 18 commits February 6, 2026 19:48
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.
@C-Achard C-Achard self-assigned this Feb 10, 2026
@C-Achard C-Achard added the documentation documentation updates/comments label Feb 10, 2026
@C-Achard C-Achard requested a review from Copilot February 10, 2026 16:28
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.yml to 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.

Comment on lines +89 to +91
# 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
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
# 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

Copilot uses AI. Check for mistakes.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving open as reminder

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.
Copy link
Collaborator

@deruyter92 deruyter92 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +5 to +7
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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +7 to +10
```{important}
Support for Aravis in the GUI is currently experimental.
Please report issues or feedback to help improve this backend.
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good addition


## File naming

For a video file named `recording_2025-10-23_143052.mp4`, the timestamp file will be:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is now in the folder name right?

BTW, I really like how recordings are saved now

Comment on lines +76 to +84
## Backend comparison

| Feature | OpenCV | GenTL | Aravis | Basler (pypylon) |
|---------|--------|-------|--------|------------------|
| Exposure control | No | Yes | Yes | Yes |
| Gain control | No | Yes | Yes | Yes |
| Windows | ✅ | ✅ | ❌ | ✅ |
| Linux | ✅ | ✅ | ✅ | ✅ |
| macOS | ✅ | ❌ | ⚠️ | ✅ |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

great that you added this as well

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation updates/comments

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants