Metadata-Version: 2.5
Name: padelkit
Version: 0.1.0
Summary: Open source toolkit for padel analytics and computer vision
Project-URL: Homepage, https://padelkit.dev
Project-URL: Documentation, https://padelkit.dev
Project-URL: Source, https://github.com/padelkit/padelkit
Project-URL: Issues, https://github.com/padelkit/padelkit/issues
Author: Fidel Echevarria
License: Apache-2.0
License-File: LICENSE
Keywords: computer vision,court geometry,padel,scoring,sports analytics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Provides-Extra: blender
Requires-Dist: bpy>=4.0.0; (python_version == '3.11' or python_version == '3.13') and extra == 'blender'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: hatchling; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# PadelKit 🎾

**An End-to-End 3D Computer Vision, Camera Calibration, Match Scoring & Synthetic Data Engine for Padel.**

![PyPI - Version](https://img.shields.io/pypi/v/padelkit)
![License](https://img.shields.io/github/license/padelkit/padelkit)

## Installation

```bash
pip install padelkit
```

For optional headless Blender synthetic rendering:
```bash
pip install "padelkit[blender]"
```

## Quickstart

```python
from padelkit import (
    BallPhysicsEngine,
    BallState,
    Camera,
    Court,
    Match,
    MatchTimeline,
    PadelVisualizer,
    TeamId,
)

# 1. 3D Court Geometry & 17 Official Landmarks
court = Court.fip_standard()
landmarks_3d = court.landmarks_3d()

# 2. Projective Camera & 3D-to-2D / 2D-to-3D Transformations
camera = Camera.broadcast_near(court=court)
landmarks_2d = camera.project_court_landmarks(court=court)
floor_xyz = camera.project_pixel_to_plane(landmarks_2d["center"], plane_z=0.0)

# 3. 9D Ball Aerodynamics (Drag + Spindt Magnus Lift) & Contact Physics
engine = BallPhysicsEngine(court=court)
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)

# 4. Universal Match Format (.parquet), 3D Visualization & Synthetic CV Passes (Three.js)
timeline = MatchTimeline.demo_rally(court=court, fps=60.0, bake_skeleton=True)
timeline.to_parquet("demo_rally.parquet")

viz = PadelVisualizer.from_parquet("demo_rally.parquet")
viz.export_html("padel_studio.html")

# 5. Event-Sourced Match Scoring Engine
match = Match(best_of_sets=3, advantage_method="gold_point")
match.history.add_point(TeamId.A)
print(match.history.get_current_score())
```

## Features

- **Court Geometry (`padelkit.court`):** Official FIP dimensions, enclosure variants, and 17-point 2D/3D landmark coordinate systems (`CENTERED` and `CORNER_BASED`).
- **Camera & 3D Projection (`padelkit.camera`):** Intrinsics (`FOV` & physical sensor models), 6-DoF extrinsics (`look_at`, `euler`, OpenCV/OpenGL matrices), lens distortion (`Brown-Conrady` & `Fisheye`), vectorized 3D-to-2D projection, and 2D-to-3D ray/plane intersection.
- **9D Ball Physics & Dynamics (`padelkit.physics`):** RK4 aerodynamic integrator with felt-adjusted drag, Spindt Magnus lift, atmospheric density modeling (`from_atmosphere`), analytical Coulomb Sliding-to-Rolling rebound physics across turf/glass/fence/net, and vectorized `simulate_batch()`.
- **3D Visualizer & Replay Studio (`padelkit.viz`):** Interactive Three.js 3D court studio supporting Universal Match Format (`.parquet`), CSV match replay, 17-joint 3D skeletal baking (`bake_skeletal_poses()`), Mixamo `.glb` animation library playback, real-time live streaming (`serve()` + `push_frame()`), standalone HTML/Jupyter export, and CV render passes (`RGB`, `Semantic Segmentation`, `Depth`, and `17 Landmarks`).
- **Scoring System (`padelkit.scoring`):** Full event-sourced match, set, game, tie-break, and serving rotation engine.

## Contributing

We welcome contributions to both the Python library and the official documentation website!

- **Code & Features:** Target your Pull Requests to the **`develop`** branch. Read our [**Contributing Guide (`CONTRIBUTING.md`)**](./CONTRIBUTING.md) for local setup with `uv`, testing (`pytest`), linting (`ruff`), and versioning rules.
- **Website Documentation (`padelkit.dev`):** All documentation pages (`.mdx`), navigation menus (`docs.config.json`), custom icons, and SVG schematics live directly inside [`docs/`](./docs/). Merging changes into `develop` automatically deploys the preview documentation site, and merging into `main` updates [https://padelkit.dev](https://padelkit.dev). See [`docs/README.md`](./docs/README.md) for details.

## License

Apache 2.0 License.

## Links

- **Documentation:** [https://padelkit.dev](https://padelkit.dev) (See [Docs Guide](./docs/README.md) for authoring instructions)
- **Contributing Guide:** [CONTRIBUTING.md](./CONTRIBUTING.md)
- **Source Code:** [GitHub](https://github.com/padelkit/padelkit)
