标定 | Qnbot Docs Center

先读：概览（标定使用已完成的采集） · 读完你能：判断某个 target 是否需要标定，并读懂标定状态与结果

标定状态与就绪判断

device.calibration_status() 是同步、只读快照，三种调用形式：

from qnbot_sdk import TargetName

# 设备只有一个 target：省略名称
readiness = device.calibration_status()

# 多个 target：按名称指定
readiness = device.calibration_status(name="dexhand")

# Skeleton：用 TargetName.SKELETON
readiness = device.calibration_status(name=TargetName.SKELETON)

省略名称时要求当前设备只有一个匹配的 target；配置能唯一确定设备和 target 时，可以在 start() 前查询，因为 SDK 创建时已经完成设备和身份检查。

返回的 CalibrationReadiness 有两个字段：state 与 operator_id。state 有三个取值：

`state`	含义
`NOT_REQUIRED`	该 target 不需要标定
`READY`	所有必需标定步骤都有当前佩戴者的兼容且有效记录
`NEEDS_CALIBRATION`	至少一个必需标定步骤缺失、无效或不兼容，或当前设置要求重新计算

operator_id 是本次判断使用的佩戴者，来自 AlgorithmsConfig.capture.operator_id，调用方无需再传入另一份标识。

完整字段、类型和可空行为见 CalibrationReadiness。

返回值属于当前 Sdk 实例：如需重新读取已保存的标定数据，应重新创建 Sdk。

标定进度与结果

通过 device.calibration_progress() 读取当前 target 的计算状态：

读取路径	含义
`job.target_id`	当前标定任务对应的 target
`job.state`	当前 target 的标定状态
`job.failure`	当前 target 的失败信息

完整字段、类型和可空行为见 CalibrationProgress。

CalibrationSession 固定使用已完成 CaptureSession 中的采集，按 targets 顺序计算并保存结果。保存成功后，SDK 会自动应用标定结果，无需再调用额外接口。标定失败不会删除已保存的采集。会话快照与结果字段见 CalibrationSessionSnapshot 和 CalibrationResult。

手动发起标定

需要自行决定何时启动标定时，在采集使用的同一个 GloveDevice 上调用 start_calibration()，把仍保持打开的已完成 CaptureSession 传进去。完整的采集到标定会话流程见手动发起采集。

为已完成采集的目标启动一个有序标定 Session：

from qnbot_sdk.glove import (
    CalibrationJobState,
    CalibrationSessionState,
)

calibration = device.start_calibration(
    completed_capture_session=left_session,
    targets=("dexhand",),
)

while True:
    snapshot = calibration.snapshot()
    render_calibration_session(snapshot)
    if snapshot.state is CalibrationSessionState.COMPLETED:
        break
    failed = next((job for job in snapshot.jobs if job.state is CalibrationJobState.FAILED), None)
    if failed is not None:
        raise RuntimeError(failed.failure.message if failed.failure else "标定失败")
    if snapshot.state is CalibrationSessionState.CANCELLED:
        raise RuntimeError("标定已取消")
    glove.update().sleep()

results = calibration.result()
if results is None:
    raise RuntimeError("已完成的标定没有结果")
calibration.close()
left_session.close()

同一次手动标定可以向 targets 传入多个 target，SDK 按传入顺序完成计算和保存。一个 source 驱动多个 target 的配置和输出读取方式见一对多。

选择 Skeleton 时，targets 中使用 TargetName.SKELETON 或字符串 "skeleton"。如还要订阅 Skeleton 输出，应在 SDK 创建后、start() 前调用对应设备的 device.skeleton()。

以上片段展示主流程，render_* 由应用实现。实际应用还应设置超时，在取消或异常时关闭 Session。完整的交互、超时与资源清理见手动发起采集链接的可运行示例。