# Proofs of concept

Each section here is a small, reproducible demonstration of a single

component working in isolation. The intent is that someone reading the

repository can verify the engineering claims without having to set up the

full hardware pipeline.

## 1. Capture ingest

`capture/ingest.py --smoke` runs a fixed-duration capture from the first

DirectShow camera-class device that exposes a 1920x1080 60 FPS YUY2 mode,

saves one annotated frame to `logs/`, and prints measured throughput.

Reference output (Monster 4K USB 3.0):

```

[capture] device 0 opened: 1920x1080 YUY2 @ 59.93 fps

[capture] frame 0 saved: logs/smoke_frame_0.jpg

[capture] 10.02 s, 600 frames, 59.88 fps

[capture] read latency: mean 16.3 ms, p95 17.4 ms, max 40 ms

```

`capture/diagnose.py` is the version that does not depend on the publish

side. It enumerates every camera-class device, queries each for native and

forced modes, and writes a per-device PNG so the operator can confirm which

index belongs to the capture card before pinning `device_index` in

`runtime.yaml`.

## 2. Ball trajectory fit

The ball tracker maintains a rolling 0.8 s window of `(t, x_px, y_px)`

detections. On each new detection it refits two models:

- A linear `x(t) = vx * t + x0` for ETA.

- A quadratic `y(x) = a x^2 + b x + c` for plate-crossing prediction.

`tools/fit_debug.py` reads a recorded `events_*.jsonl` from `logs/`, replays

the detection stream offline, and renders the fit overlaid on the actual

detections frame-by-frame. The residual RMS is printed per pitch.

Acceptance gate: residual RMS < 4 px, window timespan >= 200 ms, and the

extrapolated `plate_x` inside the visible frame. Pitches that fail any gate

are reported with `pred_good = 0` and do not arm a swing.

## 3. PCI tracker

`tools/extract_pci_template.py` is the bootstrap step. Pause the game on a

batting screen and run:

```

python -m tools.extract_pci_template --in logs/snapshot.png --out configs/templates/pci_circle.png

```

Template matching falls back to HSV-green segmentation if the template hit

score is below threshold. Both code paths emit the same `pci_track` event

schema downstream.

## 4. Decision engine deadman

`io_titan/bridge.py` consumes `pitch_pred` and `pci_track` and only emits a

non-zero stick deflection when:

1. `armed == True` (user has explicitly armed via hotkey).

2. The most recent `pitch_pred` is younger than `120 ms`.

3. The most recent `pci_track` is younger than `60 ms`.

4. The safety daemon has not raised the abort flag.

Any one failing drops the output to a zero packet. The GPC script treats a

zero packet as full passthrough, so the controller continues to behave

normally even if the entire Python pipeline crashes.

## 5. Online-mode abort

A small classifier checks for the presence of online-mode UI elements in

each frame (specific HUD glyphs, "ranked" / "co-op" text regions). The

default `runtime.yaml` sets `safety.online_mode_abort: true`. Removing

this flag, or removing the classifier, terminates the rights granted by

the LICENSE (see [NOTICE.md](../NOTICE.md)).

## 6. End-to-end timing

A full batting cycle, measured from "ball visually leaves the pitcher's

hand" to "controller stick at target deflection":

| Stage                                | Time     |

| ------------------------------------ | -------- |

| Pitch first detected                 | t = 0    |

| 5 detections accumulated (window ok) | ~80 ms   |

| First valid trajectory fit           | ~95 ms   |

| Stick deflection emitted             | ~96 ms   |

| Controller sees deflection           | ~98 ms   |

| Plate crossing (fastball, ~95 mph)   | ~400 ms  |

This leaves roughly 300 ms of in-flight time for the PCI to actually move

into position, which the calibrated stick gain comfortably covers.