initial commit

2026-10-22 09:07:39 +08:00
commit 265f11aa38
15 changed files with 2924 additions and 0 deletions
@@ -0,0 +1,119 @@
+# 灵枢 · 会话式像素→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`。