Data Structure Reference

This page lists all common data type field definitions in the Wuji SDK.

For device-specific data structures, see the corresponding device documentation: Wuji Glove SDK data reference.

Common Types

FrameHeader

Header information for each data frame.

Field	Type	Description
`seq`	`int`	Incrementing sequence number
`timestamp_us`	`int`	Device timestamp (microseconds)
`frame_id`	`str`	Coordinate frame ID (e.g., `"l_wrist"`), max 32 characters

Vector3 / Vector3F64

Three-dimensional vector. Vector3 uses f32 precision, Vector3F64 uses f64 precision (used for IMU data, ROS compatible).

Field	Type	Description
`x`	`float`	X component
`y`	`float`	Y component
`z`	`float`	Z component

Quaternion

f64 precision quaternion representing 3D rotation.

Field	Type	Description
`x`	`float`	X component
`y`	`float`	Y component
`z`	`float`	Z component
`w`	`float`	W component

Pose

Position and orientation.

Field	Type	Description
`position`	`List[float]`	Position [x, y, z] (meters)
`orientation`	Quaternion	Rotation quaternion

Handedness

Device handedness enum, used for connecting by handedness.

Value	Description
`Handedness.Left`	Left hand (fourth character of serial number is `J`)
`Handedness.Right`	Right hand (fourth character of serial number is `K`)

Coordinate Transforms

FrameTransform

Single coordinate transform.

Field	Type	Description
`timestamp_us`	`int`	Timestamp (microseconds)
`parent_frame_id`	`str`	Parent frame
`child_frame_id`	`str`	Child frame
`translation`	`List[float]`	Translation [x, y, z] (meters)
`rotation`	Quaternion	Rotation quaternion

FrameTransforms

Collection of coordinate transforms.

Field	Type	Description
`transforms`	`List[FrameTransform]`	Transform list

Recording Types

For complete usage and code examples, see Data Recording.

TopicRecorder

MCAP recording session configurator. Register channels, then call start() to begin recording.

Method	Parameters	Description
`__init__()`	`compression: str = "lz4"`, `chunk_size: int = None`	Create a recorder. Supports `"lz4"`, `"zstd"`, `"none"`
`record()`	`sub: Subscription`	Register a subscription channel
`start()`	`output_path: str`	Start recording, returns `RecordingHandle`

RecordingHandle

Recording control handle returned by TopicRecorder.start().

Method	Returns	Description
`pause()`	—	Pause recording
`resume()`	—	Resume recording
`stop()`	`RecordingSummary`	Stop recording and return summary
`subscribe_metrics()`	`MetricsStream`	Subscribe to real-time quality metrics
`subscribe_status()`	`StatusStream`	Subscribe to recording status updates
`subscribe_alerts()`	`AlertStream`	Subscribe to quality alerts

RecordingSummary

Recording statistics returned by handle.stop().

Field	Type	Description
`total_frames`	`int`	Total frames recorded
`file_size`	`int`	MCAP file size in bytes
`duration_s`	`float`	Recording duration in seconds
`quality`	`QualitySummary`	Quality statistics summary

QualityMetrics

Real-time quality metrics (5-second sliding window).

Field	Type	Description
`frame_drop_rate`	`float`	Frame drop rate (0.0–1.0)
`frame_jitter_us`	`float`	Inter-frame jitter in microseconds
`sync_offset_ms`	`float`	Cross-channel sync offset in milliseconds
`sync_rate`	`float`	Sync success rate (0.0–1.0)
`timestamp_ns`	`int`	Nanosecond timestamp

QualitySummary

Aggregate recording quality statistics.

Field	Type	Description
`total_frames`	`int`	Total frames received
`dropped_frames`	`int`	Total frames dropped
`frame_drop_rate`	`float`	Drop rate (0.0–1.0)
`avg_sync_offset_ms`	`float`	Average sync offset in milliseconds
`max_sync_offset_ms`	`float`	Maximum sync offset in milliseconds
`sync_rate`	`float`	Sync success rate (0.0–1.0)
`spc_alert_count`	`int`	Total SPC alerts triggered
`duration_s`	`float`	Recording duration in seconds

RecordingAlert

Quality alert.

Field	Type	Description
`metric`	`str`	Name of the metric that triggered the alert
`current_value`	`float`	Current measured value
`threshold`	`float`	Alert threshold
`message`	`str`	Human-readable alert message

RecordingStatus

Recording runtime status.

Field	Type	Description
`state`	`str`	Current state (`"recording"` or `"paused"`)
`frame_count`	`int`	Frames recorded so far
`duration_s`	`float`	Elapsed duration in seconds

Wuji Hand Types

The schemas below are exposed by wuji_sdk.WujiHand for Wuji Hand. For full field definitions, see Wuji Hand SDK Guide.

HandJointState

Real-time 20-joint state. Joint order is finger-major: {left,right}_finger{1..5}_joint{1..4}.

Field	Type	Description
`header`	FrameHeader	Frame header
`position`	`list[float]`	20 joint positions in radians, always length 20
`velocity`	`list[float]`	Angular velocity, length 0 when not provided
`effort`	`list[float]`	Joint effort, length 0 when not provided

{
  "header": { "seq": 42, "timestamp_us": 1709876543210, "frame_id": "" },
  "position": [0.001, -0.012, 0.087, 0.045, ...],
  "velocity": [],
  "effort": []
}

HandJointCommand

20-joint command frame. seq is client-incrementing so receivers can detect dropped frames.

Field	Type	Description
`seq`	`int`	Client-incremented sequence number
`position`	`list[float]`	Target positions, length 20
`velocity`	`list[float]`	Target velocity, optional
`effort`	`list[float]`	Target effort, optional

TactileGloveFrame

A single pressure frame from the paired tactile glove, on a 24×32 grid.

Field	Type	Description
`handedness`	`int`	Handedness (0 = Left, 1 = Right — note this is the opposite of the `WujiHand` SDO encoding)
`sequence`	`int`	Frame sequence number
`timestamp_ms`	`int`	Device timestamp in milliseconds
`pressure`	`list[float]`	768 f32 pressure values, row-major 24×32

On this page