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.4

• 适配最新版硬件底板的左右手通道映射。
• 新增五指通道同步输出。
• 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): Opens an OpenCV 2x3 grid window displaying 5-channel real-time tactile images, displacement, and force fields. The device SN is read before streaming so channels are mapped to the logical finger order for the detected left/right hand. If the glove is unplugged and reconnected, the GUI keeps running and automatically restores the stream. 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.