Metadata-Version: 2.4
Name: imprintx
Version: 0.3.1
Requires-Dist: numpy>=1.20.0
Requires-Dist: pyzmq>=22
License-File: LICENSE
Summary: Python SDK for ImprintX Sensors and Touch Gloves
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# ImprintX SDK (Python)

Python SDK for Imprint X and Imprint Glove. Imprint X support
provides event-stream acquisition and device control. Imprint Glove support
provides synchronized five-channel tactile image acquisition, raw IMU data,
device-state control, and data streaming.

The SDK distinguishes the devices as `sensor` and `glove` in module names and
the service's `--device` option. The Python classes remain `Sensor` and `TouchGlove`.

The SDK supports Python 3.8 and newer. Model inference, GUI, and recording are
not included in the package.

## What's New in 0.3.1

1. Fixed several known issues.

## Installation

```bash
pip install imprintx
```

## Imprint X

Shared mode (the service owns the serial port):

```bash
imprintx-sdk --device sensor /dev/ttyACM0
```

Direct mode (the application owns the serial port; do not run the service for
the same device at the same time):

```python
from imprintx.sensor import Sensor

with Sensor("/dev/ttyACM0") as sensor:
    sensor.set_light(True)
    try:
        sensor.start()
        if not sensor.wait_for_batch(timeout_sec=1.0):
            raise TimeoutError("No event batch received")

        for event in sensor.poll():
            print(event.x, event.y, event.polarity, event.timestamp_us)
    finally:
        try:
            if sensor.is_streaming:
                sensor.stop()
        finally:
            if not sensor.is_streaming:
                sensor.set_light(False)
```

Imprint X events include 320 x 320 coordinates, polarity, and a device timestamp
in microseconds.

## Imprint Glove

Shared mode (the service owns the serial port):

```bash
imprintx-sdk --device glove /dev/ttyACM0
```

Direct mode (the application owns the serial port; do not run the service for
the same device at the same time):

```python
from imprintx.glove import TouchGlove

with TouchGlove("/dev/ttyACM0") as glove:
    print(f"Firmware: {glove.firmware_version}; device: {glove.sn}")
    glove.start()

    if not glove.wait_for_batch(timeout_sec=1.0):
        raise TimeoutError("No synchronized tactile batch received")

    batch = glove.poll()
    for frame in batch:
        print(
            f"channel={frame.channel} "
            f"timestamp={frame.timestamp_us}us "
            f"shape={frame.image.shape}"
        )
```

Each image is a 192 x 192 NumPy array. A batch is returned only after the
detected active tactile channels have been synchronized. Opening an Imprint Glove
fails unless firmware version 1.0 or newer and the device identity are both
validated.

## Examples

For usage examples, see the
[ImprintX SDK repository](https://github.com/Imprint-X/Imprintx-sdk).

## Data Integrity

Imprint X commands validate their checksums and acknowledgements; Imprint X event
streams validate EVT20 types, coordinates, and timestamps. Imprint Glove streams
validate checksums, payload sizes, hardware timestamps, and synchronized channel
batches. Missing channels, timestamps, serial numbers, events, and frames are
never fabricated. Queue overflow, incomplete batches, and stream continuity
failures are reported as explicit errors; the SDK does not automatically
reconnect or silently retry control requests.

## License

Copyright (c) ImprintX. All rights reserved. This package is proprietary
software; use and distribution are subject to the included license terms.

