Football Panoptic Segmentation (From Scratch)

End-to-end PyTorch project for training a panoptic segmentation model on the Kaggle Soccer Panoptic Segmentation dataset.

Project Structure

football-panoptic-from-scratch/
├── data/
│   └── soccer_panoptic/              # Put Kaggle dataset here
├── src/
│   ├── datasets/
│   │   └── soccer_panoptic.py        # Dataset loader
│   ├── models/
│   │   └── backbone.py               # ResNet-FPN + panoptic heads
│   ├── utils/
│   │   └── transforms.py             # Augmentations & mask decoding
│   └── train.py                      # Training entry point
├── configs/
│   └── default.yaml                  # Hyperparameters
├── notebooks/
│   └── data_exploration.ipynb        # Dataset exploration
├── requirements.txt
└── README.md

Setup

cd football-panoptic-from-scratch
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Dataset

1. Download the dataset from Kaggle.
2. Extract it into data/soccer_panoptic/.

Expected layout:

data/soccer_panoptic/
├── images/                  # RGB frames
├── panoptic/                # RGB-encoded panoptic masks
└── annotations/
    └── panoptic_train.json  # optional COCO-style metadata

If the extracted archive uses different folder names, update configs/default.yaml accordingly.

Classes

ID	Class	Type
0	background	stuff
1	field	stuff
2	player	thing
3	goalkeeper	thing
4	referee	thing
5	ball	thing

Training

python -m src.train --config configs/default.yaml

Checkpoints are saved to checkpoints/ and TensorBoard logs to runs/.

tensorboard --logdir runs

Model

• Backbone: ResNet-50 (ImageNet pretrained)
• Neck: Feature Pyramid Network (FPN)
• Heads: Semantic segmentation (per-pixel class) + instance segmentation (per-pixel instance ID for thing classes)
• Loss: Cross-entropy (semantic) + L1 (instance, masked to thing classes)

Exploration

Open notebooks/data_exploration.ipynb to inspect sample images, decode panoptic masks, and verify class distributions before training.