API reference
Object and method summary, plus the data and result models.
API reference
The Python SDK does not provide a context manager for Sdk. Use try/finally for explicit cleanup:
sdk = Sdk(devices=(...))
try:
...
finally:
sdk.close()When using only the glove functionality, you can call glove.close() in finally. After closing, existing objects cannot continue to read data or use an existing
GloveDevice and subscription, otherwise ClosedHandleError is raised.
close() reclaims subscriptions that are still valid. Call subscription.unsubscribe() only when the SDK must keep running but needs to stop a certain
callback early; before the final close you do not need to unsubscribe one by one.
Recommended cleanup order:
- When running in the background, call
request_stop()to stop producing new data. - When running in the background, call
join()to wait for the thread to finish. - If vibration was set, call
clear()as required by your application. - Call
glove.close()orsdk.close()to reclaim the remaining subscriptions in a unified way.
The public command-line example ends the process directly with Ctrl+C; when a production program needs to stop actively, use background mode to perform the above order.
Sdk.close() can be called repeatedly. Glove.close() stops and closes all configured gloves and should be called once in the normal cleanup path. The destructor only serves as a fallback in exceptional cases and must not replace explicit closing.
Object and method summary
For methods without parameters, the "Parameters, types and defaults" column says "None".
Top-level functions
| API | Purpose | Parameters, types and defaults | Return value | When to call | Main errors |
|---|---|---|---|---|---|
discover_gloves() | Views the currently discoverable gloves | None | tuple[DiscoveredGlove, ...] | Before creating the SDK | Top-level discovery errors; per-port errors are in the result |
Sdk
| API | Purpose | Parameters, types and defaults | Return value | When to call | Main errors |
|---|---|---|---|---|---|
Sdk.glove() | Enters the glove functionality | None | Glove | SDK not closed | ClosedHandleError, capability unavailable |
Sdk.start() | Starts the configured functionality and device data streams | None | None | After preparing data reading and subscription | Connection, identity, data stream or lifecycle errors |
Sdk.update() | Performs one round of SDK task scheduling in the current loop | None | UpdateResult | Started and no other run mode in use | LifecycleError |
Sdk.run_forever() | Continuously advances SDK scheduling tasks in the current thread | None | None | Started and no other run mode in use | LifecycleError |
Sdk.run_background() | Advances SDK scheduling tasks in the background | None | None | Started and no other run mode in use | LifecycleError, background running errors |
Sdk.request_stop() | Requests the running scheduling task to stop | None | None | During foreground or background running | LifecycleError |
Sdk.join() | Waits for the background scheduling thread to finish | None | None | After a background stop has been requested | LifecycleError, background errors |
Sdk.stop() | Stops running and disconnects the devices | None | None | SDK has been started | Errors during stopping |
Sdk.close() | Finally closes the SDK and releases resources | None | None | When the SDK is no longer used | Errors during closing; the object becomes invalid after closing |
Sdk.health() | Views the health status of the entire SDK | None | Health | SDK not closed | ClosedHandleError |
Glove
| API | Purpose | Parameters, types and defaults | Return value | When to call | Main errors |
|---|---|---|---|---|---|
Glove.device(name=None, *, side=None) | Selects one device from the configured gloves | name: str | None = None or side: Side | None = None, the two are mutually exclusive | GloveDevice | After the SDK is created | NotFoundSelectionError, AmbiguousSelectionError |
Glove.sync_time(reference_time_ms) | Sets one external absolute time reference for every Glove source | reference_time_ms: float, a finite Unix-millisecond value | None | Prefer before start(); may be called again while running to resynchronize | InvalidArgumentError, ClosedHandleError, or native synchronization errors |
Glove.start() | Starts all configured gloves and functionality | None | None | After preparing data reading and subscription | Connection, identity, data stream or lifecycle errors |
Glove.update() | Performs one round of SDK task scheduling in the current loop | None | UpdateResult | Started and no other run mode in use | LifecycleError |
Glove.run_forever() | Continuously advances SDK scheduling tasks such as Retargeting and recovery in the current thread | None | None | Started and no other run mode in use | LifecycleError |
Glove.run_background() | Advances SDK scheduling tasks such as Retargeting and recovery in the background | None | None | Started and no other run mode in use | LifecycleError, background running errors |
Glove.request_stop() | Requests the running scheduling task to stop | None | None | During foreground or background running | LifecycleError |
Glove.join() | Waits for the background scheduling thread to finish | None | None | After a background stop has been requested | LifecycleError, background errors |
Glove.stop() | Stops all gloves and disconnects the devices | None | None | Glove has been started | Errors during stopping |
Glove.close() | Finally closes the glove functionality and releases resources | None | None | When the Glove is no longer used | Errors during closing; the object becomes invalid after closing |
Glove.health() | Views the health status of all configured gloves | None | Health | Glove not closed | ClosedHandleError |
GloveDevice
| API | Purpose | Parameters, types and defaults | Return value | When to call | Main errors |
|---|---|---|---|---|---|
GloveDevice.name / GloveDevice.source_id | Reads the configuration name and runtime source identifier | None, property | str | None / str | SDK not closed | ClosedHandleError |
GloveDevice.get_device_info() | Reads the verified device information snapshot | None | DeviceInfo | After the SDK is created, can be before start | UnavailableFeatureError (identity not verified) |
GloveDevice.start() / GloveDevice.stop() | Starts or stops only the selected glove | None | None | When a single device needs to be controlled separately | Connection, identity, data stream or lifecycle errors |
GloveDevice.health() | Reads health for the selected glove | None | Health | While the device is open | ClosedHandleError |
GloveDevice.close() | Releases the selected device scope | None | None | When this device is no longer needed; it cannot be restarted afterward | ClosedHandleError |
GloveDevice.pose() | Reads the raw glove pose | None | ReadChannel[GlovePose] | After the SDK is created; recommended to call before start | Lifecycle or close errors |
GloveDevice.imu() | Reads the raw IMU data of a glove | None | ReadChannel[GloveImu] | After the SDK is created; recommended to call before start | Lifecycle, close or not-supported errors; experimental feature |
GloveDevice.status() | Reads the device connection and recovery status | None | ReadChannel[GloveStatus] | After the SDK is created; recommended to call before start | Lifecycle or close errors |
GloveDevice.skeleton() | Enables and accesses Skeleton data | None | Skeleton | Must be called before start | LifecycleError, capability unavailable |
GloveDevice.skeleton().joint_angles() | Reads Skeleton joint angles | None | ReadChannel[HandJointCommand] | After skeleton is enabled | The owning object is closed or the capability is unavailable |
GloveDevice.skeleton().pose() | Reads OpenXR skeleton node poses | None | ReadChannel[HandSkeletonPose] | After skeleton is enabled | The owning object is closed or the capability is unavailable |
GloveDevice.output(name=None) | Reads the dexterous hand output of the specified target | name: str | None = None; when omitted, the target must be unique | ReadChannel[HandJointCommand] | After the SDK is created | Target not found or ambiguous |
GloveDevice.haptics() | Obtains the fingertip vibration control entry point | None | StateChannel[Haptics] | After a serial device is selected | Not supported or rejected when external, wireless or disconnected |
GloveDevice.push_frame(frame) | Submits one frame of hand data to the external input source | frame: ExternalGloveFrame, required | GlovePose | The external device has been started | Parameter, timestamp or lifecycle errors |
GloveDevice.calibration_status(name=None) | Views the calibration status of the specified target | name: str | TargetName | None = None; when omitted, the target must be unique | CalibrationReadiness | After the SDK is created | Target not found or ambiguous |
GloveDevice.capture_status(...) | Checks whether manual capture can start | package_ids, operator_id are required | CaptureReadiness | Before creating a Capture Session | InvalidArgumentError, WorkflowError |
GloveDevice.start_capture(...) | Starts manual capture | The above parameters; force: bool = False | CaptureSession | When ready to start capture | InvalidArgumentError, WorkflowError |
GloveDevice.start_calibration(...) | Starts calibration using a completed capture | completed_capture_session: CaptureSession; targets is a non-empty target sequence, all required | CalibrationSession | Capture completed and the Session remains open | Session or target validation errors |
GloveDevice.capture_progress() | Reads the current Capture progress | None | ReadChannel[CaptureProgress] | External interaction flow | Lifecycle or close errors |
GloveDevice.capture_control() | Submits a Capture confirm, skip, retry or cancel | None | CaptureControl | External interaction flow | Lifecycle or control request errors |
GloveDevice.calibration_progress(name=None) | Reads the Calibration progress of the specified target | name: str | TargetName | None = None; when omitted, the target must be unique | ReadChannel[CalibrationProgress] | During calibration observation | Target not found or ambiguous |
Sdk, Glove and GloveDevice still provide connect() and disconnect(). connect() is kept only for compatibility with old code and does not open the device; disconnect() is equivalent to stop(). New code should use start() and stop() directly.
Data reading and subscription
StateChannel[T] inherits the reading capability of ReadChannel[T], likewise supports latest(), subscribe(), next() and async iteration, and additionally provides set() and clear().
| API | Purpose | Parameters, types and defaults | Return value | When to call | Main errors |
|---|---|---|---|---|---|
ReadChannel.latest() | Reads the most recent piece of data without waiting | None | Sample[T] | None | The owning object is not closed | Close errors |
ReadChannel.subscribe(callback) | Executes the callback each time new data is received | callback: Callable[[Sample[T]], None], required | Subscription | Recommended to register before start | Parameter or close errors |
ReadChannel.next() / async iteration | Asynchronously waits for the next item or continuously reads data | None | awaitable Sample[T] / AsyncIterator[Sample[T]] | While the owning object is running | Cancellation, close or data stream errors |
StateChannel.set(value) | Updates the current vibration setting | value: Haptics, required | None | The device is connected and the capability is supported | Parameter, rejection or disconnection errors |
StateChannel.clear() | Clears the current vibration setting | None | None | The device is connected and the capability is supported | Rejection or disconnection errors |
Subscription.unsubscribe() | Stops one callback early | None | None | When the SDK keeps running but the callback is no longer needed | Synchronous unsubscription inside the callback is not safe |
Capture/Calibration Session
| API | Purpose | Parameters, types and defaults | Return value | When to call | Main errors |
|---|---|---|---|---|---|
CaptureControl.confirm() / CaptureControl.skip() / CaptureControl.cancel() | Confirms, skips or cancels the current Capture request | request_id: str, required | None | After the external interaction receives the current request | Empty, expired or not-applicable-to-the-current-state requests |
CaptureControl.retry() | Re-executes one Capture stage | stage_id: str, required | None | When the external interaction needs to retry a stage | Empty, unknown or currently non-retryable stages |
CaptureSession | Controls manual capture and reads the status or result | confirm(request_id), skip(request_id), retry(stage_id), cancel(), snapshot(), result(), close() | Status, result or None | While the Session is open | Expired requests, invalid stages, close errors |
CalibrationSession | Controls manual calibration and reads or waits for results | snapshot(), result(), wait(), cancel(), close() | Status, optional result or result tuple | While the Session is open | Workflow, cancellation or close errors |
Parameters of GloveDevice.capture_status(...):
| Parameter | Type | Required/Default | Description and constraints |
|---|---|---|---|
package_ids | Sequence[str] | Required | A non-empty sequence of algorithm package IDs; when querying multiple packages at the same time, pass them according to what is actually needed this time |
operator_id | str | Required | A non-empty wearer identifier, used to find captures reusable by that wearer |
Parameters of GloveDevice.start_capture(...):
| Parameter | Type | Required/Default | Description and constraints |
|---|---|---|---|
package_ids | Sequence[str] | Required | A non-empty sequence of algorithm package IDs, which determines the capture plan that needs to be completed this time |
operator_id | str | Required | A non-empty wearer identifier; subsequent calibration results are associated with that wearer |
force | bool | Defaults to False | False reuses available captures; True ignores reusable captures and re-completes the current plan |
Parameters of GloveDevice.start_calibration(...):
| Parameter | Type | Required/Default | Description and constraints |
|---|---|---|---|
completed_capture_session | CaptureSession | Required | Must have been created by the same Sdk, already completed, and still open |
targets | Sequence[str | TargetName | None] | Required | Non-empty and must not contain duplicates; a name selects a configured target, None selects the unique unnamed target, and Skeleton uses TargetName.SKELETON |
Data and result models
The following tables describe the public data received or returned by the public API. "Nullable" in the tables indicates whether the field can be None; empty sequences or empty mappings are pointed out separately in the description.
TelemetryMeta
TelemetryMeta is the source and frame information attached to raw glove data, appearing as fields such as GlovePose.meta and GloveImu.meta. It covers both physical glove data and external input submitted through ExternalConnection, making it easy to associate the source, device time and frame identifier.
| Field | Type | Nullable | Description |
|---|---|---|---|
source | str | No | The source ID that produced this data |
timestamp | float | No | Data timestamp |
sequence | int | None | Yes | The sequence number provided by the device or data source |
frame_id | str | None | Yes | The frame identifier provided by the device or data source |
Sample[T]
latest() and next() obtain a Sample[T]; subscribe() returns a Subscription, and the registered callback receives a Sample[T]. T is a concrete data type such as GlovePose, GloveImu, HandJointCommand or GloveStatus; value holds that data, and the remaining fields describe the SDK publish sequence and time.
| Field | Type | Nullable | Description |
|---|---|---|---|
value | T | No | Current business data |
sequence | int | No | Monotonically increasing SDK sequence number within the same kind of data |
source_time | float | None | Yes | Data source time; None when the data source does not provide it |
observed_at | float | No | The time when the SDK received the data |
Neither source_time nor observed_at is a system calendar time.
DiscoveredGlove
DiscoveredGlove is a single discovery result returned by discover_gloves(), used to view a candidate device's port, left/right hand, SN and the discovery error of that port.
| Field | Type | Nullable | Description |
|---|---|---|---|
port | str | No | The discovered serial port path |
hand | Side | None | Yes | The successfully identified left/right hand; may be absent when identification fails |
sn | str | None | Yes | The successfully read device SN |
error | GloveDiscoveryIssue | None | Yes | The discovery error of this port; None on success |
GloveDiscoveryIssue
GloveDiscoveryIssue appears as DiscoveredGlove.error and explains why a candidate port did not complete identity reading. Programs should classify and handle by the stable code; message is only used for display or logging.
| Field | Type | Nullable | Description |
|---|---|---|---|
code | GloveDiscoveryErrorCode | No | A stable error classification; use it to determine the failure reason |
message | str | No | An error description for log or UI display, not used for program branching |
DeviceInfo
DeviceInfo is returned by get_device_info() and is a verified device identity snapshot saved during SDK creation. It is used to display or record the device's canonical SN, model, firmware version and left/right hand information.
| Field | Type | Nullable | Description |
|---|---|---|---|
canonical_sn | str | No | The canonical SN that passed device identity verification |
device_type | str | No | Device type |
model | str | No | Device model |
firmware_version | str | No | Firmware version |
hand | Side | No | The left/right hand of the device |
hand_source | str | No | The source of the left/right hand information |
GloveNodePose
GloveNodePose represents the position and rotation of one hand node. It is used both to construct the fingertip input of ExternalGloveFrame and as the field type of the root node and fingertip poses in GloveFeaturePayload.
| Field | Type | Nullable | Description |
|---|---|---|---|
position | tuple[float, float, float] | No | Three-dimensional position, in meters |
quaternion_xyzw | tuple[float, float, float, float] | No | Rotation quaternion in XYZW order |
ExternalGloveFrame
ExternalGloveFrame is the external hand frame passed to push_frame(), used to submit the poses of five fingertips and an optional timestamp when there is no physical glove input.
| Field | Type | Nullable | Description |
|---|---|---|---|
thumb | GloveNodePose | No | Thumb fingertip pose |
index | GloveNodePose | No | Index fingertip pose |
middle | GloveNodePose | No | Middle fingertip pose |
ring | GloveNodePose | No | Ring fingertip pose |
pinky | GloveNodePose | No | Pinky fingertip pose |
timestamp_ms | float | None | Yes | Preferred input; a finite millisecond timestamp. When omitted, the current shared time reference is used; see Timestamps & external time sync for the time semantics |
timestamp_sec | float | None | Yes | Deprecated compatibility input; the SDK multiplies it by 1000, and it must not be set together with timestamp_ms |
GloveFeaturePayload
GloveFeaturePayload is the content of GlovePose.payload, holding the root node, five-finger poses and validity information in one frame of raw glove pose.
| Field | Type | Nullable | Description |
|---|---|---|---|
glove_id | str | No | Glove data identifier |
timestamp_ms | float | No | Device data time, in milliseconds |
root_pose | GloveNodePose | No | Hand root node pose |
fingertip_world | dict[GloveFinger, GloveNodePose] | No | The poses of the five fingertips in the world coordinate system |
fingertip_local | dict[GloveFinger, GloveNodePose] | No | The local poses of the five fingertips relative to the root node |
hand_side | str | No | The left/right hand reported in the frame |
finger_names | tuple[GloveFinger, ...] | No | The order of the fingers included in the current frame |
raw_valid_mask | dict[GloveFinger, bool] | No | Whether the raw data of each finger is valid |
held_mask | dict[GloveFinger, bool] | No | Whether each finger reuses the previous valid value |
quality_flags | tuple[str, ...] | No | The quality flags of the current frame; can be an empty sequence |
GlovePose
GlovePose is the raw glove pose published by device.pose() and also the parsed result returned after push_frame() accepts an external frame. It combines source information, pose content and extensible quality information.
| Field | Type | Nullable | Description |
|---|---|---|---|
meta | TelemetryMeta | No | source, time and frame identifier |
payload | GloveFeaturePayload | No | Root node, fingertips and quality status |
quality | dict[str, object] | No | Extensible quality information; can be an empty mapping |
GloveImuPayload
GloveImuPayload is the content of GloveImu.payload, holding the validity status, three-axis gyroscope counts and three-axis accelerometer counts of one IMU frame.
| Field | Type | Nullable | Description |
|---|---|---|---|
valid | bool | No | Whether the current raw IMU counts are valid |
gyroscope_raw | tuple[int, int, int] | No | Three-axis gyroscope raw counts |
accelerometer_raw | tuple[int, int, int] | No | Three-axis accelerometer raw counts |
GloveImu
GloveImu is the raw IMU data published by device.imu(), combining source information, six-axis raw counts and extensible quality information.
| Field | Type | Nullable | Description |
|---|---|---|---|
meta | TelemetryMeta | No | source, time and frame identifier |
payload | GloveImuPayload | No | Validity status and six-axis raw counts |
quality | dict[str, object] | No | Extensible quality information; can be an empty mapping |
HandJointCommand
HandJointCommand represents a set of joint angle outputs, containing the target, a mapping from joint names to angles, the output time, an optional source and metadata. Both device.output() and skeleton().joint_angles() provide reading of this kind of data; each read obtains a Sample[HandJointCommand], in which sample.value is the HandJointCommand. This type itself does not prescribe fixed joint names or counts.
| Field | Type | Nullable | Description |
|---|---|---|---|
target | str | No | Target identifier |
joints | dict[str, float] | No | Mapping from joint names to target positions |
timestamp | float | No | Output timestamp |
source | str | None | Yes | The source ID that produced this output |
metadata | dict[str, object] | No | Additional algorithm information; can be an empty mapping |
Skeleton fixed joints
When the data comes from skeleton().joint_angles(), HandJointCommand.joints always contains the following 25 active joints. <side> in the names is replaced with left or right; your code should read by joint name and must not rely on the key iteration order of JSON/dictionaries.
| Index | Joint name |
|---|---|
| 0 | <side>_thumb_cmc_abduction |
| 1 | <side>_thumb_cmc_flexion |
| 2 | <side>_thumb_cmc_opposition |
| 3 | <side>_thumb_mcp_abduction |
| 4 | <side>_thumb_mcp_flexion |
| 5 | <side>_thumb_ip_flexion |
| 6 | <side>_index_mcp_abduction |
| 7 | <side>_index_mcp_flexion |
| 8 | <side>_index_pip_flexion |
| 9 | <side>_index_dip_flexion |
| 10 | <side>_middle_mcp_abduction |
| 11 | <side>_middle_mcp_flexion |
| 12 | <side>_middle_pip_flexion |
| 13 | <side>_middle_dip_flexion |
| 14 | <side>_ring_cmc_cup |
| 15 | <side>_ring_mcp_abduction |
| 16 | <side>_ring_mcp_flexion |
| 17 | <side>_ring_pip_flexion |
| 18 | <side>_ring_dip_flexion |
| 19 | <side>_little_cmc_opposition |
| 20 | <side>_little_cmc_cup |
| 21 | <side>_little_mcp_abduction |
| 22 | <side>_little_mcp_flexion |
| 23 | <side>_little_pip_flexion |
| 24 | <side>_little_dip_flexion |
The dexterous hand output provided by device.output() still uses HandJointCommand, but the joint names and counts are defined by the corresponding dexterous hand algorithm package and do not use the above Skeleton fixed list.
HandSkeletonPose
HandSkeletonPose is the OpenXR skeleton node pose published by skeleton().pose(), used to read the names, positions and rotations of 25 nodes by the same index.
| Field | Type | Nullable | Description |
|---|---|---|---|
timestamp_ms | float | No | Skeleton output time, in milliseconds |
hand_side | Side | No | Left/right hand |
coordinate_frame | str | No | Currently wrist_local |
names | tuple[str, ...] | No | The names of the 25 skeleton nodes; the order matches the position and rotation arrays |
positions_local | tuple[tuple[float, float, float], ...] | No | 25 wrist-local node positions |
orientations_local_xyzw | tuple[tuple[float, float, float, float], ...] | No | XYZW quaternions of the 25 wrist-local nodes |
Haptics
Haptics is used both as the input of set() and as the vibration output state obtained by latest() and subscribe(). device.haptics() returns the fingertip vibration control and reading entry point and does not directly return Haptics.
| Field | Type | Nullable | Description |
|---|---|---|---|
strengths | dict[GloveFinger, int] | No | Mapping from fingers to an integer vibration strength in 0..100; can be an empty mapping, and fingers not listed are not included in the current vibration setting |
GloveStatus
GloveStatus is the device status published by device.status(), used to observe the current connection, whether the data is stale, the most recent error and the number of successful recoveries.
| Field | Type | Nullable | Description |
|---|---|---|---|
device_type | str | No | Device type |
connected | bool | No | Whether it is currently connected |
stale | bool | No | Whether the current data is already stale or has not started flowing yet |
timestamp | float | No | Status timestamp |
last_error | str | None | Yes | The most recent device error; None when there is no error |
reconnect_count | int | No | The cumulative number of successful connection recoveries |
fields | dict[str, object] | No | Additional status related to the device type; can be an empty mapping |
DeviceHealth
DeviceHealth is the device health summary corresponding to each source in Health.devices, used to view the connection, data freshness and most recent error of multiple gloves at the same time.
| Field | Type | Nullable | Description |
|---|---|---|---|
connected | bool | No | Whether the device is connected |
stale | bool | No | Whether the device data is stale or has not started flowing yet |
last_error | str | None | Yes | The most recent device error |
Health
Health is returned by sdk.health() or glove.health() and is used to summarize the warnings, errors, device status and scheduling status of the SDK or all gloves.
| Field | Type | Nullable | Description |
|---|---|---|---|
ok | bool | No | Whether the current summary status is healthy |
warning_count | int | No | The number of warnings in the current summary |
error_count | int | No | The number of errors in the current summary |
devices | dict[str, DeviceHealth] | No | Mapping from source ID to device health status |
last_error | str | None | Yes | The most recent SDK error |
runtime_overrun | bool | No | Whether SDK scheduling has ever overrun |
topic_callback_error | bool | No | Whether an unhandled exception has ever occurred in a callback |
CalibrationReadiness
CalibrationReadiness is returned by device.calibration_status() and is used to determine whether the specified target requires no calibration, can be used directly or needs recalibration for the current wearer.
| Field | Type | Nullable | Description |
|---|---|---|---|
state | CalibrationReadinessState | No | NOT_REQUIRED, READY or NEEDS_CALIBRATION |
operator_id | str | No | The wearer identifier used for this determination |
UpdateResult
UpdateResult is returned by sdk.update() or glove.update() and is used to view how many tasks this manual scheduling executed and whether there are still subsequent tasks, and to wait for the next task to become due.
| Field | Type | Nullable | Description |
|---|---|---|---|
tick | int | No | Current update sequence number |
ran_task_count | int | No | The number of tasks executed this time |
has_next_task | bool | No | Whether there are still subsequent scheduling tasks |
sleep() | () -> SleepResult | — | Waits for the next task to become due; each result can be called only once |
Capture models
The Capture types together describe the capture plan, the readiness state before starting, the running progress, the Session snapshot and the final result.
CapturePlanStage
CapturePlanStage is one action stage in CapturePlan.stages, used to tell the program what action to display, how many samples need to be captured and whether skipping is allowed.
| Field | Type | Nullable | Description |
|---|---|---|---|
stage_id | str | No | Action stage identifier |
prompt | str | No | The action prompt displayed to the wearer |
required_sample_count | int | No | The number of samples needed to complete the stage |
optional | bool | No | Whether skipping is allowed |
CapturePlan
CapturePlan appears as CaptureReadiness.plan and CaptureSessionSnapshot.plan and describes which algorithm packages this Capture involves and the stage execution order.
| Field | Type | Nullable | Description |
|---|---|---|---|
package_ids | tuple[str, ...] | No | The algorithm package IDs covered by this plan |
stages | tuple[CapturePlanStage, ...] | No | The capture stages executed in order |
CaptureStageReadiness
CaptureStageReadiness is the readiness state of one stage in CaptureReadiness.stages, used to determine whether the stage can reuse existing data or needs to be re-captured.
| Field | Type | Nullable | Description |
|---|---|---|---|
stage_id | str | No | Stage identifier |
required_sample_count | int | No | Required sample count |
state | CaptureStageReadinessState | No | REUSABLE or NEEDS_CAPTURE |
CaptureReadiness
CaptureReadiness is returned by device.capture_status() and is used to view the overall readiness state, the capture plan and whether each stage needs capture before creating a Capture Session.
| Field | Type | Nullable | Description |
|---|---|---|---|
state | CaptureReadinessState | No | NOT_REQUIRED, READY or NEEDS_CAPTURE |
plan | CapturePlan | No | The resolved capture plan |
stages | tuple[CaptureStageReadiness, ...] | No | Readiness state of each stage |
CaptureStageProgress
CaptureStageProgress appears as an element of CaptureProgress.stage and CaptureSessionSnapshot.stage_progress, used to drive the action prompt, sample progress and the currently allowed interaction.
| Field | Type | Nullable | Description |
|---|---|---|---|
stage_id | str | No | Current stage identifier |
prompt | str | No | Current action prompt |
optional | bool | No | Whether the current stage allows skipping |
state | CaptureStageState | No | Current stage state |
origin | CaptureStageOrigin | No | New capture or reuse of an existing capture |
collected_sample_count | int | No | Number of samples collected |
required_sample_count | int | No | Required sample count |
request_id | str | None | Yes | The current confirm or control request identifier |
CaptureFailure
CaptureFailure appears as CaptureProgress.failure and CaptureSessionSnapshot.failure, using a stable code and a readable message to describe the failure reason of the Capture Session.
| Field | Type | Nullable | Description |
|---|---|---|---|
code | str | No | Stable failure code |
message | str | No | Failure description for display or logging |
CaptureProgress
CaptureProgress is published by device.capture_progress() and is used by the external interaction interface to continuously display the current source, wearer, Session state and action stage.
| Field | Type | Nullable | Description |
|---|---|---|---|
session_id | str | No | Capture Session identifier |
session_state | CaptureSessionState | No | Session state |
failure | CaptureFailure | None | Yes | Session failure information |
source_id | str | No | The source ID used for capture |
side | Side | No | The captured left/right hand |
operator_id | str | No | Wearer identifier |
stage | CaptureStageProgress | No | Current stage progress |
CaptureSessionSnapshot
CaptureSessionSnapshot is returned by CaptureSession.snapshot() and is the current complete snapshot of a manual Capture Session, used to display progress and decide the next allowed operation.
| Field | Type | Nullable | Description |
|---|---|---|---|
side | Side | No | The captured left/right hand |
plan | CapturePlan | No | The capture plan for this session |
state | CaptureSessionState | No | Session state |
current_stage | str | None | Yes | Current stage identifier |
request_id | str | None | Yes | Current control request identifier |
collected_sample_count | int | No | Number of samples collected in the current stage |
required_sample_count | int | No | Required sample count for the current stage |
remaining_stages | tuple[str, ...] | No | Stages not yet completed |
stage_progress | tuple[CaptureStageProgress, ...] | No | Progress of all stages |
allowed_operations | tuple[CaptureControlAction, ...] | No | Currently allowed control operations |
next_action | str | No | Next action prompt |
failure | CaptureFailure | None | Yes | Session failure information |
CaptureStageSamples
CaptureStageSamples is the capture summary of one stage in CaptureResult.stage_samples, used to view how many frames were finally saved for that stage.
| Field | Type | Nullable | Description |
|---|---|---|---|
stage_id | str | No | Stage identifier |
frame_count | int | No | The number of frames saved for this stage |
CaptureResult
CaptureSession.result() returns CaptureResult | None: after the Session completes you get the capture result for this session, and while it is not yet complete you get None. CaptureResult records the wearer, left/right hand, completion time and per-stage frame count summary of this capture.
| Field | Type | Nullable | Description |
|---|---|---|---|
operator_id | str | No | Wearer identifier |
side | Side | No | The captured left/right hand |
created_at | float | No | Creation time of the capture result |
stage_samples | tuple[CaptureStageSamples, ...] | No | Frame count summary saved for each stage |
Values of the capture session enums:
| Enum | Values |
|---|---|
CaptureSessionState | RUNNING, COMPLETED, FAILED, CANCELLED |
CaptureStageState | PENDING, AWAITING_CONFIRMATION, COLLECTING, COMPLETED, SKIPPED |
CaptureStageOrigin | NEW_CAPTURE, REUSED |
CaptureControlAction | CONFIRM, RETRY, SKIP, CANCEL |
Calibration models
The Calibration types describe the computation progress per target and provide a snapshot of the entire Session and the final result.
CalibrationJobFailure
CalibrationJobFailure appears as CalibrationJobProgress.failure, using a stable code and a readable message to describe the calibration failure reason of a certain target.
| Field | Type | Nullable | Description |
|---|---|---|---|
code | str | No | Stable failure code |
message | str | No | Failure description for display or logging |
CalibrationJobProgress
CalibrationJobProgress appears as an element of CalibrationProgress.job and CalibrationSessionSnapshot.jobs, used to view the calibration state and failure information of a single target.
| Field | Type | Nullable | Description |
|---|---|---|---|
target_id | str | No | Target identifier |
state | CalibrationJobState | No | The calibration state of the current target |
failure | CalibrationJobFailure | None | Yes | Failure information of the current target |
CalibrationProgress
CalibrationProgress is published by device.calibration_progress() and is used by the external interaction interface to continuously display the computation state of one target in the current Calibration Session.
| Field | Type | Nullable | Description |
|---|---|---|---|
session_id | str | No | Calibration Session identifier |
source_id | str | No | The source ID used for calibration |
job | CalibrationJobProgress | No | Calibration progress of the current target |
CalibrationSessionSnapshot
CalibrationSessionSnapshot is returned by CalibrationSession.snapshot() and is used to view the current state of the entire Session and all of its targets at once.
| Field | Type | Nullable | Description |
|---|---|---|---|
state | CalibrationSessionState | No | Session state |
jobs | tuple[CalibrationJobProgress, ...] | No | Task states arranged in the order of targets |
CalibrationResult
CalibrationResult is a single target result in the calibration result collection, used to record the record ID, source, target and creation time of a saved calibration. CalibrationSession.result() returns tuple[CalibrationResult, ...] | None, and wait() returns tuple[CalibrationResult, ...].
| Field | Type | Nullable | Description |
|---|---|---|---|
record_id | str | No | The calibration record identifier after saving |
source_id | str | No | The source ID used for calibration |
target_id | str | No | The target ID corresponding to the calibration |
created_at | float | No | Creation time of the calibration result |
The values of both CalibrationSessionState and CalibrationJobState are RUNNING, COMPLETED, FAILED, CANCELLED, among which CalibrationJobState also includes PENDING, which is waiting to execute.