From 37116b1c870f0e6a152ac7a8b87370f145a945cb Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 17 Feb 2026 08:36:34 +0100 Subject: [PATCH 1/4] Reintroduce previous README --- README.md | 326 +++++++----------------------------------------------- 1 file changed, 38 insertions(+), 288 deletions(-) diff --git a/README.md b/README.md index 1b16d5b..acdadf2 100644 --- a/README.md +++ b/README.md @@ -1,319 +1,69 @@ - -# DeepLabCut Live GUI +# DeepLabCut-Live! GUI DLC LIVE! GUI -A modern PySide6 GUI for running [DeepLabCut-live](https://github.com/DeepLabCut/DeepLabCut-live) experiments with real-time pose estimation. The application streams frames from industrial or consumer cameras, performs DLCLive inference, and records high-quality video with synchronized pose data. +Code style: black +![PyPI - Python Version](https://img.shields.io/pypi/v/deeplabcut-live-gui) +![PyPI - Downloads](https://img.shields.io/pypi/dm/deeplabcut-live-gui?color=purple) +![Python package](https://github.com/DeepLabCut/DeepLabCut-live/workflows/Python%20package/badge.svg) -## Features +[![License](https://img.shields.io/pypi/l/deeplabcutcore.svg)](https://github.com/DeepLabCut/deeplabcutlive/raw/master/LICENSE) +[![Image.sc forum](https://img.shields.io/badge/dynamic/json.svg?label=forum&url=https%3A%2F%2Fforum.image.sc%2Ftags%2Fdeeplabcut.json&query=%24.topic_list.tags.0.topic_count&colorB=brightgreen&&suffix=%20topics&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC)](https://forum.image.sc/tags/deeplabcut) +[![Gitter](https://badges.gitter.im/DeepLabCut/community.svg)](https://gitter.im/DeepLabCut/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) +[![Twitter Follow](https://img.shields.io/twitter/follow/DeepLabCut.svg?label=DeepLabCut&style=social)](https://twitter.com/DeepLabCut) -### Core Functionality -- **Modern Python Stack**: Python 3.10+ compatible codebase with PySide6 interface -- **Multi-Backend Camera Support**: OpenCV, GenTL (Harvesters), Aravis, and Basler (pypylon) -- **Real-Time Pose Estimation**: Live DLCLive inference with configurable models (TensorFlow, PyTorch) -- **High-Performance Recording**: Hardware-accelerated video encoding via FFmpeg -- **Flexible Configuration**: Single JSON file for all settings with GUI editing +GUI to run [DeepLabCut-live](https://github.com/DeepLabCut/DeepLabCut-live) on a video feed, record videos, and record external timestamps. -### Camera Features -- **Multiple Backends**: - - OpenCV - Universal webcam support - - GenTL - Industrial cameras via Harvesters (Windows/Linux) - - Aravis - GenICam/GigE cameras (Linux/macOS) - - Basler - Basler cameras via pypylon -- **Smart Device Detection**: Automatic camera enumeration without unnecessary probing -- **Camera Controls**: Exposure time, gain, frame rate, and ROI cropping -- **Live Preview**: Real-time camera feed with rotation support (0°, 90°, 180°, 270°) +## [Installation Instructions](docs/install.md) -### DLCLive Features -- **Model Support**: Only PyTorch models! (in theory also tensorflow models work) -- **Processor System**: Plugin architecture for custom pose processing -- **Auto-Recording**: Automatic video recording triggered by processor commands -- **Performance Metrics**: Real-time FPS, latency, and queue monitoring -- **Pose Visualization**: Optional overlay of detected keypoints on live feed +## Getting Started -### Recording Features -- **Hardware Encoding**: NVENC (NVIDIA GPU) and software codecs (libx264, libx265) -- **Configurable Quality**: CRF-based quality control -- **Multiple Formats**: MP4, AVI, MOV containers -- **Timestamp Support**: Frame-accurate timestamps for synchronization -- **Performance Monitoring**: Write FPS, buffer status, and dropped frame tracking +#### Open DeepLabCut-live-GUI -### User Interface -- **Intuitive Layout**: Organized control panels with clear separation of concerns -- **Configuration Management**: Load/save settings, support for multiple configurations -- **Status Indicators**: Real-time feedback on camera, inference, and recording status -- **Bounding Box Tool**: Visual overlay for ROI definition +In a terminal, activate the conda or virtual environment where DeepLabCut-live-GUI is installed, then run: -## Installation - -### Basic Installation - -```bash -pip install deeplabcut-live-gui -``` - -This installs the core package with OpenCV camera support. - -### Full Installation with Optional Dependencies - -```bash -# Install with gentl support -pip install deeplabcut-live-gui[gentl] -``` - -### Platform-Specific Camera Backend Setup - -#### Windows (GenTL for Industrial Cameras) -1. Install camera vendor drivers and SDK -2. Ensure GenTL producer (.cti) files are accessible -3. Common locations: - - `C:\Program Files\The Imaging Source Europe GmbH\IC4 GenTL Driver\bin\` - - Check vendor documentation for CTI file location - -#### Linux (Aravis for GenICam Cameras - Recommended) -NOT tested -```bash -# Ubuntu/Debian -sudo apt-get install gir1.2-aravis-0.8 python3-gi - -# Fedora -sudo dnf install aravis python3-gobject ``` - -#### macOS (Aravis) -NOT tested -```bash -brew install aravis -pip install pygobject +dlclivegui ``` -#### Basler Cameras (All Platforms) -NOT tested -```bash -# Install Pylon SDK from Basler website -# Then install pypylon -pip install pypylon -``` -### Hardware Acceleration (Optional) +#### Configurations -For NVIDIA GPU encoding (highly recommended for high-resolution/high-FPS recording): -```bash -# Ensure NVIDIA drivers are installed -# FFmpeg with NVENC support will be used automatically -``` -## Quick Start +First, create a configuration file: select the drop down menu labeled `Config`, and click `Create New Config`. All settings, such as details about cameras, DLC networks, and DLC-live Processors, will be saved into configuration files so that you can close and reopen the GUI without losing all of these details. You can create multiple configuration files on the same system, so that different users can save different camera options, etc on the same computer. To load previous settings from a configuration file, please just select the file from the drop-down menu. Configuration files are stored at `$HOME/Documents/DeepLabCut-live-GUI/config`. These files do not need to be edited manually, they can be entirely created and edited automatically within the GUI. -1. **Launch the GUI**: - ```bash - dlclivegui - ``` +#### Set Up Cameras -2. **Select Camera Backend**: Choose from the dropdown (opencv, gentl, aravis, basler) +To setup a new camera, select `Add Camera` from the dropdown menu, and then click `Init Cam`. This will be bring up a new window where you need to select the type of camera (see [Camera Support](docs/camera_support.md)), input a name for the camera, and click `Add Camera`. This will initialize a new `Camera` entry in the drop down menu. Now, select your camera from the dropdown menu and click`Edit Camera Settings` to setup your camera settings (i.e. set the serial number, exposure, cropping parameters, etc; the exact settings depend on the specific type of camera). Once you have set the camera settings, click `Init Cam` to start streaming. To stop streaming data, click `Close Camera`, and to remove a camera from the dropdown menu, click `Remove Camera`. -3. **Configure Camera**: Set FPS, exposure, gain, and other parameters +#### Processor (optional) -4. **Start Preview**: Click "Start Preview" to begin camera streaming +To write custom `Processors`, please see [here](https://github.com/DeepLabCut/DeepLabCut-live/tree/master/dlclive/processor). The directory that contains your custom `Processor` should be a python module -- this directory must contain an `__init__.py` file that imports your custom `Processor`. For examples of how to structure a custom `Processor` directory, please see [here](https://github.com/DeepLabCut/DeepLabCut-live/tree/master/example_processors). -5. **Optional - Load DLC Model**: Browse to your exported DLCLive model directory +To use your processor in the GUI, you must first add your custom `Processor` directory to the dropdown menu: next to the `Processor Dir` label, click `Browse`, and select your custom `Processor` directory. Next, select the desired directory from the `Processor Dir` dropdown menu, then select the `Processor` you would like to use from the `Processor` menu. If you would like to edit the arguments for your processor, please select `Edit Proc Settings`, and finally, to use the processor, click `Set Proc`. If you have previously set a `Processor` and would like to clear it, click `Clear Proc`. -6. **Optional - Start Inference**: Click "Start pose inference" for real-time tracking +#### Configure DeepLabCut Network -7. **Optional - Record Video**: Configure output path and click "Start recording" + -## Configuration +Select the `DeepLabCut` dropdown menu, and click `Add DLC`. This will bring up a new window to choose a name for the DeepLabCut configuration, choose the path to the exported DeepLabCut model, and set DeepLabCut-live settings, such as the cropping or resize parameters. Once configured, click `Update` to add this DeepLabCut configuration to the dropdown menu. You can edit the settings at any time by clicking `Edit DLC Settings`. Once configured, you can load the network and start performing inference by clicking `Start DLC`. If you would like to view the DeepLabCut pose estimation in real-time, select `Display DLC Keypoints`. You can edit the keypoint display settings (the color scheme, size of points, and the likelihood threshold for display) by selecting `Edit DLC Display Settings`. -The GUI uses a single JSON configuration file containing all experiment settings: - -```json -{ - "camera": { - "name": "Camera 0", - "index": 0, - "fps": 60.0, - "backend": "gentl", - "exposure": 10000, - "gain": 5.0, - "crop_x0": 0, - "crop_y0": 0, - "crop_x1": 0, - "crop_y1": 0, - "max_devices": 3, - "properties": {} - }, - "dlc": { - "model_path": "/path/to/exported-model", - "model_type": "pytorch", - }, - "recording": { - "enabled": true, - "directory": "~/Videos/deeplabcut-live", - "filename": "session.mp4", - "container": "mp4", - "codec": "h264_nvenc", - "crf": 23 - }, - "bbox": { - "enabled": false, - "x0": 0, - "y0": 0, - "x1": 200, - "y1": 100 - } -} -``` - -### Configuration Management - -- **Load**: File → Load configuration… (or Ctrl+O) -- **Save**: File → Save configuration (or Ctrl+S) -- **Save As**: File → Save configuration as… (or Ctrl+Shift+S) - -All GUI fields are automatically synchronized with the configuration file. - -## Camera Backends - -### Backend Selection Guide - -| Backend | Platform | Use Case | Auto-Detection | -|---------|----------|----------|----------------| -| **opencv** | All | Webcams, simple USB cameras | Basic | -| **gentl** | Windows, Linux | Industrial cameras via CTI files | Yes | -| **aravis** | Linux, macOS | GenICam/GigE cameras | Yes | -| **basler** | All | Basler cameras specifically | Yes | - -### Backend-Specific Configuration - -#### OpenCV -```json -{ - "camera": { - "backend": "opencv", - "index": 0, - "fps": 30.0 - } -} -``` -**Note**: Exposure and gain controls are disabled for OpenCV backend due to limited driver support. - -#### GenTL (Harvesters) -```json -{ - "camera": { - "backend": "gentl", - "index": 0, - "fps": 60.0, - "exposure": 15000, - "gain": 8.0, - } -} -``` +If you want to stop performing inference at any time, just click `Stop DLC`, and if you want to remove a DeepLabCut configuration from the dropdown menu, click `Remove DLC`. +#### Set Up Session -See [Camera Backend Documentation](docs/camera_support.md) for detailed setup instructions. +Sessions are defined by the subject name, the date, and an attempt number. Within the GUI, select a `Subject` from the dropdown menu, or to add a new subject, type the new subject name in to the entry box and click `Add Subject`. Next, select an `Attempt` from the dropdown menu. Then, select the directory that you would like to save data to from the `Directory` dropdown menu. To add a new directory to the dropdown menu, click `Browse`. Finally, click `Set Up Session` to initiate a new recording. This will prepare the GUI to save data. Once you click `Set Up Session`, the `Ready` button should turn blue, indicating a session is ready to record. -## DLCLive Integration +#### Controlling Recording -### Model Types +If the `Ready` button is selected, you can now start a recording by clicking `On`. The `On` button will then turn green indicating a recording is active. To stop a recording, click `Off`. This will cause the `Ready` button to be selected again, as the GUI is prepared to restart the recording and to save the data to the same file. If you're session is complete, click `Save Video` to save all files: the video recording (as .avi file), a numpy file with timestamps for each recorded frame, the DeepLabCut poses as a pandas data frame (hdf5 file) that includes the time of each frame used for pose estimation and the time that each pose was obtained, and if applicable, files saved by the `Processor` in use. These files will be saved into a new directory at `{YOUR_SAVE_DIRECTORY}/{CAMERA NAME}_{SUBJECT}_{DATE}_{ATTEMPT}` -The GUI supports PyTorch DLCLive models: +- YOUR_SAVE_DIRECTORY : the directory chosen from the `Directory` dropdown menu. +- CAMERA NAME : the name of selected camera (from the `Camera` dropdown menu). +- SUBJECT : the subject chosen from the `Subject` drowdown menu. +- DATE : the current date of the experiment. +- ATTEMPT : the attempt number chosen from the `Attempt` dropdown. -1. **PyTorch**: PyTorch-based models (requires PyTorch installation) +If you would not like to save the data from the session, please click `Delete Video`, and all data will be discarded. After you click `Save Video` or `Delete Video`, the `Off` button will be selected, indicating you can now set up a new session. -Select the model type from the dropdown before starting inference. +#### References: -### Processor System - -The GUI includes a plugin system for custom pose processing: - -```python -# Example processor -class MyProcessor: - def process(self, pose, timestamp): - # Custom processing logic - x, y = pose[0, :2] # First keypoint - print(f"Position: ({x}, {y})") - def save(self): - pass -``` - -Place processors in `dlclivegui/processors/` and refresh to load them. - -See [Processor Plugin Documentation](docs/PLUGIN_SYSTEM.md) for details. - -### Auto-Recording Feature - -Enable "Auto-record video on processor command" to automatically start/stop recording based on processor signals. Useful for event-triggered recording in behavioral experiments. - -## Performance Optimization - -### High-Speed Camera Tips - -1. **Use Hardware Encoding**: Select `h264_nvenc` codec for NVIDIA GPUs -2. **Adjust Buffer Count**: Increase buffers for GenTL/Aravis backends - ```json - "properties": {"n_buffers": 20} - ``` -3. **Optimize CRF**: Lower CRF = higher quality but larger files (default: 23) -4. **Disable Visualization**: Uncheck "Display pose predictions" during recording -5. **Crop Region**: Use cropping to reduce frame size before inference - -### Project Structure - -``` -dlclivegui/ -├── __init__.py -├── gui.py # Main PySide6 application -├── config.py # Configuration dataclasses -├── camera_controller.py # Camera capture thread -├── dlc_processor.py # DLCLive inference thread -├── video_recorder.py # Video encoding thread -├── cameras/ # Camera backend modules -│ ├── base.py # Abstract base class -│ ├── factory.py # Backend registry and detection -│ ├── opencv_backend.py -│ ├── gentl_backend.py -│ ├── aravis_backend.py -│ └── basler_backend.py -└── processors/ # Pose processor plugins - ├── processor_utils.py - └── dlc_processor_socket.py -``` - - -## Documentation - -- [Camera Support](docs/camera_support.md) - All camera backends and setup -- [Aravis Backend](docs/aravis_backend.md) - GenICam camera setup (Linux/macOS) -- [Processor Plugins](docs/PLUGIN_SYSTEM.md) - Custom pose processing -- [Installation Guide](docs/install.md) - Detailed setup instructions -- [Timestamp Format](docs/timestamp_format.md) - Timestamp synchronization - -## System Requirements - - -### Recommended -- Python 3.10+ -- 8 GB RAM -- NVIDIA GPU with CUDA support (for DLCLive inference and video encoding) -- USB 3.0 or GigE network (for industrial cameras) -- SSD storage (for high-speed recording) - -### Tested Platforms -- Windows 11 - -## License - -This project is licensed under the GNU Lesser General Public License v3.0. See the [LICENSE](LICENSE) file for more information. - -## Citation - -Cite the original DeepLabCut-live paper: -```bibtex -@article{Kane2020, - title={Real-time, low-latency closed-loop feedback using markerless posture tracking}, - author={Kane, Gary A and Lopes, Gonçalo and Saunders, Jonny L and Mathis, Alexander and Mathis, Mackenzie W}, - journal={eLife}, - year={2020}, - doi={10.7554/eLife.61909} -} -``` +If you use this code we kindly ask you to you please [cite Kane et al, eLife 2020](https://elifesciences.org/articles/61909). The preprint is available here: https://www.biorxiv.org/content/10.1101/2020.08.04.236422v2 From df40496f0959fda7f3ee896d29b7d1fd9c8657c7 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 17 Feb 2026 09:07:25 +0100 Subject: [PATCH 2/4] Revise README: modern GUI, install, and usage Major rewrite of README to reflect the new PySide6-based DeepLabCut-Live-GUI. Updates include renamed project header and badges, updated license badge, new system requirements, detailed installation instructions (uv and conda/mamba workflows), run instructions, and a concise typical workflow (multi-camera preview, inference, and recording). Notes added about current limitations, references/citation, and contribution/feedback guidance; legacy tkinter-focused guidance and some older UI walkthrough text were removed or replaced with modernized guidance. --- README.md | 176 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 142 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index acdadf2..6360eb0 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,177 @@ -# DeepLabCut-Live! GUI DLC LIVE! GUI +# DeepLabCut-Live-GUI DLC LIVE! GUI -Code style: black + +[![Code style:Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) ![PyPI - Python Version](https://img.shields.io/pypi/v/deeplabcut-live-gui) ![PyPI - Downloads](https://img.shields.io/pypi/dm/deeplabcut-live-gui?color=purple) -![Python package](https://github.com/DeepLabCut/DeepLabCut-live/workflows/Python%20package/badge.svg) +![Python versions](https://img.shields.io/pypi/pyversions/deeplabcut-live-gui) + -[![License](https://img.shields.io/pypi/l/deeplabcutcore.svg)](https://github.com/DeepLabCut/deeplabcutlive/raw/master/LICENSE) -[![Image.sc forum](https://img.shields.io/badge/dynamic/json.svg?label=forum&url=https%3A%2F%2Fforum.image.sc%2Ftags%2Fdeeplabcut.json&query=%24.topic_list.tags.0.topic_count&colorB=brightgreen&&suffix=%20topics&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC)](https://forum.image.sc/tags/deeplabcut) +[![License](https://img.shields.io/github/license/DeepLabCut/DeepLabCut-live-GUI?label=license)](https://github.com/DeepLabCut/DeepLabCut-live-GUI/blob/main/LICENSE) +[![Image.sc forum](https://img.shields.io/badge/dynamic/json.svg?label=forum&url=https%3A%2F%2Fforum.image.sc%2Ftags%2Fdeeplabcut.json&query=%24.topic_list.tags.0.topic_count&colorB=brightgreen&&suffix=%20topics&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC)](https://forum.image.sc/tags/deeplabcut) [![Gitter](https://badges.gitter.im/DeepLabCut/community.svg)](https://gitter.im/DeepLabCut/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Twitter Follow](https://img.shields.io/twitter/follow/DeepLabCut.svg?label=DeepLabCut&style=social)](https://twitter.com/DeepLabCut) -GUI to run [DeepLabCut-live](https://github.com/DeepLabCut/DeepLabCut-live) on a video feed, record videos, and record external timestamps. +GUI to run [DeepLabCut-Live](https://github.com/DeepLabCut/DeepLabCut-live) on a video feed, **preview and record from one or multiple cameras**, and optionally record external timestamps and processor outputs. + +## Update + +> The GUI has been modernized and is now built with **PySide6 (Qt)** (replacing tkinter). The new interface supports **multi-camera preview** with a **tiled display**, PyTorch models, and features improved interactive workflows for experimental use. + +--- + +## Documentation + +> Full documentations is a work in progress and will be posted to DeepLabCut's official docs site when ready. + +--- + +## System requirements (quick summary) + +- **Python 3.10, 3.11 or 3.12** +- One inference backend (choose at least one): + - **PyTorch** *(recommended for best performance & compatibility)* + - **TensorFlow** *(for backwards compatibility with existing models; Windows limitation applies for Python > 3.10)* +- A supported camera backend (OpenCV webcams by default; additional backends supported) + +--- -## [Installation Instructions](docs/install.md) +## Installation -## Getting Started +This project is currently installed **from source** (editable install). +The newest GUI and features may not yet be available on PyPI. -#### Open DeepLabCut-live-GUI +### Option A — Install with `uv` -In a terminal, activate the conda or virtual environment where DeepLabCut-live-GUI is installed, then run: +#### 1) Create & activate a new virtual environment +```bash +uv venv dlclivegui +# Linux/macOS: +source dlclivegui/bin/activate +# Windows (Command Prompt): +# .\dlclivegui\Scripts\activate.bat +# Windows (PowerShell): +# .\dlclivegui\Scripts\Activate.ps1 ``` -dlclivegui + +#### 2) Clone the repository + +```bash +git clone https://github.com/DeepLabCut/DeepLabCut-live-GUI.git +cd DeepLabCut-live-GUI +``` + +#### 3) Choose inference backend and install + +You may install **PyTorch** or **TensorFlow** extras (or both), but you must choose at least one to run inference. + +- **PyTorch (recommended):** + +```bash +uv pip install -e .[pytorch] +``` + +- **TensorFlow (backwards compatibility):** + +```bash +uv pip install -e .[tf] ``` +> For GPU/CUDA specifics and framework compatibility, please follow the official PyTorch/TensorFlow install guidance for your OS. -#### Configurations +--- + +### Option B — Install with `mamba` / `conda` + +#### 1) Create & activate a new conda environment + +```bash +conda create -n dlclivegui python=3.12 +conda activate dlclivegui +``` + +#### 2) Clone the repository + +```bash +git clone https://github.com/DeepLabCut/DeepLabCut-live-GUI.git +cd DeepLabCut-live-GUI +``` + +#### 3) Install with your inference backend + +- **PyTorch (recommended):** + +```bash +pip install -e .[pytorch] +``` + +- **TensorFlow:** + +```bash +pip install -e .[tf] +``` + +--- + +## Run the application + +After installation, start the application with: + +```bash +dlclivegui # in conda/mamba or after activating your venv +# OR: +uv run dlclivegui +``` +> **Important:** Activate your venv/conda environment before launching so the GUI can access installed dependencies. -First, create a configuration file: select the drop down menu labeled `Config`, and click `Create New Config`. All settings, such as details about cameras, DLC networks, and DLC-live Processors, will be saved into configuration files so that you can close and reopen the GUI without losing all of these details. You can create multiple configuration files on the same system, so that different users can save different camera options, etc on the same computer. To load previous settings from a configuration file, please just select the file from the drop-down menu. Configuration files are stored at `$HOME/Documents/DeepLabCut-live-GUI/config`. These files do not need to be edited manually, they can be entirely created and edited automatically within the GUI. +--- -#### Set Up Cameras +## Typical workflow -To setup a new camera, select `Add Camera` from the dropdown menu, and then click `Init Cam`. This will be bring up a new window where you need to select the type of camera (see [Camera Support](docs/camera_support.md)), input a name for the camera, and click `Add Camera`. This will initialize a new `Camera` entry in the drop down menu. Now, select your camera from the dropdown menu and click`Edit Camera Settings` to setup your camera settings (i.e. set the serial number, exposure, cropping parameters, etc; the exact settings depend on the specific type of camera). Once you have set the camera settings, click `Init Cam` to start streaming. To stop streaming data, click `Close Camera`, and to remove a camera from the dropdown menu, click `Remove Camera`. +The new GUI supports **one or more cameras**. -#### Processor (optional) +Typical workflow: -To write custom `Processors`, please see [here](https://github.com/DeepLabCut/DeepLabCut-live/tree/master/dlclive/processor). The directory that contains your custom `Processor` should be a python module -- this directory must contain an `__init__.py` file that imports your custom `Processor`. For examples of how to structure a custom `Processor` directory, please see [here](https://github.com/DeepLabCut/DeepLabCut-live/tree/master/example_processors). +1. **Configure Cameras** (choose backend and devices) + - Adjust camera settings (serial, exposure, ROI/cropping, etc.) +2. **Start Preview** + - Adjust visualization settings (keypoint color map, bounding boxes, etc.) +3. **Start inference** + - Choose a DeepLabCut Live model + - Choose which camera to run inference on (currently one at a time) +4. **Start recording** + - Adjust recording settings (codec, output format, etc.) + - Record video and timestamps to organized session folders -To use your processor in the GUI, you must first add your custom `Processor` directory to the dropdown menu: next to the `Processor Dir` label, click `Browse`, and select your custom `Processor` directory. Next, select the desired directory from the `Processor Dir` dropdown menu, then select the `Processor` you would like to use from the `Processor` menu. If you would like to edit the arguments for your processor, please select `Edit Proc Settings`, and finally, to use the processor, click `Set Proc`. If you have previously set a `Processor` and would like to clear it, click `Clear Proc`. +> **Note:** OpenCV-compatible cameras (USB webcams, OBS virtual camera) work out of the box. +> For additional camera ecosystems (Basler, GenTL, Aravis, etc.), see the camera backend docs. -#### Configure DeepLabCut Network - +--- -Select the `DeepLabCut` dropdown menu, and click `Add DLC`. This will bring up a new window to choose a name for the DeepLabCut configuration, choose the path to the exported DeepLabCut model, and set DeepLabCut-live settings, such as the cropping or resize parameters. Once configured, click `Update` to add this DeepLabCut configuration to the dropdown menu. You can edit the settings at any time by clicking `Edit DLC Settings`. Once configured, you can load the network and start performing inference by clicking `Start DLC`. If you would like to view the DeepLabCut pose estimation in real-time, select `Display DLC Keypoints`. You can edit the keypoint display settings (the color scheme, size of points, and the likelihood threshold for display) by selecting `Edit DLC Display Settings`. +## Current limitations -If you want to stop performing inference at any time, just click `Stop DLC`, and if you want to remove a DeepLabCut configuration from the dropdown menu, click `Remove DLC`. +- Pose inference runs on **one selected camera at a time** (even in multi-camera mode) +- Camera features support and availability depends on backend capabilities and hardware + - OpenCV controls for resolution/FPS are best-effort and device-driver dependent +- DeepLabCut-Live models must be exported and compatible with the chosen backend +- Performance depends on resolution, frame rate, GPU availability, and codec choice -#### Set Up Session +--- -Sessions are defined by the subject name, the date, and an attempt number. Within the GUI, select a `Subject` from the dropdown menu, or to add a new subject, type the new subject name in to the entry box and click `Add Subject`. Next, select an `Attempt` from the dropdown menu. Then, select the directory that you would like to save data to from the `Directory` dropdown menu. To add a new directory to the dropdown menu, click `Browse`. Finally, click `Set Up Session` to initiate a new recording. This will prepare the GUI to save data. Once you click `Set Up Session`, the `Ready` button should turn blue, indicating a session is ready to record. +## References -#### Controlling Recording +If you use this code we kindly ask you to please cite: -If the `Ready` button is selected, you can now start a recording by clicking `On`. The `On` button will then turn green indicating a recording is active. To stop a recording, click `Off`. This will cause the `Ready` button to be selected again, as the GUI is prepared to restart the recording and to save the data to the same file. If you're session is complete, click `Save Video` to save all files: the video recording (as .avi file), a numpy file with timestamps for each recorded frame, the DeepLabCut poses as a pandas data frame (hdf5 file) that includes the time of each frame used for pose estimation and the time that each pose was obtained, and if applicable, files saved by the `Processor` in use. These files will be saved into a new directory at `{YOUR_SAVE_DIRECTORY}/{CAMERA NAME}_{SUBJECT}_{DATE}_{ATTEMPT}` +- **[Kane et al., eLife 2020](https://elifesciences.org/articles/61909)** + - If preferred, see the **[Preprint](https://www.biorxiv.org/content/10.1101/2020.08.04.236422v2)** -- YOUR_SAVE_DIRECTORY : the directory chosen from the `Directory` dropdown menu. -- CAMERA NAME : the name of selected camera (from the `Camera` dropdown menu). -- SUBJECT : the subject chosen from the `Subject` drowdown menu. -- DATE : the current date of the experiment. -- ATTEMPT : the attempt number chosen from the `Attempt` dropdown. +--- -If you would not like to save the data from the session, please click `Delete Video`, and all data will be discarded. After you click `Save Video` or `Delete Video`, the `Off` button will be selected, indicating you can now set up a new session. +## Contributing / Feedback -#### References: +This project is under active development — feedback from real experimental use is highly valued. -If you use this code we kindly ask you to you please [cite Kane et al, eLife 2020](https://elifesciences.org/articles/61909). The preprint is available here: https://www.biorxiv.org/content/10.1101/2020.08.04.236422v2 +Please report issues, suggest features, or contribute on [GitHub](https://github.com/DeepLabCut/DeepLabCut-live-GUI). From 19b286bd327902a4e8982e32c11495715a9b427b Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 17 Feb 2026 11:08:47 +0100 Subject: [PATCH 3/4] Update README.md --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 6360eb0..d975ce6 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Code style:Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) -![PyPI - Python Version](https://img.shields.io/pypi/v/deeplabcut-live-gui) +![PyPI - Package Version](https://img.shields.io/pypi/v/deeplabcut-live-gui) ![PyPI - Downloads](https://img.shields.io/pypi/dm/deeplabcut-live-gui?color=purple) ![Python versions](https://img.shields.io/pypi/pyversions/deeplabcut-live-gui) @@ -22,7 +22,7 @@ GUI to run [DeepLabCut-Live](https://github.com/DeepLabCut/DeepLabCut-live) on a ## Documentation -> Full documentations is a work in progress and will be posted to DeepLabCut's official docs site when ready. +> Full documentation is a work in progress and will be posted to DeepLabCut's official docs site when ready. --- @@ -31,15 +31,16 @@ GUI to run [DeepLabCut-Live](https://github.com/DeepLabCut/DeepLabCut-live) on a - **Python 3.10, 3.11 or 3.12** - One inference backend (choose at least one): - **PyTorch** *(recommended for best performance & compatibility)* - - **TensorFlow** *(for backwards compatibility with existing models; Windows limitation applies for Python > 3.10)* + - **TensorFlow** *(for backwards compatibility with existing models; Windows installs are no longer available for Python > 3.10)* - A supported camera backend (OpenCV webcams by default; additional backends supported) --- ## Installation -This project is currently installed **from source** (editable install). -The newest GUI and features may not yet be available on PyPI. +While `deeplabcut-live-gui` is available on **PyPI**, the newest PySide6-based GUI and features are currently best obtained by installing from source. + +To get the **latest version**, please follow the **instructions below**. ### Option A — Install with `uv` @@ -146,8 +147,8 @@ Typical workflow: - Record video and timestamps to organized session folders > **Note:** OpenCV-compatible cameras (USB webcams, OBS virtual camera) work out of the box. -> For additional camera ecosystems (Basler, GenTL, Aravis, etc.), see the camera backend docs. - +> For additional camera ecosystems (Basler, GenTL, Aravis, etc.), see the relevant documentation. + --- From 0c86c7d45471289d64dcbfdce7cefb443dc464f3 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Thu, 19 Feb 2026 17:21:31 +0100 Subject: [PATCH 4/4] Improve README installation instructions Rework and clarify installation steps in README.md: add a top-level "Clone the repository" step, consolidate and renumber environment/setup steps, and remove duplicated clone instructions. Move and clarify Windows activation commands, ensure guidance for running the app references conda/uv usage, and add TIP/IMPORTANT/NOTE callouts for GPU/CUDA compatibility and environment activation. Minor formatting and ordering fixes to make the installation flow easier to follow. --- README.md | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index d975ce6..eb77740 100644 --- a/README.md +++ b/README.md @@ -42,28 +42,31 @@ While `deeplabcut-live-gui` is available on **PyPI**, the newest PySide6-based G To get the **latest version**, please follow the **instructions below**. +### 1) Clone the repository + +```bash +git clone https://github.com/DeepLabCut/DeepLabCut-live-GUI.git +cd DeepLabCut-live-GUI +``` + ### Option A — Install with `uv` -#### 1) Create & activate a new virtual environment +#### 2) Create & activate a new virtual environment ```bash uv venv dlclivegui + # Linux/macOS: source dlclivegui/bin/activate -# Windows (Command Prompt): -# .\dlclivegui\Scripts\activate.bat -# Windows (PowerShell): -# .\dlclivegui\Scripts\Activate.ps1 -``` -#### 2) Clone the repository +# Windows (Command Prompt): +.\dlclivegui\Scripts\activate.bat -```bash -git clone https://github.com/DeepLabCut/DeepLabCut-live-GUI.git -cd DeepLabCut-live-GUI +# Windows (PowerShell): +.\dlclivegui\Scripts\Activate.ps1 ``` -#### 3) Choose inference backend and install +#### 2) Choose inference backend and install You may install **PyTorch** or **TensorFlow** extras (or both), but you must choose at least one to run inference. @@ -79,8 +82,6 @@ uv pip install -e .[pytorch] uv pip install -e .[tf] ``` -> For GPU/CUDA specifics and framework compatibility, please follow the official PyTorch/TensorFlow install guidance for your OS. - --- ### Option B — Install with `mamba` / `conda` @@ -92,14 +93,7 @@ conda create -n dlclivegui python=3.12 conda activate dlclivegui ``` -#### 2) Clone the repository - -```bash -git clone https://github.com/DeepLabCut/DeepLabCut-live-GUI.git -cd DeepLabCut-live-GUI -``` - -#### 3) Install with your inference backend +#### 2) Install with your inference backend - **PyTorch (recommended):** @@ -117,15 +111,20 @@ pip install -e .[tf] ## Run the application +> [!TIP] +> For GPU/CUDA support specifics and framework compatibility, please follow the official PyTorch/TensorFlow install guidance for your OS and drivers. + After installation, start the application with: ```bash -dlclivegui # in conda/mamba or after activating your venv +dlclivegui # in conda/mamba + # OR: uv run dlclivegui ``` -> **Important:** Activate your venv/conda environment before launching so the GUI can access installed dependencies. +> [!IMPORTANT] +> Activate your venv/conda environment before launching so the GUI can access installed dependencies. --- @@ -146,7 +145,8 @@ Typical workflow: - Adjust recording settings (codec, output format, etc.) - Record video and timestamps to organized session folders -> **Note:** OpenCV-compatible cameras (USB webcams, OBS virtual camera) work out of the box. +> [!NOTE] +> OpenCV-compatible cameras (USB webcams, OBS virtual camera) work out of the box. > For additional camera ecosystems (Basler, GenTL, Aravis, etc.), see the relevant documentation.