pico-tool-track 0.1.1

PICO track 数据可视化与编辑工具（曲线编辑 + 三维帧编辑）

tools/track — PICO Track 数据可视化与编辑工具

提供轨迹（track）JSON 数据的曲线编辑、三维帧编辑、统一 Web 编辑器与帧率重采样， 用于人工调整人形机器人的动作轨迹数据。

工具

命令	描述	依赖
pico-tool-track curve <json>	关节角度曲线编辑器，拖动控制点调整样条轨迹	matplotlib + scipy
pico-tool-track edit <json>	三维帧编辑器，逐帧调整 + 实时 3D 骨架预览	viser + mujoco
pico-tool-track web [json...]	独立编辑器（曲线编辑 + 3D 骨架联动，同一窗口内）	fastapi + mujoco
pico-tool-track resample <json>	轨迹帧率重采样（整数倍插帧 / 抽帧）	无额外依赖

安装

# 仅曲线编辑器 + 重采样（轻量）
cd tools/track
uv sync

# 同时安装三维帧编辑器
uv sync --extra edit3d

# 同时安装独立 Web 编辑器（曲线 + 3D 联动窗口）
uv sync --extra web

或通过 pico CLI 直接使用（依赖自动安装，默认走统一 Web 编辑器）：

pico tool track motion.json

独立发布安装后（见下方“独立发布”），可直接调用 pico-tool-track：

pico-tool-track curve motion.json
pico-tool-track edit  motion.json

曲线编辑器 (curve)

以稀疏控制点 + 三次样条插值方式编辑各关节角度轨迹（类似贝塞尔曲线效果）：

• 灰色曲线：原始轨迹（只读参考）
• 蓝色曲线：当前样条拟合结果
• 红点：可拖动的控制点（仅 Y 轴，上下拖拽改变曲线形状）

操作

操作	说明
左键拖动红点	调整该关节曲线
S	保存到输出文件
R（光标在某关节子图内）	还原该关节到原始轨迹
A	还原全部关节
Q / 关闭窗口	退出（不保存）

选项

pico-tool-track curve data.json                 # 默认控制点数 max(5, N//15)
pico-tool-track curve data.json --ctrl 20       # 指定 20 个控制点（越少越平滑）
pico-tool-track curve data.json -o edited.json  # 保存到新文件

三维帧编辑器 (edit)

通过浏览器 GUI（基于 viser）查看 3D 骨架动画并逐帧调整关节角度：

• 帧滑条 + 播放/暂停
• 按腿/腰/臂分组的关节滑条
• 单帧或全帧批量修改
• 修改后自动重算 FK（更新 body_pos_w）

选项

pico-tool-track edit data.json                        # 默认端口 8080
pico-tool-track edit data.json --port 8081            # 自定义端口
pico-tool-track edit data.json --mjcf robot.xml       # 手动指定 MJCF
pico-tool-track edit data.json -o edited.json         # 保存到新文件

独立编辑器 (web)

曲线编辑 + 3D 骨架联动的统一编辑器，启动后自动在系统浏览器中打开：

• 拖动控制点 → 3D 视图实时更新；播放时光标跟随
• 支持一次性加载多个文件，通过左侧文件清单切换编辑目标
• 省略输入文件可以空白地面模式启动，界面内通过 🤖 Model / 📂 Files 面板导入

pico-tool-track web data.json                     # 默认端口 27860
pico-tool-track web data.json --port 27861 --ctrl 20
pico-tool-track web file1.json file2.json          # 多文件模式
pico-tool-track web --mjcf robot.xml               # 空白模式，指定初始模型

帧率重采样 (resample)

升采样：相邻帧间线性插值（位置/关节角）+ SLERP（四元数旋转）。 降采样：均匀抽取。

pico-tool-track resample data.json --fps 100
pico-tool-track resample data.json --factor 2
pico-tool-track resample data.json --fps 25 --output out.json

数据格式

输入/输出均为 track JSON 格式，包含：

{
  "joint_names": ["left_hip_pitch_joint", ...],
  "fps": 50.0,
  "num_frames": "片段总帧数",
  "duration":   "片段时长（秒）= num_frames / fps",
  "joint_pos":  "(N, J) 关节角度（rad）",
  "root_pos_w": "(N, 3) 根节点世界坐标",
  "root_rot_w": "(N, 4) 根节点四元数 xyzw",
  "body_names": "list[str]，body_pos_w 各列对应的 MuJoCo body 名称",
  "body_pos_w": "(N, B, 3) 各 body 世界坐标（FK 重算）"
}

注意：curve 命令仅更新 joint_pos，body_pos_w 需用 edit/web 命令 重新计算 FK。resample 会同步重采样所有帧相关字段。

独立发布

tools/track/ 是完全独立于 ROS 2 工作区的 Python 包，可脱离 monorepo 单独发布安装：

pico tool release track --bump 0.2.0 --upload

生成 wheel + 一键安装脚本并上传到 GitHub Releases，目标机执行：

curl -fsSL https://github.com/<owner>/<repo>/releases/download/tools/track/v0.2.0/install-pico-tool-track.sh | bash