---
title: Football Minimap Generator
emoji: ⚽️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: "5.26.0" # Explicitly set to local version
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:**
    ```powershell
    git clone <repository-url>
    cd Foot_calib_pos_image_processor
    ```

2.  **Create a virtual environment (recommended):**
    ```powershell
    python -m venv venv
    .\venv\Scripts\Activate.ps1
    ```

3.  **Install dependencies:**
    ```powershell
    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:**
```powershell
python main.py path/to/your/image.jpg [OPTIONS]
```

**Gradio App:**
```powershell
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:**

```powershell
# 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.