# Ball detector

Two detector backends. The HSV classical path is the default. The YOLO path

is the fallback for harder lighting (HDR tone mapping, stadium shadows,

white jerseys).

## Why a learned detector at all

The HSV + circularity tracker is fast and zero-dependency, but it false-positives

on jersey numbers, scoreboard graphics, and field highlights that share the

baseball's near-white tone. Under HDR-to-SDR tone mapping (Monster card output

when the Xbox has HDR enabled), the ball loses saturation and the HSV envelope

has to be widened so much that the false-positive rate becomes unworkable.

A single-class YOLO detector trained directly on the capture feed fixes this.

## Training summary

| Metric          | Value  |

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

| Architecture    | YOLOv11n (single-class, `ball`) |

| Image size      | 640    |

| Epochs          | 45 (early-stopped from 80) |

| Batch           | 8      |

| Final mAP50     | 0.94   |

| Final mAP50-95  | 0.38   |

| Final precision | 0.92   |

| Final recall    | 0.93   |

Training curves: ![results](images/results.png)

Box precision / recall / F1 / PR curves:

| Curve | Plot |

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

| Precision | ![P](images/BoxP_curve.png) |

| Recall    | ![R](images/BoxR_curve.png) |

| F1        | ![F1](images/BoxF1_curve.png) |

| PR        | ![PR](images/BoxPR_curve.png) |

Confusion matrix (single class plus background):

![confusion](images/confusion_matrix_normalized.png)

## Dataset

Frames are sampled at 12 FPS from live capture during batting practice and

labeled in YOLO format with a single class. The labeled set is split 70 / 20 /

10 train / val / test by `tools/yolo_split_dataset.py`. A hard-negatives pass

(false-positive frames from the previous-generation HSV tracker, labeled with

empty boxes) reduces background activations on jerseys and scoreboards.

Dataset volumes are not committed to this repository. Training is intended to

be reproduced from each operator's own capture feed; see

`tools/yolo_collect_frames.py` and `tools/yolo_label_ball.py`.

## Runtime

The trained `best.pt` is exported to ONNX and consumed by

`io_titan/mlb26_gcv_yolo.py` inside Gtuner IV's Computer Vision worker. ONNX

keeps inference at ~22 ms per frame on CPU at 320x320 input, which is well

inside the 60 FPS budget. GPU inference is roughly 4 ms.