标定 | Qnbot Docs Center

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

标定状态与就绪判断

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

// 设备只有一个 target：省略名称
const auto readiness = device.calibration_status();

// 多个 target：按名称指定
const auto named = device.calibration_status("dexhand");

// Skeleton：用 qnbot::TargetName::skeleton
const auto skeleton = device.calibration_status(qnbot::TargetName::skeleton);

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

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

`state`	含义
`not_required`	该 target 不需要标定
`ready`	所有必需标定步骤都有当前佩戴者的兼容且有效记录
`needs_calibration`	至少一个必需标定步骤缺失、无效或不兼容，或被本实例的 `force` 策略排除

operator_id 是本次判断使用的佩戴者，始终来自 SDK 的 config.algorithms.capture.operator_id，调用方不额外传入标识。

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

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

标定进度与结果

CalibrationProgress.job 只报告对应目标任务的 pending、running、completed、failed 或 cancelled 状态。完整字段见 Calibration 模型。

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

手动发起标定

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

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

auto calibration = device.start_calibration(
    left_session, {std::string("target-output")});
while (true) {
    const auto snapshot = calibration.snapshot();
    render_calibration_session(snapshot);
    if (snapshot.state == qnbot::CalibrationSessionState::completed) break;
    const auto failed = std::find_if(
        snapshot.jobs.begin(), snapshot.jobs.end(),
        [](const auto& job) {
            return job.state == qnbot::CalibrationJobState::failed;
        });
    if (failed != snapshot.jobs.end() ||
        snapshot.state == qnbot::CalibrationSessionState::cancelled)
        throw std::runtime_error("calibration stopped");
    static_cast<void>(glove.update().sleep());
}
auto results = calibration.result();
if (!results)
    throw std::runtime_error("completed calibration has no result");
calibration.close();
left_session.close();

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

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

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