feat(cv): draw object-ball trails in the shot overlay

Only the cue left a tail, so the video showed the target balls
teleporting between boxes. Each ball_track now draws its own tail in
the same TRAIL_N window, coloured through init_idx -> balls_init ->
number, under the cue tail so the cue stays the main character.
Gate: pytest 188/202 green, 5 new cases on the pure half.

src/poolcoach_cv/overlay.py

@@ -3,7 +3,9 @@
 The drawing style is reused from the pilot tracking script (a track tail
 plus a status header), extended for the app: EVERY ball is drawn, not just
 the cue; colours follow the ball number (the two-stage BallID runs per frame
-on the same bbox crops); and the inferred collisions are marked.
+on the same bbox crops); EVERY tracked ball gets a tail, not just the cue
+(``ball_tracks``, coloured by the same number); and the inferred collisions
+are marked.
 
 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
@@ -38,7 +40,9 @@ import numpy as np
 
 from poolcoach_cv.broadcast import BALL_CLASSES, BALL_R_M
 
-TRAIL_N = 90            # track points drawn as the cue-ball tail
+TRAIL_N = 90            # track points drawn as a ball tail -- ONE window
+                        # for the cue and every object ball, so the tails
+                        # tell the same length of story
 
 # Ball colours by number (BGR) -- matched to the front-end COLORS table so
 # both places tell the same colour story; unknown or unrecognised is grey.
@@ -95,6 +99,43 @@ def _uncomp_xy(pts: np.ndarray, height_comp: dict | None) -> np.ndarray:
         - k * np.array([cx, cy])
 
 
+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)]``.
+
+    The colour comes from the ball NUMBER, which the track does not carry
+    itself: ``init_idx`` points back into ``balls_init``, where the worker
+    attached ``number`` from the same BallID pass the boxes use, so a ball's
+    tail and its box tell the same colour story. No number -- an
+    unrecognised colour or an older result -- draws grey rather than
+    inventing one.
+
+    Coordinates go through ``_uncomp_xy`` exactly like the cue tail: the
+    JSON holds compensated ball centres, and the frame shows where the ball
+    APPEARS. A track shorter than two points cannot be a polyline and is
+    dropped here rather than in the render loop.
+
+    Pure numpy (``th`` is the pure TableHomography), so it is unit tested in
+    the app environment.
+    """
+    hc = result.get("height_comp")
+    balls_init = result.get("balls_init") or []
+    trails: list[tuple] = []
+    for bt in result.get("ball_tracks") or []:
+        pts = bt.get("track") or []
+        if len(pts) < 2:
+            continue
+        idx = bt.get("init_idx")
+        num = (balls_init[idx].get("number")
+               if isinstance(idx, int) and 0 <= idx < len(balls_init)
+               else None)
+        xy = np.array([[float(p["x_m"]), float(p["y_m"])] for p in pts])
+        trails.append((np.array([float(p["t_s"]) for p in pts]),
+                       th.table_to_px(_uncomp_xy(xy, hc)),
+                       BALL_BGR.get(num, UNKNOWN_BGR)))
+    return trails
+
+
 def _reencode_h264(src: Path, dst: Path) -> str | None:
     """mp4v -> H.264 yuv420p +faststart so a browser <video> can play it.
     Returns None on success, or a warning message when ffmpeg is missing or
@@ -158,6 +199,7 @@ def render_shot_overlay(clip_path, corners_px, result: dict,
     trail_px = (th.table_to_px(_uncomp_xy(
         np.array([[float(p["x_m"]), float(p["y_m"])] for p in track]), hc))
         if track else np.empty((0, 2)))
+    ball_trails = _ball_trails(result, th)
     cols = result.get("collisions") or []
     col_t = [float(c["t_s"]) for c in cols]
     col_px = (th.table_to_px(_uncomp_xy(
@@ -228,6 +270,15 @@ 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.
+            for bt_t, bt_px, bt_col in ball_trails:
+                bp = bt_px[bt_t <= t_rel + 1e-6][-TRAIL_N:]
+                if len(bp) >= 2:
+                    cv2.polylines(frame, [bp.astype(np.int32)], False,
+                                  bt_col, 2)
+
             # cue-ball track tail -- the points measured up to this moment
             m = trail_t <= t_rel + 1e-6
             pts = trail_px[m][-TRAIL_N:]

tests/test_overlay.py

@@ -1,7 +1,8 @@
 """Tests for the PURE part of poolcoach_cv.overlay (slice A2 part 3) -- the
 app venv, no cv2 and no torch: RecordingModel (recording the boxes around a
-predict) plus _uncomp_xy (inverting the height compensation, so drawing back
-onto the frame lands where the ball APPEARS).
+predict), _uncomp_xy (inverting the height compensation, so drawing back
+onto the frame lands where the ball APPEARS) and _ball_trails (an
+object-ball track -> the coloured polyline the render loop clips by time).
 
 The real render was accepted by a smoke run on the shot 03 clip of rack_a1
 (the CV venv, 13/08) plus gate A2.2 when the whole VOD was rerun.
@@ -12,8 +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.camera import HeightCompensation
-from poolcoach_cv.overlay import BALL_BGR, RecordingModel, _uncomp_xy
+from poolcoach_cv.homography import TableHomography, orient_corners
+from poolcoach_cv.overlay import (BALL_BGR, UNKNOWN_BGR, RecordingModel, _ball_trails,
+                                  _uncomp_xy)
 
 
 class _Box:
@@ -75,3 +79,88 @@ def test_uncomp_xy_leaves_points_alone_when_off_or_camera_missing():
 
 def test_ball_colour_table_covers_1_to_9():
     assert set(BALL_BGR) == set(range(1, 10))
+
+
+# ----------------------------------------------------- object-ball tails
+# _ball_trails is the pure half of drawing them: track -> (times, pixel
+# polyline, colour). The render loop only clips it by time and calls
+# polylines, which is the part the smoke run covers.
+
+CORNERS_PX = [[527.5, 869.7], [1380.1, 864.0],
+              [1232.3, 278.5], [673.0, 272.8]]
+
+
+def _th():
+    return TableHomography(orient_corners(np.asarray(CORNERS_PX,
+                                                     dtype=np.float64)),
+                           table_w=TABLE_W_M, table_l=TABLE_L_M)
+
+
+def _line(t0, n=4, x=0.6, y=1.2):
+    return [{"t_s": round(t0 + i * 0.033, 3), "x_m": x + i * 0.05, "y_m": y}
+            for i in range(n)]
+
+
+def test_ball_trails_take_their_colour_from_the_number_via_init_idx():
+    """A track carries no number of its own: init_idx points back into
+    balls_init, which is where BallID left it -- so a tail and the box of
+    the same ball are drawn in the same colour."""
+    res = {
+        "balls_init": [
+            {"x_m": 0.5, "y_m": 0.2, "type": "cue", "conf": 0.9},
+            {"x_m": 0.6, "y_m": 1.2, "type": "ball", "conf": 0.9,
+             "number": 3},
+            {"x_m": 0.9, "y_m": 1.8, "type": "ball", "conf": 0.9},
+        ],
+        "ball_tracks": [{"init_idx": 1, "track": _line(0.0),
+                         "pocketed_guess": False},
+                        {"init_idx": 2, "track": _line(0.1, x=0.9),
+                         "pocketed_guess": True}],
+    }
+    trails = _ball_trails(res, _th())
+    assert len(trails) == 2
+    assert trails[0][2] == BALL_BGR[3]
+    assert trails[1][2] == UNKNOWN_BGR        # no number -> grey, not guessed
+    assert trails[0][0].tolist() == [p["t_s"] for p in _line(0.0)]
+    assert trails[0][1].shape == (4, 2)
+    assert np.isfinite(trails[0][1]).all()
+
+
+def test_ball_trails_fall_back_to_grey_on_an_init_idx_that_points_nowhere():
+    """A hand-edited or truncated result must not raise: an index outside
+    balls_init draws grey."""
+    res = {"balls_init": [{"x_m": 0.5, "y_m": 0.2, "type": "cue",
+                           "conf": 0.9}],
+           "ball_tracks": [{"init_idx": 7, "track": _line(0.0)},
+                           {"init_idx": None, "track": _line(0.0)}]}
+    assert [t[2] for t in _ball_trails(res, _th())] \
+        == [UNKNOWN_BGR, UNKNOWN_BGR]
+
+
+def test_ball_trails_drop_a_track_too_short_to_be_a_polyline():
+    res = {"balls_init": [], "ball_tracks": [
+        {"init_idx": 0, "track": _line(0.0, n=1)},
+        {"init_idx": 0, "track": []},
+        {"init_idx": 0, "track": _line(0.0, n=2)}]}
+    assert len(_ball_trails(res, _th())) == 1
+
+
+def test_a_result_without_ball_tracks_draws_no_extra_tail():
+    """An older result (the field predates nothing else) simply has no
+    object-ball tails -- the overlay is what it always was."""
+    assert _ball_trails({"track": _line(0.0)}, _th()) == []
+    assert _ball_trails({"ball_tracks": []}, _th()) == []
+
+
+def test_ball_trails_undo_the_height_compensation_like_the_cue_tail():
+    """The JSON holds COMPENSATED centres; the tail has to land where the
+    ball appears on the frame, so the same inverse the cue tail uses is
+    applied -- an on flag must move the pixels."""
+    res = {"balls_init": [], "ball_tracks": [{"init_idx": 0,
+                                              "track": _line(0.0)}]}
+    plain = _ball_trails(res, _th())[0][1]
+    res["height_comp"] = {"on": True, "h_m": 2.41, "cx_m": 0.6, "cy_m": 1.2}
+    comped = _ball_trails(res, _th())[0][1]
+    assert not np.allclose(plain, comped)
+    res["height_comp"] = {"on": False}
+    assert np.allclose(_ball_trails(res, _th())[0][1], plain)