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.2 (alpha)

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)

The DM0301 1D ToF sensor is pin-to-pin compatible with the ST VL53L4CD, so the SDK drives it through the proven Adafruit driver stack.

Wiring (Raspberry Pi): VIN→3V3, GND→GND, SDA→GPIO2, SCL→GPIO3 (I²C address 0x29).

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

from spatialai import Sensor

lock = Sensor("spatial-mini")      # auto-detects the sensor on I2C
print(lock.distance_m())           # 0.734

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

Camera("spatial-mini").detect_people() also works on real hardware: it maps near-field presence onto the people-detection schema (0 or 1 person).

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

Depth-frame backends for Spatial Home (DMOS5030A serial), Spatial Vision (DMOM2508CL) and Spatial Robot (DMAS2M001), on-device people tracking models, and the agent/fleet APIs. Follow along at visionlibra.adamaohappy.workers.dev/developer.html.

License

MIT