Add student-facing image quality scores

Author: ShengkaiXu

evaluation_function/evaluation.py

@@ -37,12 +37,20 @@
     },
     "precheck": {
         "report": (
-            "Photo quality reference values:\n"
-            "- brightness: {brightness_mean}\n"
-            "- contrast: {contrast_std}\n"
-            "- sharpness: {sharpness_score}\n"
-            "- noise: {noise_score}\n"
-            "These values are provided as reference only and do not determine whether the assembly is correct."
+            "Photo quality score: {quality_score}/100.\n"
+            "Brightness: {brightness_score}/100\n"
+            "Contrast: {contrast_score}/100\n"
+            "Sharpness: {sharpness_score}/100\n"
+            "Noise control: {noise_score}/100\n"
+            "{quality_advice}"
+        ),
+        "fail": (
+            "Photo quality score: {quality_score}/100.\n"
+            "Brightness: {brightness_score}/100\n"
+            "Contrast: {contrast_score}/100\n"
+            "Sharpness: {sharpness_score}/100\n"
+            "Noise control: {noise_score}/100\n"
+            "{quality_advice}"
         ),
     },
     "single_stage": {
@@ -274,6 +282,7 @@ def keep(e: Dict[str, Any]) -> bool:
         if task == "precheck":
             return code in {
                 "E_PRECHECK_BIG_SMALL_INCONSISTENT",
+                "E_PHOTO_QUALITY_LOW",
                 "E_NO_GEARS",
             }
 
@@ -521,18 +530,36 @@ def _build_student_message(
 
     if task == "precheck":
         quality = out.get("quality", {}) if isinstance(out.get("quality"), dict) else {}
+        codes = {
+            str(e.get("code", "")).upper()
+            for e in selected_errors
+            if isinstance(e, dict)
+        }
 
-        def qfmt(key: str) -> str:
+        def qint(key: str, default: int = 0) -> str:
             try:
-                return f"{float(quality.get(key, 0.0)):.2f}"
+                return str(int(round(float(quality.get(key, default)))))
             except Exception:
-                return str(quality.get(key, "N/A"))
-
-        return True, MESSAGE_POLICY["precheck"]["report"].format(
-            brightness_mean=qfmt("brightness_mean"),
-            contrast_std=qfmt("contrast_std"),
-            sharpness_score=qfmt("sharpness_score"),
-            noise_score=qfmt("noise_score"),
+                return str(default)
+
+        def advice_text() -> str:
+            advice = quality.get("quality_advice", [])
+            if isinstance(advice, list):
+                clean = [str(item).strip() for item in advice if str(item).strip()]
+            else:
+                clean = [str(advice).strip()] if str(advice).strip() else []
+            if not clean:
+                clean = ["The photo is clear enough for the next check."]
+            return "\n".join(f"- {item}" for item in clean[:3])
+
+        policy_key = "fail" if ("E_PHOTO_QUALITY_LOW" in codes or task_has_error) else "report"
+        return policy_key == "report", MESSAGE_POLICY["precheck"][policy_key].format(
+            quality_score=qint("quality_score"),
+            brightness_score=qint("brightness_score"),
+            contrast_score=qint("contrast_score"),
+            sharpness_score=qint("sharpness_score_100"),
+            noise_score=qint("noise_score_100"),
+            quality_advice=advice_text(),
         )
 
     if task == "single_stage":

evaluation_function/evaluation_test.py

@@ -2,8 +2,11 @@
 import unittest
 from pathlib import Path
 
+import cv2
+import numpy as np
 from lf_toolkit.evaluation import Params
 from .evaluation import evaluation_function
+from .yolo_pipeline import compute_image_quality_metrics
 
 
 def _as_file_uri(path: str) -> str:
@@ -113,6 +116,31 @@ def test_evaluation_bad_url(self):
         fb_text = _feedback_as_text(fb)
         self.assertIn("could not be loaded", fb_text.lower())
 
+    def test_image_quality_score_uses_student_friendly_threshold(self):
+        sharp = np.zeros((120, 120, 3), dtype=np.uint8)
+        sharp[:, :60] = 30
+        sharp[:, 60:] = 230
+        cv2.line(sharp, (0, 0), (119, 119), (255, 255, 255), 3)
+
+        blurry = np.full((120, 120, 3), 120, dtype=np.uint8)
+        blurry = cv2.GaussianBlur(blurry, (31, 31), 0)
+
+        sharp_quality = compute_image_quality_metrics(sharp)
+        blurry_quality = compute_image_quality_metrics(blurry)
+
+        self.assertIn("quality_score", sharp_quality)
+        self.assertIn("quality_accept_score", sharp_quality)
+        self.assertEqual(sharp_quality["quality_score_max"], 100)
+        self.assertIn("quality_advice", sharp_quality)
+        self.assertGreaterEqual(
+            sharp_quality["quality_score"],
+            sharp_quality["quality_accept_score"],
+        )
+        self.assertLess(
+            blurry_quality["quality_score"],
+            blurry_quality["quality_accept_score"],
+        )
+
 
 if __name__ == "__main__":
-    unittest.main()
+    unittest.main()

evaluation_function/yolo_pipeline.py

@@ -66,6 +66,21 @@
 
 ENABLE_ERROR_CHECKS: bool = True
 
+# Image-quality precheck thresholds. Scores are normalized to 0-100 for display.
+# The fail threshold is intentionally permissive so borderline usable photos are
+# not rejected while obviously dark/blurry/noisy ones are sent back for retake.
+QUALITY_ACCEPT_SCORE: int = int(os.environ.get("QUALITY_ACCEPT_SCORE", "40"))
+QUALITY_BRIGHTNESS_USABLE_MIN: float = 35.0
+QUALITY_BRIGHTNESS_IDEAL_MIN: float = 60.0
+QUALITY_BRIGHTNESS_IDEAL_MAX: float = 210.0
+QUALITY_BRIGHTNESS_USABLE_MAX: float = 235.0
+QUALITY_CONTRAST_USABLE_MIN: float = 10.0
+QUALITY_CONTRAST_IDEAL_MIN: float = 25.0
+QUALITY_SHARPNESS_USABLE_MIN: float = 40.0
+QUALITY_SHARPNESS_IDEAL_MIN: float = 250.0
+QUALITY_NOISE_IDEAL_MAX: float = 12.0
+QUALITY_NOISE_USABLE_MAX: float = 35.0
+
 # Geometry / ambiguity thresholds
 SHAFT_DISTANCE_AMBIG_RATIO: float = 0.08
 SPACER_ASSIGN_AXIS_DIST_RATIO: float = 0.90
@@ -711,7 +726,74 @@ def get_spacer_counts(spacers: List[Dict[str, Any]]) -> Dict[str, int]:
 # =========================
 # Precheck helpers
 # =========================
-def compute_image_quality_metrics(img_bgr: np.ndarray) -> Dict[str, float]:
+def _clip01(value: float) -> float:
+    return max(0.0, min(1.0, float(value)))
+
+
+def _score_band(value: float, usable_min: float, ideal_min: float, ideal_max: float, usable_max: float) -> float:
+    if ideal_min <= value <= ideal_max:
+        return 1.0
+    if usable_min <= value < ideal_min:
+        return _clip01((value - usable_min) / (ideal_min - usable_min))
+    if ideal_max < value <= usable_max:
+        return _clip01((usable_max - value) / (usable_max - ideal_max))
+    return 0.0
+
+
+def _score_min(value: float, usable_min: float, ideal_min: float) -> float:
+    if value >= ideal_min:
+        return 1.0
+    if value <= usable_min:
+        return 0.0
+    return _clip01((value - usable_min) / (ideal_min - usable_min))
+
+
+def _score_max(value: float, ideal_max: float, usable_max: float) -> float:
+    if value <= ideal_max:
+        return 1.0
+    if value >= usable_max:
+        return 0.0
+    return _clip01((usable_max - value) / (usable_max - ideal_max))
+
+
+def _score100(component: float) -> int:
+    return int(round(100.0 * _clip01(component)))
+
+
+def _quality_advice(
+    *,
+    brightness_mean: float,
+    contrast_component: float,
+    sharpness_component: float,
+    noise_component: float,
+) -> List[str]:
+    advice: List[str] = []
+
+    if brightness_mean < QUALITY_BRIGHTNESS_USABLE_MIN:
+        advice.append("The photo is too dark. Retake it in brighter light.")
+    elif brightness_mean < QUALITY_BRIGHTNESS_IDEAL_MIN:
+        advice.append("The photo is a little dark. Add more light if possible.")
+    elif brightness_mean > QUALITY_BRIGHTNESS_USABLE_MAX:
+        advice.append("The photo is overexposed. Reduce glare or strong direct light.")
+    elif brightness_mean > QUALITY_BRIGHTNESS_IDEAL_MAX:
+        advice.append("The photo is a little bright. Try reducing glare.")
+
+    if contrast_component < 0.5:
+        advice.append("The parts do not stand out clearly. Use a plain background and avoid shadows.")
+
+    if sharpness_component < 0.5:
+        advice.append("The photo is blurry. Hold the camera still and refocus before taking the photo.")
+
+    if noise_component < 0.5:
+        advice.append("The photo looks noisy or grainy. Use better lighting and avoid digital zoom.")
+
+    if not advice:
+        advice.append("The photo is clear enough for the next check.")
+
+    return advice
+
+
+def compute_image_quality_metrics(img_bgr: np.ndarray) -> Dict[str, Any]:
     gray = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2GRAY)
 
     brightness_mean = float(np.mean(gray))
@@ -721,11 +803,57 @@ def compute_image_quality_metrics(img_bgr: np.ndarray) -> Dict[str, float]:
     noise_residual = gray.astype(np.float32) - blur.astype(np.float32)
     noise_score = float(np.std(noise_residual))
 
+    brightness_component = _score_band(
+        brightness_mean,
+        QUALITY_BRIGHTNESS_USABLE_MIN,
+        QUALITY_BRIGHTNESS_IDEAL_MIN,
+        QUALITY_BRIGHTNESS_IDEAL_MAX,
+        QUALITY_BRIGHTNESS_USABLE_MAX,
+    )
+    contrast_component = _score_min(
+        contrast_std,
+        QUALITY_CONTRAST_USABLE_MIN,
+        QUALITY_CONTRAST_IDEAL_MIN,
+    )
+    sharpness_component = _score_min(
+        sharpness_score,
+        QUALITY_SHARPNESS_USABLE_MIN,
+        QUALITY_SHARPNESS_IDEAL_MIN,
+    )
+    noise_component = _score_max(
+        noise_score,
+        QUALITY_NOISE_IDEAL_MAX,
+        QUALITY_NOISE_USABLE_MAX,
+    )
+    quality_score = int(round(100.0 * (
+        0.25 * brightness_component
+        + 0.20 * contrast_component
+        + 0.40 * sharpness_component
+        + 0.15 * noise_component
+    )))
+    if contrast_component <= 0.0 and sharpness_component <= 0.0:
+        quality_score = min(quality_score, QUALITY_ACCEPT_SCORE - 1)
+    advice = _quality_advice(
+        brightness_mean=brightness_mean,
+        contrast_component=contrast_component,
+        sharpness_component=sharpness_component,
+        noise_component=noise_component,
+    )
+
     return {
         "brightness_mean": brightness_mean,
         "contrast_std": contrast_std,
         "sharpness_score": sharpness_score,
         "noise_score": noise_score,
+        "brightness_score": _score100(brightness_component),
+        "contrast_score": _score100(contrast_component),
+        "sharpness_score_100": _score100(sharpness_component),
+        "noise_score_100": _score100(noise_component),
+        "quality_score": quality_score,
+        "quality_score_max": 100,
+        "quality_accept_score": QUALITY_ACCEPT_SCORE,
+        "quality_pass": quality_score >= QUALITY_ACCEPT_SCORE,
+        "quality_advice": advice,
     }
 
 
@@ -2104,6 +2232,14 @@ def _need_shafts() -> bool:
         quality = compute_image_quality_metrics(img_bgr)
         counts = get_gear_counts(gears)
         errors: List[Dict[str, Any]] = []
+        if not bool(quality.get("quality_pass", True)):
+            errors.append({
+                "code": "E_PHOTO_QUALITY_LOW",
+                "message": (
+                    "The photo quality is too low for reliable checking. "
+                    "Please retake it with clearer focus and better lighting."
+                ),
+            })
 
         out = {
             "summary": {