# 灵枢 · 会话式像素→3D 精度测试

在电脑上点一下图像，板子自动抓帧、算三维点、跟踪位姿，实时给出目标点的坐标差 Δ。
不再手动 `scp` 图片、手动回传坐标。

## 目录

```
lingshu_session/
├── agents.md          # 给 AI/开发者的项目说明与硬性约定
├── README.md
├── client/            # 电脑端（Windows / Linux）
└── server/            # 板子端（Ubuntu 24.04 + ROS2 Jazzy）
```

## 快速开始

### 板子

```bash
# 1) pynng
sudo apt install -y python3-venv
python3 -m venv --system-site-packages ~/pynng_venv
~/pynng_venv/bin/pip install pynng

# 2) 把 server/ 下 5 个文件拷到 ~/Workplace/odin_ws/
#    wire.py  calib.py  target_math.py  session_server_node.py  requirements.txt

# 3) 启动驱动后，启动会话服务
source /opt/ros/jazzy/setup.bash
source ~/Workplace/odin_ws/install/setup.bash
~/pynng_venv/bin/python session_server_node.py --port 5555

# 如果开了防火墙
sudo ufw allow 5555/tcp
```

### 电脑

```bash
cd client
python -m pip install -r requirements.txt
python session_client.py --board 192.168.43.50
```

启动后自动抓帧并显示图像。点一个像素，右侧会显示：

```
p_cam（相机系）  : (0.0611, -0.0917, 2.9978)
p_lidar（雷达系）: (3.0167, -0.0277, 0.1125)
★ p_map（地图系）: (3.0167, -0.0277, 0.1125)
```

移动板子，界面每 200 ms 刷新：

```
pos=(+0.9060, -0.0413, +0.0075)  yaw=-3.2°
Δ=(+0.2507, -0.0209, +0.0144)
```

只给坐标，不给距离。

## 两种计算模式

- **默认 `--compute board`**：板子只回传图像；电脑只发 `(u,v)`；
  板子用本地点云算 `p_cam/p_lidar/p_map` 并记成目标。点云不出板。
- **`--compute pc`**：板子额外回传同帧点云；电脑本地算，再 `set_target` 回传。
  适合看候选点、平面拟合细节、离线复盘。

## 会话

- 一次客户端启动 = 一个会话（uuid + `client_ip` + `board_ip`）。
- 每条请求和应答都带会话信息，板子按会话隔离状态。
- 界面按钮：**新会话**（换 id 重抓）、**重新抓帧**（同会话重拍）、**清除目标**。

## 常用命令

```bash
# 无界面跑一次，看定位结果和 Δ
python session_client.py --board 192.168.43.50 --no-gui --u 800 --v 648 --watch

# 电脑端计算
python session_client.py --board 192.168.43.50 --compute pc --no-gui --u 800 --v 648

# 调候选半径 / 关平面拟合
python session_client.py --board 192.168.43.50 --radius 15 --no-fit
```

板子端参数：

```bash
--image-topic /odin1/image/compressed   # 默认，直接转发，不用编码
--no-compressed                          # 原始图，需要 cv2 或 Pillow
--cloud-topic /odin1/cloud_raw
--odom-topic  /odin1/odometry
--index-cell 32                          # 投影索引格子大小
--radius 10                              # 默认候选半径
```

## 测试（不需要 ROS）

```bash
cd client
python test_session.py                 # 协议 / 两种计算模式 / 会话隔离
python _bench_index.py ..\..\acc.npz   # 全量投影 vs 像素索引
```

## 常见问题

| 现象 | 处理 |
|---|---|
| `capture` 一直失败/超时 | 板子驱动是否在跑；5555 是否放行；`/odin1/cloud_raw` 是否有数据 |
| 抓到的图像很旧 | `capture` 的 `stamp_delta_ms` 是否很大；改用 `--no-compressed` |
| 点不到点 | 调大 `--radius`；换平整、点云密的区域；看 `multi_layer` / `plane_used` |
| `Δ` 一直不为 0 | 先确认站到了目标点；再查 map 原点胶带、抓帧是否属于本次会话 |
| 板子端报 `target_math.py` 缺失 | `server/` 下的 5 个文件没有拷全 |
| `pynng` 装不上 | 用 `--system-site-packages` 的 venv；或装 cmake/build-essential 从源码编 |

更细的协议、坐标约定、硬性规则见 `agents.md`。