数据结构参考

本页列出 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`）

ImuData

IMU 传感器数据，遵循 ROS sensor_msgs/Imu 约定。

字段	类型	说明
`header`	FrameHeader	帧头
`orientation`	Quaternion	朝向四元数
`orientation_covariance`	`list[float]`	朝向协方差（长度 9），首元素为 `-1` 表示朝向不可用
`angular_velocity`	Vector3F64	角速度（rad/s）
`angular_velocity_covariance`	`list[float]`	角速度协方差（长度 9）
`linear_acceleration`	Vector3F64	线加速度（m/s²）
`linear_acceleration_covariance`	`list[float]`	线加速度协方差（长度 9）

Wuji Hand 2 未做板载姿态融合，订阅 hand.imu() 时 orientation_covariance[0] 始终为 -1。

坐标变换

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`	纳秒时间戳
`channels`	`list[ChannelHealth]`	每通道健康明细，见 ChannelHealth

ChannelHealth

单通道健康明细（QualityMetrics 的 channels 元素）。

字段	类型	说明
`channel_name`	`str`	通道名
`channel_id`	`int`	通道 ID
`actual_hz`	`float`	实测帧率（Hz）
`drop_rate`	`float`	该通道丢帧率（0.0~1.0）
`last_frame_age_ms`	`int \| None`	距最近一帧的毫秒数，尚未收到帧时为 `None`
`jitter_us`	`float`	帧间抖动（微秒）
`is_online`	`bool`	通道当前是否在收数
`last_downtime_ms`	`int \| None`	最近一次断流时长（毫秒），从未断流为 `None`

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 2	Wuji Hand 2 SDK 接口参考 — 数据类型
Wuji Glove	Wuji Glove 数据流概览
Wuji Hand	本页下方（产品文档即将归档）

Wuji Hand 类型

Wuji Hand 产品文档即将归档，wuji_sdk.WujiHand 的类型定义随本页维护。

HandJointStates

20 关节实时状态（hand.joint_states().subscribe() 订阅帧）。手指顺序为 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

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

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

错误码分类

SDK 有三类互不相通的错误码，数值不能跨类解读：

类别	出现位置	解码方式
设备故障码（`u16`）	Wuji Hand 2 关节诊断的 `error_code_current`、`ErrorStatus` 的 `warning` / `deferred_stop` / `immediate_stop` / `fatal`、错误历史记录的 `error_code`、编码器标定结果的 `system_error_code`。类型定义见 Wuji Hand 2 SDK 接口参考 — 数据类型	`WujiHand2.describe_error()`
编码器标定码（`u8`）	编码器标定结果的 `enc1_error_code` / `enc2_error_code`	标定专用错误码，表示该次标定步骤的失败原因（enc1 是 0–9 的小枚举，enc2 按标定阶段分段编码），不可传 `describe_error()`。可读名称用标定结果对象的 `enc1_error_name` / `enc2_error_name` 只读属性获取
Wuji Hand 错误码位域（`u32`）	Wuji Hand 关节诊断数据的 `error_code`（见本页 Wuji Hand 类型）	Wuji Hand 自有的按位编码，每位对应一种故障，按位判读，不可传 `describe_error()`

设备故障码按 0xSCNN 布局，但不要自行拆解 hex 位。把码值当作不透明标识，用于记录日志、展示给用户或写入故障报告。Python 的 describe_error() 返回 dict，按 key 读取 info["severity"]、info["clear_policy"] 等字段。desc、cause 和 resolution 保留固件码表中的中文原文。

错误码 0 表示当前无故障，码表不包含该值。describe_error(0) 返回 None 时无需处理。如果非零错误码返回 None，应保留原始数值用于日志和故障报告。这可能表示固件包含 SDK 码表尚未收录的错误码。

Python 的 JointDiagnosticsEntry 在 repr() 中直接格式化 error_code_current。已知非零错误码显示为 0x2102(Overcurrent)，零值显示为 0x0000，未知错误码显示为 0xFFFF(Unknown)。该格式只影响对象展示，error_code_current 仍是可传入 describe_error() 的整数。

建立 Python hand.joint_diagnostics().subscribe() 或 C wuji_hand_2_subscribe_joint_diagnostics 订阅后，SDK 会在关节错误首次出现、变更或清除时记录一条可读日志。错误码保持不变时不会重复记录。Warning 级故障记录为 warn，其他非零故障记录为 error，故障清除记录为 info。