bishoygaloaa/Motion-o-MCoT-PLM-motion-keyframes

---
configs:
- config_name: default
data_files:
- split: train
path: json_data/STGR-SFT-motion-mixed-PLM-motion-only.json
---

# Motion-o-MCoT (PLM + motion keyframes)

Subset of STGR: `STR_plm_rdcap` rows with `<motion` in `reasoning_process`, plus sharded keyframes under `videos/stgr/plm/kfs/`.

- **Train split:** 3,168 examples (see `export_manifest.json` in the repo for exact export stats).
- **Keyframes:** JPEGs are stored under shard subfolders (e.g. `videos/stgr/plm/kfs/plm_0150/…`) so each directory stays under Hugging Face file-count limits. Each `key_frames[].path` in the JSON is **relative to** `videos/stgr/plm/kfs/` (e.g. `plm_0150/plm_015078_0_time_0.5.jpg`).
- **Videos:** Full PLM source videos are **not** included in this release; `video_path_full` in the JSON is a **relative** path under the dataset root (e.g. `videos/sav_036475.mp4`) for compatibility with a full STGR tree if you have it locally.

## Download

### Hugging Face CLI (`hf`)

```bash
hf auth login

# Full snapshot (JSON + all keyframe images)
hf download bishoygaloaa/Motion-o-MCoT-PLM-motion-keyframes \
--repo-type dataset \
--local-dir ./Motion-o-MCoT-PLM-motion-keyframes
```

### Python (`huggingface_hub`)

```python
from huggingface_hub import snapshot_download

snapshot_download(
repo_id="bishoygaloaa/Motion-o-MCoT-PLM-motion-keyframes",
repo_type="dataset",
local_dir="./Motion-o-MCoT-PLM-motion-keyframes",
)
```

### JSON only (small)

```bash
hf download bishoygaloaa/Motion-o-MCoT-PLM-motion-keyframes \
--repo-type dataset \
--include "json_data/*" \
--include "export_manifest.json" \
--local-dir ./Motion-o-MCoT-PLM-motion-keyframes
```

## Use with `datasets`

```python
from datasets import load_dataset

ds = load_dataset(
"bishoygaloaa/Motion-o-MCoT-PLM-motion-keyframes",
split="train",
)
print(len(ds), ds[0].keys())
print(ds[0]["key_frames"][0]["path"]) # e.g. plm_0150/plm_015078_0_time_0.5.jpg
```

## Resolve keyframe files on disk

After downloading, set a root directory `DATA_ROOT` to the folder that contains both `json_data/` and `videos/`. Then each keyframe absolute path is:

```text
{DATA_ROOT}/videos/stgr/plm/kfs/{key_frames[i]["path"]}
```

Example:

```python
import os

DATA_ROOT = "./Motion-o-MCoT-PLM-motion-keyframes" # or absolute path
rel = ds[0]["key_frames"][0]["path"]
abs_path = os.path.join(DATA_ROOT, "videos", "stgr", "plm", "kfs", rel)
assert os.path.isfile(abs_path), abs_path
```

This matches the layout expected by the Motion-o / Open-o3 training code when `DATA_ROOT` points at a full STGR-style tree (`videos/stgr/plm/kfs/` + basename or shard-relative path in JSON).

## Hub URL

[https://huggingface.co/datasets/bishoygaloaa/Motion-o-MCoT-PLM-motion-keyframes](https://huggingface.co/datasets/bishoygaloaa/Motion-o-MCoT-PLM-motion-keyframes)

## Citation

If you use this subset, please cite the Motion-o paper and the STGR / Open-o3 Video sources as appropriate. See the main project repository for BibTeX.