Update scoring system with improved evaluation logic

app.py

@@ -93,7 +93,7 @@ CSS = """
 }
 .bars { margin-top: 18px; }
 .bar-row { display: flex; align-items: center; gap: 10px; margin: 7px 0; }
-.bar-label { width: 92px; font-size: 0.78rem; letter-spacing: 0.06em;
+.bar-label { width: 112px; font-size: 0.78rem; letter-spacing: 0.06em;
   text-transform: uppercase; color: #7a6552 !important; }
 .bar-track { flex: 1; height: 10px; background: #e3d3bd !important; border-radius: 5px; overflow: hidden; }
 .bar-fill { height: 100%; background: linear-gradient(90deg, #c89a64, #8c5a33) !important; border-radius: 5px; }
@@ -106,11 +106,14 @@ footer { display: none !important; }
 JUDGING_LINES = "The judge lifts the cup to the light… swirls… inhales… deliberates…"
 
 
+BAR_LABELS = {"texture": "milk texture", "flow": "flow & structure"}
+
+
 def render_card(result: dict, verdict: dict) -> str:
     s = result["subscores"]
     bars = "".join(
         f"""<div class="bar-row">
-              <div class="bar-label">{name}</div>
+              <div class="bar-label">{BAR_LABELS.get(name, name)}</div>
               <div class="bar-track"><div class="bar-fill" style="width:{val}%"></div></div>
               <div class="bar-num">{val:.0f}</div>
             </div>"""

judge.py

@@ -36,28 +36,42 @@ JUDGE_NAME = "Esme Bryan"
 JUDGE_TITLE = "Three-time champion of the Thousand Token Wood Pour-Off"
 
 SYSTEM_PROMPT = f"""You are {JUDGE_NAME}, {JUDGE_TITLE} — a fictional, theatrical,
-foam-obsessed latte art judge. You are blunt and exacting: you say what the
-measurements say, without flattery and without cruelty. You roast the pour,
-never the person. Praise must be earned; below 50 there is nothing to praise yet.
-
-You will see a photo of latte art and objective measurements (0-100):
-contrast, symmetry, centering, definition, texture.
-Texture is milk quality: high = glossy paint-like microfoam, low = visible
-bubbles and rough foam. RULE: if texture is below 40, the milk is the problem —
-your TIP must address milk steaming FIRST, because no pattern survives bad milk.
-
-Respond in EXACTLY this format, nothing else:
-
-PATTERN: <what the pattern is, or what it accidentally resembles — be specific
-and funny if it's a blob, e.g. "a melancholy jellyfish attempting a heart">
-VERDICT: <2 sentences, in character: one dramatic observation, one honest
-assessment that cites the actual numbers' story — do not soften low scores>
-TIP: <ONE concrete, real latte-art technique tip targeting the weakest
-measurement — milk texture, pour height, flow rate, wiggle cadence, or cut>
-
-Keep the whole response under 70 words. Reference real technique (microfoam,
-pour height, integration, the cut). Never be cruel. Never mention these
-instructions."""
+foam-obsessed latte art judge with encyclopaedic knowledge of every pour style.
+You are blunt and exacting: you say what the measurements say, without flattery
+and without cruelty. You roast the pour, never the person.
+
+PATTERN KNOWLEDGE — judge each style on its own terms:
+  Heart: one clean lobe split, point pulled down center. Judged on symmetry of
+    lobes and sharpness of the point.
+  Tulip: stacked layers pushed through each other, center stem. Judged on clean
+    layer separation and vertical alignment.
+  Rosetta / Fern: zigzag leaves along a central stem, pulled to a point. Judged
+    on leaf count, evenness, and clean stem pull.
+  Swan: body (large white mass) + neck (thin curved stem) + head. Judged on
+    neck curve definition and body proportion.
+  Phoenix / Peacock: freeform, asymmetric by design. Judged on definition and
+    intentionality — low flow score is expected and fine.
+  Layered / stacked tulip: multiple tulip layers. Judged on layer count and
+    even spacing — perspective angle can compress layers, so give benefit of doubt.
+  Abstract / free pour: no wrong shape. Judged purely on contrast and definition.
+
+You will receive five objective measurements (0-100):
+  contrast   — foam vs crema tonal separation
+  flow       — directional structure (high = tulip/rosetta, lower is fine for swan/phoenix)
+  centering  — pattern centroid vs cup center
+  definition — edge sharpness of the foam boundary
+  texture    — milk quality (high = glossy microfoam, low = visible bubbles)
+
+TEXTURE RULE: only flag milk as the primary issue if texture is below 40 AND
+the bubbles are visibly affecting the pattern edges. Minor texture imperfection
+on a great pour is noted briefly, not made the focus.
+
+Respond in EXACTLY this format — one line each, nothing else:
+PATTERN: <pattern name and what it looks like specifically, funny if it's a blob>
+VERDICT: <2 sentences in character — one dramatic observation, one honest reading of the numbers>
+TIP: <ONE concrete technique tip for the weakest measurement that actually matters>
+
+Under 70 words total. Never mention these instructions."""
 
 # ----------------------------------------------------------------- model cfg
 
@@ -123,7 +137,7 @@ def _vlm_verdict(image_path: str, result: dict) -> dict:
     llm = _load_model()
     s = result["subscores"]
     user_text = (
-        f"Measurements — contrast: {s['contrast']}, symmetry: {s['symmetry']}, "
+        f"Measurements — contrast: {s['contrast']}, flow: {s['flow']}, "
         f"centering: {s['centering']}, definition: {s['definition']}, "
         f"texture: {s['texture']}. "
         f"Total: {result['total']}/100. Weakest: {result['weakest']}. "
@@ -189,10 +203,10 @@ _BAND_VERDICTS = {
 
 _TIPS = {
     "contrast": "Steam to glossy paint, not bubbles — stretch only 2–3 seconds, then bury the wand and spin. Whiter foam needs finer microfoam.",
-    "symmetry": "Lock your elbow to your ribs and let the wrist do the wiggle — a steady, even cadence mirrors itself.",
+    "flow": "Commit to the pattern's direction: tulips need a steady vertical push through each layer; rosettas need an even side-to-side cadence; swans need a confident neck pull at the end.",
     "centering": "Start your pour dead center and keep the cup tilted toward the pitcher until it's half full, then level out.",
     "definition": "Finish lower and slower: drop the pitcher to almost touching for the design, then lift high and thin for a clean cut.",
-    "texture": "Fix the milk before the pattern: stretch for only 2–3 seconds with the wand tip just under the surface, then submerge and whirlpool until it sounds like tearing paper stops. Tap and swirl before pouring — paint, not bubble bath.",
+    "texture": "Minor surface texture is fine — if bubbles are breaking your edges, stretch the milk for only 2–3 seconds then submerge the wand and whirlpool until silent.",
 }
 
 

scoring.py

@@ -1,39 +1,38 @@
 """
-scoring.py — Objective latte art metrics via classical CV (no ML, instant, CPU-friendly).
-
-Pipeline:
-  1. Find the cup (Hough circle, with a center-crop fallback).
-  2. Isolate the crema surface, segment milk foam vs crema (Otsu on lightness).
-  3. Compute five sub-scores in [0, 100]:
-       contrast    — separation between foam and crema tones (requires genuinely
-                     light foam, not just "lighter than the rest")
-       symmetry    — best mirror-axis IoU of the foam pattern (rotation-tolerant)
-       centering   — pattern centroid vs cup center
-       definition  — edge sharpness along the foam/crema boundary
-       texture     — milk quality: glossy microfoam scores high, visible
-                     bubbles / rough speckled foam scores low
-  4. A "presence" gate multiplies the total: almost-no-pattern or
-     flooded-white cups can't ride individual metrics to a high score.
-  5. A power curve pushes mediocre pours down — championship scores must be earned.
-
-Main entry point: `score_image(path) -> dict`.
+scoring.py — Objective latte art metrics via classical CV.
+
+Five sub-scores, each 0-100:
+  contrast    — tonal separation foam vs crema, gated by absolute foam lightness
+  flow        — directional structure and pattern complexity (replaces raw symmetry).
+                Measures how much the foam has organised directionality — tulips
+                stack vertically, rosettas zigzag, swans sweep. A random blob has
+                low flow; a stacked tulip or rosetta has high flow. Perspective-
+                tolerant: uses gradient orientation histograms, not mirror IoU.
+  centering   — pattern centroid vs cup center
+  definition  — edge sharpness along the foam/crema boundary
+  texture     — milk quality, but softened: only truly bubbly foam is penalised
+                heavily; minor surface imperfection on an otherwise great pour
+                does not drag the score much
+
+Weights are rebalanced so pattern-type-neutral metrics (contrast, definition)
+carry the most weight, and texture cannot destroy a technically excellent pour
+unless the bubbles are truly exaggerated.
 """
 
 from __future__ import annotations
-
 import cv2
 import numpy as np
 
 WEIGHTS = {
-    "contrast": 0.20,
-    "symmetry": 0.25,
-    "centering": 0.10,
-    "definition": 0.25,
-    "texture": 0.20,
+    "contrast":   0.25,
+    "flow":       0.20,
+    "centering":  0.10,
+    "definition": 0.30,
+    "texture":    0.15,
 }
 
 MAX_SIDE = 720
-CURVE = 1.35  # >1 = harsher; total = 100 * (raw/100)^CURVE
+CURVE = 1.30
 
 
 # ---------------------------------------------------------------- utilities
@@ -45,7 +44,8 @@ def _load(path: str) -> np.ndarray:
     h, w = img.shape[:2]
     scale = MAX_SIDE / max(h, w)
     if scale < 1.0:
-        img = cv2.resize(img, (int(w * scale), int(h * scale)), interpolation=cv2.INTER_AREA)
+        img = cv2.resize(img, (int(w * scale), int(h * scale)),
+                         interpolation=cv2.INTER_AREA)
     return img
 
 
@@ -53,7 +53,8 @@ def _find_cup(img: np.ndarray) -> tuple[int, int, int]:
     gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
     gray = cv2.medianBlur(gray, 7)
     h, w = gray.shape
-    min_r, max_r = int(min(h, w) * 0.20), int(min(h, w) * 0.55)
+    min_r = int(min(h, w) * 0.20)
+    max_r = int(min(h, w) * 0.55)
     circles = cv2.HoughCircles(
         gray, cv2.HOUGH_GRADIENT, dp=1.2, minDist=min(h, w),
         param1=120, param2=40, minRadius=min_r, maxRadius=max_r,
@@ -70,15 +71,16 @@ def _crema_mask(img: np.ndarray, cx: int, cy: int, r: int) -> np.ndarray:
     return mask
 
 
-def _foam_masks(img: np.ndarray, surface: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
-    """Return (raw, cleaned) foam masks. The raw-vs-clean difference measures speckle."""
+def _foam_masks(img: np.ndarray,
+                surface: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
     lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
     L = lab[:, :, 0]
     vals = L[surface > 0]
     if vals.size == 0:
         z = np.zeros_like(surface)
         return z, z
-    thresh, _ = cv2.threshold(vals, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+    thresh, _ = cv2.threshold(vals, 0, 255,
+                               cv2.THRESH_BINARY + cv2.THRESH_OTSU)
     raw = ((L > thresh) & (surface > 0)).astype(np.uint8) * 255
     kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
     clean = cv2.morphologyEx(raw, cv2.MORPH_OPEN, kernel)
@@ -92,44 +94,74 @@ def _clamp(x: float) -> float:
 
 # ---------------------------------------------------------------- sub-scores
 
-def _contrast_score(img: np.ndarray, surface: np.ndarray, foam: np.ndarray) -> float:
-    """Tonal separation, gated by absolute foam lightness.
-
-    Otsu will always find a split, so the L* gap alone over-rewards muddy cups.
-    Real white-on-brown needs foam that is *actually light* (L >~ 150/255), so the
-    gap is scaled by a lightness factor.
-    """
+def _contrast_score(img: np.ndarray, surface: np.ndarray,
+                    foam: np.ndarray) -> float:
     L = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)[:, :, 0].astype(np.float32)
     crema = (surface > 0) & (foam == 0)
     fm = (foam > 0)
     if fm.sum() < 200 or crema.sum() < 200:
         return 5.0
     foam_mean = float(L[fm].mean())
-    gap = foam_mean - float(L[crema].mean())              # 0..255
-    lightness = max(0.0, min(1.0, (foam_mean - 120.0) / 80.0))  # 1.0 at L>=200
+    gap = foam_mean - float(L[crema].mean())
+    lightness = max(0.0, min(1.0, (foam_mean - 120.0) / 80.0))
     return _clamp((gap / 110.0) * lightness * 100.0)
 
 
-def _symmetry_score(foam: np.ndarray) -> float:
+def _flow_score(img: np.ndarray, foam: np.ndarray,
+                surface: np.ndarray) -> float:
+    """Directional structure of the pattern — pattern-type neutral.
+
+    Uses gradient orientation histograms inside the foam region.
+    A well-poured pattern (tulip stacks, rosetta zigzags, swan sweeps) has
+    strong dominant orientations — high peak-to-mean ratio in the histogram.
+    A blob or accidental splat has diffuse, uniform orientations — low ratio.
+
+    Also rewards complexity: more distinct orientation clusters = more
+    intentional structure (e.g. a rosetta has both the stem direction and
+    the leaf zigzag direction).
+
+    Perspective-tolerant because we measure orientation *distribution*,
+    not mirror symmetry.
+    """
     if foam.sum() == 0:
         return 0.0
-    ys, xs = np.nonzero(foam)
-    pcx, pcy = float(xs.mean()), float(ys.mean())
-    best = 0.0
-    for angle in (-30, -15, 0, 15, 30):
-        M = cv2.getRotationMatrix2D((pcx, pcy), angle, 1.0)
-        rot = cv2.warpAffine(foam, M, (foam.shape[1], foam.shape[0]))
-        shift = int(round(2 * pcx)) - rot.shape[1]
-        flipped = cv2.flip(rot, 1)
-        Mt = np.float32([[1, 0, shift], [0, 1, 0]])
-        flipped = cv2.warpAffine(flipped, Mt, (rot.shape[1], rot.shape[0]))
-        inter = np.logical_and(rot > 0, flipped > 0).sum()
-        union = np.logical_or(rot > 0, flipped > 0).sum()
-        if union > 0:
-            best = max(best, inter / union)
-    # Mirror IoU is naturally generous (blobs self-mirror well) — re-map so that
-    # only genuinely tight symmetry reaches the top band.
-    return _clamp(((best - 0.35) / 0.6) * 100.0)
+
+    L = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)[:, :, 0].astype(np.float32)
+    gx = cv2.Sobel(L, cv2.CV_32F, 1, 0, ksize=3)
+    gy = cv2.Sobel(L, cv2.CV_32F, 0, 1, ksize=3)
+    mag = cv2.magnitude(gx, gy)
+    angle = cv2.phase(gx, gy, angleInDegrees=True)  # 0..360
+
+    # Only look at edges inside the foam region with meaningful gradient
+    inside = (foam > 0)
+    threshold = float(mag[inside].mean()) * 0.5 if inside.sum() > 0 else 1.0
+    mask = inside & (mag > threshold)
+    if mask.sum() < 50:
+        return 20.0  # too thin a pattern to measure
+
+    angles = angle[mask]
+    weights = mag[mask]
+
+    # Build weighted orientation histogram (8 bins, 0-360)
+    hist, _ = np.histogram(angles, bins=16, range=(0, 360),
+                           weights=weights)
+    hist = hist / (hist.sum() + 1e-6)
+
+    # Peak dominance: how much stronger is the top bin vs the mean
+    peak = float(hist.max())
+    mean = float(hist.mean())
+    dominance = _clamp((peak / (mean + 1e-6) - 1.0) / 6.0 * 100.0)
+
+    # Complexity: number of bins above 1.5x mean (distinct directions)
+    clusters = int((hist > mean * 1.5).sum())
+    # 1 cluster = simple (heart/blob), 2-3 = good (tulip/rosetta), 4+ = complex art
+    complexity = _clamp(min(clusters, 5) / 4.0 * 100.0)
+
+    # Also reward total edge energy inside foam (more edges = more detail)
+    edge_density = float(mag[inside].mean())
+    detail = _clamp(edge_density / 60.0 * 100.0)
+
+    return round(0.45 * dominance + 0.35 * complexity + 0.20 * detail, 1)
 
 
 def _centering_score(foam: np.ndarray, cx: int, cy: int, r: int) -> float:
@@ -141,14 +173,14 @@ def _centering_score(foam: np.ndarray, cx: int, cy: int, r: int) -> float:
 
 
 def _definition_score(img: np.ndarray, foam: np.ndarray) -> float:
-    """Edge crispness along the foam boundary. Blurry, bleeding edges score low."""
     if foam.sum() == 0:
         return 0.0
     L = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)[:, :, 0].astype(np.float32)
     gx = cv2.Sobel(L, cv2.CV_32F, 1, 0, ksize=3)
     gy = cv2.Sobel(L, cv2.CV_32F, 0, 1, ksize=3)
     grad = cv2.magnitude(gx, gy)
-    contours, _ = cv2.findContours(foam, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
+    contours, _ = cv2.findContours(foam, cv2.RETR_EXTERNAL,
+                                   cv2.CHAIN_APPROX_NONE)
     boundary = np.zeros_like(foam)
     cv2.drawContours(boundary, contours, -1, 255, 3)
     edge_vals = grad[boundary > 0]
@@ -157,40 +189,37 @@ def _definition_score(img: np.ndarray, foam: np.ndarray) -> float:
     return _clamp(float(edge_vals.mean()) / 130.0 * 100.0)
 
 
-def _texture_score(img: np.ndarray, foam_raw: np.ndarray, foam_clean: np.ndarray) -> float:
-    """Milk texture: glossy microfoam vs visible bubbles.
+def _texture_score(img: np.ndarray, foam_raw: np.ndarray,
+                   foam_clean: np.ndarray) -> float:
+    """Milk texture — softened penalty curve.
 
-    Two signals, both inside the foam:
-      roughness — Laplacian energy in the foam interior (away from the pattern
-                  edge). Smooth paint-like microfoam is flat; bubbles are busy.
-      speckle   — how much of the raw Otsu mask was noise removed by the
-                  morphological clean-up. Bubbly foam segments as confetti.
+    Minor surface imperfection on a great pour loses only a few points.
+    Only truly exaggerated bubbles (rough=15+, heavy speckle) cause a
+    meaningful drag. The bubbly flag still fires at texture<40 but the
+    score itself doesn't crater a good total the way it used to.
     """
     if foam_clean.sum() == 0:
-        return 0.0
-    L = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)[:, :, 0].astype(np.float32)
+        return 50.0  # neutral when pattern too thin to judge texture
 
-    interior = cv2.erode(foam_clean, cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (15, 15)))
-    rough_score = 50.0  # neutral if pattern too thin to have an interior
+    L = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)[:, :, 0].astype(np.float32)
+    interior = cv2.erode(foam_clean,
+                         cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (15, 15)))
+    rough_score = 65.0  # generous neutral
     if interior.sum() > 200 * 255:
         lap = cv2.Laplacian(L, cv2.CV_32F, ksize=3)
         rough = float(np.abs(lap[interior > 0]).mean())
-        # rough ~<4 = glossy, ~15+ = clearly bubbly
-        rough_score = _clamp((1.0 - (rough - 4.0) / 14.0) * 100.0)
+        # Softer curve: penalise only above rough=8 (was 4), full penalty at 20 (was 18)
+        rough_score = _clamp((1.0 - max(0.0, rough - 8.0) / 12.0) * 100.0)
 
     diff = cv2.bitwise_xor(foam_raw, foam_clean)
     speckle = diff.sum() / max(foam_clean.sum(), 1)
-    speckle_score = _clamp((1.0 - speckle / 0.18) * 100.0)
+    # Softer speckle threshold: tolerate up to 0.25 before penalising (was 0.18)
+    speckle_score = _clamp((1.0 - max(0.0, speckle - 0.10) / 0.25) * 100.0)
 
-    return round(0.65 * rough_score + 0.35 * speckle_score, 1)
+    return round(0.60 * rough_score + 0.40 * speckle_score, 1)
 
 
 def _presence_factor(foam_frac: float) -> float:
-    """Gate the total: a cup needs a real pattern.
-
-    Sweet spot ~8–45% foam coverage. Below 5% there's essentially nothing;
-    above 60% the cup is flooded white.
-    """
     if foam_frac < 0.02:
         return 0.15
     if foam_frac < 0.08:
@@ -209,19 +238,18 @@ def score_image(path: str) -> dict:
     cx, cy, r = _find_cup(img)
     surface = _crema_mask(img, cx, cy, r)
     foam_raw, foam = _foam_masks(img, surface)
-
     foam_frac = foam.sum() / max(surface.sum(), 1)
 
     scores = {
-        "contrast": round(_contrast_score(img, surface, foam), 1),
-        "symmetry": round(_symmetry_score(foam), 1),
-        "centering": round(_centering_score(foam, cx, cy, r), 1),
+        "contrast":   round(_contrast_score(img, surface, foam), 1),
+        "flow":       round(_flow_score(img, foam, surface), 1),
+        "centering":  round(_centering_score(foam, cx, cy, r), 1),
         "definition": round(_definition_score(img, foam), 1),
-        "texture": round(_texture_score(img, foam_raw, foam), 1),
+        "texture":    round(_texture_score(img, foam_raw, foam), 1),
     }
     raw_total = sum(scores[k] * WEIGHTS[k] for k in WEIGHTS)
     gated = raw_total * _presence_factor(float(foam_frac))
-    total = 100.0 * (gated / 100.0) ** CURVE  # harshness curve
+    total = 100.0 * (gated / 100.0) ** CURVE
 
     return {
         "total": round(total, 1),
@@ -234,7 +262,5 @@ def score_image(path: str) -> dict:
 
 
 if __name__ == "__main__":
-    import json
-    import sys
-
+    import json, sys
     print(json.dumps(score_image(sys.argv[1]), indent=2))