PadelVisualizer

PadelVisualizer is PadelKit's interactive Three.js 3D court studio, multi-camera inspector, and synthetic computer vision pass renderer (RGB, Semantic Segmentation, Depth Map, and 17 Court Landmarks). It renders MatchTimeline recordings from .parquet or .csv files, streams real-time FrameState updates over Server-Sent Events, and supports both Mixamo .glb skeletal clips and baked 17-joint H36M 3D skeletons.

Constructor & Attributes

  • Name
    court
    Type
    Court | None
    Description

    Court instance defining dimensions, enclosure variant, turf color, and 17 3D landmarks. Defaults to timeline.court or Court.fip_standard().

  • Name
    cameras
    Type
    list[Camera] | None
    Description

    List of Camera presets available in the studio's camera selector dropdown. Defaults to 5 standard presets (broadcast_near, broadcast_far, overhead_zenith, corner_near_left, side_net_right).

  • Name
    timeline
    Type
    MatchTimeline | None
    Description

    MatchTimeline loaded into the scrubber. Defaults to MatchTimeline.demo_rally().

  • Name
    animation_library_dir
    Type
    str | Path | None
    Description

    Optional directory containing manifest.json and .glb stroke animations exported by padelkit-animator.

classmethodfrom_parquet / from_csv

Create from Parquet or CSV

Constructs a PadelVisualizer directly from a Universal Match Format (.parquet) or .csv file.

When loading a .parquet file via PadelVisualizer.from_parquet(), the Court configuration (turf color, dimensions, indoor/outdoor setting) is automatically restored from the Parquet padelkit_metadata header, and any baked 17-joint 3D skeletons (keypoints_3d) are rendered directly in Three.js without requiring external .glb files.

Factory Classmethods

  • Name
    from_parquet(parquet_path, court=None, cameras=None, animation_library_dir=None)
    Type
    PadelVisualizer
    Description

    Loads a .parquet match recording and initializes the 3D visualizer with its embedded court and skeletal/trajectory data.

  • Name
    from_csv(csv_path, court=None, cameras=None, animation_library_dir=None)
    Type
    PadelVisualizer
    Description

    Loads a .csv timeline recording into a new PadelVisualizer.

Load Parquet in 3D Studio

classmethod
from_parquet
from padelkit import MatchTimeline, PadelVisualizer

# 1. Generate and save a match with baked 17-joint 3D skeletons
timeline = MatchTimeline.demo_rally(bake_skeleton=True)
timeline.to_parquet("match_baked.parquet")

# 2. Load directly from .parquet and export standalone HTML
viz = PadelVisualizer.from_parquet("match_baked.parquet")
viz.export_html("match_studio.html")
methodsexport_html / serve / push_frame

Export HTML, Serve & Stream

  • Name
    export_html(output_path)
    Type
    Path
    Description

    Writes a self-contained .html file embedding the court geometry, cameras, timeline frames, and (if configured) base64-encoded .glb animations.

  • Name
    to_html(live_stream_url=None)
    Type
    str
    Description

    Returns the complete HTML string for the 3D studio.

  • Name
    serve(host='127.0.0.1', port=8765, open_browser=True, background=False)
    Type
    ThreadingHTTPServer | None
    Description

    Starts a local HTTP + Server-Sent Events (/events) server. When background=True, runs on a daemon thread so Python code can push frames via push_frame().

  • Name
    push_frame(frame)
    Type
    None
    Description

    Appends a FrameState to self.timeline and broadcasts it immediately to all connected browser clients.

  • Name
    stop()
    Type
    None
    Description

    Stops the background HTTP server started by serve(background=True).

  • Name
    load_parquet(parquet_path) / load_csv(csv_path)
    Type
    PadelVisualizer
    Description

    Replaces the active timeline in-place from a .parquet or .csv file and returns self.

  • Name
    load_animation_library(animation_library_dir)
    Type
    PadelVisualizer
    Description

    Attaches a padelkit-animator .glb library directory and returns self.

  • Name
    add_camera(camera)
    Type
    PadelVisualizer
    Description

    Registers an additional Camera viewpoint in the 3D scene and returns self.

Interactive Server & Jupyter

method
serve
from padelkit import Camera, PadelVisualizer

viz = PadelVisualizer.from_parquet("match_baked.parquet")
viz.add_camera(Camera.overhead_zenith())

# In a Jupyter Notebook cell, returning `viz` renders an iframe automatically:
# viz

# Or launch the local interactive server:
# viz.serve(port=8765, open_browser=True)

Was this page helpful?