Add fine-tuned SuperAnimal-Quadruped support and improve demo setup

.github/workflows/codespell.yml

@@ -18,4 +18,4 @@ jobs:
       - name: Codespell
         uses: codespell-project/actions-codespell@v1
         with:
-           ignore_words_list: fmpose, mpjpe, uvd, xyz, hm36, cpn, dbb
+           ignore_words_list: fmpose, mpjpe, uvd, xyz, hm36, cpn, dbb, mot

README.md

@@ -31,7 +31,7 @@ FMPose3D creates a 3D pose from a single 2D image. It leverages fast Flow Matchi
 
 ### Set up an environment
 
-Make sure you have Python 3.10+. You can set this up with:
+Make sure you have Python 3.10. The installation and demos are tested with Python 3.10. You can set this up with:
 ```bash
 conda create -n fmpose_3d python=3.10
 conda activate fmpose_3d
@@ -45,6 +45,8 @@ For the animal pipeline, install the optional DeepLabCut dependency:
 pip install "fmpose3d[animals]"
 ```
 
+> **PyTorch/CUDA note.** FMPose3D pins `torch>=2.4.1,<2.5` and `torchvision>=0.19.1,<0.20`, which use CUDA 12.1 wheels by default on Linux. If your driver does not support CUDA 12.1, or if you need a specific CUDA build, install PyTorch first using the matching command from [pytorch.org](https://pytorch.org/get-started/locally/), then install `fmpose3d`.
+
 ## Demos
 
 ### Testing on in-the-wild images (humans)
@@ -108,7 +110,7 @@ FMPose3D also ships a high-level Python API for end-to-end 3D pose estimation fr
 
 ## Experiments on non-human animals
 
-For animal training/testing and demo scripts, see [animals/README.md](animals/README.md).
+For animal training/testing and demo scripts, see [animals/README.md](animals/README.md). The animal demo **auto-downloads both checkpoints** (a 26-joint SuperAnimal-Quadruped fine-tuned on Animal3D for 2D pose, and the FMPose3D animal flow-matching lifter for 3D) from [Hugging Face](https://huggingface.co/MLAdaptiveIntelligence/FMPose3D) on first run — no manual setup needed.
 
 ## Citation 
 

animals/README.md

@@ -9,8 +9,10 @@ In this part, the FMPose3D model is trained on [Animal3D](https://xujiacong.gith
 
 This visualization script is designed for single-frame based model, allowing you to easily run 3D animal pose estimation on any single image.
 
-Before testing, make sure you have the pre-trained model ready.
-You may either use the model trained by your own or download ours from [here](https://drive.google.com/drive/folders/1kL4aOyWNq0o9zB0rSTRM8KYgkySVmUTk?usp=drive_link) and place it in the `./pre_trained_models` directory.
+Both pre-trained checkpoints are **auto-downloaded from [Hugging Face](https://huggingface.co/MLAdaptiveIntelligence/FMPose3D)** 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:
 ```bash
@@ -49,7 +51,7 @@ Place the downloaded files in the `dataset/` folder of this project:
 ## Training
 The training logs, checkpoints, and related files of each training time will be saved in the './checkpoint' folder.
 
-For trainig on the two datasets:
+For training on the two datasets:
 
 ```bash
 cd animals