# openduckx_viewer

**Repository Path**: ncnynl/openduckx_viewer

## Basic Information

- **Project Name**: openduckx_viewer
- **Description**: 作为https://gitee.com/ncnynl/Open_Duck_Mini_Viewer的修改版本
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# openduckx_viewer — 多模型浏览器查看器（中文说明）

基于 [Open_Duck_Mini_Viewer](https://github.com/mertcookimg/Open_Duck_Mini_Viewer)
(Apache-2.0) fork 扩展：**同一个界面内切换查看多种鸭子模型**。

| 模型 | 说明 | 渲染方式 |
|---|---|---|
| **OpenDuck Mini v2** | 现役真机 (STS3215, CAD 关节限位) | URDF + STL (urdf-loader) |
| **OpenduckX v3 (21-link 树)** | "大号 microduck"：v9 CAD 逐零件几何 + 我们自己的 21-link 关节树 + 人工确认限位 | URDF + STL (urdf-loader) |
| **OpenduckX v3 (MJCF 物理模型)** | 同一份几何的 MuJoCo 描述（14 驱动关节、天线焊死、脚底 TPU 碰撞） | MJCF + STL (自研加载器) |
| **MicroDuck** | xl330 小鸭 (MJCF, 14 关节) | MJCF + STL 直读 (自研加载器, FK 与 mujoco 实测一致) |

> 两个 v3 条目是**同一份几何的两种描述**（URDF / MJCF），几何逐零件重合，
> 放在一起就是为了互相校验 —— 验证方法见 [`docs/verify_openduckx_v3.md`](docs/verify_openduckx_v3.md)。

## 搭建（一键）

```bash
git clone git@gitee.com:ncnynl/openduckx_viewer.git
cd openduckx_viewer
./scripts/setup.sh            # 开发模式 → http://localhost:5173
# ./scripts/setup.sh build    # 或构建静态站到 dist/
```

仅需 Node.js ≥ 18（`setup.sh` 会自动检查并提示安装方式）。
npm 慢可加镜像：`NPM_REGISTRY=https://registry.npmmirror.com ./scripts/setup.sh`
坑：shell 里若已设 `NODE_ENV=production`，npm 会跳过 devDependencies —— setup.sh 已自动处理。

## 装成服务（后台常驻 + 开机自启）

不想每次手动起，用服务脚本：

```bash
./scripts/service.sh install     # 装依赖 + 构建 + 注册服务 + 启动
./scripts/service.sh status      # 运行状态 + 访问地址 + 真机桥检查
./scripts/service.sh stop        # 停止
./scripts/service.sh restart     # 重启
./scripts/service.sh uninstall   # 卸载 (加 --purge 连 node_modules/dist 一起清)
```

有 systemd 时注册成 user service 自动开机启动（需 `sudo loginctl enable-linger $USER`）；
无 systemd 时回退 nohup + pidfile。端口/监听地址可调：
`VIEWER_PORT=8080 VIEWER_HOST=127.0.0.1 ./scripts/service.sh install`

详见 [`docs/service.md`](docs/service.md)。

## 使用

- 右上状态栏 **模型** 下拉框切换 v2 / OpenduckX v3（URDF & MJCF）/ MicroDuck；
  切换即重置为对应模型 home 姿态，左侧滑杆/动作按钮/表格全部跟随当前模型限位与 home。
- 动作按钮：home / stand / bow / wave / headbang / dance（MicroDuck 也适用，
  其 home = scene_walk INIT 全零直立；stand = STAND keyframe）。
- 滑杆逐关节摆姿势（超 v2 限位的 OpenduckX/MicroDuck 姿态在这里可以摆出来）。
- 驾驶摇杆 / WASD 是**演示用假 gait**（前端插值，不是 onnx 策略输出）。

## 验证

拿到 v3 模型先别急着信 —— 本仓库有两个 v3 条目可以**互相对拍**，
外加 openduckx_rl 里的一键数值自检。完整清单（含 1080Ti / Docker 上的跑法）见
**[`docs/verify_openduckx_v3.md`](docs/verify_openduckx_v3.md)**。

最短路径：

1. 切到两个 v3 条目 → 几何应逐零件重合（🧭 坐标系 + 悬停对 xyz）；
2. 拖滑杆 → 关节按轴向转动、不超限位；
3. 硬证据 → 在 openduckx_rl 里跑 `scripts/verify_openduckx_v3.py`（期望全 PASS）
   与 `scripts/verify_v3_geometry.py`（期望最大偏差 `0.000000 mm`）。

## 模型数据来源与更新

- `public/assets/odx_v8/` — OpenduckX v3 资产：`urdf/robot_v3.urdf`（21-link 树）、
  `meshes/openduckx_v3.xml`（MJCF）+ `meshes/*.stl`（91 个）、`frames_v3.json` / `frames.json`
  （坐标帧数据，由导出脚本生成）。
- `public/assets/open_duck_mini_v2/` — v2 URDF+STL（上游资产）。
- `public/models/microduck/` — `robot_walk.xml`（原样拷贝自
  mjlab_microduck/robot/microduck/）+ 38 个 visual STL + `keys.json`
  （关节限位与 scene_walk keyframes，由 mujoco 提取）。
- 限位/姿态元数据集中在 `src/robot/models.ts`；加载器在
  `src/components/viewer/MjcfDuckView.tsx`（MJCF FK 语义已与 mujoco 数值对照：
  hinge = 子 body 绕自身局部 z 轴，body 框 = T(pos)·R(quat)）。

## 局限（诚实说明）

- 本查看器**不能加载 onnx 策略、不做物理仿真**；内置 walk/dance 是演示动画。
  要看训练策略真实效果 → mujoco 脚本（`run.sh infer/view`、sim_session_101d.py）。
- MicroDuck 无天线关节；v2 的天线动作在 MicroDuck 下自动忽略。
- MicroDuck 关节滑杆范围 = robot_walk.xml 限位（真机 xl330 数据）；OpenduckX v3
  限位来自人工确认表（v9 CAD 几何 + 21-link 树），**不一定等于 v2 真机能力**。