3D geometry, 9D physics, and visualization for padel analytics
An open-source Python library for official FIP court coordinates, camera calibration & projection, 9D ball aerodynamics with analytical rebounds, 3D skeletal replays, and event-sourced match scoring.
Modular Architecture
Five core modules built for padel computing
Every subpackage shares the same physical units, centered 3D court convention, and lightweight NumPy / PyArrow data contracts.
Court Geometry & 17 Landmarks
Official FIP 20m × 10m court dimensions, centered or corner-based coordinates, glass/wall/mesh enclosure variants, and 17 standardized 2D/3D keypoints.
9D Aerodynamics & Rebound Physics
RK4 integration of gravity, quadratic drag with felt fuzz, non-linear Spindt Magnus lift, and analytical Coulomb sliding/rolling rebounds across turf, glass, wall, fence, and net.
Camera & 3D Projection
Intrinsics, Brown-Conrady & Fisheye distortion, 6-DoF extrinsics, landmark calibration, homography, and raycasting.
3D Studio & .parquet Format
Self-contained Three.js replay studio, real-time SSE streaming, RGB / Depth / Segmentation passes, and 60 FPS 17-joint H36M skeletal poses stored in Apache Parquet.
Event-Sourced Scoring
Immutable point history with instant undo/replay, golden point & advantage rules, tie-breaks, super tie-breaks, and automatic server rotation.
Developer Experience
Clean Python APIs from simulation to 3D replay
Built on NumPy, Pandas, and PyArrow with typed dataclasses and presets for standard FIP courts, weather conditions, broadcast cameras, and ball wear.
- Pure NumPy vectorization.
- Run thousands of 9D RK4 ball trajectories in parallel via simulate_batch() with zero heavy ML runtime dependencies.
- Projective 2D/3D geometry.
- Calibrate broadcast or court-side cameras from 2D landmarks, undo lens distortion, and project 3D trajectories onto frames.
- Single-file .parquet contract.
- Store court specs, match metadata, 60 FPS 9D ball state, and 17-joint H36M 3D skeletal poses in one portable Apache Parquet file.
from padelkit import BallPhysicsEngine, BallState, EnvironmentConditionsenv = EnvironmentConditions.from_atmosphere(temperature_c=24.0, altitude_m=650.0)engine = BallPhysicsEngine(environment=env)# Launch a high-spin bandeja with topspin & sidespinshot = BallState.from_shot( position=(1.8, -2.2, 2.35), velocity=(-2.4, 16.5, -1.8), topspin_rpm=-2100.0, sidespin_rpm=-450.0,)traj = engine.simulate(shot, duration_s=2.4)for bounce in traj.bounces: print(f"{bounce.timestamp:.2f}s -> {bounce.surface.value} ({bounce.regime.value})")Roadmap
Built for analytics, tracking, and synthetic data
Version 0.1.0 establishes the core physics, geometry, camera, scoring, and 3D visualization foundation. Here is what comes next.
- Physics-Informed 3D Tracking
- Vectorized NumPy particle filtering and Rauch-Tung-Striebel smoothing over BallPhysicsEngine.simulate_batch() and Camera.project_points() for 2D-to-3D trajectory reconstruction.
- Headless Blender Synthetic Data
- Photorealistic bpy renderer consuming MatchTimeline and Camera presets to export RGB frames, depth maps, segmentation masks, and 2D/3D ground-truth annotations.
- Batch Match & Rally Simulation
- High-throughput rally and match generator combining 9D ball aerodynamics, tactical shot selection, and MatchScoreHistory to synthesize large-scale tabular and trajectory datasets.
- Optional Vision & Audio Adapters
- Lightweight ONNX and PyTorch inference wrappers for ball tracking, 2D/3D player pose estimation, and acoustic shot-impact detection feeding directly into MatchTimeline.
Start building with PadelKit today
Install the core Python package in seconds, explore the API reference, or inspect the source code on GitHub under the Apache 2.0 license.