Metadata-Version: 2.1
Name: asmagic
Version: 0.1.1
Summary: AR Sensor Data Magic Library - Subscribe to AR sensor data streams
Author: ASMagic Team
License: MIT
Project-URL: Homepage, https://github.com/asmagic/asmagic
Project-URL: Documentation, https://github.com/asmagic/asmagic#readme
Project-URL: Repository, https://github.com/asmagic/asmagic
Project-URL: Issues, https://github.com/asmagic/asmagic/issues
Keywords: ar,sensor,zmq,protobuf,streaming
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pyzmq>=22.0.0
Requires-Dist: protobuf>=4.0.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: Pillow>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"

# asmagic

A lightweight Python library for subscribing to AR sensor data streams via ZeroMQ.

## Installation

```bash
pip install asmagic
```

## Quick Start

```python
from asmagic import ARDataSubscriber

# Create subscriber
sub = ARDataSubscriber("192.168.1.100")

# Get data frame
data = sub.get()
if data:
    print(data.timestamp)
    print(data.velocity)
    print(data.local_pose)
    print(data.camera_intrinsics)

sub.close()
```

## Usage

### Continuous Data Streaming

```python
from asmagic import ARDataSubscriber

sub = ARDataSubscriber("192.168.1.100")

try:
    while True:
        data = sub.get()
        if data:
            print(f"Velocity: {data.velocity}")
            print(f"Local pose: {data.local_pose}")
            print(f"Timestamp: {data.timestamp}")
except KeyboardInterrupt:
    pass
finally:
    sub.close()
```

### Image Display

```python
from asmagic import ARDataSubscriber
import cv2

sub = ARDataSubscriber("192.168.1.100")

try:
    while True:
        data = sub.get()
        if data:
            # Display both color and depth images
            data.show_images()

            # Or display individually
            # data.show_color()
            # data.show_depth()

        if cv2.waitKey(1) == 27:  # ESC to exit
            break
finally:
    sub.close()
    cv2.destroyAllWindows()
```

### Accessing Individual Fields

```python
from asmagic import ARDataSubscriber

sub = ARDataSubscriber("192.168.1.100")

# Get specific data
velocity = sub.get_velocity()
pose = sub.get_local_pose()
timestamp = sub.get_timestamp()

sub.close()
```

## API Reference

### ARDataSubscriber

**Constructor:**

```python
ARDataSubscriber(ip, port=8000, hwm=1, conflate=True, verbose=False)
```

**Parameters:**

-   `ip` (str): IP address of the AR device
-   `port` (int): Port number (default: 8000)
-   `hwm` (int): High water mark for ZMQ socket (default: 1)
-   `conflate` (bool): Enable message conflation (default: True)
-   `verbose` (bool): Print connection info (default: False)

**Methods:**

| Method                                | Returns                | Description           |
| ------------------------------------- | ---------------------- | --------------------- |
| `get(timeout=1000)`                   | `ARFrame` or `None`    | Get latest data frame |
| `get_timestamp(timeout=1000)`         | `float` or `None`      | Get timestamp         |
| `get_velocity(timeout=1000)`          | `np.ndarray` or `None` | Get velocity          |
| `get_local_pose(timeout=1000)`        | `np.ndarray` or `None` | Get local pose        |
| `get_global_pose(timeout=1000)`       | `np.ndarray` or `None` | Get global pose       |
| `get_camera_intrinsics(timeout=1000)` | `np.ndarray` or `None` | Get camera intrinsics |
| `get_color_image(timeout=1000)`       | `bytes` or `None`      | Get color image bytes |
| `get_depth_image(timeout=1000)`       | `np.ndarray` or `None` | Get depth image array |
| `close()`                             | `None`                 | Close connection      |

### ARFrame

Data object returned by `get()`:

**Properties:**

| Property            | Type         | Description                      |
| ------------------- | ------------ | -------------------------------- |
| `timestamp`         | `float`      | Frame timestamp                  |
| `velocity`          | `np.ndarray` | Velocity vector                  |
| `local_pose`        | `np.ndarray` | Local pose matrix                |
| `global_pose`       | `np.ndarray` | Global pose matrix               |
| `camera_intrinsics` | `np.ndarray` | Camera intrinsic parameters      |
| `color_img`         | `bytes`      | Color image bytes (JPEG/PNG)     |
| `depth_img`         | `bytes`      | Raw depth image bytes            |
| `depth_width`       | `int`        | Depth image width                |
| `depth_height`      | `int`        | Depth image height               |
| `has_color_image`   | `bool`       | Whether color image is available |
| `has_depth_image`   | `bool`       | Whether depth image is available |

**Methods:**

| Method                                | Returns      | Description                       |
| ------------------------------------- | ------------ | --------------------------------- |
| `get_depth_array()`                   | `np.ndarray` | Get depth as numpy array (uint16) |
| `show_color(window_name)`             | `bool`       | Display color image               |
| `show_depth(window_name, colormap)`   | `bool`       | Display depth image               |
| `show_images(show_color, show_depth)` | `tuple`      | Display both images               |

## Requirements

-   Python >= 3.8
-   numpy >= 1.20.0
-   pyzmq >= 22.0.0
-   protobuf >= 4.0.0
-   opencv-python >= 4.5.0
-   Pillow >= 8.0.0

## License

MIT License
