# Npz Video Replay

> 将仿真记录 NPZ/CSV 文件在宿主机上回放为 MuJoCo 多视角 MP4 视频。触发关键词：npz 转视频、生成视频、回放、replay、渲染视频、宿主机渲染、输出视频.

- Skill: `frankjie09/npz-video-replay` (Agent Skill)
- Install (CLI): `npx skillmds@latest add frankjie09/npz-video-replay`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frankjie09/npz-video-replay/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: FrankJIE09 (https://skillmd.com/u/frankjie09)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/frankjie09/npz-video-replay

---


# NPZ → MuJoCo 多视角视频回放（宿主机）

## 为什么要用宿主机

`replay_npz_video.py` 只需要 `mujoco` + `opencv-python` 两个 Python 包，**不需要 ROS 2 / Docker 环境**。宿主机上通常有 GPU/更好的 CPU，渲染比 Docker 内更快。用宿主机渲染可以避免 Docker X11 / GPU 转发问题。

## 前置要求（宿主机）

```bash
python3 -c "import mujoco; print(mujoco.__version__)"   # 需要 >= 3.x
python3 -c "import cv2; print(cv2.__version__)"           # 需要 opencv-python
which ffmpeg                                              # 可选，视频编码用
```

如果缺包：
```bash
pip install mujoco opencv-python
```

## 视频长度控制

**视频不要录制全部仿真时长（通常仿真跑 40-60s），只取前 ~10 秒即可**。控制方式：

| 方法 | 参数 | 示例 |
|---|---|---|
| CSV→NPZ 时限制行数 | `csv_to_npz.py --max_rows 2000` | 2000 行 @200Hz ≈ 10 秒 |
| NPZ→视频时用 `replay_npz_video.py` `--max_rows` | 不支持（需在 csv_to_npz 阶段限） | — |

## 输出路径规范

**视频必须输出到 `anyverse` 仓库内，不能放在 `/tmp`。**

```bash
# 输出目录固定
OUTPUT_DIR=/anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_cpp_validation/output_videos
```

## 用法

### 基本命令

```bash
OUTPUT_DIR=/anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_cpp_validation/output_videos
python3 /anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_validation/replay_npz_video.py \
    --npz /tmp/full_wbc_position_sim_joint_states.npz \
    --mjcf /anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_validation/kitt_1_5_robot_fixed.xml \
    --output $OUTPUT_DIR/verify_wbc.mp4 \
    --fps 30 \
    --views front iso right top
```

### 参数说明

| 参数 | 默认值 | 说明 |
|---|---|---|
| `--npz` | `/tmp/full_wbc_position_sim_joint_states.npz` | 输入的 NPZ 数据文件 |
| `--mjcf` | 脚本同目录 `kitt_1_5_robot_fixed.xml` | MuJoCo 模型文件 |
| `--output` | 脚本同目录 `vel_wbc_replay.mp4` | **必须指定仓库内路径**，自动加 `_{view}` 后缀 |
| `--fps` | 30 | 视频帧率 |
| `--views` | `front iso right top` | 要渲染的视角列表 |

### 可用视角

`front`, `rear`, `left`, `right`, `iso`, `top`

### 输出视频路径

每个视角生成独立文件：`{output}_{view}.mp4`
例如：`output_videos/verify_wbc_front.mp4`, `output_videos/verify_wbc_iso.mp4` ...

## 完整流程（仿真 → CSV → NPZ → 视频）

### 方式 A：C++ 仿真（position_verify / closed_loop 模式）

```bash
# 1. 容器内运行仿真
docker exec agent_dev_nvidia bash -lc '
source /usr/local/mw/setup.bash && source /opt/ros/jazzy/setup.bash && source /anyverse/install/setup.bash
export ROS_DOMAIN_ID=42
ros2 launch mujoco_sim_bringup mujoco_sim_verify.launch.py
'

# 2. 容器内 CSV → NPZ 转换（限 2000 行 ≈ 10 秒）
docker exec agent_dev_nvidia bash -lc '
python3 /anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_validation/csv_to_npz.py \
    --csv /tmp/wbc_debug_log.csv \
    --npz /tmp/full_wbc_position_sim_joint_states.npz \
    --skip_rows 0 \
    --max_rows 2000
'

# 3. 宿主机渲染视频（GPU 加速），输出到仓库内
OUTPUT_DIR=/anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_cpp_validation/output_videos
python3 /anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_validation/replay_npz_video.py \
    --npz /tmp/full_wbc_position_sim_joint_states.npz \
    --output $OUTPUT_DIR/verify_wbc.mp4 \
    --fps 30 \
    --views front iso right top
```

### 方式 B：Python 仿真（mujoco_wbc_validation.py 直接生成 NPZ）

```bash
# 1. 容器内运行 Python 验证脚本（自动保存 NPZ）
docker exec agent_dev_nvidia bash -lc '
cd /anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_validation
python3 mujoco_wbc_validation.py
'

# 2. 宿主机渲染视频
OUTPUT_DIR=/anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_cpp_validation/output_videos
python3 /anyverse/src/pnc/controller/wbc_controller/mujoco_wbc_validation/replay_npz_video.py \
    --npz /tmp/full_wbc_position_sim_joint_states.npz \
    --output $OUTPUT_DIR/verify_python_wbc.mp4 \
    --fps 30 \
    --views front iso right top
```

## CSV → NPZ 转换脚本

`csv_to_npz.py` 将 C++ 仿真保存的 CSV 调试日志转为 `replay_npz_video.py` 可读的 NPZ 格式：

```bash
python3 csv_to_npz.py \
    --csv /tmp/wbc_debug_log.csv \
    --npz /tmp/full_wbc_position_sim_joint_states.npz \
    --skip_rows 0 \
    --max_rows 2000          # 限制 2000 行 ≈ 10 秒
```

### CSV 格式说明

C++ 控制器 `wbc_debug_log.csv` 的列（44 列，0-indexed）：

| 列范围 | 内容 |
|---|---|
| 第 0 列 | 时间戳 (s) |
| 第 1-3 列 | 左臂末端位置误差 (e_pos_L x/y/z) |
| 第 4-6 列 | 右臂末端位置误差 (e_pos_R x/y/z) |
| 第 7-9 列 | 左臂末端姿态误差 (e_rot_L) |
| 第 10-12 列 | 右臂末端姿态误差 (e_rot_R) |
| 第 13-24 列 | 12维期望速度 (x_des) |
| 第 25 列 | dq_scale |
| **第 26-43 列** | **18 个关节位置 q**（左7 + 右7 + 躯干4）——这是视频回放用的列 |

### NPZ 包含三个数组

| 数组 | 形状 | 说明 |
|---|---|---|
| `times` | (N,) | 时间戳 |
| `positions` | (N, 18) | 关节位置，顺序：左7 + 右7 + 躯干4 |
| `joint_names` | (18,) | 关节名称列表 |

## 注意点

1. **仿真通常会跑 40-60 秒**（CSV 约 8000-12000 行），回放视频不需要这么长，用 `csv_to_npz.py --max_rows 2000` 只取前 ~10 秒
2. **输出路径必须在 anyverse 仓库内**，默认放 `output_videos/` 目录
3. CSV→NPZ 转换在容器内执行，NPZ→视频渲染在宿主机执行（利用 GPU 加速）
4. 渲染的 FPS 和仿真频率无关：仿真 200Hz 记录数据，视频可以按 30fps 回放