Refine photo quality thresholds and feedback severity

Author: ShengkaiXu

evaluation_function/evaluation_test.py

@@ -6,7 +6,7 @@
 import numpy as np
 from lf_toolkit.evaluation import Params
 from .evaluation import evaluation_function
-from .yolo_pipeline import compute_image_quality_metrics
+from .yolo_pipeline import _quality_advice, compute_image_quality_metrics
 
 
 def _as_file_uri(path: str) -> str:
@@ -157,6 +157,39 @@ def test_image_quality_rejects_low_single_component_score(self):
         )
         self.assertFalse(quality["quality_pass"])
 
+    def test_image_quality_soft_warning_does_not_request_retake(self):
+        image = np.full((120, 160), 130, dtype=np.uint8)
+        for y in range(0, 120, 20):
+            image[y:y + 10, :] = 170
+        for x in range(0, 160, 20):
+            image[:, x:x + 10] = 90
+        image = cv2.GaussianBlur(image, (3, 3), 0)
+        image = cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+
+        quality = compute_image_quality_metrics(image)
+        advice = " ".join(quality["quality_advice"]).lower()
+
+        self.assertTrue(quality["quality_pass"])
+        self.assertGreater(quality["sharpness_score_100"], quality["quality_min_component_score"])
+        self.assertLessEqual(quality["sharpness_score_100"], 50)
+        self.assertIn("a little blurry", advice)
+        self.assertNotIn("retake", advice)
+
+    def test_quality_advice_soft_warnings_cover_all_components(self):
+        advice = " ".join(_quality_advice(
+            brightness_mean=50.0,
+            brightness_component=0.35,
+            contrast_component=0.35,
+            sharpness_component=0.35,
+            noise_component=0.35,
+        )).lower()
+
+        self.assertIn("little dark", advice)
+        self.assertIn("stand out", advice)
+        self.assertIn("little blurry", advice)
+        self.assertIn("little noisy", advice)
+        self.assertNotIn("retake", advice)
+
 
 if __name__ == "__main__":
     unittest.main()

evaluation_function/yolo_pipeline.py

@@ -764,29 +764,49 @@ def _score100(component: float) -> int:
 def _quality_advice(
     *,
     brightness_mean: float,
+    brightness_component: 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.")
+    brightness_score = _score100(brightness_component)
+    contrast_score = _score100(contrast_component)
+    sharpness_score = _score100(sharpness_component)
+    noise_score = _score100(noise_component)
 
-    if contrast_component < 0.5:
-        advice.append("The parts do not stand out clearly. Use a plain background and avoid shadows.")
+    is_dark = brightness_mean < QUALITY_BRIGHTNESS_IDEAL_MIN
+    brightness_fail = (
+        "The photo is too dark for reliable checking. Please retake it in brighter light."
+        if is_dark
+        else "The photo is overexposed for reliable checking. Please retake it with less glare or strong direct light."
+    )
+    brightness_warn = (
+        "The photo is a little dark. Add more light next time if possible."
+        if is_dark
+        else "The photo is a little bright. Try reducing glare next time."
+    )
+
+    if brightness_score <= QUALITY_MIN_COMPONENT_SCORE:
+        advice.append(brightness_fail)
+    elif brightness_score <= 50:
+        advice.append(brightness_warn)
+
+    if contrast_score <= QUALITY_MIN_COMPONENT_SCORE:
+        advice.append("The parts do not stand out clearly enough for reliable checking. Please retake the photo with a plain background and fewer shadows.")
+    elif contrast_score <= 50:
+        advice.append("The parts do not stand out very clearly. Use a plain background and avoid shadows next time.")
 
-    if sharpness_component < 0.5:
-        advice.append("The photo is blurry. Hold the camera still and refocus before taking the photo.")
+    if sharpness_score <= QUALITY_MIN_COMPONENT_SCORE:
+        advice.append("The photo is too blurry for reliable checking. Please retake it after holding the camera still and refocusing.")
+    elif sharpness_score <= 50:
+        advice.append("The photo is a little blurry. For better results, hold the camera still and refocus next time.")
 
-    if noise_component < 0.5:
-        advice.append("The photo looks noisy or grainy. Use better lighting and avoid digital zoom.")
+    if noise_score <= QUALITY_MIN_COMPONENT_SCORE:
+        advice.append("The photo is too noisy or grainy for reliable checking. Please retake it with better lighting and avoid digital zoom.")
+    elif noise_score <= 50:
+        advice.append("The photo looks a little noisy or grainy. Use better lighting and avoid digital zoom next time.")
 
     if not advice:
         advice.append("The photo is clear enough for the next check.")
@@ -849,6 +869,7 @@ def compute_image_quality_metrics(img_bgr: np.ndarray) -> Dict[str, Any]:
     )
     advice = _quality_advice(
         brightness_mean=brightness_mean,
+        brightness_component=brightness_component,
         contrast_component=contrast_component,
         sharpness_component=sharpness_component,
         noise_component=noise_component,