ureca07/lol_viewport

---
license: other
language:
- en
task_categories:
- object-detection
- image-segmentation
pretty_name: LoL Viewport Prediction
size_categories:
- 100K<n<1M
tags:
- esports
- league-of-legends
- viewport-prediction
- broadcast
- computer-vision
- mask-rcnn
---

# LoL Viewport Prediction

This repository contains the minimal public release package for the Scientific Reports revision of a screen-only League of Legends viewport prediction study. It includes only the files needed to reproduce the viewport prediction experiments: source-video references, replay splits, derived role-map/viewport-mask data, evaluation boxes, and clean training/evaluation code.

Raw broadcast videos are not included because the authors do not own their copyright. The file `data/source_videos.csv` lists the YouTube sources used to reconstruct the raw broadcasts. Availability of third-party videos can change over time.

## Contents

- `data/source_videos.csv`: YouTube source references for the 20 replay sets.
- `data/splits.json`: 15 train replay sets and 5 held-out test replay sets.
- `data/metadata/matches.yaml`: champion-to-role mapping for each replay.
- `data/processed/manifest.json`: manifest for compressed role-map and viewport-mask shards.
- `data/evaluation_boxes/`: paper-style `*_gt_boxes.npy` and `*_pred_boxes.npy` files for IoU evaluation.
- `lol_viewport/`: dataset loader, Mask R-CNN model builder, and IoU metrics.
- `scripts/`: conversion, training, inference, and evaluation entry points.

## Dataset Format

The processed dataset stores compressed `.npz` shards. Each shard contains:

- `frames`: `uint8` array with shape `(N, 2, 256, 256)`. The two channels correspond to the two teams. Pixel values encode roles: `0=background`, `1=TOP`, `2=JUNGLE`, `3=MID`, `4=BOT`, `5=SUPPORT`.
- `masks`: `uint8` array with shape `(N, 1, 256, 256)`. The mask is the professional observer viewport region.
- `frame_indices`: original processed frame indices within the replay.

The training loader stacks five consecutive role-map frames into a 10-channel tensor, matching the manuscript implementation.

## Install

```bash
pip install -r requirements.txt
pip install -e .
```

## Evaluate Released Box Files

```bash
python scripts/evaluate_iou.py --box-dir data/evaluation_boxes/2ch_role_ours
```

Expected output for the released archived `2-ch + Role (Ours)` boxes is:

| Method / Setting | Mean IoU | IoU >= 0.3 (%) | IoU >= 0.5 (%) | IoU >= 0.7 (%) |
| --- | ---: | ---: | ---: | ---: |
| 2-ch + Role (Ours) | 0.4748 | 64.53 | 56.24 | 38.20 |

The manuscript reports the following reference table:

| Method / Setting | Mean IoU | IoU >= 0.3 (%) | IoU >= 0.5 (%) | IoU >= 0.7 (%) |
| --- | ---: | ---: | ---: | ---: |
| Random Champion Selection | 0.2903 | 40.45 | 28.97 | 15.93 |
| Riot Observer System Supervision | 0.2999 | 52.61 | 25.32 | 6.24 |
| 10-ch + One-hot (per champion) | 0.4496 | 61.62 | 53.02 | 34.61 |
| 1-ch (10 champions) | 0.4455 | 61.20 | 52.67 | 33.88 |
| 2-ch + One-hot | 0.4574 | 62.27 | 53.80 | 35.83 |
| 2-ch + Role (Ours) | 0.4748 | 64.53 | 56.24 | 38.20 |

The released `random_champion_selection` box files were generated from a stochastic baseline and may not reproduce the exact random-seed value in the manuscript table.

## Train

```bash
python scripts/train_maskrcnn.py \
--manifest data/processed/manifest.json \
--output-dir checkpoints/2ch_role \
--epochs 20 \
--batch-size 4 \
--lr 0.005 \
--pretrained
```

The code samples a small validation subset from the training pool during optimization, matching the revision implementation.

## Inference

```bash
python scripts/infer_maskrcnn.py \
--manifest data/processed/manifest.json \
--checkpoint checkpoints/2ch_role/best.pth \
--output-dir outputs/2ch_role_boxes
```

## Rebuilding the Processed Shards

If you have the legacy per-frame files in `data_viewport_youtube_1118`, rebuild the compressed release dataset with:

```bash
python scripts/export_legacy_dataset.py \
--legacy-root /path/to/data_viewport_youtube_1118 \
--output-root data/processed
```

## Sharing Constraints

This release intentionally excludes raw `.mp4` files, generated overlay videos, model checkpoints, API keys, IDE files, notebooks, and temporary experiment folders. The released derived data are intended to support reproducible training, validation sampling, testing, and IoU evaluation without redistributing copyrighted broadcast videos.