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.license: 其他 language: - 英语 task_categories: - 目标检测 - 图像分割 pretty_name: 英雄联盟视口预测（LoL Viewport Prediction） size_categories: - 100K < n < 1M tags: - 电子竞技 - 英雄联盟（League of Legends） - 视口预测 - 赛事转播 - 计算机视觉 - Mask R-CNN（mask-rcnn） # 英雄联盟视口预测 本仓库为《科学报告》（Scientific Reports）修订版的纯屏幕英雄联盟视口预测研究提供了最小公开发布包，仅包含复现视口预测实验所需的文件：源视频引用、回放拆分文件、衍生的角色映射/视口掩码数据、评估框，以及简洁规范的训练与评估代码。 原始赛事转播视频未包含在内，原因是作者不享有其版权。`data/source_videos.csv` 文件列出了用于重构原始转播的YouTube源地址。第三方视频的可用性可能随时间发生变化。 ## 内容说明 - `data/source_videos.csv`：对应20个回放集的YouTube源引用 - `data/splits.json`：包含15个训练回放集与5个预留测试回放集 - `data/metadata/matches.yaml`：各回放的英雄-角色映射关系 - `data/processed/manifest.json`：压缩版角色映射与视口掩码分片的索引清单 - `data/evaluation_boxes/`：用于交并比（IoU，Intersection over Union）评估的论文格式`*_gt_boxes.npy`与`*_pred_boxes.npy`文件 - `lol_viewport/`：数据集加载器、Mask R-CNN模型构建器与交并比指标实现 - `scripts/`：格式转换、训练、推理与评估的入口脚本 ## 数据集格式 处理后的数据集以压缩的`.npz`分片形式存储。每个分片包含以下内容： - `frames`：形状为`(N, 2, 256, 256)`的`uint8`数组。两个通道分别对应两支战队。像素值编码了角色信息：`0=背景`，`1=上单`，`2=打野`，`3=中单`，`4=下路`，`5=辅助` - `masks`：形状为`(N, 1, 256, 256)`的`uint8`数组。该掩码为职业解说视角的视口区域 - `frame_indices`：回放中原始处理后的帧索引 训练加载器会将连续5帧的角色映射帧拼接为10通道张量，与论文中的实现保持一致。 ## 安装方式 执行以下命令完成安装： bash pip install -r requirements.txt pip install -e . ## 评估已发布的框文件 执行以下命令进行评估： bash python scripts/evaluate_iou.py --box-dir data/evaluation_boxes/2ch_role_ours 针对已发布的归档`2-ch + Role (Ours)`框文件，预期输出结果如下： | 方法 / 设置 | 平均交并比 | IoU ≥ 0.3 (%) | IoU ≥ 0.5 (%) | IoU ≥ 0.7 (%) | | --- | ---: | ---: | ---: | ---: | | 2-ch + Role (Ours) | 0.4748 | 64.53 | 56.24 | 38.20 | 论文中报告的参考基准结果如下表所示： | 方法 / 设置 | 平均交并比 | IoU ≥ 0.3 (%) | IoU ≥ 0.5 (%) | IoU ≥ 0.7 (%) | | --- | ---: | ---: | ---: | ---: | | 随机英雄选择基准 | 0.2903 | 40.45 | 28.97 | 15.93 | | 拳头游戏解说系统监督基准 | 0.2999 | 52.61 | 25.32 | 6.24 | | 10通道 + 独热编码（按英雄） | 0.4496 | 61.62 | 53.02 | 34.61 | | 1通道（10个英雄） | 0.4455 | 61.20 | 52.67 | 33.88 | | 2通道 + 独热编码 | 0.4574 | 62.27 | 53.80 | 35.83 | | 2通道 + 角色（我们的方法） | 0.4748 | 64.53 | 56.24 | 38.20 | 已发布的`random_champion_selection`框文件由随机基准生成，可能无法复现论文表格中精确的随机种子值。 ## 训练流程 执行以下命令启动训练： 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 本代码在优化过程中会从训练池中采样少量验证子集，与修订版的实现保持一致。 ## 推理流程 执行以下命令启动推理： bash python scripts/infer_maskrcnn.py --manifest data/processed/manifest.json --checkpoint checkpoints/2ch_role/best.pth --output-dir outputs/2ch_role_boxes ## 重构处理后的分片 若你拥有`data_viewport_youtube_1118`中的旧版单帧文件，可通过以下命令重构压缩版发布数据集： bash python scripts/export_legacy_dataset.py --legacy-root /path/to/data_viewport_youtube_1118 --output-root data/processed ## 发布限制 本发布包刻意未包含原始`.mp4`文件、生成的叠加视频、模型检查点文件、API密钥、集成开发环境（IDE）文件、笔记本文件与临时实验文件夹。本次发布的衍生数据旨在支持可复现的训练、验证采样、测试与交并比评估，且不会重新分发受版权保护的赛事转播视频。