How samnguyen2k5/nusc-isc-footballanalysis works
Project Type & Purpose
• This repository is a research-oriented computer-vision pipeline for football pitch analysis (segmentation, line/conic detection, homography estimation, keypoint detection, mask clustering).
• The “notebooks/” folder drives interactive development, while “scripts/” contains the core reusable library modules. Pretrained model weights sit in “weights/”.
File Structure
• Top-level folders:
• notebooks/ – Jupyter notebooks for each development stage (e.g., “Segmentation Model.ipynb”, “HomographyNet.ipynb”, “Full Pipeline.ipynb”)
• scripts/ – Python packages separated into:
– classes/frame (frame.py)
– classes/pitch (homography_solver.py, keypoint_mapping.py, pitch.py, helper.py)
– datasets (calibration.py, field_masking.py, field_pitch.py)
• weights/ – pretrained models (e.g. yolo-sn-ball-opt.pt)
• Config files: requirements.txt, setup.sh
Read README for Context
• Project name: “NUSC-ISC-FootballAnalysis”
• No explicit architecture section, but notebook and script division implies a data-pipeline library plus experiment layer.
Main Components & Their Relationships
• Raw video frames & calibration data (<scripts/datasets/calibration.py>)
• Ground-truth masks (<scripts/datasets/field_masking.py>)
• Pretrained weights (weights/…)
B. Core Library (rectangles)
1. Frame Manager (<scripts/classes/frame/frame.py>)
2. Pitch & Homography Solver (<scripts/classes/pitch/homography_solver.py>)
3. Keypoint Mapper & Mask Clustering (<scripts/classes/pitch/keypoint_mapping.py>)
4. Dataset Handlers (<scripts/datasets/*.py>)
• Jupyter notebooks that import the Core Library to run segmentation model training, keypoint network training, homography calibration, and full end-to-end demos
• Visualizations (plots, annotated frames)
• Reports (reports/2510/*.pdf, *.drawio)
Data Flow:
1. Raw frames & calibration → Dataset Handlers → Frame Manager
2. Frames → Segmentation & Keypoint Nets (using weights/)
3. Nets’ outputs → Homography Solver → Aligned pitch coordinate outputs
4. Utilities → compute statistics & produce visualizations
5. Notebooks orchestrate steps 1–4 and export results to reports/
Architectural Patterns & Principles
• Modular separation by functionality (classes vs. datasets vs. tools)
• Single Responsibility per module
• Experiment reproducibility via notebooks + versioned requirements.txt + setup.sh