Metadata-Version: 2.4
Name: voyant-api
Version: 0.4.4
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: License :: Other/Proprietary License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=2.0
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: mypy>=1.15 ; extra == 'dev'
Requires-Dist: pyo3-stubgen>=0.3 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Python bindings for Voyant Photonics, Inc. sensors
Author-email: "Voyant Photonics, Inc." <support@voyantphotonics.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://voyant-photonics.github.io/
Project-URL: Examples, https://github.com/Voyant-Photonics/voyant-sdk
Project-URL: Homepage, https://voyant-photonics.github.io/
Project-URL: Issues, https://github.com/Voyant-Photonics/voyant-sdk/issues

# Voyant API - Python Bindings

Python bindings for Voyant Photonics LiDAR sensors, providing high-performance access to point cloud data.

## Installation

```bash
pip install voyant-api
```

## Quick Start

### Receiving Live Data

```python
from voyant_api import VoyantClient, init_voyant_logging

# Initialize logging
init_voyant_logging()

# Create client to receive live data
client = VoyantClient(
    bind_addr="0.0.0.0:4444",
    group_addr="224.0.0.0",
    interface_addr="127.0.0.1",
    filter_points=True,  # Remove invalid points
)

# Receive frames
frame_count = 0
while True:
    frame = client.try_receive_frame()
    if frame:
        frame_count += 1
        print(f"Frame {frame_count}: {frame}")

        # Get point cloud as numpy array (N x 4: x, y, z, radial_vel)
        xyzv = frame.xyzv()
        print(f"Points shape: {xyzv.shape}")
```

### Recording Data

```python
from voyant_api import VoyantClient, VoyantRecorder, RecordStatus, init_voyant_logging

init_voyant_logging()

# Create client
client = VoyantClient(
    bind_addr="0.0.0.0:4444",
    group_addr="224.0.0.0",
    interface_addr="127.0.0.1",
)

# Create recorder
recorder = VoyantRecorder(
    output_path="my_recording.bin",
    timestamp_filename=True,
    max_total_frames=1000,  # Optional: stop after 1000 frames
)

try:
    while True:
        frame = client.try_receive_frame()
        if frame:
            status = recorder.record_frame(frame)
            if status == RecordStatus.STOP:
                break
finally:
    recorder.finalize()
```

### Playing Back Recordings

```python
from voyant_api import VoyantPlayback, init_voyant_logging
from voyant_api.utils import frame_to_dataframe

init_voyant_logging()

# Create playback instance
playback = VoyantPlayback(
    rate=1.0,  # 1.0 = real-time, None = as fast as possible
    loopback=False,  # Set True to loop continuously
    filter_points=True,
)

# Open recording file
playback.open("my_recording.bin")

# Process frames
for frame in playback:
    if frame is None:
        break

    print(frame)

    # Convert to pandas DataFrame
    df = frame_to_dataframe(frame)
    print(df.head())
```

## Features

- **High Performance**: Rust-based implementation with zero-copy data access
- **NumPy Integration**: Direct conversion to NumPy arrays via `frame.xyzv()`
- **Pandas Support**: Built-in DataFrame conversion via `frame_to_dataframe()`
- **Type Hints**: Full type annotations for IDE support (`.pyi` stubs included)
- **Recording & Playback**: Save and replay sensor data with timestamp preservation
- **Network Streaming**: Multicast UDP support for live sensor data

## API Overview

### VoyantClient

Receives live data from Voyant sensors over multicast UDP.

```python
client = VoyantClient(
    bind_addr="0.0.0.0:4444",      # Local socket to bind
    group_addr="224.0.0.0",         # Multicast group
    interface_addr="127.0.0.1",     # Network interface
    filter_points=True,             # Remove invalid points
    use_msg_stamps=False,           # Use message timestamps (False for Meadowlark, True for Carbon)
)
```

### VoyantRecorder

Records frames to binary files with automatic splitting options.

```python
recorder = VoyantRecorder(
    output_path="recording.bin",
    timestamp_filename=True,         # Add timestamp to filename
    frames_per_file=None,            # Split after N frames
    duration_per_file=None,          # Split after N seconds
    size_per_file_mb=None,           # Split after N megabytes
    max_total_frames=None,           # Stop after N total frames
    max_total_duration=None,         # Stop after N total seconds
    max_total_size_mb=None,          # Stop after N total megabytes
)
```

### VoyantPlayback

Plays back recorded data with rate control.

```python
playback = VoyantPlayback(
    rate=1.0,              # Playback speed (None = unlimited)
    loopback=False,        # Loop continuously
    filter_points=True,    # Remove invalid points
)
playback.open("recording.bin")
```

### Frame Data Access

```python
# NumPy array (N x 4): [x, y, z, radial_vel]
xyzv = frame.xyzv()

# Pandas DataFrame with all default columns
df = frame_to_dataframe(frame)

# Frame metadata
print(frame.point_count())
print(frame.timestamp())
```

## Complete Examples

Full example scripts are available in the [voyant-sdk repository](https://github.com/Voyant-Photonics/voyant-sdk):

- `client_example.py` - Live data streaming
- `recorder_example.py` - Recording with all options
- `playback_example.py` - Playback and processing

## System Requirements

- **Python**: 3.9 or later
- **Dependencies**: NumPy 2.0+, Pandas 2.0+
- **Platforms**: Linux, Windows, macOS
- **Hardware**: Compatible with Voyant Photonics LiDAR sensors

## Documentation

- **Full Documentation**: https://voyant-photonics.github.io/
- **Examples Repository**: https://github.com/Voyant-Photonics/voyant-sdk

## Support

- **Issues**: https://github.com/Voyant-Photonics/voyant-sdk/issues
- **Email**: support@voyantphotonics.com

## License

Proprietary - for use with Voyant Photonics hardware products only.

Copyright © 2025 Voyant Photonics, Inc. All rights reserved.

