跳到正文
RadarAI· 智源 FlagOpen:原创开源项目·· 16 小时前AI 评分38

智源 FlagOpen 开源 HumanCOIN:基于 LeRobot 的多传感器多频率数据集扩展

FlagOpen 开源 HumanCOIN:基于 LeRobot 的多传感器多频率数据集扩展

AI 导读

智源 FlagOpen 开源 HumanCOIN,一个基于 LeRobot 的多传感器、多频率数据集扩展,每个传感器按各自采样率独立存为 parquet 文件,查询时按时间窗口动态对齐,无需预先重采样。

正文 · AI 翻译

智源 FlagOpen:原创开源项目·2026-11-17 14:19· 43 分钟前AI 评分42

FlagOpen/HumanCOIN

AI 导读

智源 FlagOpen 开源 HumanCOIN,一个基于 LeRobot 的多传感器、多频率数据集扩展,每个传感器按各自采样率独立存为 parquet 文件,查询时按时间窗口动态对齐,无需预先重采样。

正文

📖 中文文档:README_zh-CN.md

基于 LeRobot 构建的面向真实世界数据的多传感器、多频率数据集扩展 —— 各传感器按各自独立的采样率存储,每个传感器一个 parquet 文件,查询时按时间窗口动态对齐。


目录


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_simple

4.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 模拟此类数据流,并在添加数据之前将它们对齐到主时钟:

  1. t_all_started——每个传感器都已交付其第一帧的挂钟时刻(所有第一帧时间的最大值)。
  2. t = 0——主时钟参考传感器在 t_all_started 处或之后的第一帧;其更早的帧被丢弃。
  3. timestamp_start——对于其他每个传感器,是其下一帧(t = 0 处或之后的第一帧)与 t = 0 帧之间的差值;在特征规格中设置它,使存储的时间戳与主时钟保持相位对齐。
  4. 记录从 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):

Visualizer screenshot

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 帧)时每个特性返回的读数:

Readings returned per feature when querying t = 0.333s (frame 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

设计原则:

  1. 每个特征一个对象:ParquetFeature、VideoFeature 和 AudioFeature 各自封装其缓冲区、文件路径和读写逻辑。Dataset 仅作为编排者。

  2. 读写对称:每个 Feature 同时提供 add/save(写入)和 load/query(读取)。

  3. 确定性路径:文件路径仅取决于 episode_index 和 feature_key;无需在 episodes.jsonl 中查找。

  4. 继承而非重写:为 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