padex.events

Layer 2: Shot detection, bounce detection, and shot type classification.

padex.events.shot.ShotDetector

Main shot detection facade.

Combines contact detection with shot type classification and trajectory (bounce) assembly.

detect_shots(player_frames, ball_frames, bounces=None, set_num=1, game_num=1, point_num=1)

Identify shots and build trajectory for each.

Parameters:

Name	Type	Description	Default
player_frames	list[PlayerFrame]	All PlayerFrames for the sequence.	required
ball_frames	list[BallFrame]	All BallFrames from BallDetector.	required
bounces	list[Bounce] | None	All Bounce events from BounceDetector.	None
set_num, game_num, point_num		For hierarchical ID.	required

Returns:

Type	Description
list[Shot]	list[Shot] in chronological order.

padex.events.shot.PoseBasedShotTypeClassifier

Bases: ShotTypeClassifier

Classifies shot types using pre-contact ball state + pose + trajectory.

Decision tree (priority order): 1. Pre-contact ball state: no ground bounce → net play (volley family) 2. Pre-contact ball state: wall bounce → defensive (wall_return family) 3. Remaining: ground bounce only → baseline play (groundstroke family)

Within each category, pose (wrist height) and post-contact trajectory refine the specific shot type.

padex.events.bounce.BounceDetector

Main bounce detection facade.

Combines velocity-based detection with geometry-based surface classification.

detect_bounces(ball_frames, court_calibration=None, precomputed_indices=None)

Identify and classify all bounce events in a ball trajectory.

classify_surface(bounce_position)

Classify surface for a single position (convenience method).