Phase 4: Rerun.io 可视化集成

状态: ✅ 已完成 完成时间: 2025-12-26 目标: 验证多模态可视化管线

🤔 为什么需要 Rerun.io?

想象一下调试多传感器系统:

📹 Vision: 看 3D 骨架动画
📱 IMU: 看角速度曲线
💪 EMG: 看肌肉激活时序

如果用普通 matplotlib,需要:

3 个独立的图表
手动对齐时间轴
无法同步播放
调试效率低 😓

Rerun.io 能做什么?

✅ 一个窗口显示所有模态
✅ 自动同步时间轴
✅ 交互式播放/暂停
✅ 点击时间轴,所有视图跳转到同一时刻

🎯 实现方案

数据导出管线

创建了 scripts/export_to_rerun.py,包含以下模块:

python

def load_trial_data(mat_path: str):
    """从 .mat 文件加载多模态数据"""
    # 返回 IMU (240Hz), EMG (2048Hz), Marker (128Hz)

def log_marker_skeleton(marker_data, marker_rate, trial_name):
    """记录 3D 骨架点云"""
    # 33 个 marker 点
    # 计算并显示质心 (center of mass)

def log_imu_data(imu_data, imu_rate, trial_name):
    """记录 IMU 时间序列"""
    # 角速度 (angular velocity)
    # 加速度 xyz 三轴

def log_emg_data(emg_data, emg_rate, trial_name):
    """记录 EMG 肌肉激活"""
    # 按肌肉群分组: lower (0-2), core (3-5), upper (6-8)
    # 应用 RMS 平滑 (50ms 窗口)

def log_features(features, trial_name):
    """标注提取的特征"""
    # 动力链正确性状态
    # 特征汇总 (sway, lift, tempo, etc.)

降采样策略

为了减小文件大小,采用智能降采样:

模态	原始采样率	目标采样率	降采样因子	原因
Marker	128 Hz	128 Hz	1×	已经足够低,不需要降采样
IMU	240 Hz	~30 Hz	8×	视觉流畅度仅需 30fps
EMG	2048 Hz	~100 Hz	20×	保留肌肉激活细节

文件大小: 8.8 MB (3 个试次)

📊 导出结果

成功导出了 3 个试次:

1. `Subj04_jump.mat` - 正常跳跃

Marker: 4780 帧 (37.3s)
IMU: 1120 帧 (降采样后)
EMG: 3824 帧 (降采样后)
动力链状态: ✅ CORRECT

2. `Subj04_lunge.mat` - 弓步 (最差案例)

Marker: 6722 帧 (52.5s)
IMU: 1575 帧
EMG: 5378 帧
动力链状态: ❌ INCORRECT (倒置链)

3. `Subj04_squat.mat` - 深蹲

Marker: 3666 帧 (28.6s)
IMU: 859 帧
EMG: 2933 帧
动力链状态: Varies

🔍 可视化内容

生成的 .rrd 文件包含:

3D 视图

Marker Points (蓝色): 33 个身体标记点,1.5cm 半径
Center of Mass (红色): 质心轨迹,3cm 半径
动画播放,展示完整运动序列

时间序列 - IMU

Angular Velocity (°/s): 3D 角速度幅值
Acceleration X/Y/Z (m/s²): 三轴加速度

时间序列 - EMG

Lower Body (Legs): 通道 0-2 平均 RMS
Core: 通道 3-5 平均 RMS
Upper Body (Arms): 通道 6-8 平均 RMS

标注

Kinetic Chain Status: ✅ CORRECT 或 ❌ INCORRECT
Feature Summary: Sway, Lift, Peak Angular Velocity, Tempo Ratio, Core Activation

🚀 如何查看

方法 1: Rerun Viewer (推荐)

bash

# 在项目根目录运行
rerun results/rerun/multimodal_visualization.rrd

# 或激活虚拟环境后
source .venv/bin/activate
rerun results/rerun/multimodal_visualization.rrd

方法 2: Web Viewer

访问 https://rerun.io/viewer
将 .rrd 文件拖拽到浏览器
在线查看可视化

🎬 可视化界面布局

┌─────────────────────────────────────────────────┐
│  [3D View - Spatial]                            │
│   ◉ ◉ ◉  <- 33 markers (blue)                  │
│    |👤|    <- skeleton animation                │
│   ◉ ◉ ◉                                         │
│     ●     <- center of mass (red)              │
├─────────────────────────────────────────────────┤
│  [Time Series - IMU]                            │
│  Angular Velocity: ～～～～～～～               │
│  Acc X: ～～～～～～～                          │
│  Acc Y: ～～～～～～～                          │
│  Acc Z: ～～～～～～～                          │
├─────────────────────────────────────────────────┤
│  [Time Series - EMG]                            │
│  Lower (Legs):  ～～～～～～～                  │
│  Core:          ～～～～～～～                  │
│  Upper (Arms):  ～～～～～～～                  │
├─────────────────────────────────────────────────┤
│  [Annotations]                                   │
│  Kinetic Chain: ✅ CORRECT                      │
│  Sway: 0.234m, Lift: 0.089m                    │
│  Peak Angular Velocity: 198.5°/s                │
├─────────────────────────────────────────────────┤
│  [Timeline] |████████▶───────────| 15.2s / 37.3s│
└─────────────────────────────────────────────────┘

交互功能:

🎮 播放/暂停/快进/快退
🕐 拖动时间轴,所有视图同步跳转
🔍 缩放时间轴查看细节
📌 点击数据点查看数值

🔬 技术细节

Rerun API 使用

python

import rerun as rr

# 初始化
rr.init("Movement Chain AI - Multimodal Validation", spawn=False)
rr.save(str(output_file))

# 记录 3D 点云
rr.set_time("time", timestamp=time)
rr.log(
    f"{trial_name}/markers/points",
    rr.Points3D(
        valid_positions,
        radii=0.015,  # 1.5cm
        colors=[100, 200, 255]  # Blue
    )
)

# 记录标量时间序列 (注意: Scalars 是复数)
rr.log(
    f"{trial_name}/imu/angular_velocity",
    rr.Scalars(float(angular_velocity[frame_idx]))
)

# 记录文本标注
rr.log(
    f"{trial_name}/analysis/kinetic_chain_status",
    rr.TextLog(
        f"Kinetic Chain: {'✅ CORRECT' if kinetic_chain_correct else '❌ INCORRECT'}",
        level="INFO" if kinetic_chain_correct else "WARN"
    )
)

遇到的 API 变化 (Rerun 0.28.1)

旧 API	新 API	说明
`rr.set_time_seconds("time", time)`	`rr.set_time("time", timestamp=time)`	时间轴设置
`rr.Scalar(value)`	`rr.Scalars(value)`	标量记录 (注意复数)

✅ 验收标准

全部通过:

✅ 能打开 .rrd 文件 (8.8 MB)
✅ 3D 骨架动画流畅 (128 Hz)
✅ 时间序列同步播放 (IMU ~30Hz, EMG ~100Hz)
✅ 时间轴控制正常 (3 个试次独立时间轴)
✅ 标注显示正确 (动力链状态 + 特征汇总)

🎓 关键发现

1. 可视化验证了时间同步

通过同时播放三个模态,确认:

Marker 和 EMG 时间轴完全对齐 (0ms 差异)
IMU 略有偏移但在可接受范围 (<30ms)

2. 动力链倒置清晰可见

在 Subj04_lunge.mat 中:

EMG Upper (手臂) 先激活
EMG Core (核心) 随后
EMG Lower (腿部) 最后
完全违反了从下到上的动力链理论

3. EMG 降采样效果好

从 2048 Hz 降到 ~100 Hz 后:

RMS 包络曲线保持平滑
激活时序特征清晰
文件大小大幅减小

📚 相关文档

Phase 3: 时间同步验证 - 上一步,确保数据已对齐
Phase 5: 规则引擎验证 - 下一步

官方文档: https://rerun.io/docs

📦 交付物

文件	描述	大小
`scripts/export_to_rerun.py`	Rerun 导出脚本	318 行
`results/rerun/multimodal_visualization.rrd`	可视化文件	8.8 MB

Phase 4 完成 ✅

下一步: Phase 5: 规则引擎验证

查看整体验证计划了解更多信息。

Phase 4: Rerun.io 可视化集成 ​

🤔 为什么需要 Rerun.io? ​

🎯 实现方案 ​

数据导出管线 ​

降采样策略 ​

📊 导出结果 ​

1. Subj04_jump.mat - 正常跳跃 ​

2. Subj04_lunge.mat - 弓步 (最差案例) ​

3. Subj04_squat.mat - 深蹲 ​

🔍 可视化内容 ​

3D 视图 ​

时间序列 - IMU ​

时间序列 - EMG ​

标注 ​

🚀 如何查看 ​

方法 1: Rerun Viewer (推荐) ​

方法 2: Web Viewer ​

🎬 可视化界面布局 ​

🔬 技术细节 ​

Rerun API 使用 ​

遇到的 API 变化 (Rerun 0.28.1) ​

✅ 验收标准 ​

🎓 关键发现 ​

1. 可视化验证了时间同步 ​

2. 动力链倒置清晰可见 ​

3. EMG 降采样效果好 ​

📚 相关文档 ​

📦 交付物 ​