# 数据源说明 - Data Sources

> 记录所有可用的数据源位置和说明

---

## 🎯 数据源分类

本项目使用两类数据：
1. **真机数据**：真实机器人操作数据，包含复杂的失败模式
2. **仿真数据**：模拟环境生成的数据，标注更准确但可能不够真实

---

## 📍 真机数据（Real Robot Data）

### 1. DROID 数据集

**位置**：`/playpen-ssd/dataset/droid_raw/1.0.1/`

**说明**：
- 大规模多机构机器人操作数据集
- 包含成功和失败案例
- 多种任务类型（300+ 种）

**数据源分布**：

| 数据源 | 轨迹数 | 比例 | 说明 |
|--------|--------|------|------|
| AUTOLab | 3,618 | 23.9% | 主要数据源 |
| ILIAD | 1,303 | 8.6% | |
| IPRL | 1,298 | 8.6% | |
| PennPAL | 2,494 | 16.5% | 包含 failure/success 标注 |
| CLVR | 433 | 2.9% | |
| GuptaLab | 187 | 1.2% | |
| 其他 | ~6,824 | ~45% | 多个小型数据源 |
| **总计** | **15,157** | **100%** | **Failure 数据** |

**任务类型分布（Top 10）**：

| 排名 | 任务 | 数量 |
|------|------|------|
| 1 | Move object into or out of container | 2,699 |
| 2 | Move object to a new position | 2,494 |
| 3 | Open or close hinged object | 1,103 |
| 4 | Hang or unhang object | 891 |
| 5 | Move lid on or off of container | 637 |
| 6 | Open or close slidable objects | 543 |
| 7 | Press button | 489 |
| 8 | Use cup to pour | 437 |
| 9 | Fold, spread out, or clump object | 398 |
| 10 | Use cloth to clean | 312 |

**数据格式**：
- 视频：MP4 格式，多视角（wrist_image_left, exterior_image_1_left）
- 元数据：JSON 格式，包含任务描述、动作序列、相机参数等

**访问方式**：
```python
import tensorflow_datasets as tfds
ds = tfds.load("droid", data_dir="/playpen-ssd/dataset/", split="train")
```

**子目录结构**：
```
/playpen-ssd/dataset/droid_raw/1.0.1/
├── AUTOLab/
│   ├── failure/
│   │   ├── 2023-07-07/
│   │   │   └── session_xxx/
│   │   │       ├── recordings/MP4/*.mp4
│   │   │       └── metadata_*.json
│   │   └── ...
│   └── success/
├── PennPAL/
├── ILIAD/
└── ...
```

---

### 2. 本地处理后的 DROID 数据

**位置**：`./droid_processed/`

**说明**：
- 从 DROID 数据集提取的失败案例
- 已拼接双视角（wrist + exterior）
- 包含元数据 JSON

**文件格式**：
```
droid_processed/
├── episode_000000.mp4    # 视频文件
├── episode_000000.json   # 元数据
├── episode_000001.mp4
├── episode_000001.json
└── ...
```

**数量**：~20 个 episodes（示例数据）

**如何生成**：
```bash
python video_process.py
```

---

## 🎮 仿真数据（Simulation Data）

### 1. 本地 cokecan-50 数据

**位置**：`./data/cokecan-50/`

**说明**：
- 可乐罐抓取任务的仿真数据
- 按失败类型分类
- 包含完整的奖励标注

**目录结构**：
```
data/cokecan-50/
├── fall/          # 掉落失败（10 episodes）
├── collision/     # 碰撞失败（10 episodes）
├── grasp/         # 抓取失败（10 episodes）
├── smooth/        # 运动不平滑（10 episodes）
└── success/       # 成功案例（10 episodes）
```

**数据格式**：
```json
{
  "joint_poss": [[...], [...], ...],  // 关节位置序列
  "stages": [0, 0, 1, 1, 2, ...],      // 阶段标签（0-5）
  "rewards": {
    "reachout": [0.1, 0.2, 0.3, ...],  // 接近奖励
    "grasp": [0.0, 0.0, 0.8, ...],     // 抓取奖励
    "collision": [0.0, 0.1, 0.0, ...], // 碰撞惩罚
    "fall": [0.0, 0.0, 0.0, ...],      // 掉落惩罚
    "smooth": [0.9, 0.85, 0.8, ...]    // 平滑度
  }
}
```

**用途**：
- 对齐奖励指标定义
- 验证模型在仿真数据上的表现

---

### 2. fangyu 仿真数据

**位置**：
- `/playpen-ssd/yufang/projects/reward/`
- `/playpen-ssd/yufang/projects/reward/cokecan-50`

**说明**：
- 更大规模的仿真数据
- 约 800-900 条轨迹
- 同样是 cokecan 抓取任务

**状态**：⏳ 待整合

**预计用途**：
- 扩充仿真数据集
- 与真机数据混合训练

---

### 3. yangyue Libero 失败数据

**位置**：`/playpen-ssd/dataset/libero_failures/dec_29_2025_v1`

**说明**：
- Libero 环境的失败案例
- 多种任务类型
- 专门收集的失败模式

**状态**：⏳ 待整合

**预计用途**：
- 增加失败模式多样性
- 提高模型对失败的检测能力

---

## 📊 数据统计对比

| 数据源 | 类型 | 数量 | 标注质量 | 真实性 | 状态 |
|--------|------|------|----------|--------|------|
| DROID failure | 真机 | 15,157 | 需标注 | 高 | ✅ 可用 |
| DROID success | 真机 | 未统计 | 需标注 | 高 | 📋 待统计 |
| cokecan-50 本地 | 仿真 | 50 | 精确 | 中 | ✅ 已整理 |
| fangyu 仿真 | 仿真 | ~800 | 精确 | 中 | ⏳ 待整合 |
| yangyue Libero | 仿真 | 未知 | 精确 | 中 | ⏳ 待整合 |

---

## 🔄 数据处理流程

### DROID 数据处理

```mermaid
graph LR
    A[DROID TFDS] --> B[video_process.py]
    B --> C[droid_processed/*.mp4]
    C --> D[api_batch_improved.py]
    D --> E[output/labels_*.jsonl]
    E --> F[extract_frames_to_images.py]
    F --> G[data/frames/**/*.jpg]
    G --> H[convert_to_sft.py]
    H --> I[data/sft_*.json]
    I --> J[模型训练]
```

### 仿真数据处理

```
仿真数据（JSON） → 格式转换 → 与真机数据合并 → 模型训练
```

---

## 📝 数据使用建议

### 训练数据混合比例

| 阶段 | 真机:仿真 | 说明 |
|------|----------|------|
| 初期 | 1:1 | 使用仿真数据快速验证 |
| 中期 | 3:1 | 逐步增加真机数据 |
| 后期 | 5:1 或纯真机 | 提高真实场景性能 |

### Success vs Failure 比例

| 场景 | Success:Failure | 说明 |
|------|----------------|------|
| 推荐 | 1:2 | 失败案例更重要 |
| 平衡 | 1:1 | 避免类别不平衡 |
| 当前 | 约 1:10 | **需要增加 success 数据** |

---

## 🔍 数据质量检查

### 视频质量

✅ **已完成**：
- 视频帧率统计（见 `data_sta/video_framerate_stats.json`）
- 视频时长统计

❌ **待完成**：
- 图像质量评估
- 模糊/曝光异常检测
- 视角覆盖度检查

### 标注质量

❌ **待完成**：
- 人工 Golden Set 标注
- GPT 标注一致性检查
- 跨标注者一致性

---

## 💡 数据扩充计划

### 短期（1-2 周）

1. **DROID 数据扩充**
   - 从 ~100 条扩展到 2500+ 条
   - 使用 balanced 采样策略
   - 覆盖主要任务类型

2. **增加 Success 数据**
   - 从 DROID success 目录采样
   - 目标：达到 success:failure = 1:2

### 中期（1-2 月）

3. **整合 fangyu 仿真数据**
   - 格式转换和对齐
   - 与真机数据混合训练

4. **整合 yangyue Libero 数据**
   - 适配数据格式
   - 增加失败模式多样性

### 长期（3+ 月）

5. **多数据源混合**
   - 建立统一数据格式
   - 多源数据联合训练
   - 跨域泛化能力评估

---

## 📞 数据访问问题

如遇到数据访问问题，请检查：
1. 路径是否正确（绝对路径）
2. 权限是否足够（读取权限）
3. 数据是否存在（某些数据可能被移动）

---

## 📚 相关文档

- [数据统计分析](./data_sta/failure_statistics.txt) - DROID 失败数据详细统计
- [HuggingFace 数据集指南](./data_sta/README_HF_DATASET.md) - 数据集准备和上传
- [项目概述](./docs/PROJECT_OVERVIEW.md) - 完整项目说明