BallState & BallTrajectory

BallState, BallTrajectory, and BounceEvent represent the instantaneous 9D state of the padel ball, its simulated time-series trajectory, and detailed impact diagnostics across court surfaces.

BallState

Represents the 9D state [x, y, z, vx, vy, vz, wx, wy, wz] of the ball at a single instant.

Name
position
Type
tuple[float, float, float]
Description
3D position (x, y, z) in meters (CENTERED court frame).
Name
velocity
Type
tuple[float, float, float]
Description
3D linear velocity (vx, vy, vz) in m/s.
Name
angular_velocity
Type
tuple[float, float, float]
Description
3D angular velocity (wx, wy, wz) in rad/s.
Name
speed
Type
float
Description
Scalar linear speed |v| in m/s.
Name
speed_kmh
Type
float
Description
Scalar linear speed in km/h.
Name
spin_rpm
Type
float
Description
Total spin rate in revolutions per minute (RPM).
Name
vector_9d
Type
np.ndarray
Description
NumPy float64 array of shape (9,) containing [x, y, z, vx, vy, vz, wx, wy, wz].

classmethodBallState.from_shot()

Construct a Shot with RPM Spin

Creates a BallState by decomposing intuitive topspin_rpm and sidespin_rpm values into the 3D angular velocity vector (wx, wy, wz) relative to the horizontal direction of travel.

Arguments

Name
position
Type
tuple[float, float, float] | Sequence[float]
Description
Initial 3D position (x, y, z) in meters.
Name
velocity
Type
tuple[float, float, float] | Sequence[float]
Description
Initial 3D velocity (vx, vy, vz) in m/s.
Name
topspin_rpm
Type
float
Description
Topspin (> 0) or backspin (< 0) in revolutions per minute.
Name
sidespin_rpm
Type
float
Description
Sidespin in RPM around the vertical +Z axis.

Create Shot

classmethod

from_shot

from padelkit import BallState

state = BallState.from_shot(
    position=(0.0, -6.5, 2.4),
    velocity=(0.0, 25.0, -3.5),
    topspin_rpm=2400.0,
    sidespin_rpm=-300.0,
)

print(f"Speed: {state.speed_kmh:.1f} km/h | Spin: {state.spin_rpm:.0f} RPM")

Output

Speed: 90.9 km/h | Spin: 2419 RPM

BallTrajectory

Returned by BallPhysicsEngine.simulate(). Stores the full 9D state history and provides interpolation, DataFrame/CSV export, and 3D visualizer conversion.

Name
times
Type
np.ndarray
Description
1D array of shape (N,) with timestamps in seconds.
Name
states
Type
np.ndarray
Description
2D array of shape (N, 9) containing [x, y, z, vx, vy, vz, wx, wy, wz].
Name
bounces
Type
tuple[BounceEvent, ...]
Description
Chronological tuple of BounceEvent records.
Name
positions / velocities / angular_velocities
Type
np.ndarray
Description
2D views of shape (N, 3) for 3D positions (m), velocities (m/s), and spins (rad/s).
Name
speeds / spin_rpms
Type
np.ndarray
Description
1D arrays of shape (N,) with instantaneous speed (m/s) and spin (RPM).
Name
state_at(t)
Type
BallState
Description
Linearly interpolates the 9D BallState at any timestamp t (in seconds).
Name
to_dataframe() / to_csv(path)
Type
pd.DataFrame / Path
Description
Exports the trajectory (including speed_mps, spin_rpm, and bounce_surface) to a Pandas DataFrame or CSV file.
Name
to_timeline(fps=60.0)
Type
MatchTimeline
Description
Resamples the trajectory at fps into a MatchTimeline ready for PadelVisualizer.

BounceEvent & Enums

Each impact during a simulation produces an immutable BounceEvent with full pre- and post-impact kinematics:

Name
time
Type
float
Description
Timestamp of impact in seconds.
Name
position
Type
tuple[float, float, float]
Description
3D contact position (x, y, z) in meters.
Name
surface
Type
SurfaceType
Description
Impacted court surface: SurfaceType.FLOOR, BACK_GLASS, SIDE_GLASS, BACK_WALL, SIDE_WALL, BACK_FENCE, SIDE_FENCE, or NET.
Name
regime
Type
ContactRegime
Description
Tangential contact regime: ContactRegime.SLIDING, ContactRegime.ROLLING, or ContactRegime.DAMPED.
Name
pre_velocity / post_velocity
Type
tuple[float, float, float]
Description
Linear velocity (vx, vy, vz) in m/s immediately before and after impact.
Name
pre_spin / post_spin
Type
tuple[float, float, float]
Description
Angular velocity (wx, wy, wz) in rad/s immediately before and after impact.