• 具身智能
• 人工智能
• AI Agent
• 机器人
• 计算机视觉
• Agent 编排

本指南讲解如何在 jiuwensymbiosis 项目中，为 5 关节 SO-101 机械臂完成 eye-to-hand（固定相机、标定板装在夹爪上）手眼标定：先手动示教 waypoint，再自动回放采集、求解并发布正式的T_base_cam标定文件，最后接入运行配置。读完你不仅能跑通 CLI 三阶段流程，还能理解示教姿态要求、质量门禁（observability / target consistency / reload smoke）、退出码语义与故障排查的内在原理。本文适用于需要精细控制参数、批量脚本化或离线重解标定的场景。

适用场景与核心概念

本文只适用于以下固定组合：

• 机械臂：SO-101，5 个臂关节（shoulder_pan / shoulder_lift / elbow_flex / wrist_flex / wrist_roll），通过 LeRobot + Feetech STS3215 舵机驱动；
• 相机：固定在桌面、支架或机器人基座附近，不随机械臂运动；
• 标定方式：eye-to-hand（眼在手外）；
• 标定板：刚性固定在夹爪上，随机械臂一起运动；
• 求解结果：T_base_cam，即相机坐标系到机器人 base 坐标系的固定 4×4 变换，平移单位为 mm。

在 SO-101 适配器中，camera_mount被类型系统限定为唯一取值"eye_to_hand"（见 jiuwensymbiosis/adapters/so101/config.py，So101Config.camera_mount: Literal["eye_to_hand"]），from_dict加载器会拒绝其他任何值并抛出明确错误。这意味着 eye-to-hand 是该适配器唯一支持的标定拓扑，配置中的挂载方式就是整个标定子系统的唯一权威来源。

整个流程分为三个阶段：

阶段 1 和阶段 2 是首次标定的必需步骤；阶段 3 用于换算法、调阈值或复查结果。

首次标定建议先使用 GUI 向导

如果这是你第一次做标定，建议优先使用图形界面的标定向导，而不是直接操作 CLI：

python -m jiuwensymbiosis_gui --gui workbench # 打开后进入「工具 → 手眼标定」

向导把本文的全部步骤串成四步，并补上了命令行没有的三件事：

1. 没有标定板时可直接生成可打印 PDF（含校验标尺，防止打印缩放导致的静默误差），对应工作台中的板面打印模块 jiuwensymbiosis_gui/workbench/board_print.py；
2. 示教时实时显示标定板识别到了多少角点——命令行只能盲按回车，废姿态要等采集完才暴露；
3. 质量门禁失败时给出对应的改进动作（见 jiuwensymbiosis_gui/workbench/pages/calibration_view.py，它把CalibrationDecision.failed_checks逐条映射为可操作建议）。

向导与 CLI 调用的是同一套标定代码（jiuwensymbiosis-calibrate-eye-to-hand背后的统一工作流），产出的标定文件也完全相同。CLI 的价值在于：精细控制参数、批量脚本化、离线重解。

1. 安全与硬件准备

开始前必须逐项确认：

1. SO-101 已完成 LeRobot 电机标定，配置中的robot_id与 LeRobot 标定时使用的 ID 一致（LeRobot 官方标定流程要求，此处不再附外部链接，按官方文档操作即可）；
2. 用lerobot-find-port确认串口路径；
3. 固定相机支架牢固，整个采集期间相机不得移动、转动或重新对焦；
4. 标定板刚性固定在夹爪上，不能在采集过程中松动；
5. 相机视野覆盖 SO-101 的主要工作区域，USB 连接稳定；
6. 急停或断电手段触手可及；自动采集前清空机械臂周围障碍物；
7. 手动示教会释放 5 个臂关节的力矩，SO-101 的肘关节受重力影响明显，必须用另一只手托住机械臂。

⚠️ 标定配置会使用较宽的关节限位和放宽的工作空间限制，只适合受控标定。不要把这些安全参数直接复制到日常运行配置（正式运行配置见 configs/so101/so101.yaml）。

底层实现上，disable_torque_on_disconnect: false表示标定过程中断连时保持舵机力矩，避免elbow_flex等重力负载关节失力矩后下坠；断连时的清理路径_settle_holding_joints会先展宽死区来抑制舵机极限环再恢复寄存器（见 jiuwensymbiosis/adapters/so101/lowlevel.py）。

2. 安装依赖

SO-101 适配器要求Python 3.12。建议在项目环境中一次安装标定和 SO-101 依赖：

python -m pip install -e ".[gui,calib,so101]"

• guiextra 安装现有工作台的 NiceGUI 依赖（nicegui>=2,<3与pillow>=10）；
• calibextra 提供标定依赖：opencv-python>=4.8,<5.0（ChArUco 需要 OpenCV 4.7/4.8 以上主模块支持，且标定求解依赖cv2.calibrateHandEye，OpenCV 5.x 已移除该顶层名）、pyrealsense2>=2.57（RealSense 出厂内参 + 取帧）；
• so101extra 提供lerobot[feetech,kinematics]>=0.6.0,<0.7与引脚驱动。

只运行无界面 CLI 工作流时，可改装.[calib,so101]。如需运行标定子系统测试：

pytest tests/unit_tests/calibration/

标定求解在缺 OpenCV 时会给出精确安装提示（见 jiuwensymbiosis/calibration/domain/solver.py 的_require_cv2），这是calibextra 不混入重型 GPU 栈的原因。

3. 准备 ChArUco 标定板

推荐使用5×7 的 ChArUco 板。没有现成标定板时，可调用仓库自带的共享板生成器生成可打印 PNG：

python -c 'from scripts.calibrate.handeye_board import BoardSpec, generate_board_image; generate_board_image(BoardSpec("charuco", 5, 7, 20.86, 15.2), "tmp/so101_charuco.png")'

该生成器（scripts/calibrate/handeye_board.py）以 300 DPI、40px 边距输出图像，BoardSpec的square_size_mm被强制作为毫米单位，直接决定输出平移尺度。

打印和安装要求：

1. 按100% 比例打印，关闭“适应页面”或自动缩放；
2. 打印后用尺子实际测量方格边长和 marker 边长；
3. 将实测值用于后续所有命令的--square-size-mm和--marker-size-mm；
4. 把纸张平整贴在硬质平板上，避免弯曲、翘边和反光；
5. 将硬板刚性固定在夹爪上，尽量避免夹爪遮挡 marker 或角点。

以下示例统一假设实测参数为：

board=charuco squares-x=5 squares-y=7 square-size-mm=20.86 marker-size-mm=15.2

如果实际尺寸不同，必须同步修改阶段 2 的采集命令。方格尺寸错误会直接造成平移尺度错误——solvePnP的物体点坐标直接由square_size_mm构造（见BoardSpec.chessboard_object_points），尺寸偏差会成比例地进入最终T_base_cam的平移。

4. 查询 SO-101 串口和相机序列号

查询机械臂串口（按 LeRobot 提示，此步骤需要先拔掉电脑上的机械臂 USB 连接线）：

lerobot-find-port

查询 RealSense 序列号：

rs-enumerate-devices | grep "Serial Number"

也可以使用 Python：

python -c "import pyrealsense2 as rs; c=rs.context(); print([d.get_info(rs.camera_info.serial_number) for d in c.devices])"

5. 配置标定环境

以项目内的 scripts/calibrate/so101_calibrate.yaml 为模板。建议复制成本机配置，避免把设备路径和序列号提交到仓库：

cp scripts/calibrate/so101_calibrate.yaml scripts/calibrate/so101_calibrate.local.yaml

至少检查以下字段：

env: cfg: low_level: name: "so101" port: "/dev/your_port" robot_id: "so101_left" calibration_dir: null # 标定时以连接瞬间的实际关节角作为 home。 home_use_init_pose: true disable_torque_on_disconnect: false joint_limits: shoulder_pan: [-180.0, 180.0] shoulder_lift: [-180.0, 180.0] elbow_flex: [-180.0, 180.0] wrist_flex: [-180.0, 180.0] wrist_roll: [-180.0, 180.0] # 固定相机的挂载方式。SO-101 标定只允许 eye_to_hand。 camera_mount: "eye_to_hand" camera_serial: "<your-camera-serial>" camera_resolution: [640, 480] camera_fps: 30 calibration: adapter_module: "jiuwensymbiosis.adapters.so101" trajectory: space: joint output: "tmp/so101_eye_to_hand.json" observability: min_relative_rotation_deg: 5.0 min_axis_separation_deg: 15.0 min_max_rotation_deg: 20.0 min_translation_baseline_mm: 30.0 duplicate_rotation_deg: 2.0 duplicate_translation_mm: 5.0 # SO-101 舵机在重力负载下可能存在约 3.5° 稳态偏差。 capture_gate: reach_rotation_deg: 4.0 reach_translation_mm: 0.5 exposure_rotation_deg: 1.0 exposure_translation_mm: 0.5

关键字段解读（结合模板文件内注释与源码）：

• home_use_init_pose: true：connect 时把当前关节角作为 home 并豁免safety_validated门禁。标定每次起始位不同，正合此意；同时z_min_safe_mm / z_max_safe_mm / workspace_bounds设为 null/极大值以放宽笛卡尔安全边界，避免标定位姿被 SafetyRail 误拦；
• joint_limits±180°：标定用宽软限位。真机运行配置请用收紧后的限位（见 configs/so101/so101.yaml）；
• camera_mount: "eye_to_hand"：不要把camera_mount放到顶层calibration:中，它的唯一权威来源是env.cfg.low_level.camera_mount（模板文件注释明确声明）。标定 CLI 从设备（device.camera_mount）读取挂载方式，绝不由用户重复声明；
• capture_gate：决定 station 的实际位姿是否足够接近指令值以允许采图。SO-101 的 STS3215 舵机没有积分项，在重力负载下（elbow_flex接近 0° 时）稳态偏差可达约 3.5°，因此默认 0.5° 的 reach 门禁会误跳过有效 station；标定使用真实关节角的 FK，只要实际位姿落在门内就是有效观测。reach_rotation_deg: 4.0即盖住约 3.5° 稳态偏差并留 0.5° 余量；
• observability：观测性阈值，全部角度单位为度、长度单位为毫米，CLI 也提供同名参数可覆盖。

注意：模板 YAML 中move_timeout_s: 5.0、joint_tolerance_deg: 3.5、settle_overcompensate: false属于标定专用短超时与紧到位容差；max_relative_target: null保持 null，避免 LeRobot 二次逐轴裁剪。

后续命令统一使用环境变量：

export CALIB_CONFIG=scripts/calibrate/so101_calibrate.local.yaml

如果不想使用 shell 变量，可把命令中的$CALIB_CONFIG直接替换为配置文件路径。

6. 阶段 1：手动示教 waypoint

⚠️ 运行下列命令前必须先托住机械臂，防止突然松开力矩导致机械臂掉落。命令运行后机械臂会松开力矩，建议先阅读下方交互过程和示教姿态要求再开始操作。

运行：

jiuwensymbiosis-calibrate-eye-to-hand \ --config "$CALIB_CONFIG" \ --collect-poses tmp/so101_wp.npz

--collect-poses只记录关节 waypoint，不拍摄标定图像，因此此阶段的板参数不参与计算。底层实现上，collect_waypoints（jiuwensymbiosis/calibration/workflows/collect.py）调用device.manual_guidance()上下文管理器，在上下文内循环提示move to waypoint N then Enter to record (q=finish)，最终写出带自描述元数据的 waypoint 归档。

交互过程：

1. CLI 连接 SO-101；
2. 程序关闭 5 个臂关节的力矩，夹爪力矩保持开启（见disable_arm_torque，只关ARM_JOINT_ORDER五关节，jiuwensymbiosis/adapters/so101/lowlevel.py）；
3. 托住肘部，将机械臂缓慢移动到第一个姿态；
4. 确认标定板完整出现在固定相机视野中，然后按 Enter 记录；
5. 重复移动和记录，建议准备 12～20 个 waypoint（少于 2 个会直接报错拒绝）；
6. 完成后输入q并按 Enter；
7. 程序先同步当前关节目标（preset_current_joint_goal），再恢复力矩并写出tmp/so101_wp.npz。恢复力矩必须先 preset 当前位姿再上电，否则机械臂会弹回上一次的目标位置——这正是restore_torque_at_current_pose先写目标后使能的原因（jiuwensymbiosis/adapters/so101/lowlevel.py）。

示教姿态要求：

• 机械臂运动过程中标定板不要碰到物体或桌面，否则导致标定板移动或变形，直接影响标定结果；
• 至少覆盖两条不同的旋转轴，不要只绕单一轴转动；
• 最大相对旋转建议达到20° 以上；
• 标定板在相机坐标系中的平移范围建议超过 30 mm；
• 覆盖视野中央、左右、前后和不同距离，避免所有姿态集中在小区域；
• 每个姿态都要保证板完整、清晰、不过曝，并尽量减少夹爪遮挡；
• 不要重复记录几乎相同的姿态。

如果力矩恢复失败，程序会报ManualGuidanceRecoveryError。此时继续托住机械臂，停止后续自动流程，检查电机总线并人工恢复安全姿态。

7. 阶段 2：预演与自动采集

7.1 先执行 dry-run

dry-run 会检查 archive 类型、adapter、mount、关节顺序、单位、周期性和轨迹插值，但不会运动或拍照：

jiuwensymbiosis-calibrate-eye-to-hand \ --config "$CALIB_CONFIG" \ --auto tmp/so101_wp.npz \ --n-stations 20 \ --dry-run \ --out tmp/so101_eye_to_hand.json

从源码看（jiuwensymbiosis/calibration/workflows/execute.py），dry-run 也会完成轨迹稠密化（joint 空间按max_joint_step_deg插值），从而把关节顺序/单位/周期性元数据与实机核对——这些检查纯计算、绝不命令设备。只有 dry-run 成功后才进入真机自动采集。

7.2 自动采集、求解和发布

确认急停可达、工作区无障碍物后运行：

jiuwensymbiosis-calibrate-eye-to-hand \ --config "$CALIB_CONFIG" \ --board charuco \ --squares-x 5 --squares-y 7 \ --square-size-mm 20.86 --marker-size-mm 15.2 \ --auto tmp/so101_wp.npz \ --n-stations 20 \ --confirm-estop \ --cross-check \ --min-corners 16 \ --out tmp/so101_eye_to_hand.json

几个关键参数的默认值（来自 scripts/calibrate/hand_eye_calib.py 的 argparse 定义）：--board默认charuco；--min-corners默认 16、下限 6（cv2.solvePnP默认求解至少需要 6 组点对）；--max-joint-step-deg默认 5.0；--method默认PARK。注意 CLI 入口jiuwensymbiosis-calibrate-eye-to-hand在 pyproject.toml 中映射到scripts.calibrate.eye_to_hand_calib:main，它只是统一流程的薄封装，额外强制require_mount="eye_to_hand"（见 scripts/calibrate/eye_to_hand_calib.py），与hand_eye_calib.main共享同一套 Python 应用流程。

自动流程会依次执行（对应 execute.py 的execute_calibration）：

1. 校验 waypoint archive 的 adapter、mount 和关节元数据（validate_archive_ownership会核对 archive 元数据中的 adapter 包名与当前加载的适配器一致）；
2. 按默认不超过 5° 的关节步长插值轨迹（SO-101 支持move_joint_path流式下发，中间点按trajectory_hz发送、只在段末 settle）；
3. 在第一次运动前抓取一帧，验证固定相机、内参和图像数据可用（_dynamic_camera_preflight，帧被丢弃，station 仍采新鲜帧）；
4. 移动至采样位置并等待稳定（_settle：优先调用wait_until_settled，否则以 0.08s 周期轮询关节位姿，连续 3 次变化 ≤0.1° 判定稳定，硬上限 5s 防止舵机卡死挂起）；
5. 检查实际姿态与目标姿态的偏差（reach gate，注意这里只是诊断——标定记录的是真实关节角的 FK，未到位但稳定的位姿仍是几何自洽的有效观测）；
6. 拍摄图像并检测 ChArUco 板（CharucoDetector.detectBoard→matchImagePoints→solvePnP求T_cam_target与重投影 RMS，见 handeye_board.py）；
7. 检查曝光前后机械臂是否漂移（exposure gate：采图前后两次读位姿，旋转 ≤1.0°、平移 ≤0.5mm 才接受）；
8. 记录通过 gate 的 station，并写出 station 归档（*.stations.npz，自描述：含 adapter_module、mount、joint 元数据、每次尝试的 capture meta 含被拒原因）；
9. 求解T_base_cam，执行观测性和刚性一致性门禁；
10. 通过 SO-101 运行时 loader 做reload smoke；全部通过后才发布正式标定。

--n-stations是目标采样数和尝试上限，不保证最终接受同样数量的 station。板检测失败、到位偏差过大或曝光期间漂移的站点会被跳过（capture_meta会逐一记录 reason，如capture_error、detect:...、exposure_drift）。

7.3 输出文件和退出码

成功时产生：

• tmp/so101_eye_to_hand.json：正式 schema-2 标定，顶层包含T_base_cam；
• tmp/so101_eye_to_hand.stations.npz：自描述 station 归档，可用于离线重解。

如果求解完成但质量门禁或 reload smoke 未通过，会产生：

• tmp/so101_eye_to_hand.candidate.json：仅供 REVIEW，矩阵位于candidate.T_base_cam，运行时 loader 不会加载它。

如果有效 station 少于求解下限（MIN_STATIONS = 3，即 OpenCVcalibrateHandEye的硬下限；实际推荐 10～20，见 solver.py），程序可能只返回 REVIEW 状态而不生成 candidate 文件；此时应查看日志和 station 归档，重新示教或改善成像后再采集。

退出码：

只有退出码为0且输出 JSON 顶层存在T_base_cam时，才可作为运行时标定使用。退出码 3 是“有产物但不是可加载标定”的刻意设计——candidate 报告也是产物，但绝不能以 0 退出。

8. 阶段 3：离线重解（可选）

station 归档允许你不连接任何硬件地换算法、调阈值、复查结果。

8.1 不带配置：只生成 candidate

jiuwensymbiosis-calibrate-eye-to-hand \ --replay tmp/so101_eye_to_hand.stations.npz \ --method HORAUD \ --cross-check \ --out tmp/so101_eye_to_hand_horaud.json

没有--config时不会发布正式标定，只会生成tmp/so101_eye_to_hand_horaud.candidate.json，正常退出码为3。此时归档元数据是唯一的 mount 权威（replay_calibration校验metadata.mount后直接求解，见 jiuwensymbiosis/calibration/workflows/replay.py）。

8.2 带配置：允许正式发布

jiuwensymbiosis-calibrate-eye-to-hand \ --replay tmp/so101_eye_to_hand.stations.npz \ --config "$CALIB_CONFIG" \ --method HORAUD \ --cross-check \ --out tmp/so101_eye_to_hand_horaud.json

该模式无需连接机械臂和相机，但会使用配置确认 adapter 与camera_mount（作为一致性断言，归档才是发布权威），并通过 SO-101 loader 做 reload smoke。只有质量门禁和 reload smoke 均通过时，才会写出正式 JSON。

可用求解方法包括PARK、TSAI、HORAUD、ANDREFF和DANIILIDIS，对应 OpenCVcv2.CALIB_HAND_EYE_*常量（见 solver.py）。eye-to-hand 求解时 OpenCV 消费的是inv(T_base_flange)（即 base→gripper 逆变换），最终得到T_base_cam。建议：

• 以PARK为主（CLI 默认方法）；
• 用--cross-check检查不同方法之间是否存在明显分歧（报告max_rotation_deg / max_translation_mm）；
• 不要仅因为某种方法能通过门禁就忽略采样质量。

9. 应用到 SO-101 运行配置

先备份正式标定文件到稳定位置：

mkdir -p configs/so101/calibration cp tmp/so101_eye_to_hand.json configs/so101/calibration/so101_eye_to_hand.json

然后在 SO-101 运行配置的env.cfg.low_level中设置：

camera_mount: "eye_to_hand" camera_serial: "<与标定时相同的固定相机序列号>" calib_path: "configs/so101/calibration/so101_eye_to_hand.json"

calib_path字段（config.py）让运行时通过load_calibration_artifact加载 schema-2 JSON；未配置时感知工具在调用时抛错（fail-closed 语义）。

使用前检查正式 JSON：

python -c 'import json; p=json.load(open("configs/so101/calibration/so101_eye_to_hand.json")); assert p.get("schema_version")==2 and "T_base_cam" in p; print("calibration artifact OK")'

schema 词汇定义在 jiuwensymbiosis/calibration_schema.py：当前版本CURRENT_SCHEMA_VERSION = 2，eye-to-hand 的帧字段为T_base_cam（eye-in-hand 为T_flange_cam），两种 mount 以不同字段发布。

标定文件与物理安装是一一对应的。以下任一情况发生后都必须重新标定：

• 固定相机或支架被移动；
• SO-101 基座位置或朝向改变；
• 标定板在夹爪中的安装发生松动或变化后重新采集；
• 相机更换、内参发生变化或分辨率模式改变。

10. 常见故障排查

门禁失败名与EyeToHandAcceptancePolicy.decide（jiuwensymbiosis/calibration/domain/quality.py）产出的failed_checks一一对应：eye-to-hand 侧要求法兰侧与相机侧双端可观测性（各至少 2 条旋转轴、轴分离 ≥15°、最大旋转 ≥20°、平移基线 ≥30mm）+T_flange_target刚性不变量（平移 std ≤3mm、旋转 max ≤2°）。固定相机看到静止标定板会直接触发observability_camera_axes——这正是“不要把所有姿态挤在一个小区域”这条要求的量化依据。

调试时可在命令末尾增加--debug获取更详细日志。不要直接手工把 candidate 中的矩阵复制到正式 schema-2 文件，以绕过质量门禁和 reload smoke。

11. 命令速查

# 1. 示教 waypoint jiuwensymbiosis-calibrate-eye-to-hand \ --config "$CALIB_CONFIG" \ --collect-poses tmp/so101_wp.npz # 2. 无运动预检 jiuwensymbiosis-calibrate-eye-to-hand \ --config "$CALIB_CONFIG" \ --auto tmp/so101_wp.npz --n-stations 20 --dry-run \ --out tmp/so101_eye_to_hand.json # 3. 真机采集、求解、发布 jiuwensymbiosis-calibrate-eye-to-hand \ --config "$CALIB_CONFIG" \ --board charuco --squares-x 5 --squares-y 7 \ --square-size-mm 20.86 --marker-size-mm 15.2 \ --auto tmp/so101_wp.npz --n-stations 20 \ --confirm-estop --cross-check \ --out tmp/so101_eye_to_hand.json # 4. 离线重解并重新执行发布门禁 jiuwensymbiosis-calibrate-eye-to-hand \ --replay tmp/so101_eye_to_hand.stations.npz \ --config "$CALIB_CONFIG" \ --method HORAUD --cross-check \ --out tmp/so101_eye_to_hand_horaud.json

延伸阅读：标定子系统在仓库中的位置

• 统一 CLI 应用流程：scripts/calibrate/hand_eye_calib.py（argparse 与三种互斥模式--collect-poses / --auto / --replay），eye-to-hand 别名 scripts/calibrate/eye_to_hand_calib.py；
• 标定配置模板：scripts/calibrate/so101_calibrate.yaml，GUI 内置档案见 jiuwensymbiosis_gui/workbench/data/calibration_profiles.yaml；
• 工作流编排：collect_waypoints（示教）、execute_calibration（自动采集）、replay_calibration（离线重解）、solve_and_publish / publish_with_reload（发布门禁），分别位于 jiuwensymbiosis/calibration/workflows/ 下的 collect.py、execute.py、replay.py、publication.py；
• 求解与质量门禁：jiuwensymbiosis/calibration/domain/solver.py（OpenCVcalibrateHandEye+ 5 种方法 + 交叉校验）、jiuwensymbiosis/calibration/domain/quality.py（AX=XB 残差、观测性、刚性一致性、两类验收策略）；
• 标定板生成与检测：scripts/calibrate/handeye_board.py；
• schema-2 契约：jiuwensymbiosis/calibration_schema.py；
• SO-101 适配器：jiuwensymbiosis/adapters/so101/lowlevel.py（手动引导力矩恢复）、jiuwensymbiosis/adapters/so101/config.py（camera_mount校验与calib_path）；
• GUI 四步向导：jiuwensymbiosis_gui/workbench/pages/calibration_view.py 与 jiuwensymbiosis_gui/workbench/calibration_engine.py；
• 测试：pytest tests/unit_tests/calibration/覆盖求解、质量门禁、归档、发布产物与集成契约（如 tests/unit_tests/calibration/test_quality.py、tests/unit_tests/calibration/test_integration.py）。

• 具身智能
• 人工智能
• AI Agent
• 机器人
• 计算机视觉
• Agent 编排