README.md

Animals

In this part, the FMPose3D model is trained on Animal3D dataset and Control_Animal3D dataset.

Demo

Testing on in-the-wild images (animals)

This visualization script is designed for single-frame based model, allowing you to easily run 3D animal pose estimation on any single image.

Both pre-trained checkpoints are auto-downloaded from Hugging Face on first run and cached under ~/.cache/huggingface/. No manual downloads required.

• 3D lifter (fmpose3d_animals.pth) — Animal3D 26-joint flow-matching 2D→3D lifter. Override: set saved_model_path in vis_animals.sh to a local .pth.
• 2D pose model (sa_finetune_hrnet_w32.pt) — SuperAnimal-Quadruped HRNet-w32 fine-tuned on Animal3D for the 26-joint Animal3D output layout. Override: set saved_2d_model_path in vis_animals.sh to a local .pt.

Next, put your test images into folder demo/images. Then run the visualization script:

sh vis_animals.sh

The predictions will be saved to folder demo/predictions.

Datasets

Download the Animal3D dataset from here

Download the control_animal3D dataset from here

Place the downloaded files in the dataset/ folder of this project:

<project_root>/
├── dataset/
│   ├── animal3d
│       ├── images
│       ├── train.json
│       ├── test.json
│   ├── control_animal3d
│       ├── images
│       ├── train.json
│       ├── test.json

Training

The training logs, checkpoints, and related files of each training time will be saved in the './checkpoint' folder.

For training on the two datasets:

cd animals
bash ./scripts/train_animal3d.sh

Inference

Download the pretrained model from here and place it in the ./pre_trained_models directory.

cd animals # the current path is: ./animals
bash ./scripts/test_animal3d.sh