Refine spacer assignment and count feedback

Author: ShengkaiXu

evaluation_function/evaluation.py

@@ -116,9 +116,10 @@
         "none_detected": "No spacers were detected clearly. Please make sure both spacers are installed and clearly visible in the photo.",
         "short_missing": "The short spacer may be missing or not detected. Please check whether the short spacer is installed and retake the photo if needed.",
         "long_missing": "The long spacer may be missing or not detected. Please check whether the long spacer is installed and retake the photo if needed.",
+        "too_many": "Too many spacers were detected. Please make sure only the required short spacer and long spacer are visible in the photo.",
         "count_fail": "A spacer may be missing or not detected. Please check whether both spacers are installed and retake the photo if needed.",
         "type_confusion": "The spacer types could not be identified reliably. Please retake the photo from a clearer angle and make sure both spacers are fully visible.",
-        "assignment_fail": "The spacers were detected, but at least one spacer could not be reliably assigned to a shaft. Please make sure both spacers are correctly installed on the shafts and retake the photo from a clear top view.",
+        "assignment_fail": "The spacers were detected, but at least one spacer could not be reliably assigned to a shaft. Please make sure both spacers are placed on the shafts. If they are already on the shafts, retake the photo from a clear top view with both shafts and spacers fully visible.",
         "position_mismatch": "The spacer positions appear to be incorrect. Please make sure the short spacer is on the short shaft and the long spacer is on the long shaft.",
         "distance_order": "The spacer order appears to be incorrect. Please check whether the short spacer is closer to white gear than the long spacer.",
         "fail": "Please check the spacer setup again.",
@@ -719,6 +720,9 @@ def advice_text() -> str:
             if n_total == 0:
                 return False, MESSAGE_POLICY["spacer"]["none_detected"]
 
+            if n_total > 2:
+                return False, MESSAGE_POLICY["spacer"]["too_many"]
+
             if n_short == 0 and n_long >= 1:
                 return False, MESSAGE_POLICY["spacer"]["short_missing"]
 
@@ -731,6 +735,8 @@ def advice_text() -> str:
         if "E_SPACER_COUNT_MISMATCH" in codes:
             if n_total == 0:
                 return False, MESSAGE_POLICY["spacer"]["none_detected"]
+            if n_total > 2:
+                return False, MESSAGE_POLICY["spacer"]["too_many"]
             return False, MESSAGE_POLICY["spacer"]["count_fail"]
 
         if (

evaluation_function/evaluation_test.py

@@ -6,7 +6,11 @@
 import numpy as np
 from lf_toolkit.evaluation import Params
 from .evaluation import _build_student_message, evaluation_function
-from .yolo_pipeline import _quality_advice, compute_image_quality_metrics
+from .yolo_pipeline import (
+    _quality_advice,
+    compute_image_quality_metrics,
+    evaluate_spacer_step_errors,
+)
 
 
 def _as_file_uri(path: str) -> str:
@@ -234,6 +238,36 @@ def test_spacer_feedback_reports_no_spacers_detected(self):
         self.assertFalse(is_correct)
         self.assertIn("no spacers", message.lower())
 
+    def test_spacer_feedback_reports_too_many_spacers(self):
+        is_correct, message = _build_student_message(
+            task="spacer",
+            img_bgr=np.zeros((10, 10, 3), dtype=np.uint8),
+            out={"counts": {"spacer_long": 2, "spacer_short": 1}},
+            errors=[],
+            selected_errors=[],
+            part_type="",
+        )
+
+        self.assertFalse(is_correct)
+        self.assertIn("too many spacers", message.lower())
+
+    def test_spacer_assignment_feedback_mentions_placement_and_photo_quality(self):
+        errors = [{"code": "E_SPACER_ASSIGNMENT_FAIL", "message": "Assignment failed."}]
+
+        is_correct, message = _build_student_message(
+            task="spacer",
+            img_bgr=np.zeros((10, 10, 3), dtype=np.uint8),
+            out={"counts": {"spacer_long": 1, "spacer_short": 1}, "errors": errors},
+            errors=errors,
+            selected_errors=errors,
+            part_type="",
+        )
+        lower_message = message.lower()
+
+        self.assertFalse(is_correct)
+        self.assertIn("placed on the shafts", lower_message)
+        self.assertIn("clear top view", lower_message)
+
     def test_shaft_feedback_reports_short_shaft_missing_from_counts(self):
         is_correct, message = _build_student_message(
             task="shaft",
@@ -301,6 +335,40 @@ def test_shaft_feedback_reports_too_many_shafts(self):
         self.assertFalse(is_correct)
         self.assertIn("too many shafts", message.lower())
 
+    def test_spacer_assignment_checked_before_distance_order(self):
+        errors = evaluate_spacer_step_errors(
+            gears=[{"gid": 11, "center": (0.0, 0.0), "r": 10.0}],
+            shafts=[
+                {"center": (10.0, 0.0), "major_len": 40.0},
+                {"center": (30.0, 0.0), "major_len": 40.0},
+            ],
+            spacers=[
+                {"sid": 1, "cls": "short_spacer", "center": (100.0, 0.0)},
+                {"sid": 2, "cls": "long_spacer", "center": (5.0, 0.0)},
+            ],
+            gear11_gid=11,
+            spacer_to_si={2: 1},
+        )
+
+        self.assertEqual(errors[0]["code"], "E_SPACER_ASSIGNMENT_FAIL")
+
+    def test_spacer_position_checked_before_distance_order(self):
+        errors = evaluate_spacer_step_errors(
+            gears=[{"gid": 11, "center": (0.0, 0.0), "r": 10.0}],
+            shafts=[
+                {"center": (10.0, 0.0), "major_len": 40.0},
+                {"center": (30.0, 0.0), "major_len": 40.0},
+            ],
+            spacers=[
+                {"sid": 1, "cls": "short_spacer", "center": (100.0, 0.0)},
+                {"sid": 2, "cls": "long_spacer", "center": (5.0, 0.0)},
+            ],
+            gear11_gid=11,
+            spacer_to_si={1: 1, 2: 0},
+        )
+
+        self.assertEqual(errors[0]["code"], "E_SPACER_POSITION_MISMATCH")
+
 
 if __name__ == "__main__":
     unittest.main()

evaluation_function/yolo_pipeline.py

@@ -1298,18 +1298,6 @@ def evaluate_spacer_step_errors(
     short_sp = short_spacers[0]
     long_sp = long_spacers[0]
 
-    # Strong direct geometric rule first
-    d_short = center_dist(short_sp["center"], c11)
-    d_long = center_dist(long_sp["center"], c11)
-    tol_px = relative_spacer_distance_tol(shafts, gears)
-
-    if d_short > d_long + tol_px:
-        errs.append({
-            "code": "E_SPACER_DISTANCE_ORDER",
-            "message": f"The short spacer is not closer to gear11 than the long spacer (tol={tol_px:.1f}px)."
-        })
-        return errs
-
     shaft2_idx, shaft3_idx = get_expected_shaft_indices_for_step(
         gears=gears,
         shafts=shafts,
@@ -1354,6 +1342,17 @@ def evaluate_spacer_step_errors(
         })
         return errs
 
+    d_short = center_dist(short_sp["center"], c11)
+    d_long = center_dist(long_sp["center"], c11)
+    tol_px = relative_spacer_distance_tol(shafts, gears)
+
+    if d_short > d_long + tol_px:
+        errs.append({
+            "code": "E_SPACER_DISTANCE_ORDER",
+            "message": f"The short spacer is not closer to gear11 than the long spacer (tol={tol_px:.1f}px)."
+        })
+        return errs
+
     return errs
 
 # =========================