Build spatial intelligence
into your vision workflow.
Install spe-engine, import spe, and add calibration, tracking, and lane-aware spatial analytics to your vision workflow.
python -m pip install spe-enginePython import: speSpatialize in-process
No server required for calibration, transforms, inspection, or rendering.
from spe import SpatialEngine
points = [[180, 120], [1090, 150], [1180, 640], [90, 660]]
engine = SpatialEngine(grid_rows=4, grid_columns=6)
engine.calibrate(points, 1280, 720)
result = engine.inspect([640, 360])Connect to SPE
Use the typed sync client or its asyncio counterpart for server operations.
from spe import SPEClient
with SPEClient("http://127.0.0.1:5000") as client:
print(client.health())
print(client.list_models())Track and measure
Associate detections, maintain motion state, and summarize zone events.
from spe import ModelAgnosticTracker
tracker = ModelAgnosticTracker()
tracked = tracker.update(detections, timestamp)
print(tracked["diagnostics"])Installation
pip install spe-engine # published package
pip install "spe-engine[http]" # + optional httpx transport
pip install "spe-engine[docs]" # + documentation tooling
# From a repository checkout:
pip install -e ".[dev]" # + pytest, pytest-cov, ruff, mypy, build, twineRuntime dependencies are numpy >= 1.24 and opencv-python-headless >= 4.8. The HTTP clients use only the standard library unless you opt into the httpx transport.
Supported Python versions: 3.10, 3.11, 3.12, 3.13, 3.14.
Architecture
The SDK exposes two independent surfaces that share one coordinate contract:
| Module | Role |
|---|---|
spe.engine | SpatialEngine — stateful, in-process facade. |
spe.geometry | Homography math and four-point calibration (OpenCV/NumPy). |
spe.spatial | Point inspection and detection spatialization primitives. |
spe.grid | Image-space and calibrated grid rendering. |
spe.zones | Deterministic semantic zone identifiers. |
spe.tracking | Provider-neutral multi-object association (ModelAgnosticTracker). |
spe.motion | Bounded trajectories, velocity, direction, and prediction. |
spe.observations | Provider-neutral timestamped observation builders. |
spe.models | Typed value objects over the JSON contracts. |
spe.client | SPEClient — synchronous HTTP client for a running engine. |
spe.aio | AsyncSPEClient — asyncio wrapper around SPEClient. |
spe.transport | Pluggable HTTP transports (urllib, requests, httpx). |
spe.exceptions | The SPEError hierarchy. |
spe.cli | The spe command-line interface. |
The local core (SpatialEngine plus the free functions) performs all geometry in-process and never needs a server. The HTTP client speaks to a running SPE engine server and mirrors the same spatial model.
Type aliases and version
spe.__version__— the installed SDK version string (also printed byspe --version).FileSource— the accepted input type for uploads:bytes | bytearray | memoryview | str | os.PathLike | BinaryIO. Astroros.PathLikeis read from disk; bytes-like values are sent as-is; any object with a callablereadis read as a binary stream.
Coordinate contract
Three coordinate systems are kept distinct:
- Image coordinates — source pixels,
(x, y), origin at the top-left. Exposed withcoordinate_system: "image_pixels"(or"source_pixels"for model detections). - Reference coordinates — the calibrated plane, default
1000 x 600,units: "normalized". Exposed withcoordinate_system: "calibrated_reference_plane". Physical units are only reported when the calibration was created with non-normalizedunits; the SDK never invents a physical scale. - Grid coordinates — logical cells over the reference plane, plus semantic zones.
Calibration uses exactly four points in TL, TR, BR, BL order — top_left, top_right, bottom_right, bottom_left. Points must form a non-degenerate, non-self-intersecting quadrilateral inside the source frame.
A four-point calibration computes a 3 x 3 homography mapping image → reference (homography) and its inverse reference → image (inverse_homography).
Grid cells are zero-based row/column indices, exposed both as a GridCell and as a coordinate list in (column, row) order. Zones are human-readable ids built from a spreadsheet-style row label and a one-based column: A1, B3, AA2, ...