feat: Add support for mat backgrounds with image and PDF options in GUI

Author: Kevin

README.md

@@ -249,6 +249,57 @@ fll-sim-gui --exit-after 5
 
 Use `--headless` (or env `FLL_SIM_HEADLESS=1`) for CI and container runs.
 
+### Mat Backgrounds: Images & PDFs
+
+You can provide a mat image or PDF for the GUI background.
+
+- Direct image URL (PNG/JPG):
+	- `python launch_gui_enhanced.py --season latest --mat-url https://example.com/mat.png`
+- Direct PDF URL with rasterization:
+	- `python launch_gui_enhanced.py --season latest --mat-pdf-url https://example.com/mat.pdf --mat-pdf-page 0 --mat-pdf-dpi 300`
+	- Optional selectors:
+		- `--mat-pdf-page-label <label>` (uses PDF page label, if present)
+		- `--mat-pdf-toc-title <title>` (uses PDF Table of Contents title, if present)
+
+Downloaded mats are cached under `assets/mats/<season>/mat.png`.
+
+### Batch Download via Manifest
+
+Use the manifest downloader to grab multiple seasons into `assets/mats/`:
+
+```yaml
+# manifest.yml
+- season: 2024-submerged
+	url: https://example.com/2024-mat.pdf
+	type: pdf
+	page: 0
+	dpi: 300
+	# Optional selectors (if available in the PDF):
+	# page_label: "Mat"
+	# toc_title: "Field Mat"
+- season: 2023-masterpiece
+	url: https://example.com/2023-mat.png
+	type: image
+```
+
+Run:
+
+```bash
+python -m fll_sim.scripts.fetch_all_mats --manifest manifest.yml
+```
+
+### Season Mat Sizes
+
+Default physical size is used when exact season sizes aren’t provided. You can override sizes in `configs/profiles/defaults.yaml`:
+
+```yaml
+mat_sizes:
+	2024-submerged: [2362.0, 1143.0]
+	2023-masterpiece: [2362.0, 1143.0]
+```
+
+These values are in millimeters: `[width_mm, height_mm]`.
+
 ## 🤝 Contributing
 
 1. Fork the repository

configs/profiles/defaults.yaml

@@ -36,3 +36,8 @@ advanced:
     guided_tutorials: false
     competition_timer: true
     scoring_penalties: true
+
+# Optional mat size overrides (in mm). Uncomment and edit as needed.
+# mat_sizes:
+#   2024-submerged: [2362.0, 1143.0]
+#   2023-masterpiece: [2362.0, 1143.0]

launch_gui_enhanced.py

@@ -22,6 +22,7 @@
 from fll_sim.assets.mats import get_mat_for_season  # noqa: E402
 from fll_sim.environment.game_map import GameMap  # noqa: E402
 from fll_sim.scripts.fetch_mat import fetch_mat_image  # noqa: E402
+from fll_sim.scripts.fetch_mat import fetch_mat_pdf
 from fll_sim.visualization.simulator_view import SimulatorView  # noqa: E402
 
 
@@ -77,6 +78,36 @@ def parse_args() -> argparse.Namespace:
             "assets/mats/<season>/mat.png"
         ),
     )
+    p.add_argument(
+        "--mat-pdf-url",
+        default=None,
+        help=(
+            "Remote URL to mat PDF. Rasterizes to PNG and caches under "
+            "assets/mats/<season>/mat.png"
+        ),
+    )
+    p.add_argument(
+        "--mat-pdf-page",
+        type=int,
+        default=0,
+        help="PDF page index to rasterize (default 0)",
+    )
+    p.add_argument(
+        "--mat-pdf-page-label",
+        default=None,
+        help="PDF page label to select (overrides index if found)",
+    )
+    p.add_argument(
+        "--mat-pdf-toc-title",
+        default=None,
+        help="PDF TOC title to select (overrides index if found)",
+    )
+    p.add_argument(
+        "--mat-pdf-dpi",
+        type=int,
+        default=300,
+        help="DPI for PDF rasterization (default 300)",
+    )
     p.add_argument(
         "--px-per-mm",
         type=float,
@@ -115,7 +146,7 @@ def main() -> None:
     # Resolve mat image
     mat_arg: Optional[str] = args.mat_path
     mat_path = Path(mat_arg) if mat_arg else None
-    if not mat_path and args.mat_url:
+    if not mat_path and (args.mat_url or args.mat_pdf_url):
         # Cache under assets/mats/<season>/mat.png
         cache_dir = (
             project_root
@@ -126,8 +157,22 @@ def main() -> None:
         cache_dir.mkdir(parents=True, exist_ok=True)
         mat_path = cache_dir / "mat.png"
         try:
-            print(f"Downloading mat from {args.mat_url}...")
-            fetch_mat_image(url=args.mat_url, out_path=mat_path)
+            if args.mat_pdf_url:
+                print(
+                    f"Downloading mat PDF from {args.mat_pdf_url} "
+                    f"(page={args.mat_pdf_page}, dpi={args.mat_pdf_dpi})..."
+                )
+                fetch_mat_pdf(
+                    url=args.mat_pdf_url,
+                    out_path=mat_path,
+                    page=args.mat_pdf_page,
+                    dpi=args.mat_pdf_dpi,
+                    page_label=args.mat_pdf_page_label,
+                    toc_title=args.mat_pdf_toc_title,
+                )
+            else:
+                print(f"Downloading mat from {args.mat_url}...")
+                fetch_mat_image(url=args.mat_url, out_path=mat_path)
             print(f"Mat cached to {mat_path}")
         except Exception as e:  # noqa: BLE001
             print(f"Warning: Failed to download mat: {e}")

src/fll_sim/scripts/fetch_all_mats.py

@@ -56,6 +56,8 @@ def main() -> None:
         kind = entry.get("type", entry.get("format", "image")).lower()
         page = int(entry.get("page", 0))
         dpi = int(entry.get("dpi", 300))
+        page_label = entry.get("page_label")
+        toc_title = entry.get("toc_title")
         if not season or not url:
             print(f"Skipping invalid entry: {entry}")
             continue
@@ -64,7 +66,14 @@ def main() -> None:
         out_file = out_dir / "mat.png"
         print(f"Downloading {season} from {url} (type={kind}) ...")
         if kind == "pdf":
-            fetch_mat_pdf(url, out_file, page=page, dpi=dpi)
+            fetch_mat_pdf(
+                url,
+                out_file,
+                page=page,
+                dpi=dpi,
+                page_label=page_label,
+                toc_title=toc_title,
+            )
         else:
             fetch_mat_image(url, out_file)
         count += 1
@@ -74,4 +83,3 @@ def main() -> None:
 
 if __name__ == "__main__":  # pragma: no cover
     main()
-    main()

src/fll_sim/scripts/fetch_mat.py

@@ -80,6 +80,8 @@ def fetch_mat_pdf(
     *,
     page: int = 0,
     dpi: int = 300,
+    page_label: str | None = None,
+    toc_title: str | None = None,
     timeout: float = 30.0,
 ) -> Path:
     """
@@ -116,17 +118,42 @@ def fetch_mat_pdf(
 
     # Open with PyMuPDF
     doc = fitz.open(stream=pdf_bytes, filetype="pdf")
-    if page < 0 or page >= doc.page_count:
+
+    # Resolve page number
+    target_page = page
+    if page_label is not None:
+        # Find page with matching label (if available)
+        for i in range(doc.page_count):
+            try:
+                lbl = doc.load_page(i).label  # type: ignore[attr-defined]
+            except Exception:
+                lbl = None
+            if lbl and str(lbl).strip() == str(page_label).strip():
+                target_page = i
+                break
+    elif toc_title is not None:
+        # Search table of contents; fall back silently if unavailable
+        toc = None
+        try:
+            toc = doc.getToC(simple=True)  # type: ignore[attr-defined]
+        except Exception:
+            toc = None
+        if toc:
+            for _lvl, title, pgnum in toc:
+                if str(title).strip() == str(toc_title).strip():
+                    target_page = max(0, int(pgnum) - 1)
+                    break
+
+    if target_page < 0 or target_page >= doc.page_count:
         raise ValueError(
-            "Page index {page} out of range for PDF with "
-            f"{doc.page_count} pages"
+            "Page index out of range for PDF with " f"{doc.page_count} pages"
         )
-    pg = doc.load_page(page)
+    pg = doc.load_page(target_page)
 
     # Compute matrix for DPI
     zoom = dpi / 72.0  # 72 DPI is base
     mat = fitz.Matrix(zoom, zoom)
-    pix = pg.get_pixmap(matrix=mat, alpha=False)
+    pix = pg.get_pixmap(matrix=mat, alpha=False)  # type: ignore[attr-defined]
 
     # Convert pixmap to PIL Image and save as PNG
     img = Image.frombytes("RGB", (pix.width, pix.height), pix.samples)