Add Docker support and update test/demo scripts to use automatic Hugging Face downloads by xiu-cs · Pull Request #28 · AdaptiveMotorControlLab/FMPose3D

xiu-cs · 2026-04-07T09:00:30Z

This pull request introduces a Docker-based development environment for FMPose3D, adds a Makefile for common Docker workflows, and improves the robustness and maintainability of the codebase. It also fixes several typos and cleans up unused code. The most important changes are summarized below.

Dockerization and Development Workflow:

Added a new Dockerfile to provide a reproducible environment using PyTorch with CUDA, pre-installs FMPose3D and its dependencies, sets up a non-root user, and configures shell environments for development.
Introduced a Makefile with targets for building, running, and managing the Docker container, streamlining local development and GPU-enabled workflows.

Dependency Management and Weights Handling:

Changed the default model weights path to download from Hugging Face Hub automatically, with an option to use local weights if desired, and centralized the Hugging Face repo ID in fmpose3d.utils.weights. [1] [2]
Improved model weights loading in the demo to use a utility function for resolving the correct weights path based on model type.
Moved HRNet checkpoint downloading to occur only when HRNet functionality is actually used, reducing unnecessary downloads and startup time. [1] [2]

Bug Fixes and Code Quality:

Fixed multiple typos in variable names (e.g., num_peroson → num_person, hight → height) and comments throughout the codebase for clarity and correctness. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14]
Removed unused imports and dead code, including the plot_keypoint, write, and load_json functions from utilitys.py, and the temporary weights validation skip logic. [1] [2] [3] [4]

These changes collectively make the project easier to set up and contribute to, improve code maintainability, and reduce sources of error.

Introduced a Makefile to streamline Docker image building and container management. Added targets for building, running, and executing commands within the Docker container, as well as a production build process. Included help instructions for usage.

Created a Dockerfile to establish a development environment for FMPose3D, including installation of necessary packages, user setup, and configuration for Oh My Zsh. The Dockerfile also ensures proper permissions for model weights and initializes conda for the user.

…_video_kpts function

Modified the script to enable automatic downloading of model weights from Hugging Face Hub by default. Added a commented line for users to specify local weights if desired.

Modified the script to set model weights to an empty string by default, enabling automatic downloading from Hugging Face Hub. Added a commented line for users to specify local weights if needed.

…ic downloading from Hugging Face Hub. Added logic to download weights if no local path is specified, improving user experience and flexibility.

…ights from Hugging Face Hub. Updated logic to handle cases where no local weights path is specified, improving usability and flexibility for users.

Copilot

Pull request overview

Adds a Docker-based development environment and updates demo/test entrypoints to default to automatic model-weight downloads from Hugging Face when no local weights path is provided, while deferring HRNet checkpoint downloads until HRNet is actually invoked.

Changes:

Introduces a CUDA-enabled Dockerfile and a Makefile workflow for building/running dev containers.
Updates scripts/ and demo/ Python + shell entrypoints to auto-download *.pth weights from Hugging Face when model_weights_path is empty.
Adjusts HRNet keypoint generation to download checkpoints only when gen_video_kpts() is called.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`Dockerfile`	Adds a PyTorch CUDA runtime image with dev shell tooling and non-root user setup.
`Makefile`	Adds Docker build/run/exec targets and a “production” build target.
`scripts/FMPose3D_main.py`	Adds HF auto-download logic and adjusts checkpoint output directory handling when weights are not local.
`scripts/FMPose3D_test.sh`	Defaults `model_weights_path` to empty to trigger HF downloads.
`demo/vis_in_the_wild.py`	Adds HF auto-download logic for demo weights loading.
`demo/vis_in_the_wild.sh`	Defaults `model_weights_path` to empty to trigger HF downloads.
`fmpose3d/lib/hrnet/gen_kpts.py`	Defers `ensure_checkpoints()` until HRNet keypoint generation is requested.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

xiu-cs · 2026-04-07T12:03:36Z

scripts/FMPose3D_main.py

+        # If no local path is provided, download from Hugging Face Hub
+        if not model_path:
+            from huggingface_hub import hf_hub_download
+            _HF_REPO_ID = "deruyter92/fmpose_temp"
+            hf_filename = f"{args.model_type}.pth"
+            print(f"No local weights path specified. Downloading '{hf_filename}' from Hugging Face ({_HF_REPO_ID})...")
+            model_path = hf_hub_download(repo_id=_HF_REPO_ID, filename=hf_filename)


Copilot · 2026-04-07T09:05:27Z

demo/vis_in_the_wild.py

+    # If no local path is provided, download from Hugging Face Hub
+    if not model_path:
+        from huggingface_hub import hf_hub_download
+        _HF_REPO_ID = "deruyter92/fmpose_temp"
+        hf_filename = f"{args.model_type}.pth"
+        print(f"No local weights path specified. Downloading '{hf_filename}' from Hugging Face ({_HF_REPO_ID})...")
+        model_path = hf_hub_download(repo_id=_HF_REPO_ID, filename=hf_filename)
+


Same as in scripts/FMPose3D_main.py: the Hugging Face repo ID + download logic is duplicated and hard-coded here. Reusing a shared helper/constant (e.g., from the inference API module) would reduce drift and keep the demo aligned with the packaged API behavior.

Copilot · 2026-04-07T09:05:27Z

fmpose3d/lib/hrnet/gen_kpts.py

@@ -153,6 +152,9 @@ def gen_from_image(args, frame, people_sort, human_model, pose_model, det_dim=41


 def gen_video_kpts(path, det_dim=416, num_peroson=1, gen_output=False, type='image'):


Typo in the public function signature: num_peroson should be num_person. Since this function is imported/used elsewhere, rename the parameter and update call sites to avoid perpetuating the misspelling.

@copilot apply changes based on this feedback

Fixed in commit 6254cc8. Renamed num_peroson → num_person in gen_from_image and gen_video_kpts signatures in gen_kpts.py, and updated all call sites in demo/vis_in_the_wild.py and tests/test_demo_human.py.

…e_weights_path function. This change simplifies the logic for loading model weights, enhancing usability by automatically handling local and remote paths.

…weights_path function. This change simplifies the logic for loading model weights, improving usability by automatically handling local and remote paths.

…is change centralizes the repository ID definition, improving maintainability and consistency across the codebase.

Introduced a new utility function in weights.py to handle the resolution of model weights paths. This function allows users to specify a local path or automatically download weights from the Hugging Face Hub if no local path is provided, enhancing usability and flexibility in model weight management.

This new file serves as an initializer for the utils module, allowing for better organization and potential future utility functions related to FMPose3D.

…ng dependencies Modified the test to raise an ImportError with a specific message when the required 'fmpose3d[animals]' package is not installed, improving error handling and clarity in dependency management.

xiu-cs · 2026-04-07T12:03:36Z

scripts/FMPose3D_main.py

+        # If no local path is provided, download from Hugging Face Hub
+        if not model_path:
+            from huggingface_hub import hf_hub_download
+            _HF_REPO_ID = "deruyter92/fmpose_temp"
+            hf_filename = f"{args.model_type}.pth"
+            print(f"No local weights path specified. Downloading '{hf_filename}' from Hugging Face ({_HF_REPO_ID})...")
+            model_path = hf_hub_download(repo_id=_HF_REPO_ID, filename=hf_filename)


Agent-Logs-Url: https://github.com/AdaptiveMotorControlLab/FMPose3D/sessions/2136af56-29a8-4635-9ed4-faf9b8146672 Co-authored-by: xiu-cs <81274389+xiu-cs@users.noreply.github.com>

…accordingly. This change simplifies the build process by eliminating the need for a user-defined source path.

…" to "matrices" and "projectio" to "projection". Additionally, update comment for testing section to reflect correct function name "triangulate".

…lining the inference API code. This change reflects the transition towards a more permanent solution for weight management.

…tes" for improved clarity.

…ion" for improved clarity.

…rguements" to "arguments" and "availible" to "available".

…eamlining the code and improving clarity.

…o "original" and "parameteres" to "parameters".

…mproved clarity in keypoint normalization.

…o "original" and "parameteres" to "parameters".

…itys.py to streamline the code and improve maintainability.

…test organization

…hancing installation process by cloning the repository and cleaning up afterwards.

…omatic downloads from Hugging Face and providing alternative options for local weights.

…onstant `HF_REPO_ID`)

deruyter92

Looks great, very useful PR!

The typo fixes look all good to me!
Nice work on centralizing the HugginFace path loading.
Regarding the docker, you might want to consider improving the reproducibility by pinning the version and making it more robust for all platforms. See my comments.
Thanks for your fixes in the inference api as well! I pushed a small additional change to test_huggingface.py, making use of your new centralized HF_REPO_ID constant.

deruyter92 · 2026-04-08T08:31:32Z

demo/vis_in_the_wild.py

    model_dict = model['CFM'].state_dict()
-    model_path = args.model_weights_path
-    print(model_path)
+    from fmpose3d.utils.weights import resolve_weights_path


Probably better to move to the top, unless you intentionally want it to load only locally in this function ('lazy loading'). But since it is a lighweight import I don't think it provides a real benefit to keep it here.

deruyter92 · 2026-04-08T08:37:02Z

Dockerfile

+RUN python -m pip install --no-cache-dir --upgrade pip && \
+    git clone --depth 1 https://github.com/AdaptiveMotorControlLab/FMPose3D.git /tmp/fmpose3d && \
+    python -m pip install --no-cache-dir "/tmp/fmpose3d[animals,viz]" gdown && \
+    rm -rf /tmp/fmpose3d


Since docker is often used for reproducability, I think it would be best if you pin a specific version here, instead of cloning at HEAD.

Good suggestions! Actually, for the first version, I pinned a specific version, but this PR changes some functions inside the package, which makes the currently released package version not work with the training code.

deruyter92 · 2026-04-08T08:44:25Z

Dockerfile

+RUN groupadd ${USERNAME} --gid ${USER_GID}
+RUN useradd -m -s /bin/bash -g ${USERNAME} -u ${USER_UID} ${USERNAME}


Just to be safe, you could change this to the below suggestion, since the current command may fail if the user allready exists (e.g. in the parent image). But I don't expect that this is a realistic scenario, so you can also keep yours, for better readability.

Suggested change

RUN groupadd ${USERNAME} --gid ${USER_GID}

RUN useradd -m -s /bin/bash -g ${USERNAME} -u ${USER_UID} ${USERNAME}

RUN set -eux; \

if getent group "${USER_GID}" >/dev/null; then \

GROUP_NAME="$(getent group "${USER_GID}" | cut -d: -f1)"; \

else \

groupadd --gid "${USER_GID}" "${USERNAME}"; \

GROUP_NAME="${USERNAME}"; \

fi; \

if id -u "${USER_UID}" >/dev/null 2>&1; then \

EXISTING_USER="$(getent passwd "${USER_UID}" | cut -d: -f1)"; \

usermod -l "${USERNAME}" "${EXISTING_USER}" || true; \

usermod -d "/home/${USERNAME}" -m "${USERNAME}" || true; \

usermod -g "${GROUP_NAME}" "${USERNAME}" || true; \

else \

useradd -m -s /bin/bash -u "${USER_UID}" -g "${GROUP_NAME}" "${USERNAME}"; \

fi

Dockerfile

deruyter92 · 2026-04-08T08:52:52Z

fmpose3d/inference_api/fmpose3d.py


-#: HuggingFace repository hosting the official FMPose3D checkpoints.
-_HF_REPO_ID: str = "deruyter92/fmpose_temp"
+from fmpose3d.utils.weights import HF_REPO_ID as _HF_REPO_ID


Good fix, thanks! Maybe just move it to the import block with the other from fmpose3d ... imports.

Makefile

deruyter92 · 2026-04-08T09:21:59Z

Makefile

+	@echo "  3. Inside container: pip install -e '.[animals,viz]'"
+	@echo "  4. Inside container: sh scripts/FMPose3D_train.sh"


the dockerfile allready installs fmpose, right?

Suggested change

@echo " 3. Inside container: pip install -e '.[animals,viz]'"

@echo " 4. Inside container: sh scripts/FMPose3D_train.sh"

@echo " 3. Inside container: sh scripts/FMPose3D_train.sh"

deruyter92 · 2026-04-08T09:24:28Z

scripts/FMPose3D_main.py

        model_dict = model["CFM"].state_dict()
-        model_path = args.model_weights_path
-        print(model_path)
+        from fmpose3d.utils.weights import resolve_weights_path


consider moving this to the top.

deruyter92 · 2026-04-08T09:39:09Z

side note: maybe not for this PR, but in the future, you may consider setting up linting for automating the formatting a bit.

…ts_path and add it back in a more appropriate location for better code organization.

Co-authored-by: Jaap de Ruyter van Steveninck <32810691+deruyter92@users.noreply.github.com>

… top for better organization and remove redundant import in the main execution block.

deruyter92

Looks good to me!!

xiu-cs added 7 commits April 7, 2026 00:07

Ensure checkpoints are downloaded only when HRNet is requested in gen…

43aef6e

…_video_kpts function

Update FMPose3D_test.sh to allow optional local model weights

bb79602

Modified the script to enable automatic downloading of model weights from Hugging Face Hub by default. Added a commented line for users to specify local weights if desired.

Update vis_in_the_wild.sh to allow optional local model weights

d66a0a0

Modified the script to set model weights to an empty string by default, enabling automatic downloading from Hugging Face Hub. Added a commented line for users to specify local weights if needed.

Enhance model weight loading in vis_in_the_wild.py to support automat…

c43b46b

…ic downloading from Hugging Face Hub. Added logic to download weights if no local path is specified, improving user experience and flexibility.

Enhance FMPose3D_main.py to support automatic downloading of model we…

74d2dab

…ights from Hugging Face Hub. Updated logic to handle cases where no local weights path is specified, improving usability and flexibility for users.

xiu-cs requested a review from Copilot April 7, 2026 09:00

Copilot started reviewing on behalf of xiu-cs April 7, 2026 09:01 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

xiu-cs added 8 commits April 7, 2026 11:15

Refactor model weight loading in vis_in_the_wild.py to utilize resolv…

30eb7fc

…e_weights_path function. This change simplifies the logic for loading model weights, enhancing usability by automatically handling local and remote paths.

Refactor model weight loading in FMPose3D_main.py to utilize resolve_…

53aefde

…weights_path function. This change simplifies the logic for loading model weights, improving usability by automatically handling local and remote paths.

Refactor FMPose3D to import Hugging Face repository ID from utils. Th…

1ff5d01

…is change centralizes the repository ID definition, improving maintainability and consistency across the codebase.

Add __init__.py file to utils directory for FMPose3D

ce1c4f0

This new file serves as an initializer for the utils module, allowing for better organization and potential future utility functions related to FMPose3D.

add header

e122e51

add header

3d1253a

Update test for SuperAnimalPrediction to handle ImportError for missi…

ec10769

…ng dependencies Modified the test to raise an ImportError with a specific message when the required 'fmpose3d[animals]' package is not installed, improving error handling and clarity in dependency management.

AdaptiveMotorControlLab deleted a comment from Copilot AI Apr 7, 2026

xiu-cs commented Apr 7, 2026

View reviewed changes

AdaptiveMotorControlLab deleted a comment from Copilot AI Apr 7, 2026

Copilot started work on behalf of xiu-cs April 7, 2026 12:05 View session

Fix typo: num_peroson -> num_person in gen_kpts.py and call sites

6254cc8

Agent-Logs-Url: https://github.com/AdaptiveMotorControlLab/FMPose3D/sessions/2136af56-29a8-4635-9ed4-faf9b8146672 Co-authored-by: xiu-cs <81274389+xiu-cs@users.noreply.github.com>

Copilot finished work on behalf of xiu-cs April 7, 2026 12:08

Remove build_production target from Makefile and update help message …

d6e1fdb

…accordingly. This change simplifies the build process by eliminating the need for a user-defined source path.

xiu-cs requested a review from deruyter92 April 7, 2026 12:16

xiu-cs added 2 commits April 7, 2026 14:56

Fix typos in comments for clarity in lifter3d.py, correcting "matrics…

3bb81e5

…" to "matrices" and "projectio" to "projection". Additionally, update comment for testing section to reflect correct function name "triangulate".

Remove temporary weights validation sentinel from fmpose3d.py, stream…

f1631c9

…lining the inference API code. This change reflects the transition towards a more permanent solution for weight management.

xiu-cs and others added 13 commits April 7, 2026 14:57

Fix typo in comment of bbox.py, correcting "corrdinates" to "coordina…

962f395

…tes" for improved clarity.

Fix typo in comment of darknet.py, correcting "anotation" to "annotat…

09ce42f

…ion" for improved clarity.

Fix typos in comments for clarity in human_detector.py, correcting "a…

94b5100

…rguements" to "arguments" and "availible" to "available".

Remove unused import of plot_keypoint and write from gen_kpts.py, str…

b2151a6

…eamlining the code and improving clarity.

Fix typos in comments for clarity in utils.py, correcting "origial" t…

ef803e7

…o "original" and "parameteres" to "parameters".

Fix typo in animal3d_dataset.py, correcting "hight" to "height" for i…

bdd95b1

…mproved clarity in keypoint normalization.

Fix typos in comments for clarity in utils.py, correcting "origial" t…

6107a7a

…o "original" and "parameteres" to "parameters".

Remove unused functions plot_keypoint, write, and load_json from util…

2b1626d

…itys.py to streamline the code and improve maintainability.

Add testpaths configuration to pytest in pyproject.toml for improved …

c944d25

…test organization

Update Dockerfile to install FMPose3D from GitHub instead of PyPI, en…

e185185

…hancing installation process by cloning the repository and cleaning up afterwards.

Update HF_REPO_ID

11ab3d3

Update README.md to clarify pre-trained model setup, highlighting aut…

2f5f771

…omatic downloads from Hugging Face and providing alternative options for local weights.

fix test_hugginface.py: change huggingface repo ID (use centralized c…

52c2497

…onstant `HF_REPO_ID`)

deruyter92 reviewed Apr 8, 2026

View reviewed changes

xiu-cs and others added 6 commits April 8, 2026 11:53

Refactor vis_in_the_wild.py: remove redundant import of resolve_weigh…

89ff316

…ts_path and add it back in a more appropriate location for better code organization.

Update Dockerfile

9f46de8

Co-authored-by: Jaap de Ruyter van Steveninck <32810691+deruyter92@users.noreply.github.com>

Update Makefile

478abcd

Co-authored-by: Jaap de Ruyter van Steveninck <32810691+deruyter92@users.noreply.github.com>

Update Makefile

8098412

Co-authored-by: Jaap de Ruyter van Steveninck <32810691+deruyter92@users.noreply.github.com>

Update Makefile

1eb00b4

Co-authored-by: Jaap de Ruyter van Steveninck <32810691+deruyter92@users.noreply.github.com>

Refactor FMPose3D_main.py: move import of resolve_weights_path to the…

8b402c3

… top for better organization and remove redundant import in the main execution block.

xiu-cs requested a review from deruyter92 April 9, 2026 12:26

deruyter92 approved these changes Apr 10, 2026

View reviewed changes

xiu-cs merged commit 1a7439f into main Apr 10, 2026
5 checks passed

xiu-cs deleted the dockerfile branch April 10, 2026 08:17

		@@ -153,6 +152,9 @@ def gen_from_image(args, frame, people_sort, human_model, pose_model, det_dim=41


		def gen_video_kpts(path, det_dim=416, num_peroson=1, gen_output=False, type='image'):

		RUN groupadd ${USERNAME} --gid ${USER_GID}
		RUN useradd -m -s /bin/bash -g ${USERNAME} -u ${USER_UID} ${USERNAME}

-RUN groupadd ${USERNAME} --gid ${USER_GID}
-RUN useradd -m -s /bin/bash -g ${USERNAME} -u ${USER_UID} ${USERNAME}
+RUN set -eux; \
+    if getent group "${USER_GID}" >/dev/null; then \
+        GROUP_NAME="$(getent group "${USER_GID}" | cut -d: -f1)"; \
+    else \
+        groupadd --gid "${USER_GID}" "${USERNAME}"; \
+        GROUP_NAME="${USERNAME}"; \
+    fi; \
+    if id -u "${USER_UID}" >/dev/null 2>&1; then \
+        EXISTING_USER="$(getent passwd "${USER_UID}" | cut -d: -f1)"; \
+        usermod -l "${USERNAME}" "${EXISTING_USER}" || true; \
+        usermod -d "/home/${USERNAME}" -m "${USERNAME}" || true; \
+        usermod -g "${GROUP_NAME}" "${USERNAME}" || true; \
+    else \
+        useradd -m -s /bin/bash -u "${USER_UID}" -g "${GROUP_NAME}" "${USERNAME}"; \
+    fi

		@echo " 3. Inside container: pip install -e '.[animals,viz]'"
		@echo " 4. Inside container: sh scripts/FMPose3D_train.sh"

	@echo " 3. Inside container: pip install -e '.[animals,viz]'"
	@echo " 4. Inside container: sh scripts/FMPose3D_train.sh"
	@echo " 3. Inside container: sh scripts/FMPose3D_train.sh"

Conversation

xiu-cs commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deruyter92 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deruyter92 commented Apr 8, 2026

Uh oh!

deruyter92 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

xiu-cs commented Apr 7, 2026 •

edited

Loading