Metadata-Version: 2.4
Name: pico-tool-track
Version: 0.1.1
Summary: PICO track 数据可视化与编辑工具（曲线编辑 + 三维帧编辑）
Author: chenxin199305
License: Proprietary
Project-URL: Homepage, https://github.com/chenxin199305/PICO
Project-URL: Repository, https://github.com/chenxin199305/PICO
Keywords: mujoco,motion-editing,robotics,matplotlib
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.8
Requires-Dist: scipy>=1.10
Requires-Dist: numpy>=1.24
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Requires-Dist: pico-tool-common>=0.1.0
Provides-Extra: edit3d
Requires-Dist: viser>=1.0; extra == "edit3d"
Requires-Dist: mujoco>=3.0; extra == "edit3d"
Provides-Extra: web
Requires-Dist: fastapi>=0.100; extra == "web"
Requires-Dist: uvicorn>=0.20; extra == "web"
Requires-Dist: pillow>=10.0; extra == "web"
Requires-Dist: mujoco>=3.0; extra == "web"
Requires-Dist: websockets>=12.0; extra == "web"

# 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>` | 轨迹帧率重采样（整数倍插帧 / 抽帧） | 无额外依赖 |

## 安装

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

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

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

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

```bash
pico tool track motion.json
```

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

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

## 曲线编辑器 (`curve`)

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

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

### 操作

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

### 选项

```bash
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`）

### 选项

```bash
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 面板导入

```bash
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（四元数旋转）。
降采样：均匀抽取。

```bash
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 格式，包含：

```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 单独发布安装：

```bash
pico tool release track --bump 0.2.0 --upload
```

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

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