> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 实时可视化

`wuji viz` 在浏览器中实时显示 Wuji Hand 2 与 Wuji Glove 的数据。可视化界面是 Rerun Web Viewer，由 `wuji viz` 在本机提供服务、在浏览器中打开，不需要另装软件。每次会话连接 1 台设备，并按设备类型调整 Viewer 内容：

* 带指尖触觉传感器的 Wuji Hand 2：三维手部模型跟随关节状态运动，各触点受力与指尖合力以箭头显示，并配有放大的指尖面板和滚动的合力曲线。
* 不带触觉传感器的 Wuji Hand 2：只显示三维手部模型。
* Wuji Glove：显示手骨架、EMF 接收器、触觉点云和原始触觉矩阵。

命令还支持 Wuji Hand 2 的运行时触觉归零、结构化输出，以及在可信网络中共享 Viewer。命令不录制 RRD 文件，也不回放录制文件。

## 启动 Viewer

连接设备后运行：

```bash theme={null}
wuji viz
```

不带 `--sn` 时，命令同时扫描 Wuji Hand 2 与 Wuji Glove。恰好发现 1 台受支持的设备时直接连接。交互式终端发现多台设备时，从列表中选择目标设备，列表显示序列号与设备类型。在列表中按 Esc 或 Ctrl+C 可取消：命令输出 `Cancelled.`，以退出码 9 结束，不会改连其他设备。连接失败时同样不会改连其他设备。使用 `--sn` 可指定设备：

```bash theme={null}
wuji viz --sn <SN>
```

`--address` 与 `--handedness` 不能用于选择设备。左右手由命令从设备读取。

命令会输出 Viewer URL，并在默认浏览器中打开。添加 `--no-open` 后仅输出 URL，不打开浏览器。按 Ctrl+C 停止 Viewer 并释放设备连接。

每次会话只支持 1 个活动的 Viewer 页面。再次打开 URL、换浏览器或换设备打开前，先关闭原页面。两个页面同时保持连接时，其中一个页面卡顿或转入后台，最终会让两个页面都停止更新。

## Wuji Hand 2 触觉归零

归零只作用于启动时 5 个指尖传感器全部在线的 Wuji Hand 2。默认情况下，`wuji viz` 在推流前执行一次归零：先确认每个传感器上报的型号正确且处于就绪状态，再向设备下发整手零基线标定，并等待全部手指完成。终端显示 `Tactile zero: ready.` 后才开始推流。这一步等价于 SDK 的 `tactile_calibrate()`。基线保存在设备上，属于运行时基线，不会改写设备的持久化触觉模型。

从运行命令开始，到终端显示 `Tactile zero: ready.` 为止，必须保持 5 个指尖表面都不受力。如果归零时指尖压在桌面上或被握住，这部分接触力会被当作零点，之后显示的力值就会有偏差。

跳过归零：

```bash theme={null}
wuji viz --no-zero
```

是否执行归零的区别：

| | 默认（执行归零） | `--no-zero` |
| - | - | - |
| 启动要求 | 5 个指尖悬空，等待 `Tactile zero: ready.` | 无 |
| 零基线 | 启动瞬间的不受力读数 | 设备当前生效的零基线 |
| 显示的力 | 净接触力 | 可能带有零点漂移 |
| 适用场景 | 大多数场景 | 指尖无法腾空，比如手已装在机械臂上，或不想改动当前基线 |

归零未在 10 秒内完成、启动时某个传感器仍在标定，或传感器上报的型号异常时，命令报错退出。检查设备后再重试。归零期间按 Ctrl+C，命令会等待进行中的归零操作结束后再退出。

不带触觉传感器的 Wuji Hand 2 与 Wuji Glove 自动跳过归零，`--no-zero` 对它们无效。

## 查看 Viewer

Viewer 左侧的 Blueprint 面板列出全部视图，点击视图旁的眼睛图标可以隐藏或显示某个视图。布局取决于所连接的设备。

### 带触觉传感器的 Wuji Hand 2

下图的编号对应 4 类内容：

<img src="https://mintcdn.com/wuji-0bbde051/GsT0bEnPZ_18e5HL/assets/source/images/zh/wuji-cli/viz-viewer-overview.png?fit=max&auto=format&n=GsT0bEnPZ_18e5HL&q=85&s=ab81e7f1f3fd1a2c8e8d79b2d1e7a4ba" alt="Viewer 布局" width="1938" height="1174" data-path="assets/source/images/zh/wuji-cli/viz-viewer-overview.png" />

1. **三维手部模型**：左上面板。模型跟随实时关节状态运动，指尖上的白点是触觉传感器的触点。
2. **受力箭头**：指尖受力时，三维模型和对应的指尖面板会从触点画出箭头。每个触点一支细箭头表示该点的三轴力，另一支粗箭头表示该指尖的合力。箭头长度与力值成正比，颜色随力值增大由绿渐变到黄，再渐变到红。
3. **指尖面板**：下方 5 个面板按拇指到小指排列，放大显示每个指尖的触点和箭头。
4. **合力曲线**：右上面板显示 5 个指尖的合力大小，滚动显示最近 60 秒，曲线颜色与图例中的手指对应。

下面的录屏是按压指尖时的显示效果：

<video controls width="100%">
  <source src="https://mintcdn.com/wuji-0bbde051/GsT0bEnPZ_18e5HL/assets/source/images/zh/wuji-cli/viz-demo.mp4?fit=max&auto=format&n=GsT0bEnPZ_18e5HL&q=85&s=10efd54d43f1edb61b116474eca18285" type="video/mp4" data-path="assets/source/images/zh/wuji-cli/viz-demo.mp4" />
</video>

### 不带触觉传感器的 Wuji Hand 2

启动时，命令检查各指尖触觉节点是否在线。全部离线时，终端输出 `Tactile: unavailable; starting joint-only visualization.`，Viewer 只显示三维手部模型，指尖外壳仍然保留，指尖面板和合力曲线隐藏。只有部分传感器在线时，Viewer 保留全部 5 个指尖面板，缺失手指的面板留空。

### Wuji Glove

Viewer 显示手骨架、EMF 接收器、触觉点云和原始触觉矩阵。启动时，命令对 `emf_poses`、`tactile`、`tactile_zones` 和掌部 IMU 数据流请求 60 Hz，并输出各数据流实际生效的频率。不支持调节频率的固件保持默认频率，命令输出警告。两种情况下 Viewer 都按最新收到的状态渲染，上限 60 Hz。

下图是连接 Wuji Glove 时的 Viewer 布局，左侧是三维手骨架与 EMF 接收器，右侧是原始触觉矩阵：

<img src="https://mintcdn.com/wuji-0bbde051/GsT0bEnPZ_18e5HL/assets/source/images/zh/wuji-cli/viz-glove-overview.png?fit=max&auto=format&n=GsT0bEnPZ_18e5HL&q=85&s=ff0663d7cda04f9359c44a40c6d99ab2" alt="Wuji Glove 的 Viewer 布局" width="1793" height="964" data-path="assets/source/images/zh/wuji-cli/viz-glove-overview.png" />

## 处理故障

Viewer 显示各数据流最近一次收到的有效状态。详细的警告和错误显示在终端中，Viewer 页面不显示健康标记。

* Wuji Hand 2：某个指尖数据流在产生有效数据后发生故障时，对应面板保留最后一帧，其他数据流继续更新。关节数据流发生故障时，Viewer 保留最后一个有效手部姿态。
* Wuji Glove：某个数据流收到无效帧时，该数据流保留最后一个有效画面，其他数据流继续更新。
* 设备断开后，Viewer 保留最后一次有效状态，命令不会自动重新连接。按 Ctrl+C 结束后，命令返回失败状态。

## 使用结构化输出

加上 `--json` 或 `--jsonl` 后，命令在 Viewer 就绪时向 stdout 写一条启动报告，随后继续运行。报告包含 `status: "running"`、设备序列号与左右手、Viewer 地址和是否开放局域网访问。此后 stdout 不再有输出：实时数据只进 Rerun，进度、警告和错误仍写到 stderr。Ctrl+C 不会追加第二条记录。

```bash theme={null}
wuji viz --sn <SN> --no-zero --no-open --jsonl
```

```json theme={null}
{
  "status": "running",
  "device": {
    "sn": "<SN>",
    "handedness": "left"
  },
  "viewer": {
    "url": "http://127.0.0.1:<port>?theme=dark&url=<encoded-endpoint>",
    "lan": false
  }
}
```

`viewer.url` 必须按原样使用。其中的查询参数负责把 Viewer 页面连接到数据流，截掉参数后打开的是空 Viewer。

结构化输出或无人值守场景不会打开选择列表，因此发现多台受支持的设备时必须使用 `--sn`。取消交互式选择时，命令以退出码 9 结束。启动失败时 stdout 保持为空，错误写入 stderr。

## 在可信网络中共享

Viewer 默认仅绑定环回地址。使用 `--lan` 选择默认路由上的私有地址，或使用 `--bind` 指定本机地址：

```bash theme={null}
wuji viz --lan --no-open
wuji viz --bind 10.42.0.7 --no-open
```

`--lan` 和 `--bind` 不能同时使用。通过非环回地址访问时，Viewer 不提供身份验证或 TLS。仅在可信网络中使用，并将命令输出的 URL 分享给需要访问的人员。单个活动页面的限制同样适用：分享出去的 URL 同一时间只能在 1 个页面中打开。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.