数据结构参考

本页列出 Wuji SDK 中所有通用数据类型的字段定义。

各设备特定的数据结构详见对应设备文档：Wuji Glove SDK 数据参考。

通用类型

FrameHeader

每帧数据的头部信息。

字段	类型	说明
`seq`	`int`	递增序列号
`timestamp_us`	`int`	设备时间戳（微秒）
`frame_id`	`str`	坐标系 ID（如 `"l_wrist"`），最大 32 字符

Vector3 / Vector3F64

三维向量。Vector3 使用 f32 精度，Vector3F64 使用 f64 精度（用于 IMU 数据，ROS 兼容）。

字段	类型	说明
`x`	`float`	X 分量
`y`	`float`	Y 分量
`z`	`float`	Z 分量

Quaternion

f64 精度的旋转四元数。

字段	类型	说明
`x`	`float`	X 分量
`y`	`float`	Y 分量
`z`	`float`	Z 分量
`w`	`float`	W 分量

Pose

位姿，包含位置和朝向。

字段	类型	说明
`position`	`List[float]`	位置 [x, y, z]（米）
`orientation`	Quaternion	旋转四元数

Handedness

设备手性枚举，用于按手性连接。

值	说明
`Handedness.Left`	左手（序列号第 4 位为 `J`）
`Handedness.Right`	右手（序列号第 4 位为 `K`）

坐标变换

FrameTransform

单个坐标变换。

字段	类型	说明
`timestamp_us`	`int`	时间戳（微秒）
`parent_frame_id`	`str`	父坐标系
`child_frame_id`	`str`	子坐标系
`translation`	`List[float]`	平移 [x, y, z]（米）
`rotation`	Quaternion	旋转四元数

FrameTransforms

坐标变换集合。

字段	类型	说明
`transforms`	`List[FrameTransform]`	变换列表

录制类型

完整用法和代码示例详见数据录制。

TopicRecorder

MCAP 录制会话配置器。注册通道后调用 start() 开始录制。

方法	参数	说明
`__init__()`	`compression: str = "lz4"`, `chunk_size: int = None`	创建录制器，支持 `"lz4"`、`"zstd"`、`"none"`
`record()`	`sub: Subscription`	注册订阅通道到录制器
`start()`	`output_path: str`	开始录制，返回 `RecordingHandle`

RecordingHandle

录制控制句柄，由 TopicRecorder.start() 返回。

方法	返回值	说明
`pause()`	—	暂停录制
`resume()`	—	恢复录制
`stop()`	`RecordingSummary`	停止录制，返回统计摘要
`subscribe_metrics()`	`MetricsStream`	订阅实时质量指标流
`subscribe_status()`	`StatusStream`	订阅录制状态流
`subscribe_alerts()`	`AlertStream`	订阅质量告警流

RecordingSummary

录制统计摘要，由 handle.stop() 返回。

字段	类型	说明
`total_frames`	`int`	总帧数
`file_size`	`int`	MCAP 文件大小（字节）
`duration_s`	`float`	录制时长（秒）
`quality`	`QualitySummary`	质量统计摘要

QualityMetrics

实时质量指标（5 秒滑动窗口）。

字段	类型	说明
`frame_drop_rate`	`float`	丢帧率（0.0~1.0）
`frame_jitter_us`	`float`	帧间抖动（微秒）
`sync_offset_ms`	`float`	跨通道同步偏差（毫秒）
`sync_rate`	`float`	同步成功率（0.0~1.0）
`timestamp_ns`	`int`	纳秒时间戳

QualitySummary

录制质量汇总统计。

字段	类型	说明
`total_frames`	`int`	总帧数
`dropped_frames`	`int`	丢失帧数
`frame_drop_rate`	`float`	丢帧率（0.0~1.0）
`avg_sync_offset_ms`	`float`	平均同步偏差（毫秒）
`max_sync_offset_ms`	`float`	最大同步偏差（毫秒）
`sync_rate`	`float`	同步成功率（0.0~1.0）
`spc_alert_count`	`int`	SPC 告警次数
`duration_s`	`float`	录制时长（秒）

RecordingAlert

质量告警。

字段	类型	说明
`metric`	`str`	触发告警的指标名称
`current_value`	`float`	当前测量值
`threshold`	`float`	告警阈值
`message`	`str`	可读的告警信息

RecordingStatus

录制运行状态。

字段	类型	说明
`state`	`str`	当前状态（`"recording"` 或 `"paused"`）
`frame_count`	`int`	已录制帧数
`duration_s`	`float`	已用时长（秒）

Wuji Hand 类型

以下列出 Wuji Hand 通过 wuji_sdk.WujiHand 暴露的关键 schema，详细字段定义见 Wuji Hand SDK 使用说明。

HandJointState

20 关节实时状态。手指顺序为 finger-major：{left,right}_finger{1..5}_joint{1..4}。

字段	类型	说明
`header`	FrameHeader	帧头
`position`	`list[float]`	20 关节弧度位置，始终长度 20
`velocity`	`list[float]`	角速度，未提供时长度 0
`effort`	`list[float]`	关节力矩，未提供时长度 0

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

HandJointCommand

20 关节指令帧。seq 由客户端单调递增，便于接收方检测丢帧。

字段	类型	说明
`seq`	`int`	客户端自增序号
`position`	`list[float]`	目标位置，长度 20
`velocity`	`list[float]`	目标速度，可选
`effort`	`list[float]`	目标力矩，可选

TactileGloveFrame

配对触觉手套的单帧压力数据，24×31 网格。

字段	类型	说明
`handedness`	`int`	手性（0 = 左、1 = 右，注意与 `WujiHand` SDO 端编码相反）
`sequence`	`int`	帧序号
`timestamp_ms`	`int`	设备时间戳（毫秒）
`pressure`	`list[float]`	744 个 f32 压力值，按 24×31 行主序

目录