# Orisys 视触觉

夹爪左右指上的视触觉相机（**不是**腕部 D405）。SDK 用厂家 wheel 安装
（`pip install --no-deps ~/sensor_ws/0.4.2/orisys-0.4.2-cp311-*.whl` 到 ros_flexiv 环境），
本仓库只放适配器、现场参数和 `dd03.json`。

源码：

| 文件 | 作用 |
|------|------|
| `arm_application/orisys_tactile.py` | SDK 适配 + `load_orisys_from_site` + `tactile_worker`（多进程工作器） |
| `arm_application/tactile_interface.py` | 可替换接口 / Mock |
| `arm_application/tactile_node.py` | 发布 `/tactile/left\|right/status`（三力），以及可选的 `/image`（深度图）与 `/vector`（力矢量场） |
| `arm_application/image_utils.py` | numpy 数组 → `sensor_msgs/Image` 的打包（编码自动判定） |
| `devices/sensors/orisys/models/dd03/config.json` | 传感器几何/跟踪（厂家配置，可进 git）。原先在 `src/arm_application/config/orisys/`，已迁到设备目录随 SDK 一起放 |

**四路数据怎么拿到**：三力在 `/tactile/<side>/status`（`TactileStatus` 的
`fnormal` / `fshearx` / `fsheary`），深度图在 `/tactile/<side>/image`，
力矢量场在 `/tactile/<side>/vector`（`32FC2`，每像素 dx/dy）。

后两路默认**关闭**：设 `site.yaml` 的 `tactile.image_hz > 0` 才发布。原因见下节 ——
图像不该和 30fps 的三力挤同一条队列。没有硬件时可以用
`ros2 run arm_application tactile --ros-args -p backend:=mock -p image_hz:=5.0`
把这两条话题跑起来验证链路。

**架构：每侧手指一个独立进程**（厂家示例 `two_sensor_pipeline.py` 的推荐做法，
每进程独立 CUDA 上下文）。实测单进程双开两路会互相拖垮（30→0.8fps），
双进程各 30fps。`tactile` 节点内部用 `multiprocessing(spawn)` 起两个 worker，
主进程只做队列→话题转发。worker 进程 comm 名 `orisys_tac_w`，runner 脚本会
连带清理（**孤儿 worker 会占死 /dev/video\***，表现为下次启动
"Failed to open video source"，手动清：`pkill orisys_tac_w`）。

现场要点（都在 **`config/site.yaml` → `tactile:`**）：

- `left_video/right_video` 用 **`/dev/v4l/by-path/...` 稳定路径**——Orisys 是
  "USB Camera"（不是 RealSense！），video 编号随插拔漂移，by-path 绑定物理 USB 口
- `cuda: false` + `infer_backend: cpu`——双路并行抢 GPU 上下文会互相拖慢，
  CPU 解算仅 ~9ms/帧足够（单路想快可开 cuda）
- 读数是**形变任意单位**（非牛顿）且夹持基线会漂移；三阶段节点启动时自动测
  静止基线，所有力阈值都是相对增量（见 `docs/HOLE_DETECT.md` 三阶段段落）

```bash
bash ~/ros2/scripts/run_tactile.sh --cli     # 打印力 若干秒
bash ~/ros2/scripts/run_tactile.sh           # ROS 节点
```

无硬件时：`tactile.backend: mock`。

搜孔插入运动（机械臂螺旋 + 力闭环）已由三阶段实现：`stage3_search_node.py`，
见 `docs/HOLE_DETECT.md` 三阶段段落，跑 `bash ~/ros2/scripts/run_stage3_search.sh --arm 89`。