Yuchn/event-graph-vjepa-vitl-dataset

---
license: mit
tags:
- video-understanding
- event-graph
- vjepa
- slot-attention
- pytorch
- synthetic-annotations
task_categories:
- video-classification
language:
- ja
size_categories:
- 1K<n<10K
---

# Event Graph Generation Dataset — V-JEPA 2.1 ViT-L Features + VLM Annotations

## 1. データセット概要

動画から構造化されたイベントグラフ（**誰が**・**何を**・**どこから**・**どこへ**）を予測するための学習データセットです。

室内環境（デスク・キッチン・部屋）の録画動画を対象に、以下の 2 種類のデータを含みます：

1. **映像特徴量（Features）**: [V-JEPA 2.1](https://github.com/facebookresearch/vjepa) ViT-L（frozen）で抽出した時空間トークン（PyTorch `.pt` 形式）
2. **合成アノテーション（Annotations）**: [Qwen 3.5](https://huggingface.co/Qwen) VLM による自動生成アノテーション（JSON 形式）。オブジェクト検出・イベント（行動）記述を含む

## 2. データの内容・件数

| 項目 | 値 |
|---|---|
| 動画数 | 5 |
| クリップ数（16フレーム/クリップ） | 933 |
| 特徴量サイズ合計 | 17.61 GB |
| アノテーション JSON | 5 ファイル |
| V-JEPA backbone | `vjepa2_1_vit_large_384` |
| 特徴量次元 | 1024 |
| トークン数/クリップ | 4608（8 temporal x 576 spatial） |
| 入力画像サイズ | 384px |
| クリップ長 | 16 frames @ 1.0 FPS |
| オブジェクトカテゴリ数 | 28 |
| アクションクラス数 | 13 |

### 収録動画一覧

| Video ID | クリップ数 | アノテーション済み | イベントあり | 特徴量サイズ |
|---|---|---|---|---|
| `20260318_094525_tp00067` | 27 | 24 | 23 | 510 MB |
| `20260316_221254_tp00015` | 209 | 210 | 210 | 3945 MB |
| `20260317_140300_tp00039` | 228 | 171 | 170 | 4304 MB |
| `20260316_192536_tp00010` | 230 | 214 | 164 | 4342 MB |
| `20260316_195628_tp00011` | 239 | 226 | 220 | 4511 MB |

## 3. フォーマット・カラム説明

### 3.1 特徴量ファイル（`features/<video_id>/clip_XXXX.pt`）

**フォーマット**: PyTorch `.pt` ファイル（`torch.load()` で読み込み）

| キー | 型 | Shape / 値 | 説明 |
|---|---|---|---|
| `vjepa_tokens` | `Tensor` (float32) | `(4608, 1024)` | V-JEPA 2.1 ViT-L が出力した時空間トークン。8 temporal x 576 spatial tokens |
| `video_id` | `str` | `"20260316_130406_tp00001"` | 動画の一意識別子（録画日時 + 連番） |
| `clip_index` | `int` | `0` ~ | クリップの連番（動画内での順序） |
| `frame_indices` | `list[int]` | 長さ 16 | 元動画のフレームインデックス（例: `[0, 20, 40, ...]`） |

### 3.2 アノテーションファイル（`annotations/<video_id>.json`）

**フォーマット**: JSON

**トップレベル構造**:

| キー | 型 | 説明 |
|---|---|---|
| `video_id` | `str` | 動画 ID |
| `video_path` | `str` | 元動画のパス |
| `video_metadata` | `object` | `source_fps`, `target_fps`, `duration_sec`, `video_start_time`, `video_end_time` 等 |
| `coverage` | `object` | `total_clips`, `annotated_clips`, `motion_filtered_clips`, `clips_with_events` 等の統計 |
| `num_clips` | `int` | 総クリップ数 |
| `validation_stats` | `object` | VLM 出力のバリデーション統計（`discard_rate` 等） |
| `clips` | `list[object]` | 各クリップのアノテーション |

**`clips[i]` の構造**:

| キー | 型 | 説明 |
|---|---|---|
| `objects` | `list[object]` | 検出されたオブジェクト一覧 |
| `events` | `list[object]` | イベント（行動）一覧 |
| `clip_metadata` | `object` | `clip_index`, `frame_indices`, `start_time`, `end_time`, `status` |

**`objects[j]` のフィールド**:

| キー | 型 | 説明 |
|---|---|---|
| `obj_id` | `str` | オブジェクト ID（例: `"person_01"`, `"laptop_01"`） |
| `category` | `str` | カテゴリ名（28 クラスのいずれか） |
| `first_seen_frame` | `int` | オブジェクトが初めて出現するフレーム (0-15) |
| `attributes` | `object` | `color`, `material`, `position`, `size`, `state`, `orientation`, `pose`（null 許容） |

**`events[k]` のフィールド**:

| キー | 型 | 説明 |
|---|---|---|
| `event_id` | `str` | イベント ID（例: `"evt_001"`） |
| `frame` | `int` | イベント発生フレーム (0-15) |
| `action` | `str` | アクション名（13 クラスのいずれか） |
| `agent` | `str` | 行為者の `obj_id` |
| `target` | `str` | 対象物の `obj_id` |
| `source` | `str` or `null` | 取り出し元の `obj_id`（アクションに応じて任意） |
| `destination` | `str` or `null` | 格納先の `obj_id`（アクションに応じて任意） |

### 3.3 圧縮アノテーション（`annotations_compact/<video_id>.json`）

フルアノテーションと同一内容を構造的に圧縮したバージョン。オブジェクト定義の重複排除、短縮キー、null 省略により 93% のサイズ削減を実現。ロスレスで相互変換可能。

### 3.4 設定ファイル（`configs/`）

| ファイル | 説明 |
|---|---|
| `vocab.yaml` | 28 オブジェクトカテゴリと属性語彙の定義 |
| `actions.yaml` | 13 アクションクラスの定義（`source`/`destination` 要否フラグ付き） |

### アクション語彙 (13 classes)

| Action | Description | Source | Destination |
|---|---|---|---|
| take_out | 物体を容器/収納から取り出す | required | - |
| put_in | 物体を容器/収納に入れる | - | required |
| place_on | 物体を面の上に置く | - | required |
| pick_up | 面の上から物体を持ち上げる | required | - |
| hand_over | 人から人へ物体を渡す | required | required |
| open | 容器/引き出し/蓋を開ける | - | - |
| close | 容器/引き出し/蓋を閉める | - | - |
| use | 工具/道具を使用する | - | - |
| move | 物体を場所Aから場所Bへ移動する | required | required |
| attach | 物体を別の物体に取り付ける | - | required |
| detach | 物体を別の物体から取り外す | required | - |
| inspect | 物体を視認/確認する | - | - |
| no_event | イベントなし (negative class) | - | - |

### オブジェクトカテゴリ (28 classes)

person, hand, chair, desk, laptop, monitor, phone, keyboard, mouse, tablet, pen, notebook, book, bookshelf, shelf, cup, drawer, curtain, jacket, backpack, box, speaker, microphone, stool, pc_case, earbuds, smartphone, case

## 4. データの取得元・作成方法

### 出典

室内環境（オフィスデスク・キッチン・部屋）で撮影された録画動画。固定カメラ（20 FPS）で撮影。

### 特徴量の抽出方法

1. 元動画を 1 FPS でフレームサンプリング
2. 16 フレーム単位のクリップに分割（50% オーバーラップ、stride=8）
3. 各クリップを [V-JEPA 2.1](https://github.com/facebookresearch/vjepa) ViT-L（384px、frozen）に入力
4. 出力の時空間トークン（4608 tokens x 1024 dim）を `.pt` ファイルとして保存

### アノテーション方法

**VLM 合成アノテーション**（人手ラベルなし）:

1. 各クリップの 16 フレーム画像を [Qwen 3.5 VLM](https://huggingface.co/Qwen) に入力
2. 構造化プロンプトにより、オブジェクト（カテゴリ・属性）とイベント（アクション・行為者・対象）を JSON で出力させる
3. スキーマバリデーションにより不正な出力を除外
4. **モーションフィルター**: 静止シーン（オブジェクト・イベントなし）はフィルタリング

### 前処理

- フレームは 384x384 px にリサイズ（V-JEPA 入力サイズ）
- V-JEPA トークンは float32 で保存（抽出時は bfloat16、保存時に float32 変換）
- アノテーション JSON はバリデーション済み（カテゴリ・アクション語彙外の値は除外）

## 5. 想定ユースケース

- **イベントグラフ予測モデルの学習**: 本データセットの主目的。V-JEPA トークンを入力とし、構造化イベントグラフを予測する Event Decoder の学習に使用
- **動画理解の研究**: 時空間トークンとイベントアノテーションを用いた動画理解手法の開発・評価
- **合成アノテーションの品質評価**: VLM 自動生成アノテーションの精度・特性の分析
- **Transfer Learning**: V-JEPA 特徴量をファインチューニングなしで下流タスクに転用する研究

## 6. 注意点・制約

### バイアス

- **ドメインバイアス**: 学習データは室内環境（オフィス・キッチン・部屋）に限定。屋外・工場・医療等の環境には未対応
- **VLM バイアス**: アノテーションは Qwen 3.5 VLM の出力に依存。VLM 自体のバイアス（認識しやすい/しにくいオブジェクト、文化的偏り）を継承する可能性がある
- **カテゴリバイアス**: 28 カテゴリに限定されており、語彙外のオブジェクトは検出されない
- **アクションバイアス**: 13 アクションクラスは室内の日常行動に特化。製造作業や屋外行動は対象外

### 欠損

- **モーションフィルタリング**: 静止シーン（動きがないクリップ）は `objects=[], events=[]` としてアノテーションされる（`status: "motion_filtered"`）。これらのクリップには特徴量は存在するがイベント情報がない
- **VLM 出力の除外**: スキーマバリデーションで不正と判定された VLM 出力は除外される（`validation_stats.discard_rate` で確認可能）
- **部分データセット**: 全 67 動画のうち 5 動画のみ収録

### 利用上の注意

- `.pt` ファイルの読み込みには **PyTorch** が必要（`torch.load(..., weights_only=False)` を使用）
- 特徴量は V-JEPA 2.1 ViT-L 固有のもの。他のバックボーン（ViT-B, ViT-g 等）の特徴量とは互換性がない
- アノテーションは**人手レビューを経ていない**合成データ。研究・開発目的の利用を推奨
- 1 FPS サンプリングのため、1 秒未満の高速なイベントは記録されていない可能性がある
- 動画には人物が映っている。プライバシーに配慮した利用が求められる

## 7. 使い方

### ダウンロード

```python
from huggingface_hub import snapshot_download

local_dir = snapshot_download(
repo_id="Yuchn/event-graph-vjepa-vitl-dataset",
repo_type="dataset",
local_dir="data/hf_dataset",
)
```

### 特徴量 + アノテーションの読み込み

```python
import torch
import json

# V-JEPA 特徴量の読み込み（1 クリップ分）
features = torch.load(
"data/hf_dataset/features/20260316_130406_tp00001/clip_0000.pt",
map_location="cpu",
weights_only=False,
)
vjepa_tokens = features["vjepa_tokens"] # shape: (4608, 1024)
video_id = features["video_id"] # "20260316_130406_tp00001"
clip_index = features["clip_index"] # 0

# 対応するアノテーションの読み込み
with open("data/hf_dataset/annotations/20260316_130406_tp00001.json") as f:
annotation = json.load(f)

clip = annotation["clips"][clip_index]
print(clip["objects"]) # 検出オブジェクト一覧
print(clip["events"]) # イベントグラフ（行動記述）
```

### Event Graph Generation で学習

```bash
git clone https://github.com/ChanYu1224/event-graph-generation.git
cd event-graph-generation
uv sync

# ダウンロードしたデータから学習用データを構築
uv run python scripts/4b_build_vjepa_dataset.py \
--features-dir data/hf_dataset/features \
--annotations-dir data/hf_dataset/annotations \
--output-dir data/vjepa_aligned

# 学習
uv run python scripts/5_train.py --config configs/vjepa_training.yaml
```

## 8. ライセンス

MIT License

Copyright (c) 2026 Yuchn

本データセットは MIT ライセンスの下で公開されています。商用・非商用を問わず、自由に使用・改変・再配布が可能です。詳細は [LICENSE](LICENSE) ファイルを参照してください。

## 9. 引用

```bibtex
@software{event_graph_generation_2026,
title = {Event Graph Generation: Structured Event Prediction from Video},
author = {Yuchn},
year = {2026},
url = {https://github.com/ChanYu1224/event-graph-generation},
license = {MIT}
}
```

## 10. 関連リンク

- **Repository**: [ChanYu1224/event-graph-generation](https://github.com/ChanYu1224/event-graph-generation)
- **V-JEPA**: [facebookresearch/vjepa](https://github.com/facebookresearch/vjepa)
- **Qwen VLM**: [Qwen](https://huggingface.co/Qwen)