数据说明
压力矩阵
每帧数据使用 63 行、39 列的矩阵，包含五指和手掌区域。行、列索引均从 0 开始，行向下增加，列向右增加。
| 区域名称 | 手部区域 | 行索引（含两端） | 列索引（含两端） |
|---|---|---|---|
thumb | 拇指 | 8～22 | 0～6 |
index | 食指 | 0～22 | 8～14 |
middle | 中指 | 0～22 | 16～22 |
ring | 无名指 | 0～22 | 24～30 |
little | 小指 | 0～22 | 32～38 |
palm | 手掌 | 24～62 | 8～38 |
矩阵共 2457 个位置，其中六个区域覆盖 1958 个位置，其余为空白位置。单帧的有效点数取决于实际读数，可通过 frame.valid_points() 获取。手掌区域内的第 15、23、31 列属于正常数据位置。
左右手使用相同的矩阵坐标。可通过 glove.info().hand 区分设备：0 为右手，1 为左手，None 表示设备未提供该信息。需要镜像显示时，由应用调整可视化方向。
读取数值
| 访问方式 | 数据形式 | 无效位置 |
|---|---|---|
frame.value_map | 63 × 39 的二维列表 | None |
frame.values | 长度为 2457 的一维列表，按行排列 | None |
frame.get_point(row, col) | 指定位置的整数读数 | None |
frame.data_bytes | 长度为 2457 的 bytes，按行排列 | 255 |
有效 ADC 范围为 0～254，0 也是有效读数。计算统计结果或绘制热图时，应将无效位置与零值区分开。
二维坐标与一维索引的关系为：
index = row * 39 + col
输出模式
| 模式 | 数据含义 |
|---|---|
adc | 经过滤波的 ADC 数据 |
raw | 未经过滤波的 ADC 数据 |
tare_adc | 经过滤波并应用去皮结果的 ADC 数据 |
通过 glove.set_output_mode(mode) 设置模式。读取时可用 data_cmd 筛选相同模式的数据：
glove.set_output_mode("adc")
frame = glove.read_frame(data_cmd="adc")
data_cmd 只筛选读取结果。需要改变设备输出时，应先调用 set_output_mode()。
去皮用于在无负载状态下重新测量零偏。glove.tare() 执行去皮并切换到 tare_adc；单独选择 tare_adc 模式会使用已有的去皮结果。去皮结果不作为永久校准保存。
时间与帧序号
| 字段 | 含义 |
|---|---|
timestamp | SDK 接收并解析数据时的主机 Unix 时间，单位为秒 |
timestamp_ms | 设备时间，单位为毫秒，范围为 0～4294967295 |
sequence | 设备帧序号，范围为 0～65535 |
设备时间和帧序号达到上限后会从 0 重新计数。应用读取到的序号可能不连续，判断新帧可结合 timestamp 和 sequence。
read_frame() 获取最新帧；已有数据时会立即返回。timeout 控制没有可用帧时的等待时间，不限制已有帧的年龄。需要监测数据是否持续更新时，应检查时间戳，而不是仅依赖读取是否超时。
区域统计
frame.by_region() 返回 all（全部）、fingers（五指）和 palm（手掌）的统计结果；frame.by_finger() 返回五个手指各自的统计结果。
| 统计字段 | 含义 |
|---|---|
count | 有效点数，包含 ADC 为 0 的位置 |
total | 有效 ADC 总和 |
max | 最大有效 ADC |
mean | 有效 ADC 平均值 |
统计仅包含有效位置，没有有效读数时以上字段均为 0。这些统计不受接触点阈值影响，ADC 总和也不直接代表以牛顿为单位的合力。
接触点
frame.contacts(threshold=1) 返回 ADC 大于或等于阈值的有效位置，并按读数从高到低排列。阈值范围为 0～255；0 包含所有有效位置，255 返回空列表。
| 字段 | 含义 |
|---|---|
index | 在完整矩阵中的一维索引 |
row / col | 行、列坐标 |
value | ADC 读数 |
uv | 归一化坐标 [col / 38, row / 62] |
region | finger 或 palm |
finger | 手指名称；手掌位置为空字符串 |
frame.contact_uv(threshold=1) 返回读数最大的接触点坐标 [u, v]，没有满足阈值的点时返回 None。该坐标表示单个测点的位置，不是压力中心。并列最大值按上表中的区域顺序、区域内按行顺序选择。
接触点按测点返回，一次按压可能产生多个相邻点，因此接触点数量不等于独立按压次数。
IMU 数据
支持 IMU 的设备可提供三轴加速度和三轴角速度。frame.gyro 为当前压力帧附带的 IMU 样本，没有附带样本时为 None；也可以通过 glove.read_gyro() 单独读取。
| 字段 | 换算方式或含义 |
|---|---|
acc_x / acc_y / acc_z | 除以 100 得到加速度，单位为 g |
gyro_x / gyro_y / gyro_z | 除以 10 得到角速度，单位为 °/s |
timestamp_ms | 设备时间，单位为毫秒；未提供时为 None |
sequence | 帧序号；未提供时为 None |
source | 数据来源，serial 或 ble |
在已连接的 glove 上读取并换算：
sample = glove.read_gyro(timeout=1.0)
acceleration_g = (sample.acc_x / 100, sample.acc_y / 100, sample.acc_z / 100)
angular_velocity_dps = (
sample.gyro_x / 10,
sample.gyro_y / 10,
sample.gyro_z / 10,
)
print(acceleration_g, angular_velocity_dps)
独立 IMU 样本在读取后从待取列表中移除，不影响压力帧的读取。具体读取选项见 API 参考。
导出数据
可将一帧转换为字典并保存为 JSON：
import json
with open("glove-frame.json", "w", encoding="utf-8") as output:
json.dump(frame.to_dict(), output, ensure_ascii=False, indent=2)
字典包含 serial_number、timestamp、timestamp_ms、sequence、mode、rows、cols、values 和 gyro。无效位置在 JSON 中表示为 null。区域统计和接触点结果需按需单独保存。