README.md

metadata

title: Football Minimap Generator
emoji: ⚽️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.26.0
app_file: app.py
pinned: false

Foot Calib Pos Image Processor

This project uses the TvCalib library to calculate the homography matrix for a football pitch image. This matrix allows mapping image points onto a standard 2D representation of the pitch (minimap).

The project also includes:

• Ball detection using a YOLO model (yolo_football.pt).
• Pose estimation (ViTPose) to detect players and calculate the average color of their torso.

The main result is a minimap where each player is represented by their colored skeleton, drawn at a dynamically reduced scale around their projected position on the pitch, and the ball is represented by a white circle. The position is determined by projecting a reference point (feet/bottom of bbox for players, bottom center for ball) using the homography. The skeleton is then drawn using its relative coordinates (original image), scaled, and translated. The scale used depends on the player's vertical position (Y) on the minimap (higher on the minimap = smaller) and a base factor adjustable via the --target_avg_scale option.

It is also possible to visualize a minimap with the projection of the original image for comparison.

Features

• Homography calculation from a single image via TvCalib.
• Ball detection using YOLO (yolo_football.pt).
• Person detection (RT-DETR) and pose estimation (ViTPose).
• Calculation of the filtered average torso color for each player.
• Projection of each player's and the ball's reference point onto the minimap.
• Generation of a minimap with the original skeletons (colored, dynamically scaled based on projected Y position, and offset) drawn around the projected player points, and a white marker for the projected ball position.
• (Optional) Generation of a minimap with the projected original image.
• Possibility to save the calculated homography matrix.

Project Structure

.
├── .git/               # Git metadata
├── .venv/              # Python virtual environment (recommended)
├── common/             # Common Python modules (potentially)
├── data/               # Data (input images, etc.)
├── models/
│   ├── detection/
│   │   └── yolo_football.pt # YOLO model for ball detection (TO DOWNLOAD)
│   └── segmentation/
│       └── train_59.pt # Pre-trained segmentation model (TO DOWNLOAD)
├── tvcalib/            # Source code of the TvCalib library (or a fork/adaptation)
│   └── infer/
│       └── module.py   # Main module for TvCalib inference
├── .gitignore          # Files ignored by Git
├── app.py              # Gradio web application entry point
├── main.py             # Main script entry point (command line)
├── requirements.txt    # Python dependencies file
├── visualizer.py       # Module for generating visualization minimaps
├── pose_estimator.py   # Module for pose estimation and player data extraction
└── README.md           # This file

Installation

1. Clone the repository:

   git clone <repository-url>
   cd Foot_calib_pos_image_processor
   

2. Create a virtual environment (recommended):

   python -m venv venv
   .\venv\Scripts\Activate.ps1
   

3. Install dependencies:

   pip install -r requirements.txt
   

   (Make sure to install PyTorch with appropriate CUDA support if needed, see comment in requirements.txt)

4. Download the required models:

   • Place the segmentation model train_59.pt in models/segmentation/.
   • Place the YOLO ball detection model yolo_football.pt in models/detection/. (You need to obtain this model separately).

5. (Automatic) Download other detection/pose models: The RT-DETR and ViTPose models will be downloaded automatically by the transformers library on first use.

Usage

Run the main.py script (command line) or app.py (Gradio interface) providing the path to the image:

Command Line:

python main.py path/to/your/image.jpg [OPTIONS]

Gradio App:

python app.py 
# Then open the provided local URL in your browser.

Options (for main.py):

• image_path: Path to the input image (required).
• --output_homography PATH.npy: Saves the calculated homography matrix.
• --optim_steps NUMBER: Number of optimization steps for calibration (default: 500).
• --target_avg_scale FLOAT: Target average scale factor for drawing skeletons (default: 1.0). The script attempts to adjust the internal base scale so that the resulting average scale (after inverse dynamic modulation) is close to this value.

Example:

# Simple usage (target average size 1.0)
python main.py data/img3.png

# Aim for larger skeletons on average (target 1.5)
python main.py data/img2.png --target_avg_scale 1.5 

The script (main.py) or Gradio app (app.py) will display:

• Time taken for different steps (console output for main.py).
• Calculated homography matrix (console output for main.py).
• Information about detected ball and players (console output for main.py).
• Estimated internal base scale for skeletons (console output for main.py).
• Requested TARGET average scale (console output for main.py).
• ACTUALLY applied FINAL average scale (console output for main.py).
• Window/Image Output 1: Minimap with Original Projection.
• Window/Image Output 2: Minimap with Offset Skeletons (dynamically scaled inversely, targeting the average scale) and Ball Marker.
• (main.py only) Press any key to close the display windows.

Key Dependencies

• PyTorch, OpenCV, NumPy, PyTorch Lightning
• SoccerNet, Kornia, Hugging Face Transformers, Pillow
• ultralytics (for YOLO ball detection)
• gradio (for the web interface app.py)

---

Note: Ensure the tvcalib directory is correctly structured or added to your PYTHONPATH if you encounter import errors related to it.