From e85346e619224fba051eb64e388fca2110b82520 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 6 May 2026 13:41:13 +0200 Subject: [PATCH] Add XROMM+DeepLabCut local integration guide Add docs/dlc-utils/XROMM/usage.md describing the local 3-repo XROMM workflow with XROMM_DLCTools, DeepLabCut, and xmalab. Covers recommended sibling checkout layout, DeepLabCut's role in the workflow, developer setup (uv sync --group dev/dlc), example validation and end-to-end commands to run the baseline harness, and a compatibility note about lite-mode importability when GUI deps are unavailable. Co-Authored-By: homfunc_ <4338462+homfunc@users.noreply.github.com> --- _toc.yml | 2 ++ docs/dlc-utils/XROMM/usage.md | 64 +++++++++++++++++++++++++++++++++++ docs/dlc-utils/index.md | 22 +++++++++++- 3 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 docs/dlc-utils/XROMM/usage.md diff --git a/_toc.yml b/_toc.yml index 1d7943a7f..815ed3094 100644 --- a/_toc.yml +++ b/_toc.yml @@ -103,6 +103,8 @@ parts: - file: docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook # - file: docs/course - file: docs/dlc-utils/index + sections: + - file: docs/dlc-utils/XROMM/usage - caption: Project & Community chapters: diff --git a/docs/dlc-utils/XROMM/usage.md b/docs/dlc-utils/XROMM/usage.md new file mode 100644 index 000000000..f581ce61f --- /dev/null +++ b/docs/dlc-utils/XROMM/usage.md @@ -0,0 +1,64 @@ +(file:xamalab-dlc-integration)= + +# XROMM + DeepLabCut local integration + +These notes describe how this repository is used in the local 3-repo XROMM workflow together with `../XROMM_DLCTools` and `../xmalab`. + +> Contributed by [@homfunc](https://github.com/homfunc) + +## 1) Expected local layout + +Recommended sibling checkout layout: + +- `XROMM_DLCTools/` +- `DeepLabCut/` +- `xmalab/` + `XROMM_DLCTools/pyproject.toml` maps its optional `dlc` dependency group to this repository through `tool.uv.sources`. + +## 2) DeepLabCut’s role in the workflow + +Within the integrated workflow, DeepLabCut provides: + +- project creation / dataset generation support +- video analysis / prediction entrypoints +- the local import target used by `XROMM_DLCTools` +- synthetic smoke coverage through the baseline harness + The current local integration suite also uses this repo to verify that the newer workflow service in `XROMM_DLCTools` still interoperates with a sibling DeepLabCut checkout. + +## 3) Local setup for this repo + +Standard developer setup: + +```bash +uv sync --group dev +``` + +When working from `../XROMM_DLCTools`, enable the sibling import path there with: + +```bash +uv sync --group dlc +``` + +## 4) Integration validation from XROMM_DLCTools + +Run these commands from `../XROMM_DLCTools`: + +```bash +uv run python scripts/baseline_harness.py --scenario deeplabcut_repo_smoke --output-dir baseline_artifacts/deeplabcut_smoke --deeplabcut-repo ../DeepLabCut +``` + +Full multi-repo suite: + +```bash +uv run python scripts/baseline_harness.py --scenario all --output-dir baseline_artifacts/integration_all --deeplabcut-repo ../DeepLabCut --xmalab-repo ../xmalab +``` + +True end-to-end local workflow scenario: + +```bash +uv run python scripts/baseline_harness.py --scenario phase3_local_workflow_e2e --output-dir baseline_artifacts/e2e_local_workflow --deeplabcut-repo ../DeepLabCut --xmalab-repo ../xmalab +``` + +## 5) Compatibility notes + +The local workflow integration path expects this repo to remain importable in “lite mode” when GUI dependencies are unavailable, and relies on the public `deeplabcut` import surface plus the synthetic project helpers under `examples/utils.py`. diff --git a/docs/dlc-utils/index.md b/docs/dlc-utils/index.md index 432c5c149..6127abc18 100644 --- a/docs/dlc-utils/index.md +++ b/docs/dlc-utils/index.md @@ -18,7 +18,14 @@ align: right --- ``` -This repository contains various scripts as well as links to other packages related to [DeepLabCut](https://github.com/AlexEMG/DeepLabCut). Feel free to contribute your own analysis methods, and perhaps some short notebook of how to use it. Thanks! +The DeepLabCut-Utils repository contains various scripts as well as links to other packages related to [DeepLabCut](https://github.com/AlexEMG/DeepLabCut). Feel free to contribute your own analysis methods, and perhaps some short notebook of how to use it. Thanks! + +```{admonition} DLC-Utils +--- +class: tip +--- +[Link to repository](https://github.com/DeepLabCut/DLCutils) +``` ```{caution} Please direct inquiries to the **contributors/code maintainers of that code**. Note that the software(s) are provided "as is", without warranty of any kind, express. @@ -34,6 +41,19 @@ These two scripts illustrate how to train, test, and analyze videos for multiple Contributed by [Alexander Mathis](https://github.com/AlexEMG) +## Using DLC + XROMM_DLCTools + xmalab + +> Contributed by [@homfunc](https://github.com/homfunc) + +The DeepLabCut repository can also be used as a sibling checkout together with: + +- `../XROMM_DLCTools` +- `../xmalab` + +In that local layout, `XROMM_DLCTools` uses the optional `dlc` dependency group to import this checkout directly, and its baseline harness runs both a DeepLabCut smoke scenario and a broader end-to-end local workflow integration scenario. + +See {ref}`file:xamalab-dlc-integration` for the local integration notes and exact commands. + ## Using your DLC outputs, loading, simple ROI analysis, visualization examples ### Time spent of a body part in a particular region of interest (ROI)