From b30e2337ebac20ab009eea6616f1de8394b6c6d8 Mon Sep 17 00:00:00 2001 From: MMathisLab Date: Thu, 16 Apr 2026 16:33:51 +0200 Subject: [PATCH 1/4] Improve README setup for running all demos locally. Document local editable installation, clarify demo-specific optional dependencies, and expand demo commands/output notes so users can run no-TTA, TTA, and Gradio demos with the required packages. Made-with: Cursor --- README.md | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ecc48d2..507b02b 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ PRIMA creates a 3D quadruped mesh from a single 2D image. It leverages BioCLIP-b ## Installation -### Install from PyPI +### Local setup (recommended for running demos from this repository) > Recommended: Python 3.10 and a CUDA-enabled PyTorch installation that you manage yourself. @@ -36,17 +36,25 @@ pip install --index-url https://download.pytorch.org/whl/cu118 \ python -m pip install --no-build-isolation \ "git+https://github.com/mattloper/chumpy.git" -# Install PRIMA core package (from PyPI / TestPyPI) -pip install \ - --index-url https://test.pypi.org/simple/ \ - --extra-index-url https://pypi.org/simple \ - prima-animal==0.1.7 +# Install PRIMA from this cloned repository +pip install -e . # Install PyTorch3D python -m pip install --no-build-isolation "git+https://github.com/facebookresearch/pytorch3d.git" ``` -The `prima-animal` package installs most Python dependencies required by PRIMA, except heavy components such as PyTorch, Detectron2 and PyTorch3D. +The local editable install (`pip install -e .`) installs the core PRIMA Python package from your cloned source tree. Heavy components such as PyTorch, Detectron2 and PyTorch3D are still installed separately. + +### Install from PyPI (package-only usage) + +If you only want to consume the package and not edit repo code: + +```bash +pip install \ + --index-url https://test.pypi.org/simple/ \ + --extra-index-url https://pypi.org/simple \ + prima-animal==0.1.7 +``` ### Optional dependencies @@ -69,6 +77,12 @@ needed for certain demos or advanced features: pip install "deeplabcut@git+https://github.com/DeepLabCut/DeepLabCut.git" ``` +### Demo dependency matrix + +- `demo.py` (no TTA): requires **Detectron2** +- `demo_tta.py` (with TTA): requires **Detectron2 + DeepLabCut** +- `app.py` (Gradio web demo): requires **Detectron2 + DeepLabCut** (plus Gradio, already in `prima-animal` dependencies) + --- ## Demo @@ -121,6 +135,8 @@ python demo.py \ --out_folder demo_out/ ``` +Outputs are written to `demo_out/`. + --- ### Demo (with TTA) @@ -132,10 +148,14 @@ Example: ```bash python demo_tta.py \ --checkpoint data/PRIMAS1/checkpoints/s1ckpt.ckpt \ + --img_folder demo_data/ \ + --out_folder demo_out_tta/ \ --tta_lr 1e-6 \ --tta_num_iters 30 ``` +Outputs are written to `demo_out_tta/` (before/after TTA renders, keypoints, and optional meshes). + --- ### Gradio demo @@ -149,7 +169,7 @@ python app.py \ --out_folder demo_out_tta_gradio/ ``` -This will start a local Gradio app (by default on http://127.0.0.1:7860), where +This starts a local Gradio app (by default on http://127.0.0.1:7860), where you can upload images and visualize PRIMA predictions and adaptation results. --- From f0912886965bc4b038f21ef2b2a8747bf4880be8 Mon Sep 17 00:00:00 2001 From: MMathisLab Date: Thu, 16 Apr 2026 16:39:20 +0200 Subject: [PATCH 2/4] Refactor README installation instructions for clarity and conciseness. Streamlined local setup details, emphasized PyPI installation, and consolidated optional dependencies for better user guidance. --- README.md | 58 ++++++++----------------------------------------------- 1 file changed, 8 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 507b02b..1c13682 100644 --- a/README.md +++ b/README.md @@ -17,71 +17,29 @@ PRIMA creates a 3D quadruped mesh from a single 2D image. It leverages BioCLIP-b ## Installation -### Local setup (recommended for running demos from this repository) +### Install from PyPI -> Recommended: Python 3.10 and a CUDA-enabled PyTorch installation that you manage yourself. +> Recommended: Python 3.10 and a CUDA-enabled PyTorch installation. ```bash conda create -n prima python=3.10 -y conda activate prima -git clone https://github.com/AdaptiveMotorControlLab/PRIMA.git -cd PRIMA - # Install PyTorch matching your CUDA (example: CUDA 11.8) pip install --index-url https://download.pytorch.org/whl/cu118 \ "torch==2.2.1" "torchvision==0.17.1" "torchaudio==2.2.1" -# Install chumpy +# Install chumpy and PyTorch3D python -m pip install --no-build-isolation \ "git+https://github.com/mattloper/chumpy.git" +python -m pip install --no-build-isolation \ + "git+https://github.com/facebookresearch/pytorch3d.git" -# Install PRIMA from this cloned repository -pip install -e . - -# Install PyTorch3D -python -m pip install --no-build-isolation "git+https://github.com/facebookresearch/pytorch3d.git" -``` - -The local editable install (`pip install -e .`) installs the core PRIMA Python package from your cloned source tree. Heavy components such as PyTorch, Detectron2 and PyTorch3D are still installed separately. - -### Install from PyPI (package-only usage) - -If you only want to consume the package and not edit repo code: - -```bash -pip install \ - --index-url https://test.pypi.org/simple/ \ - --extra-index-url https://pypi.org/simple \ - prima-animal==0.1.7 +# Install PRIMA from PyPI +pip install prima-animal==0.1.7 ``` -### Optional dependencies - -The following packages are **not** hard requirements of `prima-animal`, but are -needed for certain demos or advanced features: - -- **Detectron2** – animal detection backbone used in `demo.py`, `demo_tta.py`, and `app.py`: - - ```bash - # See Detectron2 docs and choose the wheel matching your torch/CUDA - python -m pip install --no-build-isolation \ - "git+https://github.com/facebookresearch/detectron2.git" - ``` - - -- **DeepLabCut** – only required when using 2D keypoint TTA in - `demo_tta.py` and `app.py`: - - ```bash - pip install "deeplabcut@git+https://github.com/DeepLabCut/DeepLabCut.git" - ``` - -### Demo dependency matrix - -- `demo.py` (no TTA): requires **Detectron2** -- `demo_tta.py` (with TTA): requires **Detectron2 + DeepLabCut** -- `app.py` (Gradio web demo): requires **Detectron2 + DeepLabCut** (plus Gradio, already in `prima-animal` dependencies) +`prima-animal` includes demo runtime dependencies used by `demo.py`, `demo_tta.py`, and `app.py` (including Detectron2 and DeepLabCut). --- From a1768b86895fe70e545ff165e6d7a36d81c163a8 Mon Sep 17 00:00:00 2001 From: MMathisLab Date: Thu, 16 Apr 2026 16:40:21 +0200 Subject: [PATCH 3/4] Include demo dependencies in main package installation. Add Detectron2 and DeepLabCut to core dependencies so the default PRIMA installation includes packages required for demo execution. Made-with: Cursor --- pyproject.toml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index c114432..d546f4c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,6 +67,10 @@ dependencies = [ # Training framework "pytorch-lightning==2.5.5", + + # Demo runtime dependencies (included in main PyPI install) + "detectron2 @ git+https://github.com/facebookresearch/detectron2.git", + "deeplabcut", ] [project.optional-dependencies] From e50469f1769c96033b0ee839bbfba82a12fe7597 Mon Sep 17 00:00:00 2001 From: MMathisLab Date: Thu, 16 Apr 2026 16:44:55 +0200 Subject: [PATCH 4/4] Remove pinned PRIMA package version in README install command. Use an unpinned `pip install prima-animal` instruction so users install the latest published release by default. Made-with: Cursor --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1c13682..ed0ea58 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ python -m pip install --no-build-isolation \ "git+https://github.com/facebookresearch/pytorch3d.git" # Install PRIMA from PyPI -pip install prima-animal==0.1.7 +pip install prima-animal ``` `prima-animal` includes demo runtime dependencies used by `demo.py`, `demo_tta.py`, and `app.py` (including Detectron2 and DeepLabCut).