DeepLabCut-live-GUI PySide6/multicamera documentation ("2.0")#3206
DeepLabCut-live-GUI PySide6/multicamera documentation ("2.0")#3206C-Achard merged 57 commits intoDeepLabCut:mainfrom
Conversation
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
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.
docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/aravis_backend.md
Show resolved
Hide resolved
docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/camera_support.md
Show resolved
Hide resolved
Rework the installation docs to support multiple install workflows and clarify steps. Changes include: less strong recommendations of installers (uv and mamba/conda), add a brief note that the full DeepLabCut package is not required, and provide updated uv venv commands and tabbed platform instructions. Standardized backend extras (.[pytorch] and .[tf] instead of live-latest variants), moved repository clone into conda/mamba flow, and kept the requirement to install from source because the package is pre-release. Also replaced tab markup with consistent fenced tab-set blocks and added a "Supported OSes" toggle summarizing backend availability.
…eepLabCut into cy/dlclivegui2.0-docs
deruyter92
left a comment
There was a problem hiding this comment.
Thanks for these amazing docs, they are really clear.
Few minor comments, but feel free to merge once you think it's ready.
docs/dlc-live/dlc-live-gui/user_guide/misc/modelzoo_downloads.md
Outdated
Show resolved
Hide resolved
docs/dlc-live/dlc-live-gui/user_guide/misc/modelzoo_downloads.md
Outdated
Show resolved
Hide resolved
Introduce a recommended quickstart with clone/install commands, add Key takeaways (OS/TensorFlow notes), and standardize uv virtualenv usage (use .venv and -p Python version). Quote extras in pip/uv commands, add repo clone and verify steps, and clarify backend selection and conda instructions. Also clarify modelzoo docs for TensorFlow (point to model directory and top-down detector exports) and add a reference link for camera support in the overview.
Add an important admonition directing users to the official PyTorch install guide for enabling GPU support and consolidate duplicate installation notes. Reorganize the PyTorch/TensorFlow tab blocks for clarity and adjust install command lines (changed occurrences to `uv pip install -e "[pytorch]"` and `uv pip install -e "[tf]"`). Also add minor spacing/formatting fixes and retain the TensorFlow Windows/Python compatibility caution.
Clean up and improve DeepLabCut-Live! GUI docs: remove an inline TOC note, add a caution block and section anchor for limitations, and clarify/current-limitations wording and performance guidance. Improve quickstart and install pages with a tip, clearer hardware/backend bullet formatting, an explicit pip torch install example for CUDA, and simplify installation commands. Minor copyedits for clarity and contribution/feedback section formatting.
Add explicit Sphinx file targets to OpenCV, GenTL and Basler backend docs and update camera_support.md to reference them via {ref}`... <file:...>` links. Clarify that GenTL requires vendor CTI files and remove the obsolete "Links to backend documentation" block, cleaning up backend listing and link targets.
Add a general recommendations note for backend selection and clarify platform-specific guidance. Standardize product name to "DeepLabCut-Live-GUI", adjust GenTL and Basler backend recommendations (note that OpenCV is available but not recommended for Basler), and fix minor formatting issues in the camera support document.
Refactor and clarify the OpenCV backend documentation: rephrase exposure/gain note, rename and reorganize sections (Features -> Features & design; Installation -> Dependencies information; Full properties -> Advanced configuration) and add nested headings for clarity. Clarify that OpenCV and cv2-enumerate-cameras are installed by default with the GUI, simplify device enumerator mention, adjust wording for fast_start and opening behavior, standardize Resolution/FPS headers, and remove a duplicated FPS note. These edits improve readability and make dependency/install guidance and configuration details clearer for users.
Reorganize and clean up the Aravis backend documentation for readability. Convert the Installation section into a tab-set with separate tabs for Linux (Ubuntu/Debian), Fedora, Windows, and macOS; add a caution note for Windows. Tweak wording for identity fields (now "used internally and set by the GUI"). Rename "Full properties and configuration" to "Full properties and advanced configuration", adjust heading levels for streaming/performance tuning (Buffer Count and Timeout become subheadings), remove extraneous blank lines, and fix the markdown table alignment in the GenTL comparison. These changes improve structure and presentation of the camera backend docs.
Rework the Basler backend documentation for clarity and navigation. Changes include renaming "Features" to "Features & design", converting OS install instructions into a tab-set (Linux/Windows/macOS), adjusting several section headings to subsections (Exposure, Frame rate, Resolution, Pixel format, Device discovery), and a minor tweak to the pip install line. These edits improve readability and make platform-specific install steps easier to scan.
Rewrite and clarify the GenTL backend user guide: reorganized headings and wording, emphasized support for loading multiple CTI producers, and added CTI persistence & diagnostics (`properties.gentl.cti_files`, `cti_files_loaded`, `cti_files_failed`, `cti_file`). Documented CTI resolution precedence and `cti_files_source` semantics ("auto" vs "user"), discovery fallbacks, and pinning behavior. Added automated rebind behavior for stable device identity (`properties.gentl.device_id`) and clarified selection order, telemetry fields, and fast-start probe mode. Clarified pixel-format normalization (BGR 8-bit), exposure/gain/fps/resolution handling, and updated examples to remove hard-coded index/cti entries.
Move the "About frame size mismatches" warning and the note about automatic frame conversions from timestamp_format.md into the GUI overview to centralize recorder guidance and remove duplication. Also apply several small copy edits in overview.md: tweak preview wording to "live video feed", add a "Show controls" option, change the "Save configuration as" menu item to include ellipsis, clarify how saved configurations are loaded (manual load vs. last-saved auto-restore), and adjust the tip wording about relying on saved configs. Removed the redundant section from timestamp_format.md.
Update the example in docs/dlc-live/.../modelzoo_downloads.md to include the detector_name parameter in the export_modelzoo_model call (set to "fasterrcnn_resnet50_fpn_v2") and add an inline comment showing an example for model_name (e.g. "hrnet_w32"). This clarifies how to specify the detector and provides a concrete model_name example in the snippet.
Clarify the model-zoo reference to include detectors and update the example export call to pass a detector_name ("fasterrcnn_resnet50_fpn_v2"). This makes the docs explicit about available detectors and demonstrates how to specify the detector when exporting a model from the Model Zoo.
Add a section to the dlclive GUI quickstart install page explaining how to programmatically download and export pretrained models from the DeepLabCut Model Zoo for use in the GUI. The new text references the pretrained-models doc, recommends using the dlclive.modelzoo API to fetch and export models, and includes an important callout mentioning potential future built-in browsing/downloading support.
Reword the note to say the example is intended for the PyTorch engine and clarify TensorFlow guidance: point the GUI to a DLC model .pb file (not a .pth/.pt file). Also remove an extraneous blank line before the example script for minor cleanup.
Update quickstart install instructions: create and cd into a local 'dlclivegui' directory (removed leading ~ and corrected the cd target), and correct the pip package spec from 'dlclivegui[...] @ git+https://...' to 'deeplabcut-live-gui[...] @ git+https://...'. These are documentation fixes to ensure the commands match the project and install the correct package.
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 in the sidebar.
NOTE The install procedure is no longer a placeholder with the DLC-live 1.1.0 release, but still requires cloning the main repo while we work on a PyPi release.
Related
See:
TODO
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.