drs_modules/lbw_decision.py

"""LBW decision logic for the cricket DRS demo.

This module encapsulates the high‑level logic used to decide whether a
batsman is out leg before wicket (LBW) based on the ball's trajectory.
In professional systems the decision depends on many factors: where
the ball pitched, the line it travelled relative to the stumps, the
height of impact on the pad/glove, and whether the batsman offered a
shot.  To keep this example straightforward we apply a very simple
rule:

  * If the predicted trajectory intersects the stumps, the batsman is
    declared **OUT**.
  * Otherwise the batsman is **NOT OUT**.

We also return the index of the frame deemed to be the impact frame.
Here we take the impact frame to be the last frame where the ball was
detected.  In a more complete system one would detect the moment of
contact with the pad or glove and use that as the impact frame.
"""

from __future__ import annotations

from typing import List, Tuple


def make_lbw_decision(
    centers: List[Tuple[int, int]],
    trajectory_model: dict,
    will_hit_stumps: bool,
) -> Tuple[str, int]:
    """Return a simple LBW decision based on trajectory intersection.

    Parameters
    ----------
    centers: list of tuple(int, int)
        Sequence of detected ball centres.
    trajectory_model: dict
        The polynomial model fitted to the ball path (unused directly
        here but included for extensibility).
    will_hit_stumps: bool
        Prediction that the ball's path intersects the stumps.

    Returns
    -------
    Tuple[str, int]
        The decision text (``"OUT"`` or ``"NOT OUT"``) and the index
        of the impact frame.  The impact frame is taken to be the
        index of the last detection.
    """
    impact_frame_idx = len(centers) - 1 if centers else -1
    decision = "OUT" if will_hit_stumps else "NOT OUT"
    return decision, impact_frame_idx