Create tutor/visual_grounding.py

tutor/visual_grounding.py

@@ -0,0 +1,50 @@
+"""tutor/visual_grounding.py — renders a counting stimulus as an RGB numpy array."""
+from __future__ import annotations
+import math
+import numpy as np
+from typing import Optional
+
+try:
+    from PIL import Image, ImageDraw, ImageFont  # type: ignore
+    _PIL = True
+except ImportError:
+    _PIL = False
+
+_PALETTE = ["#e74c3c","#3498db","#2ecc71","#f39c12",
+            "#9b59b6","#1abc9c","#e91e63","#f1c40f"]
+
+def _hex(h):
+    h = h.lstrip("#")
+    return int(h[:2],16), int(h[2:4],16), int(h[4:],16)
+
+
+def render_counting_stimulus(count: int, label: str = "●",
+                              canvas_w: int = 400, canvas_h: int = 300
+                              ) -> Optional[np.ndarray]:
+    if not _PIL or count <= 0 or count > 20:
+        return None
+    img  = Image.new("RGB", (canvas_w, canvas_h), (255,255,255))
+    draw = ImageDraw.Draw(img)
+    try:
+        font = ImageFont.truetype(
+            "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 22)
+    except Exception:
+        font = ImageFont.load_default()
+
+    draw.text((canvas_w//2, 14), f"Count the {label}s!", fill=(30,30,30),
+              font=font, anchor="mt")
+
+    cols   = min(count, 5)
+    rows   = math.ceil(count / cols)
+    dot_r  = min(26, (canvas_w-40)//(cols*2), (canvas_h-70)//(rows*2))
+    xstep  = (canvas_w-40)//cols
+    ystep  = (canvas_h-70)//rows
+    x0, y0 = 20+xstep//2, 55+ystep//2
+
+    for i in range(count):
+        cx = x0 + (i % cols)*xstep
+        cy = y0 + (i // cols)*ystep
+        c  = _hex(_PALETTE[i % len(_PALETTE)])
+        draw.ellipse([cx-dot_r, cy-dot_r, cx+dot_r, cy+dot_r], fill=c)
+
+    return np.array(img)