# Sparrow Spatial — repo contract

Live monocular sparse mapping. Everything here is the product:

```
scene.py        synthetic camera (deterministic path = contract). stills/stream
core.py         pipeline: extract() + step() + SparseMap + Pipeline
overlay.py      WINDOW 1: on-scene HUD (tracked points, tails, metric strip)
topmap.py       WINDOW 2: top-down sparse panel (points, camera trail, scale)
main.py         the live viewer — the product the boss demos
judge.py        behavioral gate: run headlessly, prints PASS/FAIL + names owners
demo.md         (T7) exact boss instructions to demo both panels
```

## Day-1 state (seed v1)

It runs and it is *crudely correct*: plain goodFeaturesToTrack, plain
Lucas-Kanade, a naive WeakMap whose "map" is not really a map. The judge
fails it on purpose (see its thresholds) — that gap is the backlog.

## House rules

1. New modules keep the seed's APIs (core.py imports them if present;
   duck-typing — the rest of the repo must never care).
2. Every change lands with a real commit (git history is the truth).
3. Anything you can't verify doesn't exist: run me
   (`python3 judge.py`) before claiming numbers.
4. Never touch scene.py's camera path without a meeting — the judge
   and PRs all measure against that trajectory.
5. The two panels are the product: aesthetics violations go to June,
   metric regressions to Tomas. `look` at a real frame before arguing.

## Boss usage

    cd work/project
    pixi run demo               # live demo, both panels (--source scene|webcam)
    pixi run judge              # quality gate (or type `judge` in console)
    pixi run scene              # the raw feed, if you want it

ALWAYS use the pixi env: `pixi run python <script.py>`. Never system python,
never bare pip — dependency changes are a PR that edits pixi.toml with a note
to the lead. The judge, the viewer, capture, everything runs in the env.