humanoidsctu/alphapose repository overview

This image has been used for the paper: https://link.springer.com/article/10.3758/s13428-025-02816-x⁠ (free access to the pdf: https://rdcu.be/eFwac⁠) The Dockerfile is available at the osf repository: https://osf.io/4zdbr/⁠

⁠0. Prerequisite

The host computer must have the appropriate packages installed to allow GPUs to be used by the Docker containers, e.g., for Nvidia GPUs, it requires to install the Nvidia container toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html⁠⁠

All ready-to-use Docker containers (including this one), are constrained to the dependencies software versions they had when built. The main cause for compatibility issues and the container not working properly comes from the graphic card and the versions of CUDA/cudnn/Pytorch. In particular, any recent enough GPU that is not handled by the pre-installed version would lead to errors, or the images/videos not being processed. In such a case, the fix is to use the Dockerfile shared on our osf and modify the appropriate lines to use versions of the software. For example, using an Nvidia GPU RTX A4000 or A5000 requires to modify the Dockerfile to use CUDA version 11.3, and cudnn 8; then to rebuild a docker container using the updated Dockerfile.

⁠1. Docker build

Dockerfile inspired by: https://github.com/nianjingfeng/AlphaPose_Docker⁠ https://github.com/MVIG-SJTU/AlphaPose/blob/master/docs/INSTALL.md⁠

Also see: https://pythonspeed.com/articles/activate-conda-dockerfile/⁠

docker build -t alphapose:paper .

Due to the script setup.py not running properly and throwing errors when trying to install some of the required packages when building the Docker image from the Dockerfile, we install them through pip before the script is started, causing the script to verify their existence and not throw errors when trying to download them directly. However, one of the packages could not be installed at all, hence we use an altered version of the script removing these packages, which do not impact the running of the method in our particular case :

• Line 166 Removed the installation of halpecocotools package

⁠2. Docker startup

Default command: sudo docker run --rm --gpus all -it -e="DISPLAY" -v=/tmp/.X11-unix:/tmp/.X11-unix:rw -v /home/$user:/home/$user alphapose:paper /bin/bash

Replace $user by the session's username.

Add -v /media:/media to give access to external hard drives

If needed, limit the amount of RAM shared with docker with the parameter: --shm-size=8gb

⁠3. Processing commands for Alphapose:

Replace $data_path by the path to the data folder and $result_path by the path to the result folder.

Memory profiling can be done by adding the following command before the processing commands described below: mprof run --include-children --multiprocess --output $result_path/alphapose/mprofile.dat

If Alphapose gets stuck while loading the pose model it is a known issue that can be fixed by adding the parameter --sp.

To output images with keypoints and skeleton showing, add the parameter --save_img

⁠3.1 Running Alphapose on images without visualisation

python scripts/demo_inference.py --cfg configs/coco/resnet/256x192_res50_lr1e-3_1x-duc.yaml --checkpoint pretrained_models/fast_421_res50-shuffle_256x192.pth --indir $data_path/images/ --outdir $result_path/alphapose/ --detbatch 2 --posebatch 40

⁠3.2 Running Alphapose on video without visualisation

python scripts/demo_inference.py --cfg configs/coco/resnet/256x192_res50_lr1e-3_1x-duc.yaml --checkpoint pretrained_models/fast_421_res50-shuffle_256x192.pth --video $data_path/$video --outdir $result_path/alphapose/ --detbatch 2 --posebatch 40

Replace $video by the name of the video to process.

To avoid potential changes or unavailability of the file, and ensure reproduction of results the model weights were downloaded on 2023.11.06 from the google documents linked on the AlphaPose github repository as files fast_421_res50-shuffle_256x192.pth and yolov3-spp.weights, added to the gitlab repository, and the local version is used to run Detectron2, rather than being always downloaded from facebook servers.