Calibration

Calibration readiness

calibration_status(name?) is a synchronous, read-only snapshot with three call forms:

// The device has a single target: omit the name
const auto readiness = device.calibration_status();

// Multiple targets: name the one you want
const auto named = device.calibration_status("dexhand");

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

Omitting the name requires the current device to have exactly one matching target; when the configuration already determines the device and target uniquely, the query can be made before start(), because the device catalog and identity constraints have already been resolved by the time SDK creation succeeds.

The returned CalibrationReadiness has two fields: state and operator_id. state has three values:

operator_id is the wearer used for this determination; it always comes from the SDK's config.algorithms.capture.operator_id, and the caller does not pass an identifier in addition.

For the complete fields, types, and nullability, see CalibrationReadiness.

Calibration progress and results

CalibrationProgress.job reports only the pending, running, completed, failed, or cancelled state of the corresponding target job. For the complete fields, see Calibration models.

CalibrationSession always uses the capture from the completed CaptureSession and computes and saves results in the order of targets. After saving succeeds, the SDK makes the results take effect for the selected targets; the application does not need to call any additional interface. A calibration failure does not delete the saved capture. For the session snapshot and result fields, see CalibrationSessionSnapshot and CalibrationResult.

Starting calibration manually

When the application needs to decide when calibration starts, call start_calibration() on the same GloveDevice used for capture and pass in the completed CaptureSession, which is still kept open. For the full capture-to-calibration session flow, see Starting capture manually.

Start an ordered calibration Session for the targets of a completed capture:

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();

The same manual calibration can pass multiple targets to targets, and the SDK computes and saves them in the order given. For how to configure one source to drive multiple targets and read the output, see One-to-many.

When selecting Skeleton, use the string "skeleton" in targets. If the application also needs to read Skeleton output, it should call device.skeleton() on the corresponding device after SDK creation and before start().

The snippets show the main flow; the application supplies render_*. Set a timeout and close Sessions on cancellation or failure. The linked runnable example in Starting capture manually includes interaction, timeouts, and resource cleanup.