跳转到内容
知行具身 ImprintX开发者中心
产品官网
文档导航Imprint SDK 入门
开发者中心Imprint SDK

Imprint SDK 入门

用十分钟完成 Imprint SDK 安装、设备发现、实时数据读取与录制。

更新于 2026年10月12日约 4 分钟阅读

你将完成什么

本指南将带你跑通第一条完整链路：安装 SDK、发现 ImprintX 触觉设备、读取实时数据，并保存一份可用于分析的采集结果。

完成后，你将能够：

  • 扫描并连接当前电脑上的 ImprintX 设备
  • 在控制台或可视化窗口中查看五通道触觉数据
  • 保存触觉快照，或录制带微秒级时间戳的 H.265 视频

建议先使用一台设备完成本页流程，再开始多设备或长时间采集。这样更容易定位连接、权限和运行环境问题。

开始之前

请确认设备已通过数据线连接到电脑，并在独立的 Python 虚拟环境中安装 SDK。若系统首次连接该设备，请先确认串口访问权限正常。

1. 安装 SDK

在终端中运行：

Terminal
python -m pip install imprintx

安装完成后，运行一次导入与设备扫描检查：

Terminal
python -c "from imprintx import glove; print(glove.list_ports())"

如果输出了串口路径列表，说明 SDK 已安装且设备可被发现。空列表表示当前没有检测到可用设备，请先查看本页末尾的故障排查。

2. 发现并连接设备

list_ports() 会返回当前可连接的串口路径。下面的示例会明确处理未发现设备的情况，方便你在集成时快速定位问题。

Python
from imprintx import glove

ports = glove.list_ports()
if not ports:
    raise RuntimeError("未发现 ImprintX 设备，请检查连接与串口权限")

port = ports[0]
print(f"使用设备端口: {port}")

3. 读取实时数据

最短路径是使用 stream()。它会连接指定设备，并持续输出实时触觉数据：

Python
glove.stream(port=port)

需要图形化检查传感数据时，可以打开五通道网格视图：

Python
glove.show_gui(port=port, model="dense_3ch.onnx", device="auto")

在可视化窗口中，按 q 退出，按 b 重新标定零点。

4. 保存快照与录制数据

保存五通道快照

Python
glove.save_image(
    port=port,
    output_dir="./snapshots",
    prefix="grasp_test",
    save_grid=True,
)

该调用会保存各通道图片和一张组合网格图，适合快速检查数据质量。

录制视频与时间戳

Python
glove.record_video(
    port=port,
    output_path="./records/grasp_test.mp4",
    duration=10.0,
    fps=30.0,
)

录制结果包含五通道 H.265 网格视频，以及微秒级对齐的 JSON 时间戳元数据。

5. 使用底层接口

当你需要自定义控制循环、批次读取或设备时钟同步时，使用 TouchGlove：

Python
import time
from imprintx.glove import TouchGlove, list_ports

ports = list_ports()
if not ports:
    raise RuntimeError("未发现 ImprintX 设备")

with TouchGlove(port=ports[0]) as device:
    print("Device SN:", device.get_sn())
    device.sync_rtc()
    device.start()

    for _ in range(100):
        for frame in device.poll():
            print(frame.channel, frame.seq_id, frame.timestamp_us)
        time.sleep(0.01)

上下文管理器会在代码块结束时关闭设备连接，建议在自定义脚本中优先使用这种写法。

常见问题

现象建议检查
list_ports() 返回空列表确认数据线与供电正常，重新插拔设备，并检查当前用户是否有串口访问权限
可视化窗口无法打开确认当前环境支持图形界面，并检查 OpenCV 相关运行依赖
录制文件未生成确认输出目录可写，并检查目标路径与 H.265 编码环境
数据基线异常在设备静止、无外力时按 b，或调用 calibrate_baseline() 重新标定

下一步