arm_dev
d32e6ae53f
一、场景物料（新增）
devices/sim/gazebo/models/workpiece/ 带三个孔的铝板。碰撞体是"带方孔的平板"，
视觉额外加两个 φ14/φ7 亮环 —— 因为真机的 HoughCircles 就是靠这两个亮环找孔，
只按碰撞体建视觉会让"孔检测"在仿真里永远失败，而那看起来像算法问题。
devices/sim/gazebo/models/gauge/ 通止规：通端/套环/握柄/止端四段，各段异色
便于肉眼判断方向。接触刚度刻意比台面软 —— 位置控制器会"刚性压进去"，
用默认刚度会被弹飞（注释里写了原因，不是随手抄的参数）。
devices/sim/gazebo/models/gauge_stand/ 规座（static）。规直接站在台面上会立刻倒，
加个方孔底座把它立住。
三个模型都是 model.sdf + model.config，原点在**底面中心**，单位米。
二、场景配置与校验（新增）
config/scene.yaml 物体不再写死在 world 里，改为 scene.yaml + 启动时动态 spawn。
理由：world 是"环境"（地面/台面/相机/系统插件），场景是"这一批活做什么"。
动 world 的风险面太大 —— 它只要丢一个系统声明，所有模型都 spawn 不进去（见旧坑 2）。
含 operating（相机到工件的距离等作业条件）与 gates_px（像素门槛）。
sim_scene.py 摆放校验：从 SDF **逐碰撞体**解析 AABB（不抄尺寸，避免漂移），
检查原点在底面 / 不穿台面 / 不出界 / 物体之间不嵌入。
重叠判定必须逐碰撞体三维判，不能拿总包围盒相交 ——
正常装配里本来就有嵌套（规立在规座方孔里），粗判会误报，
而误报的后果是人把检查整个关掉，之后真重叠也抓不到。
另有成像几何：把亮环/孔间距按相机距离换算成像素，与门槛比对。
scripts/check_sim_scene.py 验收工具（退出码可用）：摆放 + 门槛漂移 + 成像几何 +
悬停高度 vs 工作空间 + 手外相机是否**完整**看得见工件 + Gazebo 实际位姿。
三、修掉两处静默失效（都是"看起来一切正常"）
1) parse_spawned_poses 一直是**死代码**：它按 "x: N / y: N / z: N" 解析，
而 Fortress 实际输出是方括号两行（XYZ / RPY）。对不上 → 永远返回空 →
调用方按设计"降级成跳过位姿核对" → 位姿检查**从来没跑过**，
而日志只说"跳过"，看起来像正常降级。
现在两种格式都支持，并用真实抓下来的输出样本做回归测试。
教训：宽容降级会把"没检查"伪装成"检查通过"。
2) stop_sim_gz.sh 的模式表里漏了 robot_state_publisher（而注释里写着它有覆盖）：
脚本报"已停止"，它却还在发上一份 /robot_description 与 TF，
下一次启动就会"改了描述却不生效"。
顺带修掉同源的两个问题：awk 用 -v 传模式导致它匹配到自己、每次复查都多报
一个空命令行的幽灵 PID；以及"杀的时候"和"复查的时候"两份扫描实现会各自漂移。
现在共用同一个 scan_pids()，模式改用环境变量传递，并在杀完之后**再扫一遍**：
有残留就报出来并非零退出 —— 下次再有漏项，不再静默。
实测：--list 列出全套 9 个进程；停止后 rc=0 且 pgrep 干净。
四、相机：D405 分辨率对齐真机
仿真的 D405 此前渲染 640x480，而真机跑 848x480（fx 337 而非 447）。后果是
58mm 的两孔间距成像只剩 85px，低于 hole_distance_min=90 ——
孔检测在仿真里根本不可能通过，而现象看起来像"算法不行"。
已把 xacro 与 cameras.yaml 一起改成 848x480，并把启动时的比对从"只比视场"
扩成"视场 + 图幅"（sim_cameras.check_camera_consistency），
不一致时说明它对像素门槛的影响。
五、文档
devices/sim/gazebo/README.md 重写为中文手册：使用方法 / 建模要求 / 导入格式 /
配置方式（含"改哪里才真的生效"的接线表）/ 11 条实测坑（每条都有"怎么发现"）。
manifest.yaml 的进度、assets、description、坑清单与本轮状态对齐。
scripts/README.md 补两个验收工具与停止脚本；根 README 补仿真入口与手册链接。
cameras.yaml 里一处过期的函数名（check_fov_consistency）修正。
六、测试
新增 test_sim_scene.py（79 条，此前 sim_scene.py 完全没有单测 —— 这正是
位姿解析死掉却无人发现的原因）与 test_check_sim_scene.py（21 条），
含三条回归：world_boxes 的偏移碰撞体不能被对称化放大（假重叠）、
center_bore 不能被 _bore 后缀吃掉、Fortress 位姿输出格式。
全量：src/arm_sim_gazebo + arm_interfaces + arm_application 共 515 通过。
同时附上 config/site.example.yaml 的重新生成（此前 site.yaml 的注释改动没同步，
它的 parity 测试是红的）。
Co-authored-by: Cursor <cursoragent@cursor.com>
scripts — 唯一操作入口
实现细节在 docs/WORKSPACE.md 和 docs/。
每天： run_real.sh · run_camera_d405.sh · run_visual_servo_rt.sh · go_home.sh
三阶段串联： run_all.sh --arm 89 [--hole k2] [--skip-stage1]（run_pipeline.sh 是它的旧名别名）
手眼： run_handeye.sh（teach / merge / calibrate / show）
夹爪： run_gripper.sh --arm 89|91 · run_dual_gripper.sh
入孔： run_hole_detect.sh --arm … [--preview]
触觉： run_tactile.sh [--cli]
权重： weights.sh（list / labels / convert / doctor / show）
- 转换：
weights.sh convert <文件> --name <模型名>—— PT→ONNX→TensorRT，自动改名归位 + 固化标签 - 标签：
weights.sh labels <模型名>看，--set "工件,通止规"改 - 体检：
weights.sh doctor --check-engines（能查出 engine 与 TensorRT 版本不匹配这类静默失效） - 规则写在 models/README.md。
export_yolo_trt.sh现在是它的兼容转发壳。 配置：show_site_config.sh·lib/export_site_env.py
仿真：run_sim_gz.sh（Gazebo 物理仿真，唯一能做接触/力控验证的入口） 停：stop_sim_gz.sh（别敲pkill -f gz—— 会杀掉调用它的 shell，见脚本文件头） - 环境是独立 conda 环境
ros_gz_sim（install_sim_env.sh装、sim_env.sh激活），与真机环境隔离 - 相机验收：
python3 scripts/check_sim_cameras.py—— 别用ros2 topic hz或肉眼看图验收相机， 仿真相机的错误几乎全是静默的（深度单位、frame_id、内参、位姿方向），都能出图却是错的。 这条命令把深度反投影到 world，要求命中已知平面（地面/台面）才算通过。 - 场景验收：
python3 scripts/check_sim_scene.py—— 同样别靠肉眼。它管四件事： 物体的摆放（悬空/穿模/出界/互相嵌入）、场景里的像素门槛与真机生效值是否漂移、 孔检测的成像几何（亮环/孔间距换算成像素后够不够门槛）、以及粗定位用的手外相机 能不能完整看见工件。第二条尤其重要：门槛抄了两份，不一致时仿真会"通过"而真机不认。 - 注意
run_sim.sh不是 Gazebo，它走 mock 驱动（假数据 + RViz），永远不会产生接触力 环境：env.sh·build_all.sh
RDK：test_rdk_python.sh·rdk_switch_tool.sh·rdk_drag_bridge.py
搁置未用：fetch_isaac_flexiv.sh（拉 Flexiv 的 Isaac Sim / RDK 源码到thirdparty/；Isaac 路线目前搁置，Gazebo 是选定平台）
lib/parse_arm_args.sh 解析 --arm 89|91。
lib/load_site_config.sh 把 config/site.yaml 变成 SITE_*。
排查脚本卡住时的常识
几个脚本开头会等外部条件（控制器 ACTIVE、相机出图、触觉就绪）。正确的判活顺序是
先 ros2 service list / ros2 topic list 看目标在不在，再去 call / echo：
# 对：服务不存在时立刻返回
timeout 3 ros2 service list | grep -q '^/controller_manager/list_controllers$' || exit 1
timeout 3 ros2 service call /controller_manager/list_controllers ...
# 错：服务不存在时每次 call 都要耗满超时才返回，
# 30 次循环 = 白等两三分钟（实测 63s），看起来就像脚本卡死了
for _i in $(seq 1 30); do timeout 5 ros2 service call ... ; done
run_all.sh / run_stage2_locate.sh / run_stage3_search.sh 已按正确顺序改过；
run_handeye.sh 一开始就是对的。