# AthletePose3D Dataset for Kinemotion Validation

This directory is for the AthletePose3D dataset, used to validate the accuracy of Kinemotion's pose tracking and kinematic metrics against gold-standard research data.

## License Requirements

Before downloading, you must read and accept the **AthletePose3D Non-Commercial Research License**:
[https://github.com/calvinyeungck/AthletePose3D/blob/main/license/README.md](https://github.com/calvinyeungck/AthletePose3D/blob/main/license/README.md)

## Download Instructions

1. **Accept License:** Visit the [License Page](https://github.com/calvinyeungck/AthletePose3D/blob/main/license/README.md).
1. **Download Link:** [Google Drive - AthletePose3D Dataset](https://drive.google.com/drive/folders/10YnMJAluiscnLkrdiluIeehNetdry5Ft?usp=sharing)
1. **Priority Subset:** Download the **Figure Skating** subset (recommended priority for jump analysis).
1. **Extract:** Place raw `.mp4/.mov` files in `videos/` and `.pkl/.npy` ground truth in `ground_truth/`.

## Directory Structure

```
data/athletepose3d/
├── README.md              # This file
├── videos/                # Place raw .mp4/.mov files here
├── ground_truth/          # Place .pkl/.npy ground truth files here
├── annotations/           # (Optional) COCO format annotations
└── manifest.json          # Generated by scripts/ap3d/prepare_ap3d_data.py
```

## Quick Start

Once you have downloaded the data:

1. **Prepare the manifest:**

   ```bash
   python scripts/ap3d/prepare_ap3d_data.py
   ```

1. **Run baseline validation:**

   ```bash
   python scripts/ap3d/validate_baseline.py
   ```

1. **Review the report:**
   Check `reports/ap3d_baseline_validation.md` for results.

## Citation

If you use this dataset in your research, please cite:

```bibtex
@misc{yeung2025athletepose3d,
  title={AthletePose3D: A Benchmark Dataset for 3D Human Pose Estimation and Kinematic Validation in Athletic Movements},
  author={Calvin Yeung and Tomohiro Suzuki and Ryota Tanaka and Zhuoer Yin and Keisuke Fujii},
  year={2025},
  eprint={2503.07499},
  archivePrefix={arXiv}
}
```
