Metadata-Version: 2.4
Name: pico-tool-track
Version: 0.1.2
Summary: PICO track 数据可视化与编辑工具（曲线编辑 + 三维帧编辑）
Author: chenxin199305
License: MIT
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
License-File: LICENSE
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.1
Requires-Dist: viser>=1.0
Requires-Dist: mujoco>=3.0
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.20
Requires-Dist: pillow>=10.0
Requires-Dist: websockets>=12.0
Provides-Extra: edit3d
Provides-Extra: web
Dynamic: license-file

# pico-tool-track

Curve editing, 3D frame editing, a unified web editor, and frame-rate
resampling for humanoid robot motion tracks (track JSON).

[中文说明](#中文说明) · [Changelog](CHANGELOG.md)

## Quickstart (PyPI)

```bash
# 1. Install uv (once)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install the tool — everything included, no extras needed
uv tool install pico-tool-track

# 3. Run
pico-tool-track web motion.json                  # unified editor (curve + 3D skeleton)
pico-tool-track web motion.json --mjcf robot.xml # with an explicit robot model
pico-tool-track curve motion.json                # matplotlib curve editor
pico-tool-track resample motion.json --fps 100   # resample to 100 Hz
```

After installation the `pico-tool-track` command is available globally.
One-off runs without installing: `uvx pico-tool-track web motion.json`.

## Tools

| Command | Description | Backend |
|---|---|---|
| `pico-tool-track web [json...]` | Unified editor: spline curve editing + linked 3D skeleton preview | fastapi + mujoco |
| `pico-tool-track curve <json>` | Joint-angle curve editor with draggable control points | matplotlib + scipy |
| `pico-tool-track edit <json>` | Per-frame 3D editor with live skeleton preview | viser + mujoco |
| `pico-tool-track resample <json>` | Frame-rate resampling (integer-multiple up/down) | — |

## Notes

- **Robot model**: pass `--mjcf <file>` to preview a skeleton, or load one in
  the UI via the 🤖 Model button. Without a model the editor starts with an
  empty floor.
- **Headless servers**: 3D rendering uses MuJoCo offscreen rendering. On a
  headless Linux server without GPU, run with `MUJOCO_GL=osmesa`.
- **Data format**: input/output is track JSON (`joint_names`, `fps`,
  `num_frames`, `joint_pos`, `root_pos_w`, `root_rot_w`, `body_names`,
  `body_pos_w`).

---

## 中文说明

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

### 安装（PyPI）

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install pico-tool-track   # 全量安装，所有功能开箱即用
```

### 使用

```bash
pico-tool-track web motion.json               # 统一编辑器（曲线 + 3D 骨架联动）
pico-tool-track web motion.json --mjcf robot.xml
pico-tool-track curve motion.json             # 曲线编辑器
pico-tool-track resample motion.json --fps 100
```

### 说明

- **机器人模型**：通过 `--mjcf` 指定，或启动后点界面 🤖 Model 按钮导入；
  不传模型则以空白地面模式启动。
- **无 GPU 服务器**：3D 渲染走 MuJoCo 离屏渲染，无显示无 GPU 的 Linux
  服务器请用 `MUJOCO_GL=osmesa pico-tool-track web ...`。
- **版本与更新**：`pico-tool-track --version` 查看版本；
  `uv tool upgrade pico-tool-track` 升级。

### 仓库内开发

```bash
cd tools/track
uv sync                                # 安装全部依赖
uv run pico-tool-track web data.json
```

## 独立发布（GitHub Releases 一键安装）

除 PyPI 外，也可以用 `pico tool release track --upload` 生成 wheel +
一键安装脚本发布到 GitHub Releases：

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