SpatialAI SDK

Python SDK for VisionLibra ToF depth sensors and cameras.

Physical AI starts with Spatial Intelligence + AI Agents.

pip install spatialai

Five lines to spatial intelligence:

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)

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:

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.

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:

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.

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

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:

pip install "spatialai[dmos5030]"

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:

pip install "spatialai[realsense]"

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:

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.

License

MIT