Add PASS_ALTERNATIVES freeze planner, overlays, and mode.

Reuse PassQualityScorer for lane scoring, existing pass annotators for
freeze UI, and BallPositionHistory for ball-speed freeze gates — no parallel
scoring or draw stacks.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: AlexBodner

examples/soccer/README.md

@@ -177,9 +177,15 @@ on the field.
   --device mps --mode PASS_NETWORK --tracker bytetrack
   ```
 
-- `PASS_ALTERNATIVES` — *(library Stage 0 on this branch)* Lane scoring
-  (`pass_options`) and quality decoration for detected passes. Freeze-moment
-  planner + CLI mode runner still to land. Not part of `ALL`.
+- `PASS_ALTERNATIVES` — Freeze moments with ranked open teammate pass lanes
+  (lane scoring via `pass_options` / `PassQualityScorer`). Opt-in only (not
+  part of `ALL`). Requires ball weights like `PASS_NETWORK`; prefer a full clip.
+
+  ```bash
+  python main.py --source_video_path data/08fd33_0.mp4 \
+  --target_video_path data/renders/08fd33_0-pass-alternatives.mp4 \
+  --device mps --mode PASS_ALTERNATIVES --tracker bytetrack
+  ```
 
 - `ALL` — Runs DIRECTION, SPEED, DISTANCE, SPEED_AND_DISTANCE (all players), and
   SPEED_AND_DISTANCE (spotlight) in one pass. Builds a shared

examples/soccer/main.py

@@ -26,6 +26,7 @@
 
 from direction import run_direction
 from distance import run_distance
+from pass_alternatives import run_pass_alternatives
 from pass_network import run_pass_network
 from run_all import run_all
 from speed import run_speed
@@ -93,12 +94,13 @@ class Mode(Enum):
     DISTANCE = 'DISTANCE'
     SPEED_AND_DISTANCE = 'SPEED_AND_DISTANCE'
     PASS_NETWORK = 'PASS_NETWORK'
+    PASS_ALTERNATIVES = 'PASS_ALTERNATIVES'
     ALL = 'ALL'
 
 
 ANALYTICS_MODES = (
     Mode.DIRECTION, Mode.SPEED, Mode.DISTANCE,
-    Mode.SPEED_AND_DISTANCE, Mode.PASS_NETWORK, Mode.ALL,
+    Mode.SPEED_AND_DISTANCE, Mode.PASS_NETWORK, Mode.PASS_ALTERNATIVES, Mode.ALL,
 )
 
 
@@ -113,6 +115,8 @@ def run_analytics_mode(mode: Mode, args: argparse.Namespace) -> None:
         run_speed_and_distance(args)
     elif mode == Mode.PASS_NETWORK:
         run_pass_network(args)
+    elif mode == Mode.PASS_ALTERNATIVES:
+        run_pass_alternatives(args)
     elif mode == Mode.ALL:
         run_all(args)
     else:

examples/soccer/pass_alternatives.py

@@ -0,0 +1,157 @@
+"""PASS_ALTERNATIVES mode: freeze moments with ranked open pass lanes."""
+
+from __future__ import annotations
+
+import supervision as sv
+
+from sports.annotators.passing import (
+    CARRIER_SHADOW_BGR,
+    annotate_ball,
+    annotate_pass_players,
+    draw_carrier_ground_ellipse,
+    draw_hud_bar,
+    draw_pass_alternatives_overlay,
+    draw_radar_minimap,
+)
+from sports.common.kinematics import feet_xy
+from sports.common.pass_alternatives import (
+    DEFAULT_FINAL_OPTION_EXTRA_SECONDS,
+    DEFAULT_FREEZE_SECONDS,
+    DEFAULT_OPTION_REVEAL_SECONDS,
+    DEFAULT_SLOWDOWN_RAMP_SECONDS,
+    slowdown_hold_count,
+)
+from sports.common.pass_pitch import lane_scoring_transformer_for_frame
+from sports.common.possession import find_control_carrier
+from sports.common.tracking import open_video
+from sports.common.video_tracking import VideoTrackingSession, build_video_tracking_session
+
+
+def run_pass_alternatives(args, session: VideoTrackingSession | None = None) -> None:
+    """Render pass-alternative freeze frames to ``args.target_video_path``."""
+    if session is None:
+        session = build_video_tracking_session(args, need_homography=True)
+    _render_pass_alternatives(args, session)
+
+
+def _annotate_live(
+    frame,
+    dets,
+    *,
+    radar_h,
+    locked_goals,
+) -> object:
+    image = frame.copy()
+    image = annotate_pass_players(image, dets, show_tracker_ids=True)
+    image = annotate_ball(image, dets)
+    carrier = find_control_carrier(dets, transformer=radar_h)
+    if carrier is not None:
+        draw_carrier_ground_ellipse(
+            image,
+            feet_xy(dets)[carrier.index],
+            transformer=radar_h,
+            color_bgr=CARRIER_SHADOW_BGR,
+            radius_m=0.5,
+            alpha=0.42,
+            filled=True,
+            thickness=1,
+        )
+    image = draw_radar_minimap(
+        image,
+        dets,
+        radar_h,
+        locked_goal_defenders=locked_goals,
+    )
+    return draw_hud_bar(image, "PASS ALTERNATIVES")
+
+
+def _render_pass_alternatives(args, session: VideoTrackingSession) -> None:
+    locks = session.team_locks()
+    locked_goals = locks.locked_goal_defenders
+    pass_by_frame = session.pass_by_frame
+    freeze_events = session.pass_alternative_events()
+    events_by_frame = {e.frame_idx: e for e in freeze_events}
+    event_frames = sorted(events_by_frame)
+    fps = float(session.fps)
+    width, height = session.width, session.height
+    ramp_frames = max(1, int(round(DEFAULT_SLOWDOWN_RAMP_SECONDS * fps)))
+    reveal_frames = max(4, int(round(DEFAULT_OPTION_REVEAL_SECONDS * fps)))
+    gap_filled = (
+        session.gap_filled_transforms_by_frame if session.kp_by_frame is not None else {}
+    )
+    minimap_transforms = session.minimap_transforms_by_frame
+    pitch_confidence = 0.9
+
+    print(f"PASS_ALTERNATIVES: {len(freeze_events)} freeze events")
+
+    cap, _, _, _ = open_video(args.source_video_path)
+    try:
+        with sv.VideoSink(args.target_video_path, sv.VideoInfo(width, height, fps)) as sink:
+            frame_idx = 0
+            while True:
+                ret, frame = cap.read()
+                if not ret:
+                    break
+                frame_idx += 1
+                if session.max_frames is not None and frame_idx > session.max_frames:
+                    break
+                dets = pass_by_frame.get(frame_idx)
+                if dets is None:
+                    continue
+
+                kps = (session.kp_by_frame or {}).get(frame_idx)
+                radar_h = minimap_transforms.get(frame_idx)
+                lane_h = lane_scoring_transformer_for_frame(
+                    gap_filled, frame_idx, kps, pitch_confidence=pitch_confidence
+                ) or radar_h
+
+                live = _annotate_live(
+                    frame, dets, radar_h=radar_h, locked_goals=locked_goals,
+                )
+                frames_until = next(
+                    (ef - frame_idx for ef in event_frames if ef >= frame_idx), None
+                )
+                hold = (
+                    slowdown_hold_count(frames_until, ramp_frames=ramp_frames)
+                    if frames_until is not None
+                    else 1
+                )
+                for _ in range(hold):
+                    sink.write_frame(live)
+
+                if frame_idx not in events_by_frame:
+                    continue
+
+                event = events_by_frame[frame_idx]
+                n_options = min(3, len(event.options))
+                phases: list[tuple[int, int]] = [(0, reveal_frames)]
+                phases.extend((i, reveal_frames) for i in range(1, n_options + 1))
+                min_freeze = sum(h for _, h in phases)
+                extra_hold = max(
+                    0, int(round(DEFAULT_FREEZE_SECONDS * fps)) - min_freeze
+                )
+                final_extra = max(
+                    4, int(round(DEFAULT_FINAL_OPTION_EXTRA_SECONDS * fps))
+                )
+                if phases:
+                    phases[-1] = (
+                        phases[-1][0],
+                        phases[-1][1] + extra_hold + final_extra,
+                    )
+                for revealed, phase_hold in phases:
+                    for step in range(phase_hold):
+                        progress = (step + 1) / max(phase_hold, 1)
+                        overlay = draw_pass_alternatives_overlay(
+                            frame,
+                            dets,
+                            event,
+                            revealed_options=revealed,
+                            reveal_progress=progress,
+                            transformer=lane_h,
+                            locked_goal_defenders=locked_goals,
+                            metric=True,
+                        )
+                        sink.write_frame(overlay)
+    finally:
+        cap.release()
+    print(f"Wrote {args.target_video_path}")

sports/annotators/passing.py

@@ -559,13 +559,88 @@ def draw_pass_network_end_card(
     return card
 
 
+RANK_COLORS_BGR = (
+    (80, 180, 255),   # gold-ish BGR
+    (200, 200, 200),  # silver
+    (180, 130, 70),   # bronze
+)
+RANK_LABELS = ("1st", "2nd", "3rd")
+
+
+def draw_pass_alternatives_overlay(
+    frame: np.ndarray,
+    dets: sv.Detections,
+    event,
+    *,
+    revealed_options: int | None = None,
+    reveal_progress: float = 1.0,
+    transformer=None,
+    locked_goal_defenders: tuple[int, int] | None = None,
+    metric: bool = True,
+) -> np.ndarray:
+    """Dimmed freeze frame with ranked pass-lane arrows (reuses shared draw helpers)."""
+    dim = (frame.astype(np.float32) * 0.32).astype(np.uint8)
+    options = list(event.options)
+    visible = options
+    if revealed_options is not None:
+        visible = options[: max(0, revealed_options)]
+
+    dim = annotate_pass_players(dim, dets, show_tracker_ids=True)
+    dim = annotate_ball(dim, dets)
+
+    feet = feet_xy(dets)
+    carrier_xy = feet[event.carrier.index]
+    cx, cy = int(carrier_xy[0]), int(carrier_xy[1])
+    draw_carrier_ground_ellipse(
+        dim,
+        carrier_xy,
+        transformer=transformer,
+        color_bgr=CARRIER_SHADOW_BGR,
+        radius_m=0.55,
+        alpha=0.55,
+        filled=True,
+        thickness=2,
+    )
+
+    if revealed_options == 0:
+        draw_score_chip(dim, "ON BALL", (cx, cy - 42), bg_bgr=ROBOFLOW_PURPLE_BGR)
+        return draw_hud_bar(dim, "PASS ALTERNATIVES")
+
+    progress = float(np.clip(reveal_progress, 0.0, 1.0))
+    for rank, option in enumerate(visible):
+        color = RANK_COLORS_BGR[min(rank, len(RANK_COLORS_BGR) - 1)]
+        recv_xy = feet[option.receiver_index]
+        rx, ry = int(recv_xy[0]), int(recv_xy[1])
+        is_new = rank == len(visible) - 1
+        alpha = ease_out_cubic(progress) if is_new else 1.0
+        draw_glow_arrow(dim, (cx, cy), (rx, ry), color, thickness=5, alpha=alpha)
+        if alpha < 0.85:
+            continue
+        midx, midy = (cx + rx) // 2, (cy + ry) // 2
+        label = RANK_LABELS[min(rank, len(RANK_LABELS) - 1)]
+        chip = f"{label}  {option.score:.2f}"
+        if metric:
+            chip += f"  {option.length:.1f} m"
+        draw_score_chip(dim, chip, (midx, midy), bg_bgr=color)
+
+    dim = draw_radar_minimap(
+        dim,
+        dets,
+        transformer,
+        locked_goal_defenders=locked_goal_defenders,
+    )
+    return draw_hud_bar(dim, "PASS ALTERNATIVES  -  top open lanes")
+
+
 # Re-export for runners that already use motion.draw_radar_minimap
 __all__ = [
     "annotate_ball",
     "annotate_pass_players",
     "draw_carrier_ground_ellipse",
     "draw_collaboration_web",
+    "draw_glow_arrow",
     "draw_hud_bar",
+    "draw_pass_alternatives_overlay",
     "draw_pass_network_end_card",
     "draw_pass_network_frame_overlays",
     "draw_radar_minimap",