Update README.md

README.md

@@ -1,3 +1,85 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+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="<org>/<repo>", filename="fmpose3d_humans.pth")
+# or
+path = hf_hub_download(repo_id="<org>/<repo>", 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
+
+Apache 2.0. We thank the Swiss National Science Foundation (SNSF Project # 320030-227871) and the Kavli Foundation for financial support.