# track — Run the tracking stack

Runs the context generator and (optionally) the inference pipeline; can record
datasets, launch an interactive UI, and/or expose a telemetry service.

## Usage (selected)

```bash
# Live network cameras, UI enabled
s6 track -i network -v

# Local USB cameras, record only into a dataset directory
s6 track -i local -o ./runs/dataset1 -r

# Replay a dataset directory in a loop (headless)
s6 track ./datasets/session_001 --repeat

# Use a database source and enable the telemetry WebSocket service
s6 track -i db:MyDataset --service

# Override pipeline parameters from a config file
s6 track --config configs/pipeline.config.yaml
```

## How it works
- Selects a context generator from `s6.app._contextgenerators` based on `--input`:
  - `network` → `CameraContextGenerator`
  - `local` → `PhysicalCameraContextGenerator`
  - `db:<name>` → `DatabaseContextGenerator`
  - directory path → `DatasetContextGenerator` (with `--repeat` support)
- Unless `--record-only` is set, applies `s6.app._pipeline.pipeline` to each
  context to populate `context["export"]`.
- With `-v/--ui`: starts a Qt/VisPy UI (`s6.app._gui.MainWindow`) and runs the
  pipeline in a background process; the UI subscribes via a multiprocessing
  queue.
- With `--service`: launches a FastAPI server that streams telemetry while the
  generator/pipeline run in a companion process.

### Telemetry service
- WebSocket: `ws://<host>:8001/ws/telemetry` — streams `{ "export": {...}, "stats": {"queue_size": N} }`.
- HTTP: `GET http://<host>:8001/queue_size` — returns `{ "queue_size": N | null }`.

## Common flags
- `-i, --input` — data source (`network`, `local`, `db:<name>`, or a dataset path)
- `-o, --output-dataset` — write a dataset to this directory
- `-x, --output-log` — write logs under `logs/runs/YYYMMDD_HHMMSS`
- `-r, --record-only` — do not run inference; only record frames
- `-v, --ui` — enable the VisPy UI
- `--service` — run the telemetry FastAPI service
- `--enable-plots` — show the plot panel in the UI
- `--repeat` — loop dataset playback (dataset input only)
- `--config` — path to a pipeline config file (JSON/YAML)