MediaPipe Pose Export: 33 Landmarks to Video + CSV/MAT/NPZ

Run MediaPipe Pose (Tasks API) on a video, overlay all 33 landmarks with indices, and export per-frame pose data to CSV, MAT, and NPZ, plus a _meta.json summary.
Also writes an annotated AVI (or MP4) video.

Repo: https://github.com/KyleKimx/mediapipe-pose-export

---

Demo

Add a 3–5s sample or GIF showing the indexed 33 landmarks. Avoid any private footage. -> Soon

---

Project Structure

mediapipe-pose-export/
├─ assets/models/pose_landmarker_full.task # model (see Setup)
├─ data/videos/sample.mp4 # small demo video
├─ outputs/ # results (generated)
├─ src/extract_pose.py # main script (CLI)
├─ notebooks/quick_viz.ipynb # optional
├─ requirements.txt
├─ .gitignore
├─ LICENSE
└─ README.md

---

Setup

1) Environment

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2) Model

Download pose_landmarker_full.task to assets/models/.

• Official: MediaPipe Pose Landmarker (Tasks API).

• You can store via Git LFS or provide a small download script.

3) Data

Place a short test video at data/videos/sample.mp4 (or pass your own via --video).

---

Usage

python src/extract_pose.py \
  --model assets/models/pose_landmarker_full.task \
  --video data/videos/sample.mp4 \
  --outdir outputs \
  --format avi            # or mp4
  --force_landscape       # optional

Outputs (same stem as input video)

• outputs/<name>.avi – annotated video with 33 landmarks (indexed)
• outputs/<name>.npz – NumPy arrays
• outputs/<name>.mat – MATLAB file
• outputs/<name>.csv – long-format table (frame × landmark)
• outputs/<name>_meta.json – summary (fps, duration, detected frames, etc.)

---

Output Schema

CSV columns

• frame – frame index (0-based)
• t_ms – timestamp in milliseconds
• lm_id – landmark ID (0–32)
• x_px, y_px – pixel coordinates
• z_norm – normalized depth (relative, often negative closer to camera)
• visibility, presence – model confidence (0–1)
• wx_m, wy_m, wz_m – world coordinates in meters (hip-centered)

NPZ/MAT keys

• timestamps_ms [N]
• pix_xy [N, 33, 2]
• pix_z [N, 33]
• visibility [N, 33]
• presence [N, 33]
• world_xyz [N, 33, 3]

---

Notes

• Effective pose sampling rate is reported as pose_sampling_hz in _meta.json.
• For MP4 output, use --format mp4 or change codec to mp4v in the script.
• Avoid pushing sensitive footage; use a public demo or synthetic data.

---

Roadmap

• Optional JSON dump per frame (all points)
• Smoothing & interpolation utilities
• Velocity/speed computation examples
• Wide-format export for ML pipelines

---

License

MIT © Byounguk Kim

---

Citation

If you use this code, please cite this repository and MediaPipe:
@software{kim_mediapipe_pose_export_2025,
  title        = {MediaPipe Pose Export: 33 Landmarks to Video + CSV/MAT/NPZ},
  author       = {Byounguk Kim},
  year         = {2025},
  url          = {https://github.com/KyleKimx/mediapipe-pose-export}
}

---

License

This project is licensed under the MIT License. See LICENSE for details.