ImprintX Tactile SDK

Unified Python SDK for ImprintX tactile devices:

• imprintx.glove: Touch Glove 5-channel tactile glove SDK.
• imprintx.sensor: Single-channel tactile sensor SDK (reserved for future devices).

Powered by a native Rust core with high-efficiency PyO3 bindings.

What's New in 0.2.5

• GUI 改为逐通道监测，单个手指通道停滞时也会自动重建数据流。
• 适配最新版硬件底板的左右手通道映射。
• 新增五指通道同步输出。
• show_gui() 启动数据流前读取 SN，并支持 USB 拔插后自动恢复视频流。
• 补充 OpenCV 运行时依赖，pip install imprintx 会自动安装 GUI 所需依赖。

⚡ Quick Start

Installation

pip install imprintx

This installs the Python runtime dependencies used by the high-level APIs, including NumPy and OpenCV. CUDA inference additionally requires a compatible NVIDIA driver, CUDA runtime, and cuDNN; ROS 2 integration requires a separately installed ROS 2 environment.

High-Level One-Line Glove APIs 🚀

from imprintx import glove

# 1. 实时流式控制台输出
glove.stream()

# 2. GUI 网格图形界面展示（支持模型推理与 'b' 键实时去皮标定）
glove.show_gui(model="dense_3ch.onnx", device="cuda")

# 3. 抓取并保存 5 通道快照图片
glove.save_image(output_dir="./snapshots")

# 4. 录制 H.265 MP4 视频与微秒级时间戳 JSON
glove.record_video(output_path="recording.mp4", duration=5.0)

📖 Submodule APIs (imprintx.glove)

You can import directly via from imprintx.glove import ... or import imprintx.glove as glove:

from imprintx.glove import TouchGlove, stream, show_gui, save_image, record_video, list_ports

1. High-Level Functions

• glove.stream(port=None, callback=None, duration=None): Connects to device and streams real-time tactile data to console or custom callback function.

• glove.show_gui(port=None, model=None, device="auto", auto_reconnect=True, display_fps=60.0): Opens an OpenCV 2x3 grid window displaying 5-channel real-time tactile images, displacement, and force fields. Rendering is capped at display_fps and skipped when no newer frame is available. The device SN is read before streaming so channels are mapped to the logical finger order for the detected left/right hand. The GUI monitors every finger channel independently and automatically restores the stream if one channel stalls or the glove is unplugged and reconnected. Press 'q' to exit or 'b' to calibrate zero point.

• glove.save_image(port=None, output_dir=".", prefix="tactile", save_grid=True): Captures a 5-channel tactile snapshot and saves channel images (*_ch0.png ... *_ch4.png) and a combined grid image (*_grid.png) to output_dir.

• glove.record_video(port=None, output_path="output_h265.mp4", duration=5.0, fps=30.0): Records 5-channel H.265 grid video and exports microsecond-level aligned timestamp JSON metadata.

• glove.list_ports(): Scans and returns a list of available serial port paths.

• glove.load_video_timestamps(path: str): Loads and parses recorded video timestamp metadata from .json files.

2. Core API (TouchGlove Class)

For custom control loops and fine-grained integration:

from imprintx.glove import TouchGlove, list_ports
import time

ports = list_ports()
with TouchGlove(port=ports[0]) as g:
    print("Device SN:", g.get_sn())
    g.sync_rtc()  # Synchronize host clock with hardware RTC
    g.start()

    while True:
        batch = g.poll()
        for frame in batch:
            print(f"Ch {frame.channel} | Seq: {frame.seq_id} | Timestamp: {frame.timestamp_us} us | Image: {frame.image.shape}")
        time.sleep(0.01)

TouchGlove Methods

• glove.open(port) / glove.close(): Connection management.
• glove.start() / glove.stop(): Streaming control.
• glove.poll() -> FrameBatch: Fetch latest 5-channel frame batch.
• glove.calibrate_baseline(duration_sec=1.0): Recalibrate zero point.
• glove.get_dense_fields(): Get 5-channel 3D displacement/force fields (5, 32, 32, 3).
• glove.get_sn() / glove.set_sn(sn): Read / write hardware serial number.
• glove.sync_rtc() / glove.query_rtc(): RTC clock synchronization.
• glove.start_recording(output_path) / glove.stop_recording(): Video recording control.

📜 License

Proprietary / All Rights Reserved.