智源 FlagOpen 开源 HumanCOIN:基于 LeRobot 的多传感器多频率数据集扩展
FlagOpen 开源 HumanCOIN:基于 LeRobot 的多传感器多频率数据集扩展
智源 FlagOpen 开源 HumanCOIN,一个基于 LeRobot 的多传感器、多频率数据集扩展,每个传感器按各自采样率独立存为 parquet 文件,查询时按时间窗口动态对齐,无需预先重采样。
智源 FlagOpen:原创开源项目·2026-11-17 14:19· 43 分钟前AI 评分42
FlagOpen/HumanCOIN
AI 导读
智源 FlagOpen 开源 HumanCOIN,一个基于 LeRobot 的多传感器、多频率数据集扩展,每个传感器按各自采样率独立存为 parquet 文件,查询时按时间窗口动态对齐,无需预先重采样。
正文
📖 中文文档:README_zh-CN.md
基于 LeRobot 构建的面向真实世界数据的多传感器、多频率数据集扩展 —— 各传感器按各自独立的采样率存储,每个传感器一个 parquet 文件,查询时按时间窗口动态对齐。
目录
- HumanCOIN
1. 动机:为什么需要多频率支持
真实世界的数据采集往往需要多个传感器来捕捉同一过程:摄像头记录视觉信息,IMU 测量运动,EEG 和 EMG 捕捉生理信号。人类行为研究、可穿戴设备、实验记录和环境感知都涉及此类数据的组合。各传感器在采样率、启动时间和数据格式上各不相同,因此在使用时需要保留其各自的时间序列并进行对齐。
常见传感器的采样率差异很大:
| 传感器 | 典型频率 | 形状 | 示例 |
|---|---|---|---|
| 摄像头 RGB | 30 / 60 Hz | 480×640×3 | 场景相机 + 可穿戴相机 |
| IMU | 50-1000 Hz | 6(加速度×3 + 陀螺仪×3) | 加速度计 + 陀螺仪 |
| EEG | 256 / 512 / 1000 Hz | 8-256 通道 | 脑电信号 |
| EMG | 20-500 Hz | 4-16 通道 | 肌电信号 |
将不同采样率的数据流强制放入单一帧率的表中,通常需要对低频数据上采样、对高频数据下采样或聚合,这可能会丢弃原始样本。本项目基于 LeRobot 的数据集基础设施,支持传感器独立存储和基于时间的查询。
humancoin 的解决方案:每个传感器都独立存储为一个带时间索引的 parquet 文件。读取时,window 参数定义“如何围绕查询时间戳聚合数据”——无需预先重采样。
写入 —— add_frame 将每个键路由到其对应的特征缓冲区;save_episode() 将它们刷写到磁盘:
flowchart LR
AF["add_frame(key, value)"]
IX["MasterIndex record_frame(ts, task)"]
PF["ParquetFeature buffer.append(ts, data)"]
VF["VideoFeature save PNG + timestamp list"]
AuF["AudioFeature buffer chunks + timestamp list"]
MI[("master_index.parquet timestamp | task | frame_index")]
P1[("imu.parquet 1000Hz × 6d")]
P2[("eeg.parquet 256Hz × 8d")]
P3[("state.parquet 30Hz × 7d")]
C1[("head_rgb.parquet timestamps only")]
V1[("head_rgb.mp4 30fps video")]
A1[("mic.parquet timestamp | num_samples")]
W1[("mic.wav 16kHz audio")]
AF -->|"key = task"| IX
AF -->|"key = sensor<br/>imu / eeg / state"| PF
AF -->|"key = video"| VF
AF -->|"key = audio"| AuF
IX --> MI
PF --> P1
PF --> P2
PF --> P3
VF --> C1
VF --> V1
AuF --> A1
AuF --> W1
style AF fill:#fafafa,stroke:#9e9e9e,color:#000
style IX fill:#e1f5fe,stroke:#4fc3f7,color:#000
style PF fill:#fafafa,stroke:#9e9e9e,color:#000
style VF fill:#f3e5f5,stroke:#9c27b0,color:#000
style AuF fill:#e8f5e9,stroke:#66bb6a,color:#000
style MI fill:#e1f5fe,stroke:#4fc3f7,color:#000
style P1 fill:#fff3e0,stroke:#ff9800,color:#000
style P2 fill:#fff3e0,stroke:#ff9800,color:#000
style P3 fill:#fce4ec,stroke:#e91e63,color:#000
style C1 fill:#f3e5f5,stroke:#9c27b0,color:#000
style V1 fill:#f3e5f5,stroke:#9c27b0,color:#000
style A1 fill:#e8f5e9,stroke:#4caf50,color:#000
style W1 fill:#e8f5e9,stroke:#4caf50,color:#000
加载中
读取 —— 在 master_index 中查找主时钟时间戳,然后按该时间戳查询每个特征:
flowchart TD
IDX["ds[10]"] -->|"① look up frame 10"| MI[("master_index.parquet timestamp | task | frame_index")]
MI -->|"② get timestamp"| TS["t = 0.333s"]
TS -->|"③ nearest<br/>closest row in time"| P3[("state.parquet 30Hz × 7d")]
TS -->|"③ window=(-0.033, 0] all rows in range"| P1[("imu.parquet 1000Hz × 6d")]
TS -->|"③ window=(-0.033, 0] all rows in range"| P2[("eeg.parquet 256Hz × 8d")]
TS -->|"③ nearest, closest row in time"| C1[("head_rgb.parquet timestamp")]
C1 -->|"④ get frame_index"| V1[("rgb → 480×640×3")]
P3 -->|"1 row"| RS["state → [7]"]
P1 -->|"33 rows"| RI["imu → [33, 6]"]
P2 -->|"8 rows"| RE["eeg → [8, 8]"]
V1 -->|"1 frame"| RV["head_rgb → [3, 480, 640]"]
style IDX fill:#fafafa,stroke:#9e9e9e,color:#000
style MI fill:#e1f5fe,stroke:#4fc3f7,color:#000
style TS fill:#fafafa,stroke:#9e9e9e,color:#000
style P3 fill:#fce4ec,stroke:#e91e63,color:#000
style P1 fill:#fff3e0,stroke:#ff9800,color:#000
style P2 fill:#e8f5e9,stroke:#4caf50,color:#000
style C1 fill:#f3e5f5,stroke:#9c27b0,color:#000
style V1 fill:#f3e5f5,stroke:#9c27b0,color:#000
style RS fill:#fce4ec,stroke:#e91e63,color:#000
style RI fill:#fff3e0,stroke:#ff9800,color:#000
style RE fill:#e8f5e9,stroke:#4caf50,color:#000
style RV fill:#f3e5f5,stroke:#9c27b0,color:#000
加载中
ds[10] 的结果(t=0.333s):
state→ 最近匹配 →[7]imu→(-0.033, 0]窗口内的全部 33 个读数 →[33, 6]eeg→(-0.033, 0]窗口内的全部 8 个读数 →[8, 8]head_rgb→ timestamp parquet 中最近的一行 →frame_index→ 解码该帧 →[3, 480, 640]
2. 安装
Python 3.10–3.13(已在 Python 3.12 上验证)。LeRobot 目前固定为 0.3.3。
从 PyPI 安装:
pip install humancoin
或从源码安装:
git clone https://github.com/FlagOpen/HumanCOIN cd HumanCOIN pip install -e .
依赖项:
| 依赖 | 用途 |
|---|---|
lerobot |
基础数据集框架(继承 LeRobotDataset) |
pyarrow |
parquet 文件读写 |
numpy / torch |
数据处理 |
av(PyAV) |
视频编码/解码 |
matplotlib |
可视化 |
scipy |
Web 可视化器信号滤波 |
下载 HumanCOIN 数据集
在 Hugging Face 或 ModelScope 上浏览数据集名称。这些是组织页面;将所选 hub 中的数据集名称传给下面的命令。
pip install humancoin # Replace DATASET_NAME with an actual dataset repository name humancoin-download --hub huggingface --datasets DATASET_NAME --target-dir ./data humancoin-download --hub modelscope --datasets DATASET_NAME --target-dir ./data # Download only selected files (partial download; may not be loadable as a full dataset) humancoin-download --datasets DATASET_NAME --include "meta/*" README.md --target-dir ./data # Multiple datasets; preview without downloading humancoin-download --datasets DATASET_A DATASET_B --target-dir ./data --dry-run # Also available as: python -m humancoin.download ...
默认命名空间为 HumanCOIN;也接受显式的 owner/name ID。--ds_lists 是 --datasets 的别名。文件存储在 <target-dir>/HumanCOIN/<dataset-name> 下;默认目标目录为 ~/.cache/huggingface/lerobot。重复下载会通过 hub SDK 复用文件。使用 --revision 选择版本,使用 --max-workers 控制并行下载。私有/受限数据集需要访问权限以及 HF_TOKEN 或 MODELSCOPE_TOKEN(或 --token);ModelScope 使用轻量级 modelscope-hub SDK;凭据会传给客户端或从其登录缓存中读取。也接受 MS_TOKEN。某个数据集失败不会停止其余下载;只要有失败,命令就会以非零状态退出。
from humancoin import HumanCOINDataset ds = HumanCOINDataset( repo_id="HumanCOIN/DATASET_NAME", root="data/HumanCOIN/DATASET_NAME", ) item = ds[0]
下载会保留仓库文件;加载需要本项目支持的多频率数据集布局。下载不会转换其他格式。
3. 快速开始
import numpy as np from humancoin import HumanCOINDataset ds = HumanCOINDataset.create( repo_id="my_dataset", root="data/", fps=30, features={ # camera: dtype="video" auto-encodes to MP4 "observation.images.cam": { "dtype": "video", "shape": (480, 640, 3), "names": ["h", "w", "c"], "fps": 30, }, # high-rate IMU: window defines "return all readings in (t-33ms, t]" "observation.imu": { "dtype": "float32", "shape": (6,), "names": ["ax", "ay", "az", "gx", "gy", "gz"], "fps": 1000, "window": (-0.033, 0.0), "tolerance_s": 0.002, }, # mid-rate EEG "observation.eeg": { "dtype": "float32", "shape": (8,), "names": ["Fz", "Cz", "Pz", "Oz", "F3", "F4", "C3", "C4"], "fps": 256, "window": (-0.033, 0.0), }, # end-effector pose: no window → nearest neighbor by default "observation.state": { "dtype": "float32", "shape": (7,), "names": ["x", "y", "z", "roll", "pitch", "yaw", "gripper"], "fps": 30, }, "action": { "dtype": "float32", "shape": (7,), "names": ["dx", "dy", "dz", "droll", "dpitch", "dyaw", "dgrip"], "fps": 30, }, }, ) # recording: task = master clock, each frame is bounded by a task call for i in range(300): # high-rate sensors: multiple writes per frame for _ in range(33): # 1000Hz / 30fps ≈ 33 ds.add_frame("observation.imu", imu_sample) for _ in range(8): # 256Hz / 30fps ≈ 8 ds.add_frame("observation.eeg", eeg_sample) # a task call = frame boundary, timestamp auto-generated ds.add_frame("task", "reach_target") # camera-rate sensors: once per frame ds.add_frame("observation.state", joint_state) ds.add_frame("action", action_cmd) ds.add_frame("observation.images.cam", camera_image) ds.save_episode()
读取 — 窗口特征返回窗口内的所有读数,最近特征返回单个向量:
ds = HumanCOINDataset(repo_id="my_dataset", root="data/") item = ds[10] item["observation.imu"] # tensor([33, 6]) — 33 readings in (-0.033, 0] item["observation.imu_timestamps"] # tensor([33]) item["observation.eeg"] # tensor([8, 8]) item["observation.state"] # tensor([7]) — nearest item["observation.images.cam"] # tensor([3, 480, 640]) — CHW item["task"] # "reach_target"
sequenceDiagram
participant User
participant DS as Dataset
participant PF as ParquetFeature<br/>(imu)
participant VF as VideoFeature<br/>(cam)
participant IX as MasterIndex
loop each frame
User->>DS: add_frame("imu", data)
DS->>DS: _auto_timestamp("imu")<br/>ts = counter × 1/1000
DS->>PF: add(data, ts)
Note over PF: buffer.append((ts, data))
User->>DS: add_frame("task", "reach")
DS->>DS: ts = len(index) / fps
DS->>IX: record_frame(ts, "reach")
User->>DS: add_frame("cam", image)
DS->>DS: _auto_timestamp("cam")<br/>ts = counter × 1/30
DS->>VF: add(image, ts)
Note over VF: save PNG + record timestamp
end
User->>DS: save_episode()
DS->>IX: write(ep_idx) → master_index.parquet
DS->>PF: save() → imu.parquet
DS->>VF: save() → timestamp parquet + MP4
DS->>DS: meta.save_episode()
DS->>DS: _check_episode_alignment()
加载中
4. 演示与可视化
4.1 运行演示
# write 3 episodes of simulated data python -m examples.01write_simple # read and inspect the data python -m examples.01read_simple # interactive visualizer humancoin-visualize data/demo --episode 0 # web visualizer (browser UI, draggable time window) humancoin-visualize-web /path/to/dataset # audio: microphone stored as WAV + timestamp parquet python -m examples.06audio_example
Web 可视化器支持对 EEG/EMG 条带进行可选的零相位滤波:在条带上打开 滤波 面板,可将高通/低通巴特沃斯滤波器与工频及其所有谐波的梳状陷波组合(内置 EEG/EMG 预设)。API 对每个特征采用相同的规格:/api/frame?...&filt=observation.eeg:hp=0.5,lp=40,notch=50。
它还会在 SteamVR 右手 y 轴向上的世界中渲染 3D 姿态视图(*_pose 6-DoF 特征作为坐标三轴 + 带时间淡出的近期历史运动轨迹,来自 hand_skeleton 正向运动学的指尖末端执行器路径;拖动旋转,滚轮缩放),并为静态快照特征(如 eeg_impedance)渲染颜色编码的电极网格(按通道分质量等级)。姿态旋转与录制器完全一致(R = Rz(yaw)·Ry(pitch)·Rx(roll),即录制器对 OpenVR 矩阵进行 ZYX 欧拉分解的逆);手部骨架通过每只手的常量 Manus→tracker 安装映射附着(+z = 手指,+y = 手背,另沿 −y 偏移 −5cm,因为 tracker 位于手背上方)。
4.2 演示 1:写入(01write_simple.py)
主写入演示:一组模拟传感器流——3 个摄像头 + IMU + EEG + EMG + 温度——录制三个 2 秒的 episode(reach_target、pour_liquid、stack_blocks):
| 传感器 | 形状 | 速率 | 窗口 |
|---|---|---|---|
| head_rgb | 480×640×3 | 30 fps | —(视频) |
| left_wrist_rgb | 480×640×3 | 30 fps | —(视频) |
| right_wrist_rgb | 480×640×3 | 30 fps | —(视频) |
| imu | 6(加速度+陀螺仪) | 1000 Hz | (-0.033, 0.0) |
| eeg | 8(EEG 通道) | 256 Hz | (-0.033, 0.0) |
| emg_left | 4(肌肉通道) | 100 Hz | (-0.033, 0.0) |
| emg_right | 4(肌肉通道) | 100 Hz | (-0.033, 0.0) |
| temperature | 1 | 10 Hz | —(最近) |
| state | 7(x,y,z,r,p,y,grip) | 30 Hz | —(最近) |
| action | 7(速度指令) | 30 Hz | —(最近) |
它展示了:
dtype: "video"特征自动编码为 MP4,每个主帧恰好一帧- 高频传感器在两次任务调用之间被多次写入;时间戳按特征自动生成为
timestamp_start + counter × 1/fps - 每次
save_episode()写入master_index.parquet+ 各特征 parquet + 视频,然后运行对齐检查器(每个特征都应报告 OK)
python -m examples.01write_simple
4.3 演示 2:读取(01read_simple.py)
读取 Demo 1 写入的数据集,并端到端地演练每一条读取路径:
- window 特征(
observation.imu)返回窗口内的所有读数及其时间戳 - nearest 特征(
observation.temperature、observation.state、action)返回单个向量 - 视频被解码回 CHW 张量
window_overrides在读取时拓宽 IMU 窗口,而不改动已存储的数据- 打印各帧的 IMU 片段大小——最初的几帧为空,因为 IMU 直到
timestamp_start: 0.1才上线
python -m examples.01read_simple # needs data/ from 01write_simple4.4 Demo 3:对齐容差(02tolerance_example.py)
展示对齐检查器捕获一个违反对齐约定的传感器:IMU 配置了 timestamp_start: 0.1(它晚 100 ms 上线)外加一个很紧的 tolerance_s: 0.002,因此其采样点距离最初的 master 帧太远。在 save_episode() 之后,检查器将违规帧写入 meta/alignment_check.jsonl,demo 打印报告。
经验法则:tolerance_s 必须覆盖从 master 帧到该传感器最近采样点的距离——最多为其周期的一半(例如 10 Hz 传感器为 ≤ 50 ms)——再加上启动偏移和抖动。
python -m examples.02tolerance_example
4.5 Demo 4:窗口模式(03window_example.py)
一个 episode,三种聚合模式并排对比:
observation.imu以 1000 Hz 配合window: (-0.033, 0.0)——范围查询,每帧约 33 个读数observation.finger_pose以 120 Hz 配合window: "interpolate"——在帧时间戳处插值取值observation.temperature以 10 Hz 且无窗口——最近邻
随后用 window_overrides 重新打开数据集——更宽的 IMU 窗口,手指姿态切换为范围查询——证明窗口是读取时的决定,而不是已存储数据的属性。
python -m examples.03window_example
4.6 Demo 5:Delta 时间戳(04delta_example.py)
使用 delta_timestamps={"observation.state": [-0.1, 0.0, 0.1]} 进行多帧时间查询:读取 ds[i] 返回在三个时间点(t-0.1、t、t+0.1)上堆叠的状态,而不是单个向量——这是 delta 姿态训练和时间增强的构建模块。
python -m examples.04delta_example
4.7 Demo 6:异步传感器启动(05async_startup_example.py)
真实传感器不会在同一瞬间上线:进程启动后,每个传感器都在各自的挂钟时间返回其第一帧(IMU 在 0.04 s,EMG 在 0.12 s,EEG 放大器在 0.31 s,……)。本 demo 模拟此类数据流,并在添加数据之前将它们对齐到主时钟:
- t_all_started——每个传感器都已交付其第一帧的挂钟时刻(所有第一帧时间的最大值)。
- t = 0——主时钟参考传感器在
t_all_started处或之后的第一帧;其更早的帧被丢弃。 - timestamp_start——对于其他每个传感器,是其下一帧(t = 0 处或之后的第一帧)与 t = 0 帧之间的差值;在特征规格中设置它,使存储的时间戳与主时钟保持相位对齐。
- 记录从 t = 0 起的所有内容。episode 在主时钟停止时结束,但每个传感器会继续流式传输,直到其在主时钟最后一帧之后的下一帧——这个尾部采样使最后一帧的窗口保持完整。
模拟的启动延迟:
| 传感器 | 速率 | 第一帧(挂钟时间) |
|---|---|---|
observation.imu |
1000 Hz | 0.04 s |
observation.emg |
100 Hz | 0.12 s |
observation.state(主时钟参考) |
30 Hz | 0.18 s |
observation.temperature |
10 Hz | 0.22 s |
action |
30 Hz | 0.24 s |
observation.eeg |
256 Hz | 0.31 s |
该 demo 计算 t_all_started = 0.31 s,取 master 的下一帧作为 t = 0,推导每个传感器的 timestamp_start,写入数据集,在磁盘上验证每个特征的首个存储时间戳等于其 timestamp_start,且其最后一个采样落在 master 停止之后,然后回读第 0 帧、episode 中间的一帧以及最后一帧。
两个值得了解的后果:
- 第 0 帧的回溯窗口为空。每个传感器的首个存储帧都位于其自身的
timestamp_start> 0 处,更早的数据按设计被丢弃,因此像(-0.033, 0.0)这样的窗口在第一帧上没有任何内容可返回。 - 容差必须覆盖传感器周期的一半。对齐检查器会将每个主帧与该传感器的最近样本进行比较,其距离最多为半个周期(10 Hz 传感器最多可相差 50 ms)加上抖动——例如此处 10 Hz 温度传感器的
tolerance_s: 0.06。
python -m examples.05async_startup_example
4.8 演示 7:音频(06audio_example.py)
一个摄像头 + 状态 + 一个模拟麦克风,端到端展示音频存储路径:
dtype: "audio"特性将shape定义为一块样本(n_samples,)(单声道)或(n_samples, channels),并要求sample_rate- 每个主帧一个
add_frame存储一块;save_episode()将所有块拼接为每个 episode 一个 PCM16 WAV,位于audios/下,并在其他按特性 parquet 旁附带一个时间戳 parquet 索引(timestamp | episode_index | num_samples) - 在最近邻模式下读取
ds[i]会通过 parquet 索引解析出最接近主时间戳的块并整体返回——这是原子单位,类似于一个视频帧;使用window(spec、window_overrides或直接的read(..., window=(start, end))参数)时,它会返回时间落在(t + start, t + end]内的所有样本,以样本精度跨块边界切片并拼接 - 对齐检查器报告 WAV 完整性:块数量与索引行数、样本数量与索引求和
python -m examples.06audio_example
4.9 可视化控件
可视化器(humancoin-visualize data/demo --episode 0):
space — play / pause
← → — step frame backward / forward
↑ ↓ — faster / slower playback
w s — widen / shrink the window
q / Esc — quit
5. 核心概念
5.1 按特性独立存储
存储布局:
data/
└── chunk-000/
└── episode_000000/
├── master_index.parquet # timestamp | frame_index | task_index
├── observation.imu.parquet # 1000Hz · 1980 rows · 6 cols
├── observation.eeg.parquet # 256Hz · 512 rows · 8 cols
├── observation.state.parquet # 30Hz · 60 rows · 7 cols
└── observation.images.head_rgb.parquet # 30Hz · 60 rows · timestamps only
videos/
└── chunk-000/
└── observation.images.head_rgb/
└── episode_000000.mp4
audios/
└── chunk-000/
└── observation.audio.mic/
└── episode_000000.wav
每个非视频特性都获得一个具有统一列布局的 parquet:
timestamp (float64) | episode_index (int64) | col_0 (float32) | ... | col_D (float32)
- 摄像头速率特性(state、action):每帧一行,行数 = 帧数
- 高速率特性(imu、eeg):帧之间多个样本,行数 = 速率 × 时长
- 摄像头特性:时间戳 parquet + MP4 视频
- 音频特性:时间戳 parquet(
timestamp | episode_index | num_samples,每个添加的块一行)+ 每个 episode 一个 WAV;块按时间戳顺序拼接
5.2 以任务作为主时钟
整个数据集围绕任务调用作为帧边界来组织:add_frame("task", ...) 声明“当前帧在此结束,下一帧开始”。
- 帧 = 两次任务调用之间写入的所有特性数据。
add_frame("task", ...)自动生成帧时间戳:t = frame_index / fps(如有需要可用timestamp=覆盖) - 主时钟 = 帧序列。读取
ds[i]时首先在master_index中查找第 i 帧时间戳 t;然后每个特性围绕 t 对齐(窗口 / 最近邻,见 5.3) - 每个特性的时间戳独立于主时钟生成:每个特性一个计数器,每次
add_frame时ts = timestamp_start + counter × (1 / fps);计数器在save_episode()后重置 - 无需配置 master_feature——任务就是主时钟,任何采样率的特性都对齐到它
# standard call order per frame: high-rate first → task bounds the frame → low-rate last ds.add_frame("observation.imu", ...) # high-rate sensor, written multiple times between frames ds.add_frame("observation.eeg", ...) ds.add_frame("task", "pick_up") # ← frame boundary: frame_index++, master-clock timestamp ds.add_frame("observation.state", ...) # camera-rate sensor, once per frame ds.add_frame("observation.images.cam", image)
5.3 窗口参数
主时钟帧时间戳是查询锚点,但特性的读数不一定落在帧上——window 定义“如何围绕帧时间戳聚合该特性的读数”:
window 值 |
行为 | 典型用途 |
|---|---|---|
None(默认) |
最近邻:返回单个最接近的读数 | 摄像头速率传感器(state、action);音频:一个完整块 |
"interpolate" |
在查询时间进行线性插值 | 中速率传感器(手指姿态) |
(start_s, end_s) |
范围查询:返回 (t+start, t+end] 内的所有读数 |
高速率传感器(IMU、EEG、EMG);音频:样本精确切片 + 拼接 |
# IMU at 1000Hz, 30fps master → ~33 readings per frame "window": (-0.033, 0.0) # (t-33ms, t] # wider window for context "window": (-0.066, 0.0) # (t-66ms, t], ~66 readings # override at read time ds = HumanCOINDataset( repo_id="my_dataset", root="data/", window_overrides={"observation.imu": (-0.100, 0.0)}, )
查询 t = 0.333s(第 10 帧)时每个特性返回的读数:
注意温度(10Hz)在 0.333 处没有样本——其采样网格为 0.3、0.4、……,因此最近邻回退到 t=0.300 处的读数。
6. API 参考
创建数据集
ds = HumanCOINDataset.create( repo_id="my_dataset", fps=30, features={...}, # see Feature Definition Format below )
| 参数 | 类型 | 默认 | 描述 |
|---|---|---|---|
repo_id |
str |
— | 数据集名称,即 root 下的目录名 |
fps |
float |
— | 主时钟帧率;帧时间戳 = frame_index / fps |
features |
dict[str, dict] |
— | 特征定义,格式见下文 |
root |
str | Path |
~/.cache/huggingface/lerobot/<repo_id> |
存储根目录 |
robot_type |
str |
None |
机器人类型,仅作元数据 |
use_videos |
bool |
True |
是否将 dtype="video" 特征编码为 MP4 |
image_writer_processes |
int |
0 |
图像写入子进程数(0 = 在主进程中写入) |
image_writer_threads |
int |
0 |
图像写入线程数 |
video_backend |
str |
None |
视频后端(例如 "pyav"),None 自动选择 |
batch_encoding_size |
int |
1 |
每 N 个 episode 批量编码一次视频 |
window_overrides |
dict |
None |
覆盖每个特征的窗口(格式与读取时相同) |
特征定义格式
features = { "feature_key": { "dtype": "video" | "audio" | "float32" | "int64", # required "shape": (H, W, C) | (N,) | (D,), # required "names": ["col_0", ...], # required # optional: "fps": 1000, # sampling rate of this feature "window": (-0.033, 0.0), # query window "timestamp_start": 0.1, # timestamp start offset "tolerance_s": 0.002, # alignment tolerance "sample_rate": 16000, # audio only: sample rate of the WAV } }
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
dtype |
str |
✓ | 存储类型:"float32"(连续)、"int64"(离散/id)、"video"(相机帧)、"audio"(麦克风数据块) |
shape |
tuple |
✓ | 单次读数的形状:数值特征为 (D,),视频为 (H, W, C),音频为 (n_samples,) 或 (n_samples, channels) |
names |
list[str] |
✓ | 每个维度的列名(用作 parquet 列名) |
fps |
float |
可选 | 该特征的采样率;时间戳自动生成为 timestamp_start + counter × 1/fps;省略时回退到主时钟 fps |
window |
None | "interpolate" | (start, end) |
None |
查询时读数的聚合方式(见 5.3) |
timestamp_start |
float |
0.0 |
时间戳起始偏移,例如传感器仅在 t=0.1s 时才开始记录 |
tolerance_s |
float |
None |
对齐容差:在 save_episode() 之后,会检查每帧最近读数的间隔,并将违规记录到 meta/alignment_check.jsonl |
sample_rate |
int |
仅音频 | WAV 文件的采样率(例如 16000);dtype="audio" 必填 |
约定与提示:
- 特征键遵循 LeRobot 命名规范,不得包含
/(例如observation.imu、action) dtype="video"特征仅存储时间戳 parquet;图像编码为 MP4 存放在videos/下dtype="audio"特征每个 episode 在audios/下存储一个 WAV 文件,外加一个时间戳 parquet;每次add_frame传入一个 float32 样本块,取值范围为 [-1, 1]((n_samples,)单声道或(n_samples, channels))。最近邻读取返回整个数据块;window(start, end)读取返回(t+start, t+end]中的样本拼接结果(时序约定:数据块的第一个样本位于其标签处,样本严格按1/sample_rate推进,真实丢帧会缩短该段而非拉伸它)- 对于高频率特征,务必同时提供
fps和window——否则最近邻查询只会返回单个读数,高频信息就会丢失
写入
ds.add_frame(key: str, value: np.ndarray | torch.Tensor | str, timestamp: float | None = None) ds.save_episode()
key:"task"或已定义的特征键value:数值特征为np.ndarray/torch.Tensor(形状必须与shape匹配);视频特征为np.ndarray(H, W, C);任务为str任务标签timestamp:None自动生成——任务使用主时钟len(records) / fps,其他特征使用各自的计数器timestamp_start + counter × 1/fps;传入float可手动设置
完整的写入循环:
FPS = 30 imu_per_frame = 1000 // FPS # 33 eeg_per_frame = 256 // FPS # 8 for frame in range(60): # 2 seconds / 30fps for _ in range(imu_per_frame): # high-rate: multiple writes per frame ds.add_frame("observation.imu", imu_sample) for _ in range(eeg_per_frame): ds.add_frame("observation.eeg", eeg_sample) ds.add_frame("task", "reach_target") # ← frame boundary ds.add_frame("observation.state", joint_state) # low-rate: once per frame ds.add_frame("action", action_cmd) ds.add_frame("observation.images.cam", camera_image) ds.save_episode() # flush all buffers, run alignment/video checks, reset counters
读取
ds = HumanCOINDataset( repo_id="my_dataset", root="data/", episodes=[0, 2], # load only episodes 0, 2 image_transforms=my_transforms, # torchvision transforms delta_timestamps={"observation.state": [-0.1, 0, 0.1]}, # multi-frame query window_overrides={"observation.imu": (-0.066, 0)}, # override window video_backend="pyav", ) item = ds[10]
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
repo_id |
str |
— | 数据集名称 |
root |
str | Path |
~/.cache/huggingface/lerobot/<repo_id> |
存储根目录 |
episodes |
list[int] |
None |
仅加载指定的 episode 索引 |
image_transforms |
可调用对象 | None |
图像变换(torchvision 风格) |
delta_timestamps |
dict[str, list[float]] |
None |
多帧查询:返回 {key: master frame + each offset frame},例如 {"observation.state": [-0.1, 0, 0.1]} |
tolerance_s |
float |
1e-4 |
delta_timestamps 的帧对齐容差 |
video_backend |
str |
None |
视频解码后端(例如 "pyav") |
batch_encoding_size |
int |
1 |
(写入侧)视频批量编码大小 |
window_overrides |
dict |
None |
在读取时覆盖每个特征的窗口,例如 {"observation.imu": (-0.066, 0)} |
深度视频读取:具有 info["video.is_depth_map"] = true 和 HWC shape = [H, W, 1] 的特征直接使用 PyAV 解码。读取返回原生样本,形式为 (1, H, W) 张量(例如 gray12le 的 uint16),不进行 RGB 转换,也不除以 255。单位和无效值保持存储数据的原样。这适用于读取;深度专用编码尚未实现。
返回结构
item = ds[10] # { # "timestamp": tensor(0.3333), # "frame_index": tensor(10), # "episode_index": tensor(0), # "index": tensor(10), # "task_index": tensor(0), # "task": "reach_target", # # # window feature: all readings + timestamps # "observation.imu": tensor([33, 6]), # "observation.imu_timestamps": tensor([33]), # # # nearest feature: a single vector # "observation.state": tensor([7]), # "observation.temperature": tensor([1]), # # # video feature: CHW format # "observation.images.head_rgb": tensor([3, 480, 640]), # # # audio feature: one chunk of samples, float32 in [-1, 1] # "observation.audio.mic": tensor([533]), # # # audio feature with window (-0.033, 0): samples in (t-33ms, t], concatenated # "observation.audio.mic": tensor([528]), # }
7. 架构
flowchart TB
subgraph Entry["entry layer"]
DS["HumanCOINDataset<br/>dataset.py · orchestrator<br/>(inherits LeRobotDataset)"]
end
subgraph Core["core layer"]
IX["MasterIndex<br/>index.py"]
MD["HumanCOINDatasetMetadata<br/>metadata.py"]
end
subgraph Features["feature layer"]
PF["ParquetFeature<br/>parquet.py"]
VF["VideoFeature<br/>video.py"]
AuF["AudioFeature<br/>audio.py"]
end
subgraph Validate["validation layer"]
CK["DatasetChecker<br/>checker.py"]
end
subgraph Store["storage layer"]
PQ[("parquet files<br/>data/chunk-*/episode_*/")]
MP4[("MP4 videos<br/>videos/chunk-*/")]
WAV[("WAV audio<br/>audios/chunk-*/")]
META[("metadata<br/>meta/")]
end
DS -->|"frame index I/O"| IX
DS -->|"info.json / metadata"| MD
DS -->|"write readings / window query"| PF
DS -->|"write images / decode videos"| VF
DS -->|"write chunks / read WAV"| AuF
DS -->|"post-save validation"| CK
PF -->|"save / read"| PQ
VF -->|"encode MP4"| MP4
VF -->|"timestamp table"| PQ
AuF -->|"write WAV"| WAV
AuF -->|"timestamp table"| PQ
IX -->|"save"| PQ
MD -->|"save"| META
CK -->|"validation report"| META
style DS fill:#e8eaf6,stroke:#4fc3f7,stroke-width:2px,color:#000
style IX fill:#ffebee,stroke:#ef9a9a,color:#000
style MD fill:#fafafa,stroke:#9e9e9e,color:#000
style PF fill:#e8f5e9,stroke:#66bb6a,color:#000
style VF fill:#f3e5f5,stroke:#ce93d8,color:#000
style AuF fill:#e8f5e9,stroke:#66bb6a,color:#000
style CK fill:#fff3e0,stroke:#ffcc80,color:#000
style PQ fill:#fafafa,stroke:#9e9e9e,color:#000
style MP4 fill:#fafafa,stroke:#9e9e9e,color:#000
style WAV fill:#fafafa,stroke:#9e9e9e,color:#000
style META fill:#fafafa,stroke:#9e9e9e,color:#000
加载中
文件布局:
src/humancoin/
├── dataset.py (341 lines) orchestrator — add_frame / save_episode / __getitem__
├── audio.py (185 lines) AudioFeature — buffer chunks, write WAV + timestamp parquet
├── parquet.py (168 lines) ParquetFeature — write buffer, save parquet, load, window query
├── video.py (168 lines) VideoFeature — save PNG, encode MP4, decode frames
├── index.py (127 lines) MasterIndex — frame index I/O
├── metadata.py (123 lines) HumanCOINDatasetMetadata — info.json management
├── checker.py (162 lines) DatasetChecker — video frame count + audio integrity + timestamp alignment checks
└── utils.py (236 lines) constants + info.json creation/validation
设计原则:
-
每个特征一个对象:
ParquetFeature、VideoFeature和AudioFeature各自封装其缓冲区、文件路径和读写逻辑。Dataset 仅作为编排者。 -
读写对称:每个 Feature 同时提供
add/save(写入)和load/query(读取)。 -
确定性路径:文件路径仅取决于
episode_index和feature_key;无需在episodes.jsonl中查找。 -
继承而非重写:为
start_image_writer、_save_image及其他基础功能继承LeRobotDataset;仅重写 4 个核心方法。
8. 与原生 LeRobotDataset 的对比
| 方面 | 原生 LeRobotDataset | humancoin |
|---|---|---|
| 存储 | 1 个合并 parquet | 每个特征 N 个 parquet |
| 多速率传感器 | 需要预重采样 | 原生速率,独立存储 |
| 时间对齐 | tolerance_s 容差匹配 |
窗口机制(范围 / 插值 / 最近邻) |
| 主时钟 | 相机帧 | add_frame("task", ...) 调用 |
| 视频编码 | 在 save_episode 中统一批量编码 |
每个 VideoFeature 独立编码 |
| 元数据 | episodes.jsonl 记录所有内容 |
仅记录基本帧信息;路径确定性计算 |
| 每特征 fps | 不支持 | 每个特征独立的 fps |
| 每特征容差 | 全局 tolerance_s |
每个特征独立的 tolerance_s |
| 音频存储 | 不支持 | 每 episode 一个 WAV + 时间戳 parquet 索引,最近块读取 |
| 写入 API | add_frame(frame_dict, task) |
每个字段 add_frame(key, value) |
| 对齐检查 | 无 | 自动 alignment_check.jsonl |
| 视频检查 | 无 | 自动帧数/时长检查 |
9. 致谢
本项目基于以下开源项目和工作构建:
-
LeRobot — 基础数据集框架。本项目继承
LeRobotDataset和LeRobotDatasetMetadata的 API 设计,并复用其视频编码和图像写入基础设施。感谢 Hugging Face 团队对开源机器人学习生态的贡献。 -
PyArrow — 高性能列式存储,是每特征 parquet I/O 的基础。
-
PyAV — FFmpeg 的 Python 绑定,为视频编码(AV1)和解码提供支持。
-
Matplotlib — 可视化。
-
Neuropixels 数据格式和来自 Allen Institute for Neural Dynamics 的 BIDS 标准 — 为组织多模态神经数据提供了灵感。
感谢所有同事的反馈和讨论。
构建并检查发布版本
pip install -e ".[dev]" python -m unittest discover -s tests -v python -m build python -m twine check dist/*
该 wheel 包含数据集读写、下载以及两个可视化器。安装 humancoin 即可使用所有这些功能;无需检出源代码。examples/ 演示脚本需要检出源代码。
来源:智源 FlagOpen:原创开源项目 · github.com
来源:RadarAI · aihot.news

