fix(analyzer): draw only on-table detections in the overlay

The overlay drew every recorded box while analyze_clip has always
dropped the ones projecting off the cloth, so the imgsz 960 pass put
rectangles on the wall behind the far rail -- 2172 of 3476 ball boxes
on shot_02, reaching table y 4.48 and x -0.42. _on_table_dets applies
the same class filter and the same IN_TOL_M gate, in the same
height-compensated frame, and none survives into the drawing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/poolcoach_cv/overlay.py

@@ -9,6 +9,11 @@ viewer sees immediately); EVERY tracked ball gets a tail, not just the cue
 (``ball_tracks``, coloured by the same number); and the inferred collisions
 are marked.
 
+Only detections ON THE CLOTH are drawn: the same class filter and the same
+IN_TOL_M projection gate ``analyze_clip`` applies, so the video shows what
+the measurement accepted and nothing else (before that gate reached here,
+the imgsz 960 pass put boxes on the wall behind the far rail).
+
 Rendering happens INSIDE the analyze job, BEFORE the worker deletes the clip
 -- the lesson from the first full run being that once the clip is gone the
 overlay cannot be produced retroactively. Detections are NOT recomputed:
@@ -40,7 +45,8 @@ from pathlib import Path
 
 import numpy as np
 
-from poolcoach_cv.broadcast import BALL_CLASSES, BALL_R_M
+from poolcoach_cv.broadcast import (BALL_CLASSES, BALL_R_M,
+                                    IN_TOL_M, TABLE_L_M, TABLE_W_M)
 
 TRAIL_N = 90            # track points drawn as a ball tail -- ONE window
                         # for the cue and every object ball, so the tails
@@ -112,6 +118,65 @@ def _uncomp_xy(pts: np.ndarray, height_comp: dict | None) -> np.ndarray:
         - k * np.array([cx, cy])
 
 
+def _comp_xy(pts: np.ndarray, height_comp: dict | None) -> np.ndarray:
+    """Apply the ball-centre height compensation: X', the cloth-plane
+    mapped position of a bbox centre, forward to P, the coordinate the JSON
+    speaks in. The exact forward of ``_uncomp_xy`` and a copy of
+    ``camera.HeightCompensation.apply``: P = (X' + k.C)/(1 + k) with
+    k = R/(h - R).
+
+    It exists so the overlay can ask the SAME question about a detection
+    that ``analyze_clip`` asked -- is this box on the cloth? -- in the same
+    coordinates. Reading the raw homography instead would put the far
+    cushion 3 cm further away here than there, and a box the numeric layer
+    accepted could vanish from the video that is supposed to show it.
+    An off flag or a missing camera leaves the points alone."""
+    if not height_comp or not height_comp.get("on"):
+        return pts
+    h = height_comp.get("h_m")
+    cx, cy = height_comp.get("cx_m"), height_comp.get("cy_m")
+    if h is None or cx is None or cy is None:
+        return pts
+    k = BALL_R_M / (h - BALL_R_M)
+    return (np.asarray(pts, dtype=np.float64)
+            + k * np.array([cx, cy])) / (1.0 + k)
+
+
+def _on_table_dets(th, dets: list[tuple],
+                   height_comp: dict | None) -> list[tuple]:
+    """The recorded detections that are BALLS ON THE CLOTH, each paired
+    with its table position: ``[((cls, conf, box), (x_m, y_m)), ...]``.
+
+    Two filters, both copied from ``broadcast.table_det`` so the overlay
+    draws neither more nor less than the numeric layer accepted: the class
+    has to be in BALL_CLASSES, and the bbox centre has to project inside the
+    table plus IN_TOL_M. The second one is why this function exists. The
+    detector at imgsz 960 returns boxes off the cloth -- the far-zone probe
+    measured one projecting to y ~ 4.25 m, 1.7 m past the far cushion --
+    and analyze_clip has always dropped them, but the overlay drew every
+    recorded box and so painted rectangles on the wall behind the table.
+    A viewer reading the video as the picture of the measurement was being
+    told the analyzer had found a ball there.
+
+    Pure numpy (``th`` is the pure TableHomography), so it is unit tested
+    in the app environment.
+    """
+    out: list[tuple] = []
+    for det in dets:
+        cls, _conf, (x1, y1, x2, y2) = det
+        if cls not in BALL_CLASSES:
+            continue
+        xy = _comp_xy(np.asarray(th.px_to_table(((x1 + x2) / 2.0,
+                                                 (y1 + y2) / 2.0)),
+                                 dtype=np.float64).reshape(2),
+                      height_comp)
+        tx, ty = float(xy[0]), float(xy[1])
+        if (-IN_TOL_M <= tx <= TABLE_W_M + IN_TOL_M
+                and -IN_TOL_M <= ty <= TABLE_L_M + IN_TOL_M):
+            out.append((det, (tx, ty)))
+    return out
+
+
 def _ball_trails(result: dict, th) -> list[tuple]:
     """Every OBJECT-ball track of the result, ready to draw:
     ``[(t_s array, pixel polyline, BGR colour)]``.
@@ -189,6 +254,9 @@ def render_shot_overlay(clip_path, corners_px, result: dict,
     suspect_not_shot -- table coordinates, with t_s relative to the first
     frame of the clip).
     ``frames_dets``: from RecordingModel -- the index is the frame order.
+    They are filtered through ``_on_table_dets`` before anything is drawn:
+    a box the numeric layer threw away for projecting off the cloth must
+    not appear on the video either.
     ``label``: the leading text of the header (ASCII), e.g. "shot 03".
     ``beat``: a callback invoked periodically to keep the heartbeat alive
     during a long job.
@@ -263,10 +331,9 @@ def render_shot_overlay(clip_path, corners_px, result: dict,
                 beat()
 
             dets = frames_dets[i] if i < n_total else []
-            balls = [(cls, conf, box) for cls, conf, box in dets
-                     if cls in BALL_CLASSES]
-            others = [b for b in balls if b[0] != "Cue"]
-            cue = next((b for b in balls if b[0] == "Cue"), None)
+            balls = _on_table_dets(th, dets, hc)
+            others = [b for b, _xy in balls if b[0] != "Cue"]
+            cue = next((b for b, _xy in balls if b[0] == "Cue"), None)
             assigns = []
             if others:
                 try:
@@ -290,6 +357,7 @@ def render_shot_overlay(clip_path, corners_px, result: dict,
                 cv2.rectangle(frame, (int(x1), int(y1)),
                               (int(x2), int(y2)), CUE_BGR, 2)
 
+
             # object-ball tails -- the same TRAIL_N window as the cue, each
             # in its own ball colour. Drawn FIRST so the cue tail stays on
             # top: the cue is still the main character of the shot.

tests/test_overlay.py

@@ -13,10 +13,11 @@ from __future__ import annotations
 import numpy as np
 import pytest
 
-from poolcoach_cv.broadcast import TABLE_L_M, TABLE_W_M
+from poolcoach_cv.broadcast import IN_TOL_M, TABLE_L_M, TABLE_W_M
 from poolcoach_cv.camera import HeightCompensation
 from poolcoach_cv.homography import TableHomography, orient_corners
-from poolcoach_cv.overlay import (BALL_BGR, UNKNOWN_BGR, RecordingModel, _ball_trails,
+from poolcoach_cv.overlay import (BALL_BGR, UNKNOWN_BGR, RecordingModel,
+                                  _ball_trails, _comp_xy, _on_table_dets,
                                   _uncomp_xy)
 
 
@@ -164,3 +165,82 @@ def test_ball_trails_undo_the_height_compensation_like_the_cue_tail():
     assert not np.allclose(plain, comped)
     res["height_comp"] = {"on": False}
     assert np.allclose(_ball_trails(res, _th())[0][1], plain)
+
+
+# ------------------------------------------- only what is ON THE CLOTH
+# _on_table_dets is the whole of step 1 of hand-off 4: the overlay used to
+# draw every recorded box, so the imgsz 960 pass painted rectangles on the
+# wall behind the far rail -- boxes analyze_clip itself had thrown away.
+
+HC = {"on": True, "h_m": 2.363, "cx_m": 0.549, "cy_m": -2.366}
+
+
+def _box_at(x_m, y_m, hc=None, s=8.0):
+    """A square pixel box whose CENTRE maps back to the table point
+    (x_m, y_m) -- built through the same inverse the drawing uses, so a
+    point placed here is a point _on_table_dets has to read back."""
+    cx, cy = _th().table_to_px(_uncomp_xy(np.array([[x_m, y_m]]), hc))[0]
+    return (cx - s, cy - s, cx + s, cy + s)
+
+
+def test_comp_xy_is_the_exact_forward_of_uncomp_xy():
+    """The overlay asks analyze_clip's question in analyze_clip's
+    coordinates, so the two directions have to be one map."""
+    pts = np.array([[0.2, 0.4], [1.1, 2.3]])
+    assert _comp_xy(_uncomp_xy(pts, HC), HC) == pytest.approx(pts, abs=1e-9)
+    comp = HeightCompensation(True, cam_xy=(HC["cx_m"], HC["cy_m"]),
+                              h_m=HC["h_m"], f_px=2155.0, ball_r=0.028575)
+    assert _comp_xy(pts, HC) == pytest.approx(comp.apply(pts), abs=1e-9)
+    assert _comp_xy(pts, {"on": False}) is pts
+    assert _comp_xy(pts, None) is pts
+
+
+def test_on_table_dets_keeps_a_detection_inside_the_cloth():
+    th = _th()
+    det = ("Solid", 0.8, _box_at(0.6, 1.2))
+    got = _on_table_dets(th, [det], None)
+    assert len(got) == 1 and got[0][0] is det
+    assert got[0][1] == pytest.approx((0.6, 1.2), abs=1e-6)
+
+
+def test_on_table_dets_drops_a_detection_off_the_cloth():
+    """The box on the wall: the probe measured one projecting to y ~ 4.25 m,
+    1.7 m past the far cushion."""
+    th = _th()
+    assert _on_table_dets(th, [("Solid", 0.7, _box_at(0.6, 4.25))], None) == []
+    assert _on_table_dets(th, [("Cue", 0.9, _box_at(-0.4, 1.2))], None) == []
+
+
+def test_on_table_dets_reads_the_edge_the_way_analyze_clip_does():
+    """IN_TOL_M is the tolerance the numeric layer uses, inclusive -- one
+    tolerance, not two, or a ball the metric table shows would have no box
+    on the video."""
+    th = _th()
+    inside = ("Solid", 0.7, _box_at(0.6, TABLE_L_M + IN_TOL_M - 1e-4))
+    outside = ("Solid", 0.7, _box_at(0.6, TABLE_L_M + IN_TOL_M + 1e-3))
+    assert len(_on_table_dets(th, [inside], None)) == 1
+    assert _on_table_dets(th, [outside], None) == []
+    left = ("Solid", 0.7, _box_at(-IN_TOL_M + 1e-4, 1.2))
+    assert len(_on_table_dets(th, [left], None)) == 1
+
+
+def test_on_table_dets_still_drops_a_class_that_is_not_a_ball():
+    """The class filter did not move -- a diamond marker is not a ball."""
+    th = _th()
+    assert _on_table_dets(th, [("Dot", 0.9, _box_at(0.6, 1.2))], None) == []
+
+
+def test_on_table_dets_answers_in_the_compensated_frame():
+    """A box read at the far rail: with the compensation on it lands where
+    balls_init would put it, which is the only frame the two layers can
+    compare positions in."""
+    th = _th()
+    det = ("Solid", 0.7, _box_at(1.146, 2.4519, HC))
+    got = _on_table_dets(th, [det], HC)
+    assert len(got) == 1
+    assert got[0][1] == pytest.approx((1.146, 2.4519), abs=1e-6)
+    # read WITHOUT the flag the same box sits further away -- which is the
+    # bias this exists to avoid
+    plain = _on_table_dets(th, [det], None)
+    assert plain[0][1][1] > got[0][1][1] + 0.02
+