Metadata-Version: 2.4
Name: imprintx
Version: 0.2.2
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

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.

---

## ⚡ Quick Start

### Installation

```bash
pip install imprintx
```

### High-Level One-Line Glove APIs 🚀

```python
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`:

```python
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")`**:
  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.

- **`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:

```python
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.

