Metadata-Version: 2.4
Name: spatialai
Version: 0.5.1
Summary: SpatialAI SDK — Python API for VisionLibra ToF depth sensors and cameras (simulator, depth-CV models, DM0301 I2C and DMOS5030 UART hardware backends)
Author-email: VisionLibra <sales@visionlibra.com>
License: MIT
Project-URL: Homepage, https://visionlibra.adamaohappy.workers.dev
Project-URL: Documentation, https://visionlibra.adamaohappy.workers.dev/developer.html
Keywords: tof,time-of-flight,depth,sensor,lidar,vl53l4cd,spatial,visionlibra
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dm0301
Requires-Dist: smbus2>=0.4; extra == "dm0301"
Provides-Extra: dmos5030
Requires-Dist: pyserial>=3.5; extra == "dmos5030"
Provides-Extra: hardware
Requires-Dist: smbus2>=0.4; extra == "hardware"
Requires-Dist: pyserial>=3.5; extra == "hardware"
Provides-Extra: realsense
Requires-Dist: pyrealsense2>=2.54; sys_platform != "darwin" and extra == "realsense"
Requires-Dist: pyrealsense2-macosx>=2.54; sys_platform == "darwin" and extra == "realsense"
Requires-Dist: numpy>=1.24; extra == "realsense"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# SpatialAI SDK

Python SDK for [VisionLibra](https://visionlibra.adamaohappy.workers.dev) ToF depth
sensors and cameras.

> Physical AI starts with Spatial Intelligence + AI Agents.

```bash
pip install spatialai
```

Five lines to spatial intelligence:

```python
from spatialai import Camera

cam = Camera()
result = cam.detect_people()
print(result)
# {'people': 1, 'nearest_m': 1.42, 'positions': [...], 'source': 'simulator'}
```

## Status — v0.5 (alpha)

| Feature | Status |
|---|---|
| Simulator (all products, depth frames included) | ✅ works everywhere |
| Spatial Mini / DM0301 over I²C (native protocol @ 0x41) | ✅ beta — Linux SBCs, `pip install "spatialai[dm0301]"` |
| Spatial Home / DMOS5030 over UART (protocol v1.4.4) | ✅ beta — any OS via USB-serial, `pip install "spatialai[dmos5030]"` |
| Spatial Vision / OPN6001 toolkit (`spatialai.opn6001`) | ✅ beta — RAW12 decode, post-filter chain, SPI/boot builders |
| Intel RealSense adapter (`Camera("realsense")`) | ✅ run the models on any RealSense today |
| `load_model()` + `presence-core`, `occupancy-home-v1` | ✅ free, shipped with the SDK |
| Spatial Vision full V4L2 backend, Spatial Robot (UVC) | 🚧 in development |
| Remaining marketplace models, agents, fleet | 🚧 in development — `load_model()` raises with waitlist info |

Hardware backends are implemented straight from the DOMI datasheets and
protocol docs with full protocol-level test coverage; they carry a *beta*
label until validated on production modules.

## Models

Two production models ship free with the SDK today:

```python
from spatialai import Camera

cam = Camera("spatial-home", simulate=True)
cam.load_model("occupancy-home-v1")    # room occupancy from depth CV
cam.load_model("presence-core")        # presence/approach with debouncing

for frame in cam.stream(hz=10, duration=5):
    occ = frame.models["occupancy"]
    print(f"people={occ['people']} pets={occ['pets']} occupied={occ['occupied']}")
```

`occupancy-home-v1` is classic depth computer vision — background estimation,
foreground clustering, person/pet size classification — so it needs no GPU and
runs on a Raspberry Pi. Announced models that haven't shipped
(`people-tracking-v3`, `forklift-safety`, …) raise `ModelNotAvailableYet` with
waitlist instructions instead of failing silently.

## Simulator — works on any machine

Every device can run in simulator mode, which generates realistic distance and
people-detection streams. It is the default whenever no hardware is detected,
so the quickstart above always runs.

```python
from spatialai import Camera

cam = Camera("spatial-vision", simulate=True)
for frame in cam.stream(hz=10, duration=3):
    print(f"people={frame.people} nearest={frame.nearest_m:.2f}m")
```

Try it from the terminal:

```bash
spatialai demo                  # live simulated distance readout
spatialai demo --device spatial-vision
spatialai scan                  # look for real hardware on I2C
```

## Real hardware — Spatial Mini (DM0301, I²C)

The DM0301 speaks its own register protocol at I²C address `0x41` (it is
*pin*-compatible with the VL53L4CD, but not protocol-compatible — don't use
ST drivers). Wiring on a Raspberry Pi: VIN→3V3, GND→GND, SDA→GPIO2, SCL→GPIO3,
XSHUT pulled high.

```bash
sudo raspi-config          # enable I2C
pip install "spatialai[dm0301]"
```

```python
from spatialai import Sensor

lock = Sensor("spatial-mini")      # auto-detects the sensor at 0x41
print(lock.distance_m())           # 0.734

for reading in lock.stream(hz=20):
    if reading.distance_m < 0.5:
        print("presence!", reading)
```

## Real hardware — Spatial Home (DMOS5030, UART)

Wire the module to any USB-serial adapter (115200 8N1 by default) and pass
the port:

```bash
pip install "spatialai[dmos5030]"
```

```python
from spatialai import Camera

cam = Camera("spatial-home", port="/dev/ttyUSB0")   # COM3 on Windows
cam.load_model("occupancy-home-v1")
print(cam.infer()["occupancy"])
```

Defaults to 25×25 depth at 5 fps (fits 115200 baud). For the full 100×100
resolution pass `resolution=(100, 100), baud=921600, fps=10`.

## Bring your own depth camera — Intel RealSense

Have a RealSense (D4xx/L5xx) on your desk? Run the whole SpatialAI stack on
real depth frames today:

```bash
pip install "spatialai[realsense]"
```

```python
from spatialai import Camera

cam = Camera("realsense")               # opens the first RealSense found
cam.load_model("occupancy-home-v1")
cam.load_model("presence-core")

for frame in cam.stream(hz=10):
    occ = frame.models["occupancy"]
    print(f"people={occ['people']} pets={occ['pets']} nearest={frame.nearest_m}")
```

The field of view is read from the stream intrinsics, so person/pet size
classification stays physically correct on any RealSense model.

## Real hardware — Spatial Vision (OPN6001/OPN6002, MIPI)

Spatial Vision streams 320×240 depth over MIPI CSI-2, which needs a platform
kernel driver (V4L2) — the vendor provides an RK3566 reference. Everything
above that layer ships in `spatialai.opn6001` today:

```python
from spatialai import opn6001

planes = opn6001.decode_frame(raw_u16)          # RAW12 → depth_m / ir / status / bk
depth = opn6001.ir_filter(planes["depth_m"], planes["ir"], ir_limit=50)
depth = opn6001.confidence_filter(depth, planes["status"])
depth = opn6001.median_filter(depth)            # vendor-recommended chain

words = opn6001.spi_write_words(0x4000E000, [0x80000082])   # control plane
```

The two vendor reference decoders disagree on line-1 bit positions, so
`decode_frame(variant=...)` implements both — run the module's test-pattern
modes on first bring-up to lock in the right one.

## API overview

- `Camera(device_id=None, simulate=None)` — unified entry point.
  `.detect_people()`, `.stream(hz, duration)`, `.distance_m()`, `.info()`
- `Sensor(device_id)` — alias of `Camera` tuned for 1D sensors.
- `spatialai.devices()` — catalog of supported products.
- Exceptions: `DeviceNotFound`, `HardwareNotSupportedYet`.

## Roadmap

Spatial Vision full V4L2 backend, Spatial Robot (DMAS2M001) UVC backend,
people-tracking models, and the agent/fleet APIs. Follow along at
[visionlibra.adamaohappy.workers.dev/developer.html](https://visionlibra.adamaohappy.workers.dev/developer.html).

## License

MIT
