Quickstart

This guide will get you up and running with PadelKit. You'll learn how to install the package and start using the Court Geometry, Camera Projection, 9D Ball Physics, 3D Visualization, and Scoring modules.

Installation

To install PadelKit, simply use pip or uv:

pip install padelkit

Basic Usage

Once installed, you can easily import the necessary classes to map a court, project 3D points to a camera, simulate 9D ball trajectories with spin, visualize rallies in 3D, or track a match score.

Working with Court Geometry

You can instantiate a standard FIP padel court and query for 2D or 3D landmark coordinates:

from padelkit import Court

# Instantiate a standard 20x10 court
court = Court.fip_standard()

# Get the coordinates of the center of the net
net_center = court.point("center")
print(f"Net center: {net_center}")
# Output: Net center: (0.0, 0.0)

Simulating 9D Ball Aerodynamics & Bounces

You can simulate realistic 3D trajectories with topspin/backspin, air drag, Spindt Magnus lift, and multi-surface rebounds:

from padelkit import BallPhysicsEngine, BallState

engine = BallPhysicsEngine()
shot = BallState.from_shot(
    position=(-2.5, -2.0, 2.3),
    velocity=(3.5, 16.0, -2.5),
    topspin_rpm=-1800.0,
)
trajectory = engine.simulate(shot, duration=2.5)
print(f"Bounces: {[b.surface.value for b in trajectory.bounces]}")

Tracking Match Score

You can use the scoring module to track a match's state using the event-sourcing architecture:

from padelkit import Match, TeamId

# Initialize a new match wrapper
match = Match()

# Team A wins the first point
match.history.add_point(TeamId.A)

# You can easily undo a point in case of a mistake
match.history.undo_point()

# Print the cleanly formatted current state
print(match.history.get_current_score())

Next steps

Now that you have a basic understanding of PadelKit, you can dive deeper into the specific API documentation for each module.