Football 3D Engine

Synthetic 3D football action-spotting clip generator using Google Research Football.

Produces a 10-second shot-on-goal clip (250 frames @ 25fps) rendered in 3D with a matching ground-truth JSON annotation tracking all 22 players and the ball.

Setup

# System deps (macOS)
brew install cmake sdl2 sdl2_image sdl2_ttf sdl2_gfx boost boost-python3

# Python deps
pip install gfootball opencv-python numpy

Note: gfootball may require building from source with CMake patches on modern toolchains. See google-research/football for details.

Usage

1. Copy shot_on_goal_5v.py into your gfootball scenarios directory:

   cp shot_on_goal_5v.py $(python -c "import gfootball; import os; print(os.path.join(os.path.dirname(gfootball.__file__), 'scenarios'))")/

2. Run the generator:

   python generate_clip_3d.py

Output

• output/clip_001_3d.mp4 — 1280×720 3D-rendered video
• output/clip_001_3d_gt.json — ground-truth annotation with:
  • Shot action label at frame 125 (5.0s)
  • Per-frame 3D trajectories for all 22 players (11v11, 4-4-2)
  • Per-frame ball trajectory with height

Stack

• gfootball — 3D rendering engine + physics
• opencv-python — video encoding (mp4v)
• numpy — coordinate transforms