beketov027/soccer_depth_recognition

Depth Recognition

Author: goldenboy

Monocular depth estimation on football broadcast screenshots using Depth Anything V2 (DAv2) via Hugging Face Transformers.

Features

• Loads DAv2 models from a local models/ directory (no Hugging Face cache at inference time)
• Supports three model sizes: small, base, large
• Downloads football broadcast video clips and extracts screenshots automatically
• Runs depth inference on all images in images/ and saves results to output/

Project Structure

depth_recognition/
├── main.py
├── requirements.txt
├── README.md
├── models/
│   ├── Depth-Anything-V2-Small-hf/
│   ├── Depth-Anything-V2-Base-hf/
│   └── Depth-Anything-V2-Large-hf/
├── videos/
│   ├── broadcast_corner_kick.mp4
│   └── broadcast_goal.mp4
├── images/
│   ├── broadcast_corner_kick_0060.jpg
│   ├── broadcast_corner_kick_0150.jpg
│   └── ...
└── output/
    ├── broadcast_corner_kick_0060_small_depth.png
    └── ...

Setup

1. Create a virtual environment (recommended):

python -m venv .venv
.venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Download a DAv2 model into the local models/ folder:

python main.py --download-model small

Optional larger models (better quality, slower, more disk space):

python main.py --download-model base
python main.py --download-model large

Model size	Params	Local folder
small	~25M	models/Depth-Anything-V2-Small-hf/
base	~98M	models/Depth-Anything-V2-Base-hf/
large	~335M	models/Depth-Anything-V2-Large-hf/

Usage

Full pipeline (download videos, extract screenshots, run inference)

python main.py

Choose model size

python main.py --model-size small
python main.py --model-size base
python main.py --model-size large

Extract screenshots only

python main.py --extract-screenshots

Re-extract even if screenshots already exist:

python main.py --extract-screenshots --force-extract

Run on a single image

python main.py --image images/broadcast_corner_kick_0060.jpg --model-size small

Download broadcast videos only

python main.py --download-videos

Input Images

Screenshots are extracted from professional football broadcast clips in the infactory-ai/soccer-events dataset:

• Corner kick clip → 4 frames
• Goal clip → 3 frames

You can also add your own .jpg / .png images to images/ and run inference on them.

Output

Depth maps are saved as grayscale PNG files in output/:

{image_name}_{model_size}_depth.png

Example: broadcast_corner_kick_0060_small_depth.png

Model Sources

• Depth-Anything-V2-Small-hf
• Depth-Anything-V2-Base-hf
• Depth-Anything-V2-Large-hf

Notes

• GPU is used automatically when available; CPU inference also works.
• Base and Large models are under CC-BY-NC-4.0. Small is Apache-2.0.
• First model download requires an internet connection. Inference uses only local files.

Author

goldenboy