Metadata-Version: 2.4
Name: imprintx
Version: 0.2.1
Requires-Dist: numpy >=1.20.0
License-File: LICENSE
Summary: ImprintX Tactile SDK - Python bindings
Author: ImprintX
License: Proprietary
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# ImprintX Tactile SDK

High-performance Python SDK for **Touch Glove** 5-channel tactile data acquisition, RTC time synchronization, real-time 3D displacement/force physical inference (ONNX Runtime / OpenVINO), and H.265 video recording with microsecond-level timestamps.

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

---

## ⚡ Quick Start

### Installation

```bash
pip install imprintx
```

### High-Level One-Line APIs 🚀

```python
import imprintx

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

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

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

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

---

## 📖 Key Python APIs

### 1. High-Level Functions

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

- **`imprintx.show_gui(port=None, model=None, device="auto")`**:
  Opens an OpenCV 2x3 grid window displaying 5-channel real-time tactile images, displacement, and force fields. Press `'q'` to exit or `'b'` to calibrate zero point.

- **`imprintx.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`.

- **`imprintx.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.

- **`imprintx.list_ports()`**:
  Scans and returns a list of available serial port paths.

- **`imprintx.load_video_timestamps(path: str)`**:
  Loads and parses recorded video timestamp metadata from `.json` files.

---

### 2. Low-Level Core API (`TouchGlove` Class)

For custom control loops and fine-grained integration:

```python
from imprintx import TouchGlove, list_ports
import time

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

    while True:
        batch = glove.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.

