JiuwenSymbiosis视觉感知管线深度解析：从开放词汇检测到像素到基座坐标的三维反投影

JiuwenSymbiosis视觉感知管线深度解析：从开放词汇检测到像素到基座坐标的三维反投影

【免费下载链接】jiuwensymbiosisJiuwen Symbiosis就是一个"能懂人话、看得见物理世界、长了四肢的智能助手"。用户不需要示教，不需要教它怎么抓东西，怎么走路，就像指挥一个经验丰富的工人一样，用自然语言下任务，它就能自己完成感知、理解、规划、执行。项目地址: https://gitcode.com/openJiuwen/jiuwensymbiosis

JiuwenSymbiosis（openJiuwen/jiuwensymbiosis）是一个"能懂人话、看得见物理世界、长了四肢"的开源智能机器人助手：你用自然语言下任务，它自己完成感知、理解、规划与执行。这篇文章带你完整拆解它的视觉感知管线——从一句"抓起那个黑色盒子"出发，经过开放词汇检测、掩膜质心、深度采样，最终完成像素到基座坐标的三维反投影，得到机械臂可以直接执行的抓取点。无需示教，无需手写算法，理解这条管线你就理解了它"看得见"的秘密 👀

一、管线总览：一句话任务背后的四步流水线

整个视觉感知管线位于 jiuwensymbiosis/perception/，由四个模块接力完成，任何机器人平台（Piper、SO101、CRUZR 等）都可以直接复用：

整体架构图可以参阅官方文档：docs/zh/explanation/architecture.md。

二、开放词汇检测：GroundingDINO + SAM2 的"文字找物体"

传统检测器只能识别训练过的固定类别，而 JiuwenSymbiosis 采用开放词汇检测（Open-Vocabulary Detection）：你用什么词描述物体，它就能找什么物体——"红色马克杯""那个带条码的白盒子"都可以直接作为提示词。

检测服务是一个独立的 FastAPI 侧车进程（sidecar），由 detector_sidecar.py 以子进程方式拉起：

• GroundingDINO（IDEA-Research，Apache-2.0）负责"文字 → 目标框"的零样本检测，默认使用grounding-dino-base模型；
• SAM2（Meta，Apache-2.0）再把每个框"精修"成高质量像素掩膜，对不规则物体也能给出贴合的轮廓；
• 客户端 detector_client.py 只需一次 HTTP 调用：POST /segment，传入 base64 图像 +text_prompt，拿回[mask, box, score, label]列表。服务不可达时返回空列表并记日志，而不是抛异常——"没检测到"被视为可恢复状态，交给上层决策。

POST /segment {image_base64, text_prompt} → {results: [ {mask_base64, shape, box, score, label}, ... ]}

框/文本阈值默认 0.35 / 0.25，可在 YAML 中配置；下游永远只取得分最高的检测结果，优先保证"不抓错物体"。不想装 SAM2 时，服务器支持--no-sam2轻量模式，直接用检测框中心做质心，对盒状物体完全够用。

💡防误检彩蛋：vision.py 还内置了颜色校验（region_color_matches）——当你说"白色的桌子"，检测却落在一个棕色盒子上，掩膜区域的 HSV 色相与提示词颜色矛盾，结果会被直接剔除，从源头减少抓错物体。

三、从掩膜到像素：质心与深度采样

拿到检测掩膜后，detect_and_centroid（vision.py#L301-L388）做三件事：

1. 取中值质心：对掩膜内所有像素坐标取中值而非均值，个别边缘噪点无法把质心"拉偏"；掩膜分辨率与图像不一致时自动缩放到图像坐标系，保证和相机内参严格对齐；
2. 深度窗口中值：在质心周围取 5×5 邻域内所有有效深度的中值，单像素深度孔洞不会导致失败；
3. 稳定失败契约：所有失败原因（no_detection、empty_mask、no_valid_depth、detector_unavailable等）统一取自 contracts.py 的DETECTION_REASONS，调用方和上层 LLM 诊断共用同一套词汇。

四、像素到基座坐标：三维反投影的数学

这是整条管线最核心的一步，实现在 vision.py#L579-L610 的default_pixel_to_base_xyz，分两小步：

4.1 针孔相机模型：像素 + 深度 → 相机系 XYZ

用相机内参矩阵 K（焦距 fx/fy、主点 ppx/ppy），把 (u, v, 深度) 反投回相机坐标系：

x = (u − ppx) × z / fx y = (v − ppy) × z / fy z = 深度

对应 geometry.py#L61-L74 的pixel_and_depth_to_camera_xyz。注意一个小细节：深度以米读入，输出直接换算成毫米，与基座坐标系单位一致，避免拼接变换时出现单位跳变。

4.2 手眼标定：两个 4×4 变换串起来

腕部相机（eye-in-hand）相对基座的位置由手眼标定给出。管线把两个齐次变换相乘：

T_base_cam = T_base_flange × T_flange_cam

• T_flange_cam来自标定的 JSON 文件（由 calibration.py 加载），标定流程见 docs/zh/how-to/calibrate-hand-eye.md；
• T_base_flange来自当前法兰位姿（各厂商适配器提供pose_to_tf回调）——机械臂动一下，相机位置就实时更新，反投影结果始终跟随当前姿态。

相乘后对相机系点做一次apply_transform，像素点就变成了基座系下的毫米级 XYZ 坐标。

五、修正与抓点：让"理论值"变成"能抓的值"

理论反投影永远存在残差（标定误差、相机安装偏差）。管线提供了两级补偿（vision.py#L391-L429 的apply_xy_correction）：

1. xy_transform：多点仿射/相似变换拟合，能同时吸收平移和旋转/缩放残差（推荐，由robot calibrate --correct生成）；
2. xy_correction_mm：单点平移量的旧版兼容项。

之后default_get_grasp_info_simple（vision.py#L613-L702）给出最终结果：目标位置、grasp_z（抓取高度，受安全下限约束）、place_z（放置高度 = 顶面 + 夹爪厚度偏移）等一整套几何参数。

对于顶视抓取，还有一个进阶路径：把整个掩膜投影成基座系点云（object_geometry.py），用 MAD 鲁棒剔除深度飞点，取顶面分位高度z_top，再用 PCA 短轴估计yaw 角，得到"俯视抓取点"——避免斜视相机取到的侧面中点让夹爪撞上物体顶部（vision.py#L492-L548 的select_top_surface_grasp）。点云还能继续喂给 scene3d.py 判断"左/右/上/下"等空间关系，让"放在黑色盒子左边"这样的指令也能被理解。

六、真实画面：看一次运行里的感知

下图是 GUI 运行视图：左侧任务执行、右侧相机画面同步滚动，每一步的检测结果、抓取点都会标注在画面上，方便你直观核对管线的输出。

仓库内置了一段真实运行样本，examples/sample_trace/ 下有 31 帧腕部相机画面、时间轴 JSON 和可交互 HTML 回放（说明见 examples/sample_trace/README.md），是理解"检测 → 反投影 → 抓取"全过程的最佳教材：

调试时，dump_grasp_debug会把每次检测的**原始帧 + 红色掩膜叠加图 + 完整数值快照（像素、深度、内参、变换矩阵、修正量）**写到运行目录的grasp_debug/下，离线即可复现排查任何一次抓取偏差。

七、快速上手：跑通视觉感知管线检查清单

1. 装好 RealSense 深度相机：相机由 camera.py 封装，自动对齐彩色流与深度流；
2. 完成手眼标定：在 YAML 中配置calib_path指向标定 JSON（参考 configs/piper/piper.yaml）；
3. 启动检测服务：python -m jiuwensymbiosis.serving.grounding_dino_sam2_server --port 8114（首次运行会从模型仓库下载权重，请耐心等待）；
4. 跑一个任务：用 GUI 或 CLI 下达自然语言指令，在运行视图中核对掩膜、质心与反投影坐标；
5. 仍有偏差？执行robot calibrate --correct生成xy_transform多点修正。

八、总结

JiuwenSymbiosis 的视觉感知管线用一条清晰的四级流水线，把"人话"变成了"坐标"：

开放词汇检测 → 掩膜质心 + 深度中值 → 针孔反投影 + 手眼标定 → 残差修正 + 抓点几何

每一步都做了工程化的鲁棒设计（中值统计、颜色校验、稳定失败契约、完整调试快照），并且与机器人平台完全解耦——这套管线正是它能"像老工人一样"理解物理世界、直接上手干活的核心能力。想继续深入，可以从 jiuwensymbiosis/perception/init.py 的模块说明读起，配合 docs/zh/explanation/architecture.md 的架构图，一图胜千行。

【免费下载链接】jiuwensymbiosisJiuwen Symbiosis就是一个"能懂人话、看得见物理世界、长了四肢的智能助手"。用户不需要示教，不需要教它怎么抓东西，怎么走路，就像指挥一个经验丰富的工人一样，用自然语言下任务，它就能自己完成感知、理解、规划、执行。项目地址: https://gitcode.com/openJiuwen/jiuwensymbiosis