Metadata-Version: 2.4
Name: imprintx
Version: 0.2.5.1
Requires-Dist: numpy >=1.20.0
Requires-Dist: opencv-python >=4.5.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 Touch Glove SDK

Python SDK for tactile acquisition, synchronized active-channel streaming and five-channel H.265 recording. Model inference is not included in this release.

## What's new in 0.2.5.1

- Detects connected tactile channels from image traffic during the first 100 ms of streaming.
- `poll()`, `stream()`, `show_gui()`, and `save_image()` support fewer than five connected channels without creating placeholder images.
- Exposes the detected logical-channel mask through `TouchGlove.active_channels`.
- Disables automatic USB RTC synchronization in high-level APIs by default.
- Improves serial polling, queue diagnostics, and the Rust-to-NumPy zero-copy path.
- Keeps H.265 grid recording strict: all five tactile channels are required.

See [the complete 0.2.5.1 release notes](PYPI_CHANGELOG.md) for details.

```bash
pip install imprintx
```

```python
from imprintx.glove import TouchGlove, list_ports

port = list_ports()[0]
with TouchGlove(port=port) as glove:
    glove.start()
    if not glove.wait_for_batch(timeout_sec=0.1):
        raise RuntimeError("[TS_ERROR_TIMEOUT:-4] example: no synchronized batch")
    batch = glove.poll()
    for frame in batch:
        print(frame.channel, frame.seq_id, frame.timestamp_us, frame.image.shape)
```

High-level APIs:

- `glove.stream(port=None, callback=None, duration=None, stream_timeout=2.0)`
- `glove.show_gui(port=None, display_fps=60.0, stream_timeout=2.0)`
- `glove.save_image(port=None, output_dir=".", timeout_sec=3.0)`
- `glove.record_video(port=None, output_path="output_h265.mp4", duration=5.0, fps=30.0, stream_timeout=2.0)`
- `glove.load_video_timestamps(path)`

The SDK does not fabricate timestamps or missing-channel images, overwrite queued batches, return stale SN data, automatically reconnect, switch encoder backends, or silently replace invalid configuration. SN/UID handshakes, checksums, active-channel completeness, and hardware timestamps remain mandatory. Native errors contain stable codes such as `[TS_ERROR_IO:-3]`; high-level validation raises `TouchGloveError` with an `ErrorCode` value and writes an error log record.

The streaming core uses one blocking serial reader, a fixed USB/TTY coalescing window, reusable receive buffers, and ownership transfer for synchronized image frames. Complete active-channel batches are published directly without a relay thread. Python mode does not allocate the legacy C ring buffers, while the C API retains its existing ABI layout. All stream and recording queues are bounded and reject overflow instead of overwriting old frames.

