Command line
Installed as the spe console script; also runnable as python -m spe.
spe [--url URL] [--api-key KEY] [--timeout SECONDS] [--compact] [--version]
{health,state,models,inspect,calibrate,spatialize,track,render-grid} ...| Command | Description | Options |
|---|---|---|
health | Check server health. | — |
state | Fetch the master spatial state. | — |
models | List registered perception models. | --descriptors (typed output) |
inspect | Inspect a point against a calibration file. | --x FLOAT, --y FLOAT, --calibration PATH, --size WxH (default 1000x600), --rows INT (3), --columns INT (3) |
calibrate | Calculate a calibration from four points. | --size WxH (required), --points X,Y X,Y X,Y X,Y (required), --rows INT (3), --columns INT (3), --reference WxH (1000x600), --units STR (normalized) |
spatialize | Add spatial data to detections JSON. | --calibration PATH (required), --detections PATH (required), --rows INT, --columns INT |
track | Track a JSON list of frames. | --frames PATH (required), --min-iou FLOAT, --max-distance-scale FLOAT, --max-missing FLOAT, --confirmation INT |
render-grid | Draw a grid onto an image. | --image PATH (required), --output PATH (required), --calibration PATH, --rows INT (8), --columns INT (12), --thickness INT (1) |
Global options: --url (default http://127.0.0.1:5000), --api-key, --timeout (30 seconds), --compact (compact JSON), and --version (prints spe-engine <version>). Points may be written with either commas or semicolons. Errors print error: ... to stderr and return exit code 1.
spe --url http://127.0.0.1:5000 health
spe state
spe calibrate --size 1280x720 --points 180,120 1090,150 1180,640 90,660 --rows 4 --columns 6
spe inspect --x 640 --y 360 --calibration calibration.json --size 1280x720
spe spatialize --calibration calibration.json --detections frames.json
spe track --frames frames.json
spe render-grid --image frame.jpg --output annotated.png --rows 4 --columns 6
spe --versionStand-alone demos
Four runnable applications live under examples/ and install the built wheel from examples/assets into their own virtual environments. They never import from src/, which makes them practical proof that the package works as a normal dependency.
examples/cli— interactive media shell with lane analytics and overlays.examples/powershell— PowerShell bootstrap around a.batbatch analyzer.examples/template— Flask studio with spatial presets and Jinja JSON output.examples/web— FlowTraffic OPS camera wall with selected-feed analytics, lane telemetry, incident logging, response advisories, and replay.
See each folder's README.md for setup, commands, and output locations.
Development
pip install -e ".[dev]"
ruff check . # lint
ruff format --check . # formatting
mypy # static types
pytest --cov=spe # tests + coverage- Lint/format: ruff (config in
pyproject.toml). - Types: mypy in strict-ish mode; all public functions are fully annotated.
- Tests: pytest with branch coverage held at ~99% (CI gate: 90%).
- Packaging:
python -m buildproduces an sdist and wheel;twine checkvalidates the metadata.
Pre-commit hooks are provided (pre-commit install). See CONTRIBUTING.md for conventions and the release process, and CHANGELOG.md for version history.