README.md

---
library_name: fmpose3d
pipeline_tag: image-to-3d
tags:
  - pose-estimation
  - 3d-pose-estimation
  - monocular
  - flow-matching
  - human-pose
  - animal-pose
  - pytorch
datasets:
  - human3.6m
  - animal3d
language:
  - en
---

# FMPose3D: Monocular 3D Pose Estimation via Flow Matching

Official model weights for **[FMPose3D: monocular 3D pose estimation via flow matching](https://arxiv.org/abs/2602.05755)** by Ti Wang, Xiaohang Yu, and Mackenzie Weygandt Mathis.

| [Paper](https://arxiv.org/abs/2602.05755) | [Project Page](https://xiu-cs.github.io/FMPose3D/) | [GitHub](https://github.com/AdaptiveMotorControlLab/FMPose3D) | [PyPI](https://pypi.org/project/fmpose3d/) |

## Overview

FMPose3D lifts 2D keypoints from a single image into 3D poses using **flow matching** — a generative technique based on ODE sampling. It generates multiple plausible 3D pose hypotheses in just a few steps, then aggregates them using a reprojection-based Bayesian module (RPEA) for accurate predictions, achieving state-of-the-art results on human and animal 3D pose benchmarks.

## Available Checkpoints

| Filename | Skeleton | Joints | Training Data | Description |
|---|---|---|---|---|
| `fmpose3d_humans.pth` | H36M | 17 | Human3.6M | Human 3D pose estimation |
| `fmpose3d_animals.pth` | Animal3D | 26 | Animal3D | Quadruped animal 3D pose estimation |

## Quick Start

```bash
pip install fmpose3d
```

Weights are downloaded automatically when using the Python API:

```python
from fmpose3d import FMPose3DInference

# Human — weights auto-downloaded on first use
result = FMPose3DInference().predict("photo.jpg")

# Animal
result = FMPose3DInference.for_animals().predict("dog.jpg")
```

For the full API reference, see the [GitHub repository](https://github.com/AdaptiveMotorControlLab/FMPose3D).

## Manual Download

```python
from huggingface_hub import hf_hub_download

path = hf_hub_download(repo_id="DeepLabCut/FMPose3D", filename="fmpose3d_humans.pth")
# or
path = hf_hub_download(repo_id="DeepLabCut/FMPose3D", filename="fmpose3d_animals.pth")

api = FMPose3DInference(model_weights_path=path)
```

## Citation

```bibtex
@misc{wang2026fmpose3dmonocular3dpose,
      title={FMPose3D: monocular 3D pose estimation via flow matching}, 
      author={Ti Wang and Xiaohang Yu and Mackenzie Weygandt Mathis},
      year={2026},
      eprint={2602.05755},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2602.05755}, 
}
```

## License

Model weights are for non-commerical use. Please contact the EPFL TTO for future information.  We thank the Swiss National Science Foundation (SNSF Project # 320030-227871) and the Kavli Foundation for financial support.