企业官网建设流程全解析

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

本篇围绕 Jiuwen Symbiosis 仓库中的 SO-101 eye-to-hand 手眼标定指南，完整讲解"桌面固定相机 + 标定板固定在夹爪"这一组合下的三阶段标定流程：手动示教 waypoint、自动回放采集与求解发布、离线重解。读完本文，你可以独立完成 SO-101 的固定相机标定、读懂各质量门禁（observability、capture gate、AX=XB 残差）的底层判据，并将 schema-2 标定文件正确接入 SO-101 运行时。

适用场景与三阶段总览

该流程只适用于以下组合：

• 机械臂：SO-101，5 个臂关节；
• 相机：固定在桌面、支架或机器人基座附近，不随机械臂运动；
• 标定方式：eye-to-hand；
• 标定板：固定在夹爪上，随机械臂一起运动；
• 求解结果：T_base_cam，即相机坐标系到机器人 base 坐标系的固定变换。

整个流程分为三个阶段：

阶段 1 和阶段 2 是首次标定的必需步骤；阶段 3 用于换算法、调阈值或复查结果。对应的统一 CLI 入口是 hand_eye_calib.py，它通过pyproject.toml中的 console script 暴露为jiuwensymbiosis-calibrate-eye-to-hand；eye_to_hand_calib.py 只是在其上加了一个 mount 守卫（require_mount="eye_to_hand"），如果设备的camera_mount不是 eye_to_hand，会直接拒绝执行。

图形界面入口

如果这是你第一次做标定，建议改用图形界面的标定向导，而不是本文的命令行：

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

（正确命令为python -m jiuwensymbiosis_gui --gui workbench。）

向导把全部步骤串成四步，并补上了命令行没有的三件事：没有标定板时可直接生成可打印 PDF（含校验标尺，防止打印缩放导致的静默误差）、示教时实时显示标定板识别到了多少角点（命令行只能盲按回车，废姿态要等采集完才暴露）、以及质量门禁失败时给出对应的改进动作。它与本文调用的是同一套标定代码，产出的标定文件也完全相同。本文适合需要精细控制参数、批量脚本化或离线重解的场景。

安全与硬件准备

开始前确认：

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

标定配置会使用较宽的关节限位和放宽的工作空间限制，只适合受控标定。不要把这些安全参数直接复制到日常运行配置。

从源码注释看（so101_calibrate.yaml 文件头），这些放宽是刻意的安全语义：home_use_init_pose: true用连接瞬间的实际关节角作为 home，豁免safety_validated门禁（标定每次起始位不同）；joint_limits为 ±180° 的宽软限位，避免标定位姿被 SafetyRail 误拦；workspace_bounds与z_max_safe_mm置空表示不限制笛卡尔工作空间；disable_torque_on_disconnect: false保证断连后舵机保持力矩。

安装依赖

SO-101 适配器要求 Python 3.12（pyproject.toml 中so101extra 的注释明确说明：lerobot[feetech,kinematics]限定在 0.6.x，feetech 提供 STS3215 串口总线驱动）。建议在项目环境中一次安装标定和 SO-101 依赖：

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

这里的guiextra 安装现有工作台的 NiceGUI 依赖；只运行无界面 CLI 工作流时，可改装.[calib,so101]。其中calibextra 刻意独立于重型 GPU 栈，仅包含opencv-python>=4.8,<5.0与pyrealsense2>=2.57；ChArUco 自 OpenCV 4.7/4.8 起位于cv2.aruco主模块，无需 opencv-contrib。

如需运行标定模块测试：

pytest tests/unit_tests/calibration/

准备 ChArUco 标定板

推荐使用 5×7 的 ChArUco 板。没有现成标定板时，可调用共享板生成器：

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")'

对应实现在 handeye_board.py：BoardSpec是 frozen dataclass，字段为kind（"charuco"/"chessboard"）、squares_x/y、square_size_mm（强制 mm，决定输出平移单位）、marker_size_mm（None 时取 0.75 倍方格边长）、aruco_dict（默认DICT_4X4_50）。generate_board_image以 300 DPI、40 px 边距渲染 PNG，square_size_mm直接决定了打印图的物理尺寸——这也是"按 100% 比例打印"要求的技术原因。

打印和安装要求：

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 的采集命令。方格尺寸错误会直接造成平移尺度错误——从检测端看，handeye_board.py 的_detect_charuco用cv2.aruco.CharucoDetector提取角点后，_fill_pose以solvePnP求出T_cam_target，其平移量纲完全来自square_size_mm的设定。

查询串口和相机序列号

查询机械臂串口（这一步按 LeRobot 提示需要拔掉电脑上的机械臂连接线）：

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])"

配置标定环境

以项目内的 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

关键约束与参数语义（均有源码依据）：

• camera_mount的唯一权威来源是env.cfg.low_level.camera_mount，不要放到顶层calibration:段。so101/config.py 中So101Config.from_dict会显式拒绝非eye_to_hand的取值，因为该适配器的相机是桌面固定的。
• capture_gate的 4.0° 旋转阈值针对 SO-101 的舵机特性：配置注释说明 STS3215 舵机没有积分项，重力负载下（elbow_flex接近 0°）稳态偏差可达约 3.5°，默认 0.5° 的 reach gate 会误杀合法站点。从 execute.py 的实现看，标定记录的是实际关节角的 FK，因此 reach gate 只作诊断日志，不作跳过依据；真正会跳过站点的是取帧失败、板未检出和曝光漂移（exposure gate 默认 0.5°/0.5 mm，SO-101 模板放宽到 1.0°）。
• observability各阈值对应 quality.py 中ObservabilityThresholds的同名字段，CLI 也提供同名--参数可命令行覆盖。
• 模板中另有几个未在上方片段出现的字段值得注意：move_timeout_s: 5.0、joint_tolerance_deg: 3.5是标定专用的短超时与紧到位容差；z_min_safe_mm: -1000000.0、z_max_safe_mm: null、workspace_bounds: null表示标定不设笛卡尔边界。

后续命令统一使用：

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

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

阶段 1：手动示教 waypoint

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

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

--collect-poses只记录关节 waypoint，不拍摄标定图像，因此此阶段的板参数不参与计算。

交互过程：

1. CLI 连接 SO-101；
2. 程序关闭 5 个臂关节的力矩，夹爪力矩保持开启；
3. 托住肘部，将机械臂缓慢移动到第一个姿态；
4. 确认标定板完整出现在固定相机视野中，然后按 Enter 记录；
5. 重复移动和记录，建议准备 12～20 个 waypoint；
6. 完成后输入q并按 Enter；
7. 程序先同步当前关节目标，再恢复力矩并写出tmp/so101_wp.npz。

从 collect.py 的实现看，示教通过device.manual_guidance()上下文进入，快照按trajectory.space取值：joint空间记录关节向量，归档时同时写入joint_unit、joint_order、joint_periodic、adapter_module和mount元数据——这些元数据就是阶段 2 校验"archive 属于哪个适配器、哪种挂载"的依据。

示教姿态要求：

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

这些数值与质量门禁一一对应：min_max_rotation_deg=20.0、min_translation_baseline_mm=30.0、重复姿态判据duplicate_rotation_deg=2.0/duplicate_translation_mm=5.0。

如果力矩恢复失败，程序会报ManualGuidanceRecoveryError（由jiuwensymbiosis.env.protocol.HandGuidingRecoveryError别名导出，见 ports.py）。此时继续托住机械臂，停止后续自动流程，检查电机总线并人工恢复安全姿态。CLI 层把该异常列入unsafe_cleanup_errors，资源准入上下文会以"不安全清理"语义处理退出。

阶段 2：预演与自动采集

先执行 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

只有 dry-run 成功后才进入真机自动采集。从 execute.py 看，dry-run 在"轨迹展开（interpolate）"完成后立即返回：即关节序列已经过插值与限位检查，但camera preflight、取帧与求解全部跳过。

自动采集、求解和发布

确认急停可达、工作区无障碍物后运行（不带--confirm-estop时 CLI 会直接抛错，见 hand_eye_calib.py）：

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

自动流程会依次执行：

1. 校验 waypoint archive 的 adapter、mount 和关节元数据；
2. 按默认不超过 5° 的关节步长插值轨迹（--max-joint-step-deg，笛卡尔空间另有--max-cartesian-step-mm/-deg）；
3. 在第一次运动前抓取一帧，验证固定相机、内参和图像数据可用（_dynamic_camera_preflight，该帧被丢弃，采集仍取新帧）；
4. 移动至采样位置并等待稳定（settle 轮询每 0.08 s 采样，连续 3 次变化小于 0.1° 判稳，硬超时 5 s）；
5. 检查实际姿态与目标姿态的偏差（SO-101 下仅诊断，不跳过）；
6. 拍摄图像并检测 ChArUco 板（单帧角点数低于--min-corners即弃帧，下限 6 是cv2.solvePnP的硬要求）；
7. 检查曝光前后机械臂是否漂移（exposure gate，不通过则跳过该站）；
8. 记录通过 gate 的 station，并写出 station 归档；
9. 求解T_base_cam，执行观测性和刚性一致性门禁；
10. 通过 SO-101 运行时 loader 做 reload smoke；全部通过后才发布正式标定。

--n-stations是目标采样数和尝试上限，不保证最终接受同样数量的 station。板检测失败、曝光期间漂移或取帧异常的站点会被跳过（注意：reach gate 在 SO-101 上只打诊断日志，不会弃站）。采样点在密集轨迹上等间隔选取（含首尾），实现见 _capture_indices。

输出文件和退出码

成功时产生：

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

schema 词汇定义在 calibration_schema.py：CURRENT_SCHEMA_VERSION = 2，eye-to-hand 的位姿字段名是T_base_cam。写文件时 solver.py 的save_calibration会对旋转块再做一次正交化（defense in depth），并把矩阵保留 6 位小数。

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

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

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

退出码：

这四个退出码在 hand_eye_calib.py 中以EXIT_OK/EXIT_ERROR/EXIT_PREFLIGHT/EXIT_REVIEW常量定义。只有退出码为0且输出 JSON 顶层存在T_base_cam时，才可作为运行时标定使用。

质量门禁的底层判据

正式发布不是"算出一个矩阵"那么简单。求解核心 solver.py 的_calibrate_once把每个 station 的tf_base_flange取逆后与T_cam_target一起喂给cv2.calibrateHandEye（eye-to-hand 约定），--cross-check会额外跑全部五种方法并报告最大分歧。随后 evaluate_calibration_quality 组装统一质量报告，EyeToHandAcceptancePolicy 按下述规则裁决：

• 法兰侧激励（法兰侧）：去重后的相对旋转轴须 ≥2 条（observability_flange_axes）、轴间最大夹角 ≥15°（observability_flange_sep）、最大相对旋转 ≥20°（observability_flange_rot）、最大相对平移 ≥30 mm（observability_flange_trans）；
• 相机侧激励：同样要求 ≥2 条轴、≥15° 分离、≥20° 最大旋转、≥30 mm 最大平移——"固定相机看静止板"的经典退化正是在相机侧被拦下（observability_camera_*）；
• 重复站点：observability_duplicates，任一相对位姿小于 2°/5 mm 即判重；
• 刚性一致性（target_consistency）：对每个 station 计算T_flange_target = inv(T_base_flange) @ T_base_cam @ T_cam_target，理论上板与夹爪刚性连接、相机与基座刚性连接，该变换应跨站点恒定；门禁要求平移标准差 ≤3.0 mm、旋转离散 ≤2.0°（TargetConsistencyThresholds）；
• AX=XB 残差（axxb_residuals）：对每对 station 检验理想情况下应为单位阵的一致性矩阵，其旋转/平移统计写入报告，作为采样质量的交叉佐证；
• 此外还有一道独立的reload smoke：用 SO-101 适配器的运行时 loader 真实加载临时 JSON，"通过 smoke 的标定正是运行时将要加载的标定"，该 loader 封装在 so101/_calibration.py，走与So101Driver运行时完全相同的load_calibration路径（eye-to-hand 帧字段T_base_cam）。

candidate 文件中记录的reasons就是上述failed_checks的展开，排查时应先读它。

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

不带配置：只生成 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 元数据是唯一权威。

带配置：允许正式发布

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（映射见 solver.py 的_cv2_methods，全部落到cv2.calibrateHandEye的五个常量）。建议以PARK为主（--method默认值），并用--cross-check检查不同方法之间是否存在明显分歧；不要仅因为某种方法能通过门禁就忽略采样质量。

应用到 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中设置（参考 so101.yaml 中已有的camera_mount/camera_serial/calib_path字段）：

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

使用前检查正式 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")'

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

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

常见故障排查

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

命令速查

# 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 参数与退出码在 hand_eye_calib.py，采集与门禁在 execute.py，求解与 schema-2 发布在 solver.py，质量判据与验收策略在 quality.py，CLI 行为测试可参考 test_eye_to_hand_calib_cli.py 与 tests/unit_tests/calibration。英文版本见 calibrate-so101-eye-to-hand.md。

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