⚽ Football Analytics

🛠️ Build with

Summary

This repository contains the implementation of a data science project focused on real-time match analysis and metrics creation for football (soccer) matches. The project utilizes computer vision techniques to detect and track players, analyze their movements, and generate various metrics such as speed, distance covered, and possession time. The architecture is designed as a microservice-based system, allowing for modular development and deployment.

👥 Contributions

Ole Schildt

Philipp Meyer

Florian Wölfel

Laelia Chi

Lukas Ihrig

Yaren Erol

🚀 Features

• 🤖 Training of a custom object detection model for player detection
• 📹 Real-Time Video Streaming – Capture and stream live football matches
• 🎥 Live Match Analysis – Real-time insights opf small-sided football games
• 🧠 AI-Based Player Detection – Object detection and tracking using computer vision
• 👁️‍🗨️ 2D Bird’s Eye View – Visual representation of player positions and movements
• 📈 Player Metrics – Speed, distance covered, possession time, and more
• 📊 Data Visualizations – Heatmaps, possession, distance covered, passes
• 🖥️ Interactive Frontend – User interface for viewing metrics and controlling the analysis

🎬 Little Demo

Demo Stream

Inference

Frontend

Structure

The whole sturcture is based on a micro service architecture. Each component is a separate micro service which can be run independently. The whole architecture is based on Docker and Docker Compose to easily run and manage the services. For more information look into the docs folder.

Here is a brief overview of the final structure:

.
├── .github/
│   └── ... for workflows and pipelines
├── .vscode/
│   └── ... to unify our settings (vim is better)
├── docs/
│   └── docs.md
├── demo_stream/
│   └── ... demo stream to test the final architecture
├── bff_api/
│   ├── ... own micro service which exposes the metrics
│   ├── ... here also as example a structure for a ms
│   ├── src/
│   │   └── logic.py
│   ├── test/
│   │   └── test.py
│   ├── config.yaml
│   ├── Dockerfile
│   ├── main.py
│   └── pyproject.toml
├── frontend/
│   └── ... based on the bff_api data
├── inference/
│   └── ... mirco service live inference
├── metrics/
│   └── ... scheduled etl job as micro service
├── model_training/
│   └── ... here we independently train our model
├── db_data/
│   └── ... dir to persist the postgres data (in .gitignore)
├── docker-compose.yaml
├── .env
├── LICENSE
├── README.md
└── ruff.toml

📦 Installation & Build

Environment

Here are the vars you need to define:

NGINX_HOST=nginx
RTMP_PORT=1935
HTTP_PORT=5555
DATABASE_HOST=db
DATABASE_PORT=5432
DATABASE_NAME=mydatabase
DATABASE_USER=myuser
DATABASE_PSWD=mypwd
USER=test
PSWD=test
RTMP_URL=rtmp://nginx/hls
STREAM_NAME=demo
VIDEO_FILE_PATH=/app/demo.mp4
STREAM_URL=http://nginx:5555/hls/demo.m3u8
ROBOFLOW_API_KEY=your-roboflow-api-key
GOOGLE_CLIENT_ID=xxx
GOOGLE_CLIENT_SECRET=yyy
USER_MAIL=mail_which_you_want_to_use_for_sso( no db or hashmap to keep it simple )

You also need to add your .mp4 file whoch you want to stream to folloing path: demo_stream/trigger_api/demo.mp4

🔐 How to Create a Google OAuth Client for SSO

To enable Google Sign-In for the admin panel, follow these steps:

1. Go to Google Cloud Console

👉 https://console.cloud.google.com/

2. Create a new project

• Click the project dropdown at the top and select "New Project"
• Give your project a name (e.g. Football Analytics SSO)
• Click Create

3. Enable OAuth 2.0 APIs

• Navigate to APIs & Services > Library
• Search for "Google Identity Services"
• Click Enable

4. Configure the OAuth consent screen

• Go to APIs & Services > OAuth consent screen
• Select External user type
• Fill in:
  • App name
  • Support email
  • Developer contact info
• Scopes: Add the default scopes openid, email, profile

5. Create OAuth credentials

• Go to APIs & Services > Credentials
• Click Create Credentials > OAuth client ID
• Choose Web application
• Under Authorized redirect URIs, add: http://localhost:8501

6. Copy your credentials

• After creation, copy your Client ID and Client Secret
• Add them to your .env file:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

### Docker Compose - Final Architecture

Everything is based on the `docker-compose.yaml`. To run and build it use following:

```bash
docker-compose up --build -d

# to close
docker-compose down

To access the services look into the compose file to find the corresponding ports.

Single Micro Service

The micro services are all independent in their folder and cen be executed there.

cd micro_service
uv run main.py

Single Docker Build

To finally test and run only one single artifact

cd micro_service
docke build -t my_container .
docker run -p 8000:8000 my_container

▶️ Usage

Stream

After starting the docker compose, you can start the stream witht the API under localhost:8000 The stream is available under http://localhost:5555. It simulates a real time stream which can then be procssed by our micro services.

Trigger API

The trigger API is available under http://localhost:8000. It allows you to start the stream processing by sending a POST request. The stream will be processed and the metrics will be generated.

BFF API

The BFF API is available under http://localhost:8001. It provides endpoints to access the metrics and data processed from the stream.

Frontend

The frontend is available under http://localhost:8501. It provides a user interface to visualize the metrics and data processed from the stream.

✅ Local Testing, Linting & Formating

HELPWe use uv to manage testing, linting, and formatting.

# Run tests
uv run pytest

# Lint code
uvx ruff check .

# Format code
uvx ruff format .

🧾 License

This project is licensed under the MIT License. See the LICENSE file for details.