Calibration

Calibration readiness

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

from qnbot_sdk import TargetName

# The device has a single target: omit the name
readiness = device.calibration_status()

# Multiple targets: name the one you want
readiness = device.calibration_status(name="dexhand")

# Skeleton: use TargetName.SKELETON
readiness = device.calibration_status(name=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 and identity checks are already complete when the SDK is created.

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

operator_id is the wearer used for this determination; it comes from AlgorithmsConfig.capture.operator_id, and the caller does not need to pass another identifier.

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

Calibration progress and results

Read the computation status of the current target via device.calibration_progress():

For the complete fields, types, and nullability behavior, see CalibrationProgress.

A CalibrationSession always uses the capture from the completed CaptureSession and computes and saves results in the order of targets. After saving succeeds, the SDK automatically applies the calibration result, with no need to call additional interfaces. A calibration failure does not delete an already saved capture. For the complete fields, types, and nullability behavior, see CalibrationSessionSnapshot and CalibrationResult.

Starting calibration manually

When you need to decide for yourself when to start calibration, call start_calibration() on the same GloveDevice used for capture, passing in the completed CaptureSession that is still open. For the full capture-to-calibration session flow, see Starting capture manually.

Start an ordered calibration Session for targets whose capture has been completed:

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 "calibration failed")
    if snapshot.state is CalibrationSessionState.CANCELLED:
        raise RuntimeError("calibration cancelled")
    glove.update().sleep()

results = calibration.result()
if results is None:
    raise RuntimeError("completed calibration has no result")
calibration.close()
left_session.close()

A single manual calibration can pass multiple targets to targets, and the SDK completes computation and saving in the order passed. For how to configure and read the output when one source drives multiple targets, see One-to-Many.

When selecting Skeleton, use TargetName.SKELETON or the string "skeleton" in targets. If you also need to subscribe to Skeleton output, call device.skeleton() of the corresponding device after the SDK is created and before start().

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