feat: 5 sample photos with verified queen detection + disclaimer about operating conditions

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+sample_photos/*.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -11,5 +11,6 @@ data/processed/
 weights/*
 !weights/honey_bee_detector.pt
 !weights/queen_classifier.pt
+!sample_photos/
 
 .env

app.py

@@ -100,9 +100,17 @@ def parse_response(text: str, hive_name: str) -> dict:
 
 
 def build_narrative(r: dict, raw: str) -> str:
-    queen_line = (
-        " Queen detected" if r["queen_detected"] else " No queen visible"
-    )
+    if r["queen_detected"]:
+        queen_line = "Queen detected (specialist classifier)"
+    elif r.get("queen_candidate"):
+        queen_line = (
+            f"Likely queen flagged in cyan - **confirm by eye** "
+            f"(stands out by {r.get('queen_standout', 0):.1f} vs the other bees)"
+        )
+    else:
+        queen_line = (
+            "No queen candidate stood out - she may be hidden or on another frame"
+        )
     swarm_line = (
         " Swarm cells (VLM estimate)"
         if r["swarm_cells_detected"]
@@ -247,9 +255,20 @@ def analyze_frame(image: Image.Image, hive_name: str):
 
     results = parse_response(response, hive_name)
 
-    # Override hallucinated fields with hard YOLO evidence
+    # Override hallucinated fields with hard YOLO evidence.
+    # Two distinct, honest signals:
+    #   queen_detected  - a CONFIRMED queen (only the trained classifier sets
+    #                     class="queen"). Hard yes.
+    #   queen_candidate - a best-effort geometric outlier flagged "confirm by
+    #                     eye". Never a hard yes - the queen may not even be
+    #                     in frame.
     if yolo_active:
+        cand = next((d for d in detections if d.get("queen_candidate")), None)
         results["queen_detected"] = counts.get("queen", 0) > 0
+        results["queen_candidate"] = cand is not None
+        results["queen_standout"] = (
+            cand.get("queen_standout", 0.0) if cand else 0.0
+        )
         results["yolo_counts"] = counts
         # Track the top confidence per class so the UI can show how
         # confident the model was about each detection.
@@ -533,9 +552,47 @@ def build_ui() -> gr.Blocks:
                             type="pil",
                             sources=["upload", "webcam"],
                         )
+                        gr.Markdown(
+                            "*Best with close-up macro shots of frame inspections "
+                            "(a single bee or small cluster filling the frame). "
+                            "Wide-angle photos with hands and background may not "
+                            "reliably detect the queen.*"
+                        )
                         analyze_btn = gr.Button(
                             " Analyze Frame", variant="primary"
                         )
+
+                        sample_dir = Path(__file__).parent / "sample_photos"
+                        sample_files = (
+                            sorted(sample_dir.glob("*.jpg"))
+                            if sample_dir.exists() else []
+                        )
+                        if sample_files:
+                            gr.Markdown("### Or try a sample photo")
+                            sample_gallery = gr.Gallery(
+                                value=[str(p) for p in sample_files],
+                                label="Click any sample to load it",
+                                columns=3, height="auto",
+                                allow_preview=False, show_label=False,
+                                interactive=False,
+                            )
+
+                            def _load_sample(evt: gr.SelectData):
+                                if evt is None or evt.index is None:
+                                    return gr.update()
+                                idx = (
+                                    evt.index
+                                    if isinstance(evt.index, int)
+                                    else evt.index[0]
+                                )
+                                if 0 <= idx < len(sample_files):
+                                    return Image.open(str(sample_files[idx])).convert("RGB")
+                                return gr.update()
+
+                            sample_gallery.select(
+                                fn=_load_sample,
+                                outputs=[image_input],
+                            )
                     with gr.Column():
                         annotated_output = gr.Image(label="Annotated Frame")
                         narrative_output = gr.Markdown()

cascade.py

@@ -25,6 +25,7 @@ from typing import Callable
 from PIL import Image, ImageDraw, ImageFont
 
 import queen_clf
+import queen_locate
 
 
 GRID_SIDE_PX = 240        # each crop tile this size in the composite grid
@@ -193,36 +194,25 @@ def verify_queens(
             "raw_response": "",
         }
 
-    # ---- Path B: VLM-grid fallback (older approach) ----
-    if qwen_caller is None or len(candidates) < 2:
-        return detections, {"method": "skip", "n_candidates": len(candidates),
-                            "queen_prob": 0.0, "raw_response": ""}
-
-    candidates.sort(key=lambda d: _box_area(d["bbox"]), reverse=True)
-    top = candidates[: MAX_CANDIDATES]
-    crops = [_crop_with_padding(image, d["bbox"]) for d in top]
-    grid = _make_grid(crops)
-    response = qwen_caller(grid, _GRID_PROMPT)
-    queen_idx_1based = _parse_queen_indices(response)
-    if len(queen_idx_1based) > 1:
-        queen_idx_1based = set()
-    queen_idx_0based = {i - 1 for i in queen_idx_1based if 1 <= i <= len(top)}
-
-    new_detections = []
-    others = [d for d in detections if d not in candidates]
-    for i, d in enumerate(top):
-        new_d = dict(d)
-        if i in queen_idx_0based:
-            new_d["class"] = "queen"
-            new_d["vlm_verified"] = True
-        else:
-            new_d["class"] = "bee"
-        new_detections.append(new_d)
-    new_detections.extend(others)
+    # ---- Path B: geometric outlier locator (no weights, no VLM) ----
+    #
+    # This replaces the old VLM-grid pick, which was unreliable because it
+    # asked the model to judge each crop in isolation. Here we keep every
+    # bee's class as "bee" and instead TAG the single most queen-like bee
+    # as a *candidate* to confirm by eye - judged relative to the other
+    # bees on this same frame. If none stands out, nothing is tagged.
+    new_detections = [dict(d) for d in detections]
+    info, chosen = queen_locate.locate(new_detections)
+    if chosen is not None:
+        chosen["queen_candidate"] = True
+        chosen["queen_standout"] = info["score"]
 
     return new_detections, {
-        "method": "vlm",
-        "n_candidates": len(top),
-        "queen_indices": queen_idx_1based,
-        "raw_response": response,
+        "method": "geometric",
+        "n_candidates": info["n_pool"],
+        "queen_candidate": info["candidate"],
+        "standout": info["score"],
+        "margin": info["margin"],
+        "length_ratio": info["length_ratio"],
+        "raw_response": "",
     }

detector.py

@@ -8,6 +8,7 @@ weights file is missing, useful while training is still in progress.
 
 from __future__ import annotations
 
+import math
 import os
 import sys
 from pathlib import Path
@@ -15,6 +16,12 @@ from typing import Optional
 
 from PIL import Image, ImageDraw, ImageFont
 
+# Run inference at a larger size than the YOLO default (640). Bees are tiny
+# relative to a full frame photo; at 640 the queen's distinguishing abdomen
+# length collapses to a couple of pixels. 1280 keeps that detail (and lifts
+# small-bee recall generally) at a modest CPU cost.
+INFER_IMGSZ = 1280
+
 
 # Resolve the weights file relative to this module's actual location.
 _HERE = Path(os.path.dirname(os.path.abspath(__file__)))
@@ -155,7 +162,9 @@ def detect(
 
     try:
         # Cast a wide net at the model level, then filter per-class below.
-        results = yolo(image, conf=conf, verbose=False, device="cpu")
+        results = yolo(
+            image, conf=conf, imgsz=INFER_IMGSZ, verbose=False, device="cpu"
+        )
         if not results:
             return [], image
         r = results[0]
@@ -209,8 +218,30 @@ def _font(size: int = 14):
     return ImageFont.load_default()
 
 
+_CANDIDATE_COLOR = (90, 220, 255)  # cyan - distinct from the green of a confirmed queen
+
+
+def _dashed_rectangle(draw, box, color, width=3, dash=12, gap=8):
+    """Draw a dashed rectangle (PIL has no native dashed outline)."""
+    x1, y1, x2, y2 = box
+    corners = [(x1, y1), (x2, y1), (x2, y2), (x1, y2), (x1, y1)]
+    for (ax, ay), (bx, by) in zip(corners, corners[1:]):
+        length = math.hypot(bx - ax, by - ay)
+        if length == 0:
+            continue
+        n = int(length // (dash + gap)) + 1
+        for s in range(n):
+            t0 = (s * (dash + gap)) / length
+            t1 = min(t0 + dash / length, 1.0)
+            draw.line(
+                [ax + (bx - ax) * t0, ay + (by - ay) * t0,
+                 ax + (bx - ax) * t1, ay + (by - ay) * t1],
+                fill=color, width=width,
+            )
+
+
 def draw_annotations(image: Image.Image, detections: list[dict]) -> Image.Image:
-    """Public wrapper so the VLM cascade can re-annotate after re-classification."""
+    """Public wrapper so the cascade can re-annotate after re-classification."""
     return _draw_annotations(image, detections)
 
 
@@ -248,6 +279,22 @@ def _draw_annotations(image: Image.Image, detections: list[dict]) -> Image.Image
             draw.rectangle([bx1, by1, bx2, by2], fill=color + (235,))
             draw.text((bx1 + 5, by1 + 1), label, fill=(20, 16, 8), font=font_queen)
 
+    # Best-effort queen candidate (geometric outlier). Drawn last so it sits
+    # on top, with a dashed cyan box + a question mark - it is a "confirm by
+    # eye" hint, deliberately NOT styled like the confident green queen box.
+    cand = next((d for d in detections if d.get("queen_candidate")), None)
+    if cand is not None:
+        cx1, cy1, cx2, cy2 = cand["bbox"]
+        _dashed_rectangle(draw, [cx1, cy1, cx2, cy2],
+                          _CANDIDATE_COLOR + (255,), width=3)
+        label = "LIKELY QUEEN?"
+        tw = draw.textlength(label, font=font_queen)
+        th = font_queen.size + 4
+        bx1, by1 = cx1, max(0, cy1 - th - 2)
+        draw.rectangle([bx1, by1, bx1 + tw + 10, by1 + th],
+                       fill=_CANDIDATE_COLOR + (235,))
+        draw.text((bx1 + 5, by1 + 1), label, fill=(8, 16, 20), font=font_queen)
+
     return out
 
 

queen_locate.py

@@ -0,0 +1,120 @@
+"""
+Best-effort unmarked-queen *locator*.
+
+Honesty note: there is no reliable way to find an unmarked queen in a
+single top-down frame photo. This module does NOT pretend to. It surfaces
+the single most queen-like bee on the frame as a CANDIDATE to confirm by
+eye, using the one signal that actually carries information:
+
+    the queen is a *relative* outlier - longer and more elongated than the
+    worker bees AROUND her on this same frame.
+
+That is why every per-crop / per-grid approach failed before: queen-ness
+is relative, not absolute. A single cropped bee has no scale reference, so
+the classifier/VLM was guessing. Here we judge every bee against the
+population of bees on the *same* frame.
+
+Two robust features per detected bee box:
+  - length:     the longer side of the box (queen's body is longer)
+  - elongation: length / breadth (her abdomen extends past the wings, so
+                her box is proportionally longer-and-thinner than a worker;
+                this also separates her from drones, which are big but stocky)
+
+We compute robust z-scores (median / MAD, so a few mislabelled boxes don't
+wreck the stats), combine them, and pick the top bee - but ONLY return it
+if it clears a real standout threshold AND beats the runner-up by a margin
+AND is meaningfully longer than the median bee. Otherwise: no candidate.
+Returning "nothing stood out" when the queen isn't in frame is the whole
+point - it's what stops the app from lying.
+"""
+
+from __future__ import annotations
+
+from statistics import median
+
+
+# Classes that could plausibly be the queen. Drones are already separated
+# by YOLO and are stocky (low elongation), so we leave them out of the pool.
+QUEEN_POOL = ("bee", "pollenbee", "queen")
+
+MIN_BEES_FOR_STATS = 5      # need a population before "outlier" means anything
+LENGTH_WEIGHT = 1.0         # she is longer than the workers
+ELONGATION_WEIGHT = 0.6     # ...and proportionally longer-and-thinner
+STANDOUT_THRESHOLD = 2.5    # min combined robust z-score to flag at all
+MIN_MARGIN = 0.8            # top bee must beat the runner-up by this much
+MIN_LENGTH_RATIO = 1.25     # top box must be >=25% longer than the median bee
+
+
+def _mad(values: list[float], med: float) -> float:
+    """Median absolute deviation, scaled (~1.4826) to match a std-dev."""
+    if not values:
+        return 0.0
+    return 1.4826 * median([abs(v - med) for v in values])
+
+
+def _features(det: dict) -> tuple[float, float]:
+    x1, y1, x2, y2 = det["bbox"]
+    w, h = max(0.0, x2 - x1), max(0.0, y2 - y1)
+    length = max(w, h)
+    breadth = max(min(w, h), 1e-3)
+    return length, length / breadth  # (length, elongation)
+
+
+def locate(detections: list[dict]) -> tuple[dict, dict | None]:
+    """
+    Pick the single most queen-like bee on the frame, if one stands out.
+
+    `detections` is judged in place - the returned dict (when not None) is a
+    reference INTO `detections`, so the caller can tag it directly.
+
+    Returns (info, chosen_detection_or_None). `info` carries the standout
+    score, margin and length ratio for honest UI messaging.
+    """
+    pool = [d for d in detections if d["class"] in QUEEN_POOL]
+    if len(pool) < MIN_BEES_FOR_STATS:
+        return (
+            {"method": "geometric", "candidate": False,
+             "reason": "too few bees to judge relative size",
+             "n_pool": len(pool), "score": 0.0, "margin": 0.0,
+             "length_ratio": 0.0},
+            None,
+        )
+
+    feats = []
+    for d in pool:
+        length, elong = _features(d)
+        feats.append({"d": d, "length": length, "elong": elong})
+
+    lengths = [f["length"] for f in feats]
+    elongs = [f["elong"] for f in feats]
+    med_l = median(lengths)
+    med_e = median(elongs)
+    mad_l = _mad(lengths, med_l)
+    mad_e = _mad(elongs, med_e)
+
+    for f in feats:
+        z_l = (f["length"] - med_l) / mad_l if mad_l > 0 else 0.0
+        z_e = (f["elong"] - med_e) / mad_e if mad_e > 0 else 0.0
+        f["score"] = LENGTH_WEIGHT * z_l + ELONGATION_WEIGHT * z_e
+
+    feats.sort(key=lambda f: f["score"], reverse=True)
+    best = feats[0]
+    runner = feats[1]["score"] if len(feats) > 1 else 0.0
+    margin = best["score"] - runner
+    length_ratio = best["length"] / med_l if med_l > 0 else 0.0
+
+    confident = (
+        best["score"] >= STANDOUT_THRESHOLD
+        and margin >= MIN_MARGIN
+        and length_ratio >= MIN_LENGTH_RATIO
+    )
+
+    info = {
+        "method": "geometric",
+        "candidate": confident,
+        "n_pool": len(pool),
+        "score": round(best["score"], 2),
+        "margin": round(margin, 2),
+        "length_ratio": round(length_ratio, 2),
+    }
+    return (info, best["d"]) if confident else (info, None)