Metadata-Version: 2.4
Name: imprintx
Version: 0.3.0
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 ImprintX Sensors and Touch Gloves. ImprintX Sensor support
provides event-stream acquisition and device control. Touch Glove support
provides synchronized five-channel tactile image acquisition, raw IMU data,
device-state control, and data streaming.

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

## Installation

```bash
pip install imprintx
```

## ImprintX Sensor

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)
```

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

## Touch 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 a Touch 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

Sensor commands validate their checksums and acknowledgements; Sensor event
streams validate EVT20 types, coordinates, and timestamps. Touch 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.

