orisys/ros_contorl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

P4d：文档同步 —— 修掉 P3 手眼路径迁移后遗留的过期引用，并指向新的 weights 工具

Browse Source 
P3 把 handeye 相关文件从 src/arm_application/config/ 迁到了仓库根的 handeye/，
但文档还写着老路径。这类"代码改了、文档没跟"的偏差最麻烦：新人照着文档敲
命令会直接报文件不存在，然后开始怀疑人生。

同步内容
- docs/HANDEYE.md / WORKSPACE.md / SITE_CONFIG.md / ARCHITECTURE.md：
  手眼结果与示教点位改指 handeye/results|poses/<臂号>_<模式>.yaml，
  临时目录改指 handeye/tmp/<臂号>/，并补上 --mode / --points / --auto-solve。
- docs/INTERFACES.md / TRACKING.md / docs/HOLE_DETECT.md / README.md：
  权重那一行从 export_yolo_trt.sh 改为 weights.sh，并注明前者已是兼容转发壳。
- docs/HOLE_DETECT.md：hole_weights / workpiece_weights 的实际取值改为
  models/hole_insert/detect_best_1.onnx（原文档写的是不存在的 best.pt）。
- scripts/merge_handeye_poses.py：只更新文件头注释里的示例路径。

多处改为指向 models/README.md 与 handeye/README.md，避免同一套规则在
七八个文件里各写一遍、然后各自漂移。

验证：rg 扫 docs/ README.md，已无 handeye_poses_/handeye_result_/
/tmp/handeye 之类过期路径残留。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
arm_dev
2026-09-23 13:52:28 +08:00
parent a89250d05d
commit d93dab31c9
9 changed files with 45 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+2 -2
View File
@@ -19,7 +19,7 @@
cd ~/ros2 cd ~/ros2
cp config/site.example.yaml config/site.yaml cp config/site.example.yaml config/site.yaml
# 编辑 site.yaml：robot.sn / robots[].ip / camera.serial / paths.yolo_weights # 编辑 site.yaml：robot.sn / robots[].ip / camera.serial / paths.yolo_weights
# 权重文件放到 models/yolo/（二进制不在 git 里） # 权重文件放到 models/<分组>/（二进制不在 git 里；布局与标签见 models/README.md）
conda activate ros_flexiv conda activate ros_flexiv
source scripts/env.sh source scripts/env.sh
@@ -75,7 +75,7 @@ bash ~/ros2/scripts/run_visual_servo_rt.sh --arm 89 --control
## 上传 git 时 ## 上传 git 时
- **要提交**：`src/` `scripts/` `docs/` `config/site.example.yaml` `models/yolo/README.md` `models/hole_insert/README.md` - **要提交**：`src/` `scripts/` `docs/` `config/site.example.yaml` `models/README.md` `models/**/*.labels.yaml`
- **不要提交**：`config/site.yaml`（含本机 IP/序列号）、`build/` `install/` `log/`、YOLO `.pt/.onnx/.engine`、`thirdparty/` `vendor/` - **不要提交**：`config/site.yaml`（含本机 IP/序列号）、`build/` `install/` `log/`、YOLO `.pt/.onnx/.engine`、`thirdparty/` `vendor/`
- 规则已写在 `.gitignore` - 规则已写在 `.gitignore`
docs/ARCHITECTURE.md
+3 -3
View File
@@ -27,8 +27,8 @@ D405 USB 独占：相机节点与示教/标定自己开会互斥；wrapper 会
│ ├── site.example.yaml # 模板（入库） │ ├── site.example.yaml # 模板（入库）
│ └── site.yaml # 本机配置（不入库） │ └── site.yaml # 本机配置（不入库）
├── docs/ # 说明；总表见 WORKSPACE.md ├── docs/ # 说明；总表见 WORKSPACE.md
├── models/yolo/ # 工件权重二进制不入库 ├── handeye/ # 手眼标定，见 handeye/README.md
├── models/hole_insert/ # 入孔权重二进制不入库 ├── models/ # 算法权重模块，见 models/README.md
├── scripts/ # 唯一操作入口 ├── scripts/ # 唯一操作入口
├── src/ # ROS 2 包 ├── src/ # ROS 2 包
├── build/ install/ log/ # colcon，不入库 ├── build/ install/ log/ # colcon，不入库
@@ -47,7 +47,7 @@ config/site.yaml
## 跟踪几何 ## 跟踪几何
手眼 `T_cam_to_gripper`（`handeye_result.yaml`）把相机点变到法兰。 手眼 `T_cam_to_gripper`（`handeye/results/<臂号>_<模式>.yaml`）把相机点变到法兰。
`servo.xy_track`： `servo.xy_track`：
- `hover`：基座系法兰 XY = 工件 3D 点 XY，任意 `ee_z_m` - `hover`：基座系法兰 XY = 工件 3D 点 XY，任意 `ee_z_m`
docs/HANDEYE.md
+10 -4
View File
@@ -4,8 +4,12 @@
| 臂 | 结果 | 示教关节 | 工作目录 | | 臂 | 结果 | 示教关节 | 工作目录 |
|----|------|----------|----------| |----|------|----------|----------|
| 89 左 | `src/arm_application/config/handeye_result_89.yaml` | `handeye_poses_89.yaml` | `/tmp/handeye_calib_89` | | 89 左 | `handeye/results/89_eye_in_hand.yaml` | `handeye/poses/89_eye_in_hand.yaml` | `handeye/tmp/89/` |
| 91 右 | `src/arm_application/config/handeye_result_91.yaml` | `handeye_poses_91.yaml` | `/tmp/handeye_calib_91` | | 91 右 | `handeye/results/91_eye_in_hand.yaml` | `handeye/poses/91_eye_in_hand.yaml` | `handeye/tmp/91/` |
文件名统一为 `<臂号>_<模式>.yaml`（模式 = `eye_in_hand` | `eye_to_hand`），
全部集中在仓库根 `handeye/`（`poses/` 输入、`results/` 输出、`tmp/` 临时产物）。
目录结构、板尺寸三处一致性与全部选项见 `handeye/README.md`。
`T_4x4` = **相机 → 法兰**。跟踪和静态 TF 都读当前 `--arm` 对应的文件。 `T_4x4` = **相机 → 法兰**。跟踪和静态 TF 都读当前 `--arm` 对应的文件。
@@ -14,6 +18,8 @@
## 流程 ## 流程
`teach`（RDK 软拖拽）与 `run_real.sh` **互斥**。全程带同一 `--arm`。 `teach`（RDK 软拖拽）与 `run_real.sh` **互斥**。全程带同一 `--arm`。
`--mode eye_in_hand|eye_to_hand` 选模式（读写对应 `<臂号>_<模式>.yaml`，两种模式互不覆盖）；
`teach --points N` 设定目标点数；`teach --ros --auto-solve` 采完自动 merge 并接着标定。
```bash ```bash
# 1) 停掉 run_real.sh 和视觉伺服 # 1) 停掉 run_real.sh 和视觉伺服
@@ -22,7 +28,7 @@ bash ~/ros2/scripts/run_handeye.sh --arm 89 teach
# 窗口：d=拖拽 Enter=拍照 q=结束 # 窗口：d=拖拽 Enter=拍照 q=结束
# 接着采、不清空旧点： teach --append # 接着采、不清空旧点： teach --append
# 3) 写入该臂的 handeye_poses_XX.yaml # 3) 写入该臂 handeye/poses/<臂号>_<模式>.yaml
bash ~/ros2/scripts/run_handeye.sh --arm 89 merge bash ~/ros2/scripts/run_handeye.sh --arm 89 merge
# 4) 再开实机 + 相机，棋盘不要动 # 4) 再开实机 + 相机，棋盘不要动
@@ -41,4 +47,4 @@ bash ~/ros2/scripts/run_handeye.sh --arm 89 calibrate
`servo_node` 用同一份 T 做 `hover` / `lookat`。换结果后**重启** `run_visual_servo_rt.sh --arm …`。 `servo_node` 用同一份 T 做 `hover` / `lookat`。换结果后**重启** `run_visual_servo_rt.sh --arm …`。
装配 HMI（`ros_flexiv`）选左/右臂后，读同一份 `handeye_result_89.yaml` / `_91.yaml`。 装配 HMI（`ros_flexiv`）选左/右臂后，读同一份 `handeye/results/89_eye_in_hand.yaml` / `91_eye_in_hand.yaml`。
docs/HOLE_DETECT.md
+3 -3
View File
@@ -32,8 +32,8 @@ bash ~/ros2/scripts/run_hole_detect.sh --arm 89 --preview
```yaml ```yaml
hole_detect: hole_detect:
backend: "two_stage" # two_stage | yolo | hough backend: "two_stage" # two_stage | yolo | hough
weights: "/home/USER/ros2/models/hole_insert/best.pt" weights: "/home/USER/ros2/models/hole_insert/detect_best_1.onnx"
workpiece_weights: "" # 空 = paths.yolo_weights workpiece_weights: "/home/USER/ros2/models/hole_insert/detect_best_1.onnx" # 空 = paths.yolo_weights
conf: 0.25 conf: 0.25
hough_param2: 26 hough_param2: 26
hole_distance_min: 150 hole_distance_min: 150
@@ -43,7 +43,7 @@ hole_detect:
- `yolo`：模型框直接当孔（原 `hole_insert` HoleDetector）。 - `yolo`：模型框直接当孔（原 `hole_insert` HoleDetector）。
- `hough`：整幅图圆检测，不用权重。 - `hough`：整幅图圆检测，不用权重。
权重放到 `~/ros2/models/hole_insert/best.pt`。`two_stage` 的工件模型默认就是跟踪用的 `paths.yolo_weights`。 权重放到 `~/ros2/models/hole_insert/`（当前 `detect_best_1.onnx`，二进制不进 git，布局见 `models/README.md`）。`two_stage` 的工件模型默认就是跟踪用的 `paths.yolo_weights`（`hole_detect.workpiece_weights` 可覆盖）。
## ROS ## ROS
docs/INTERFACES.md
+2 -1
View File
@@ -21,7 +21,8 @@
| `run_dual_gripper.sh` | 两侧 `robots[].gripper` | 双爪 ROS 节点 | | `run_dual_gripper.sh` | 两侧 `robots[].gripper` | 双爪 ROS 节点 |
| `run_hole_detect.sh --arm …` | `hole_detect.*` `camera` | 入孔像素 | | `run_hole_detect.sh --arm …` | `hole_detect.*` `camera` | 入孔像素 |
| `run_tactile.sh [--cli]` | `tactile.*` | Orisys 左右指 | | `run_tactile.sh [--cli]` | `tactile.*` | Orisys 左右指 |
| `export_yolo_trt.sh [onnx] [imgsz]` | 权重 | 同名 `.engine` | | `weights.sh list\|labels\|convert\|doctor\|show` | 权重模块 | 管理权重与标签，见 `models/README.md` |
| `export_yolo_trt.sh [onnx] [imgsz]` | 权重 | **旧命令**，转发壳 → `weights.sh convert --to engine` |
| `show_site_config.sh` | `site.yaml` | 打印解析结果 | | `show_site_config.sh` | `site.yaml` | 打印解析结果 |
| `rdk_switch_tool.sh --list` | SN | Studio 工具列表 | | `rdk_switch_tool.sh --list` | SN | Studio 工具列表 |
| `run_sim.sh` | — | mock stack | | `run_sim.sh` | — | mock stack |
docs/SITE_CONFIG.md
+4 -4
View File
@@ -24,8 +24,8 @@
| 臂 | SN | IP | 手眼 | 夹爪 | | 臂 | SN | IP | 手眼 | 夹爪 |
|----|----|----|------|------| |----|----|----|------|------|
| 左 89 | Rizon4-063989 | 192.168.2.101 | `handeye_result_89.yaml` | PGEA `/dev/ttyUSB0` | | 左 89 | Rizon4-063989 | 192.168.2.101 | `handeye/results/89_eye_in_hand.yaml` | PGEA `/dev/ttyUSB0` |
| 右 91 | Rizon4-063991 | 192.168.2.100 | `handeye_result_91.yaml` | RGI `/dev/ttyUSB1` | | 右 91 | Rizon4-063991 | 192.168.2.100 | `handeye/results/91_eye_in_hand.yaml` | RGI `/dev/ttyUSB1` |
```bash ```bash
bash ~/ros2/scripts/run_real.sh --arm 89 bash ~/ros2/scripts/run_real.sh --arm 89
@@ -57,8 +57,8 @@ bash ~/ros2/scripts/run_handeye.sh --arm 91 teach # 91 必须单独标定
|----|------| |----|------|
| `robot.sn` / `--arm` | 当前臂。可被 `run_real.sh --arm 91` 覆盖 | | `robot.sn` / `--arm` | 当前臂。可被 `run_real.sh --arm 91` 覆盖 |
| `robot.robots[].camera.serial` | 该臂腕部 D405。91 必须单独填写 | | `robot.robots[].camera.serial` | 该臂腕部 D405。91 必须单独填写 |
| `robot.robots[].paths.handeye_file` | 该臂手眼结果，禁止混用 | | `robot.robots[].paths.handeye_file` | 该臂手眼结果（`handeye/results/<臂号>_<模式>.yaml`），禁止混用 |
| `paths.yolo_weights` | `.onnx` 或 `.pt`；`backend: tensorrt` 时必须有同名 `.engine` | | `paths.yolo_weights` | 写 `.onnx` 或 `.pt`；`backend: tensorrt` 时须有同名 `.engine`（见 `models/README.md`） |
| `yolo.imgsz` | 必须等于模型输入边长 | | `yolo.imgsz` | 必须等于模型输入边长 |
| `yolo.backend` | `tensorrt` / `onnx` / `auto` | | `yolo.backend` | `tensorrt` / `onnx` / `auto` |
| `camera.serial` `width` `height` `fps` | D405 流。改分辨率要重启相机 | | `camera.serial` `width` `height` `fps` | D405 流。改分辨率要重启相机 |
docs/TRACKING.md
+1 -1
View File
@@ -40,6 +40,6 @@ D405 彩图+深度
| 臂丝滑 | 加大 `a_max` 会更快起步；减小 `a_max` / `vel_lpf_alpha` 更顺 | | 臂丝滑 | 加大 `a_max` 会更快起步；减小 `a_max` / `vel_lpf_alpha` 更顺 |
| 轨迹预测 | `predict_enable` `predict_sec`；乱飞则减小 `predict_sec` 或关预测 | | 轨迹预测 | `predict_enable` `predict_sec`；乱飞则减小 `predict_sec` 或关预测 |
| 画面中心对准 | `xy_track: lookat` | | 画面中心对准 | `xy_track: lookat` |
| 换模型 | `paths.yolo_weights` + `yolo.imgsz` + 导出 `.engine` | | 换模型 | `paths.yolo_weights` + `yolo.imgsz`；模型布局与转换见 `models/README.md` |
改完重启 T3。 改完重启 T3。
docs/WORKSPACE.md
+16 -14
View File
@@ -21,8 +21,8 @@
| `config/fastdds_visual_servo.xml` | 是 | 可选 FastDDS；默认不用 | | `config/fastdds_visual_servo.xml` | 是 | 可选 FastDDS；默认不用 |
| `scripts/` | 是 | 唯一操作入口 | | `scripts/` | 是 | 唯一操作入口 |
| `src/` | 是 | ROS 2 包源码 | | `src/` | 是 | ROS 2 包源码 |
| `models/yolo/` | 目录是；`.pt/.onnx/.engine` **否** | 工件 YOLO 权重，自己放 | | `handeye/` | 目录是；`tmp/` 内容 **否** | 手眼标定配置 / 采点 / 结果，见 `handeye/README.md` |
| `models/hole_insert/` | 目录是；权重二进制 **否** | 入孔 YOLO（`backend=yolo` 时） | | `models/` | 目录与 `.labels.yaml` 是；权重二进制 **否** | 算法权重模块，见 `models/README.md` |
| `build/` `install/` `log/` | **否** | `colcon` 产物，本地编译生成 | | `build/` `install/` `log/` | **否** | `colcon` 产物，本地编译生成 |
| `thirdparty/` `vendor/` | **否** | 可选离线 RDK / Isaac 克隆 | | `thirdparty/` `vendor/` | **否** | 可选离线 RDK / Isaac 克隆 |
| `.gitignore` | 是 | 上面「否」的规则 | | `.gitignore` | 是 | 上面「否」的规则 |
@@ -61,9 +61,9 @@
| 脚本 | 作用 | | 脚本 | 作用 |
|------|------| |------|------|
| `run_handeye.sh --arm … teach` | RDK 软拖拽记点。必须先停 `run_real.sh`（RDK 独占） | | `run_handeye.sh --arm … teach` | RDK 软拖拽记点。必须先停 `run_real.sh`（RDK 独占）。`--mode eye_in_hand\|eye_to_hand`、`--points N`、`--ros --auto-solve` |
| `run_handeye.sh --arm … merge` | 把 `/tmp/handeye_calib_XX/taught_poses.txt` 写入该臂 `handeye_poses_XX.yaml` | | `run_handeye.sh --arm … merge` | 把 `handeye/tmp/<臂号>/taught_poses.txt` 写入该臂 `handeye/poses/<臂号>_<模式>.yaml` |
| `run_handeye.sh --arm … calibrate` | 走 12 点拍棋盘，解 T，写入 `handeye_result_XX.yaml`。需要 T1 实机 + T2 相机 | | `run_handeye.sh --arm … calibrate` | 走一遍示教点拍棋盘，解 T，写入 `handeye/results/<臂号>_<模式>.yaml`。需要 T1 实机 + T2 相机 |
| `run_handeye.sh --arm … show` | 打印该臂板尺寸、poses 路径、点数 | | `run_handeye.sh --arm … show` | 打印该臂板尺寸、poses 路径、点数 |
| `merge_handeye_poses.py` | merge 的实现，一般不直接调 | | `merge_handeye_poses.py` | merge 的实现，一般不直接调 |
@@ -82,7 +82,8 @@
| `check_robot_network.sh` `fix_robot_lan.sh` | 查/修工控机到机器人网段 | | `check_robot_network.sh` `fix_robot_lan.sh` | 查/修工控机到机器人网段 |
| `test_rdk_python.sh` | 测 RDK Python 能否连上 | | `test_rdk_python.sh` | 测 RDK Python 能否连上 |
| `rdk_switch_tool.sh` | 切换 Studio Tools 名（`site.yaml` `robot.tool_name`） | | `rdk_switch_tool.sh` | 切换 Studio Tools 名（`site.yaml` `robot.tool_name`） |
| `export_yolo_trt.sh` | ONNX → TensorRT `.engine` | | `weights.sh` | 权重模块入口（list / labels / convert / doctor / show），见 `models/README.md` |
| `export_yolo_trt.sh` | **旧命令**，转发壳 → `weights.sh convert --to engine` |
| `run_sim.sh` `run_mock_demo.sh` | 无真机 mock | | `run_sim.sh` `run_mock_demo.sh` | 无真机 mock |
| `run_display.sh` | RViz 等显示 | | `run_display.sh` | RViz 等显示 |
| `convert_traj.sh` `convert_flexiv_traj.py` | 非夕轨迹 → ROS | | `convert_traj.sh` `convert_flexiv_traj.py` | 非夕轨迹 → ROS |
@@ -114,9 +115,9 @@
`arm_application` 节点见该包 README。手眼结果： `arm_application` 节点见该包 README。手眼结果：
- `src/arm_application/config/handeye_result_89.yaml` / `_91.yaml` — **相机→法兰** `T_4x4`，标定写入 - `handeye/results/<臂号>_<模式>.yaml` — **相机→法兰** `T_4x4`，标定写入（见 `handeye/README.md`）
- `handeye_poses_89.yaml` / `_91.yaml` — 示教关节 - `handeye/poses/<臂号>_<模式>.yaml` — 示教关节
- `perception.yaml` `servo.yaml` `handeye_calibrate.yaml` — 默认值，被 site 覆盖 - `perception.yaml` `servo.yaml` — 默认值，被 site 覆盖；标定参数在 `handeye/calibrate.yaml`
### Flexiv 官方（一般不要改） ### Flexiv 官方（一般不要改）
@@ -133,11 +134,12 @@
--- ---
## `models/yolo/` 与 `models/hole_insert/` ## `models/` — 算法权重模块
工件跟踪权重放 `models/yolo/`，`site.yaml` → `paths.yolo_weights`。 权重、标签与转换规则见 **`models/README.md`**（布局 `models/<分组>/<模型名>.{pt,onnx,engine}`
入孔 `backend: yolo` 的孔模型放 `models/hole_insert/`。 与旁挂 `<模型名>.labels.yaml`、`weights.sh` 用法）。
二进制不进 git。`backend: tensorrt` 时必须有同名 `.engine`（`export_yolo_trt.sh`）。 工件跟踪权重走 `site.yaml` → `paths.yolo_weights`；入孔孔模型走 `hole_detect.weights`。
二进制不进 git（`.labels.yaml` 进），`backend: tensorrt` 时必须有同名 `.engine`。
--- ---
@@ -164,7 +166,7 @@
```bash ```bash
cd ~/ros2 cd ~/ros2
cp config/site.example.yaml config/site.yaml # 填硬件 cp config/site.example.yaml config/site.yaml # 填硬件
# 权重放到 models/yolo/，改 site.yaml paths.yolo_weights # 权重放到 models/<分组>/（布局见 models/README.md），改 site.yaml paths.yolo_weights
conda activate ros_flexiv conda activate ros_flexiv
source scripts/env.sh source scripts/env.sh
./scripts/build_all.sh ./scripts/build_all.sh
scripts/merge_handeye_poses.py
+4 -4
View File
@@ -6,13 +6,13 @@ Input (from handeye_teach / handeye_waypoints append file):
0.123456, -0.700000, ... 0.123456, -0.700000, ...
Target can be either: Target can be either:
- config/handeye/waypoints.yaml (/**: ros__parameters) - handeye/poses/<臂号>_<模式>.yaml (/** ros__parameters)
- handeye_calibrate.yaml (handeye_calibrate: ros__parameters) - handeye/calibrate.yaml (handeye_calibrate: ros__parameters)
Usage: Usage:
python3 scripts/merge_handeye_poses.py \\ python3 scripts/merge_handeye_poses.py \\
~/ros2/config/handeye/taught_poses.txt \\ ~/ros2/handeye/tmp/89/taught_poses.txt \\
~/ros2/config/handeye/waypoints.yaml ~/ros2/handeye/poses/89_eye_in_hand.yaml
# or via wrapper: # or via wrapper:
bash ~/ros2/scripts/run_handeye.sh merge bash ~/ros2/scripts/run_handeye.sh merge