Upload folder using huggingface_hub

measure_finger.py

@@ -455,6 +455,34 @@ def _save_debug_visualization(path: str, image: np.ndarray) -> None:
         f.write(buf.tobytes())
 
 
+def _write_card_failure_viz(
+    result_png_path: Optional[str],
+    image_canonical: np.ndarray,
+    hand_data: Dict[str, Any],
+    card_result: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Write a diagnostic overlay for card-phase failures.
+
+    Shows the hand mask + skeleton on the canonical image, plus either the
+    detected card corner quadrilateral (when the card was found but rejected,
+    e.g. card_not_parallel) or the card-prompt seed points (when detection
+    itself failed). Uses the same corner-quad rendering as the success path
+    (draw_card_overlay) rather than the raw SAM card mask, which can have
+    stray blobs outside the true card boundary.
+    """
+    if result_png_path is None:
+        return
+    vis = image_canonical.copy()
+    vis = _overlay_sam_masks(vis, hand_mask=hand_data.get("mask"))
+    vis = _overlay_hand_skeleton(vis, landmarks=hand_data.get("landmarks"))
+    if card_result is not None:
+        vis = draw_card_overlay(vis, card_result)
+    else:
+        vis = _overlay_card_seeds(vis, hand_data.get("_sam_card_seed_debug"))
+    _save_debug_visualization(result_png_path, vis)
+    logger.info("card-failure viz saved: %s", result_png_path)
+
+
 def _sam_card_detect(
     image_canonical: np.ndarray,
     hand_data: Dict[str, Any],
@@ -610,6 +638,7 @@ def measure_finger(
 
         if card_result is None:
             logger.warning("card not detected in image")
+            _write_card_failure_viz(result_png_path, image_canonical, hand_data)
             return create_output(
                 card_detected=False,
                 fail_reason="card_not_detected",
@@ -629,6 +658,9 @@ def measure_finger(
         if not view_angle_ok:
             logger.warning("card not parallel to camera (scale_confidence=%.2f, required>0.9)",
                            scale_confidence)
+            _write_card_failure_viz(
+                result_png_path, image_canonical, hand_data, card_result=card_result
+            )
             return create_output(
                 card_detected=True,
                 finger_detected=False,
@@ -1255,24 +1287,16 @@ def measure_multi_finger(
             else:
                 card_result = detect_credit_card(image_canonical, debug_dir=card_debug_dir)
         if card_result is None:
-            # Emit a diagnostic visualization so the failure is debuggable:
-            # hand mask + card-prompt seeds on the canonical image. Without
-            # this, a card_not_detected failure on HF leaves no PNG to pull.
-            if result_png_path is not None:
-                vis = image_canonical.copy()
-                vis = _overlay_sam_masks(vis, hand_mask=hand_data.get("mask"))
-                vis = _overlay_hand_skeleton(vis, landmarks=hand_data.get("landmarks"))
-                vis = _overlay_card_seeds(
-                    vis, hand_data.get("_sam_card_seed_debug")
-                )
-                _save_debug_visualization(result_png_path, vis)
-                logger.info("[multi] card-not-detected viz saved: %s", result_png_path)
+            _write_card_failure_viz(result_png_path, image_canonical, hand_data)
             return {"fail_reason": "card_not_detected", "per_finger": {}, "fingers_measured": 0, "fingers_succeeded": 0}
         px_per_cm, scale_confidence = compute_scale_factor(card_result["corners"])
         view_angle_ok = scale_confidence > 0.9
         card_detected = True
 
         if not view_angle_ok:
+            _write_card_failure_viz(
+                result_png_path, image_canonical, hand_data, card_result=card_result
+            )
             return {"fail_reason": "card_not_parallel", "per_finger": {}, "fingers_measured": 0, "fingers_succeeded": 0}
 
         card_frame = check_card_in_frame(card_result["corners"], image_canonical.shape)

src/sam_card_detection.py

@@ -22,7 +22,6 @@ import numpy as np
 
 from .card_detection import (
     CARD_ASPECT_RATIO,
-    MAX_CARD_AREA_RATIO,
     MIN_CARD_AREA_RATIO,
     get_quad_dimensions,
     order_corners,
@@ -35,6 +34,13 @@ logger = logging.getLogger(__name__)
 MIN_RECTANGULARITY = 0.90  # mask_area / minAreaRect_area; card mask is near-perfect rectangle
 ASPECT_RATIO_TOLERANCE = 0.15  # fractional deviation from 1.586
 MAX_HAND_OVERLAP_RATIO = 0.20  # reject candidates that swallow the hand (background paper, tabletop)
+# SAM-specific upper bound on card area. Tighter than the shared
+# MAX_CARD_AREA_RATIO (0.5) because SAM happily returns whole-background
+# segments (ceilings, walls) as a single rectangular-ish mask when no card
+# is actually present — a ~50% half-image mask can pass rectangularity and
+# aspect ratio purely by accident. A real credit card held alongside a hand
+# is ~5-15% of the frame; 25% is already 2× the realistic maximum.
+SAM_MAX_CARD_AREA_RATIO = 0.25
 
 
 def _score_card_mask(
@@ -51,7 +57,7 @@ def _score_card_mask(
     mask_area = float(mask.sum())
 
     area_ratio = mask_area / image_area
-    if area_ratio < MIN_CARD_AREA_RATIO or area_ratio > MAX_CARD_AREA_RATIO:
+    if area_ratio < MIN_CARD_AREA_RATIO or area_ratio > SAM_MAX_CARD_AREA_RATIO:
         return None
 
     contours, _ = cv2.findContours(mask_u8, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)

web_demo/app.py

@@ -104,24 +104,12 @@ def _make_base_name(kol_name: str) -> Tuple[str, str]:
     return base_name, run_id
 
 
-class _NumpyEncoder(json.JSONEncoder):
-    """Handle numpy types that aren't natively JSON serializable."""
-    def default(self, obj):
-        if isinstance(obj, np.bool_):
-            return bool(obj)
-        if isinstance(obj, np.integer):
-            return int(obj)
-        if isinstance(obj, np.floating):
-            return float(obj)
-        if isinstance(obj, np.ndarray):
-            return obj.tolist()
-        if isinstance(obj, np.generic):
-            return obj.item()
-        return super().default(obj)
-
-
 def _numpy_safe(obj):
-    """Recursively convert numpy types to native Python types."""
+    """Recursively convert numpy types to native Python types.
+
+    Applied to measurement results before they hit either Flask's jsonify
+    (which doesn't know about numpy) or the JSON file writer.
+    """
     if isinstance(obj, dict):
         return {k: _numpy_safe(v) for k, v in obj.items()}
     if isinstance(obj, (list, tuple)):
@@ -142,7 +130,21 @@ def _numpy_safe(obj):
 def _save_json(path: Path, data: Dict[str, Any]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     with path.open("w", encoding="utf-8") as f:
-        json.dump(data, f, indent=2, ensure_ascii=False, cls=_NumpyEncoder)
+        json.dump(data, f, indent=2, ensure_ascii=False)
+
+
+def _read_form_settings() -> Dict[str, str]:
+    """Parse the measurement-request form fields shared by /api/measure and
+    /api/measure-default."""
+    ring_model = request.form.get("ring_model", DEFAULT_RING_MODEL)
+    if ring_model not in VALID_RING_MODELS:
+        ring_model = DEFAULT_RING_MODEL
+    return {
+        "finger_index": request.form.get("finger_index", "index"),
+        "mode": request.form.get("mode", "single"),
+        "kol_name": request.form.get("kol_name", "").strip(),
+        "ring_model": ring_model,
+    }
 
 
 @app.route("/")
@@ -178,13 +180,8 @@ def api_measure():
     if not _allowed_file(file.filename):
         return jsonify({"success": False, "error": "Unsupported file type"}), 400
 
-    finger_index = request.form.get("finger_index", "index")
-    mode = request.form.get("mode", "single")
-    kol_name = request.form.get("kol_name", "").strip()
-    ring_model = request.form.get("ring_model", DEFAULT_RING_MODEL)
-    if ring_model not in VALID_RING_MODELS:
-        ring_model = DEFAULT_RING_MODEL
-    base_name, run_id = _make_base_name(kol_name)
+    settings = _read_form_settings()
+    base_name, run_id = _make_base_name(settings["kol_name"])
     suffix = Path(secure_filename(file.filename)).suffix.lower() or ".jpg"
     upload_name = f"{base_name}{suffix}"
     upload_path = UPLOAD_DIR / upload_name
@@ -195,39 +192,23 @@ def api_measure():
     if image is None:
         return jsonify({"success": False, "error": "Failed to load image"}), 400
 
-    if mode == "multi":
-        return _run_multi_measurement(
-            image=image,
-            input_image_url=f"/uploads/{upload_name}",
-            ring_model=ring_model,
-            kol_name=kol_name,
-            upload_path=upload_path,
-            upload_name=upload_name,
-            base_name=base_name,
-            run_id=run_id,
-        )
-
-    return _run_measurement(
+    common_kwargs = dict(
         image=image,
-        finger_index=finger_index,
         input_image_url=f"/uploads/{upload_name}",
-        ring_model=ring_model,
-        kol_name=kol_name,
+        ring_model=settings["ring_model"],
+        kol_name=settings["kol_name"],
         upload_path=upload_path,
         upload_name=upload_name,
         base_name=base_name,
         run_id=run_id,
     )
+    if settings["mode"] == "multi":
+        return _run_multi_measurement(**common_kwargs)
+    return _run_measurement(finger_index=settings["finger_index"], **common_kwargs)
 
 
 @app.route("/api/measure-default", methods=["POST"])
 def api_measure_default():
-    finger_index = request.form.get("finger_index", "index")
-    mode = request.form.get("mode", "single")
-    kol_name = request.form.get("kol_name", "").strip()
-    ring_model = request.form.get("ring_model", DEFAULT_RING_MODEL)
-    if ring_model not in VALID_RING_MODELS:
-        ring_model = DEFAULT_RING_MODEL
     if not DEFAULT_SAMPLE_PATH.exists():
         return jsonify({"success": False, "error": "Default sample image not found"}), 500
 
@@ -235,27 +216,20 @@ def api_measure_default():
     if image is None:
         return jsonify({"success": False, "error": "Failed to load default sample image"}), 500
 
-    base_name, run_id = _make_base_name(kol_name or "sample")
+    settings = _read_form_settings()
+    base_name, run_id = _make_base_name(settings["kol_name"] or "sample")
 
-    if mode == "multi":
-        return _run_multi_measurement(
-            image=image,
-            input_image_url=DEFAULT_SAMPLE_URL,
-            ring_model=ring_model,
-            kol_name=kol_name,
-            base_name=base_name,
-            run_id=run_id,
-        )
-
-    return _run_measurement(
+    common_kwargs = dict(
         image=image,
-        finger_index=finger_index,
         input_image_url=DEFAULT_SAMPLE_URL,
-        ring_model=ring_model,
-        kol_name=kol_name,
+        ring_model=settings["ring_model"],
+        kol_name=settings["kol_name"],
         base_name=base_name,
         run_id=run_id,
     )
+    if settings["mode"] == "multi":
+        return _run_multi_measurement(**common_kwargs)
+    return _run_measurement(finger_index=settings["finger_index"], **common_kwargs)
 
 
 def _run_measurement(
@@ -264,14 +238,11 @@ def _run_measurement(
     input_image_url: str,
     ring_model: str = DEFAULT_RING_MODEL,
     kol_name: str = "",
-    upload_path: Path = None,
+    upload_path: Optional[Path] = None,
     upload_name: str = "",
     base_name: str = "",
     run_id: str = "",
 ):
-    if not base_name:
-        base_name, run_id = _make_base_name(kol_name)
-
     result_png_name = f"{base_name}_result.png"
     result_png_path = RESULTS_DIR / result_png_name
 
@@ -342,15 +313,12 @@ def _run_multi_measurement(
     input_image_url: str,
     ring_model: str = DEFAULT_RING_MODEL,
     kol_name: str = "",
-    upload_path: Path = None,
+    upload_path: Optional[Path] = None,
     upload_name: str = "",
     base_name: str = "",
     run_id: str = "",
 ):
     """Run multi-finger measurement pipeline."""
-    if not base_name:
-        base_name, run_id = _make_base_name(kol_name)
-
     result_png_name = f"{base_name}_result.png"
     result_png_path = RESULTS_DIR / result_png_name
 

web_demo/static/app.js

@@ -17,7 +17,7 @@ const failReasonMessageMap = {
   card_not_detected:
     "Card not detected. A card of standard credit card dimensions (85.6 × 54 mm) is required as a scale reference to measure your finger width. Place the card beside your hand on a plain white background (e.g. a sheet of paper), and turn on your phone's flash.",
   card_not_parallel:
-    "Card scale calibration failed. Use a standard-size card (same size as a credit/debit card) and keep your phone parallel to the card.",
+    "Card scale calibration failed. Use a card of standard credit card dimensions (85.6 × 54 mm) as the scale reference to measure your finger width, and keep your phone parallel to the card.",
   card_near_edge:
     "Card appears cropped. Place the entire card within the photo frame.",
   hand_not_detected:
@@ -121,6 +121,23 @@ const buildMeasureSettings = () => {
   };
 };
 
+const buildSizeRefTable = () => {
+  const ringModel = ringModelSelect ? ringModelSelect.value : "gen";
+  const sizeTable = RING_SIZE_TABLES[ringModel] || RING_SIZE_TABLES.gen;
+  const modelLabel = RING_MODEL_LABELS[ringModel] || ringModel;
+  const rows = Object.entries(sizeTable)
+    .map(([size, mm]) => `<tr><td>${size}</td><td>${mm.toFixed(1)}</td></tr>`)
+    .join("");
+  return `
+    <div class="size-ref-table">
+      <h3 class="size-ref-title">Size Reference (${modelLabel})</h3>
+      <table>
+        <thead><tr><th>Size</th><th>Inner ⌀ (mm)</th></tr></thead>
+        <tbody>${rows}</tbody>
+      </table>
+    </div>`;
+};
+
 const renderMultiResult = (result) => {
   if (!result || !result.per_finger) {
     overallSize.innerHTML = `<div class="size-hero"><span class="size-label">Measurement Failed</span></div>`;
@@ -158,23 +175,7 @@ const renderMultiResult = (result) => {
   }
   html += "</div>";
   html += `<div class="finger-count">${result.fingers_succeeded}/${result.fingers_measured} fingers measured</div>`;
-
-  // Size reference table (dynamic based on selected ring model)
-  const ringModel = ringModelSelect ? ringModelSelect.value : "gen";
-  const sizeTable = RING_SIZE_TABLES[ringModel] || RING_SIZE_TABLES.gen;
-  const modelLabel = RING_MODEL_LABELS[ringModel] || ringModel;
-  let tableRows = "";
-  for (const [size, mm] of Object.entries(sizeTable)) {
-    tableRows += `<tr><td>${size}</td><td>${mm.toFixed(1)}</td></tr>`;
-  }
-  html += `
-    <div class="size-ref-table">
-      <h3 class="size-ref-title">Size Reference (${modelLabel})</h3>
-      <table>
-        <thead><tr><th>Size</th><th>Inner ⌀ (mm)</th></tr></thead>
-        <tbody>${tableRows}</tbody>
-      </table>
-    </div>`;
+  html += buildSizeRefTable();
 
   fingerBreakdown.innerHTML = html;
 };
@@ -199,7 +200,7 @@ const renderSingleResult = (result) => {
   const fingerSelect = form.querySelector('[name="finger_index"]');
   const fingerName = fingerSelect ? fingerSelect.value : "finger";
   const capitalName = fingerName.charAt(0).toUpperCase() + fingerName.slice(1);
-  let html = `<div class="finger-cards">
+  fingerBreakdown.innerHTML = `<div class="finger-cards">
     <div class="finger-card" style="border-top: 3px solid #00dddd;">
       <div class="finger-name">${capitalName}</div>
       <div class="finger-size-label">Size</div>
@@ -207,26 +208,7 @@ const renderSingleResult = (result) => {
       <div class="finger-range">${rs.range_min} – ${rs.range_max}</div>
       <div class="finger-width">${diamMm} mm</div>
     </div>
-  </div>`;
-
-  // Size reference table
-  const ringModel = ringModelSelect ? ringModelSelect.value : "gen";
-  const sizeTable = RING_SIZE_TABLES[ringModel] || RING_SIZE_TABLES.gen;
-  const refLabel = RING_MODEL_LABELS[ringModel] || ringModel;
-  let tableRows = "";
-  for (const [size, mm] of Object.entries(sizeTable)) {
-    tableRows += `<tr><td>${size}</td><td>${mm.toFixed(1)}</td></tr>`;
-  }
-  html += `
-    <div class="size-ref-table">
-      <h3 class="size-ref-title">Size Reference (${refLabel})</h3>
-      <table>
-        <thead><tr><th>Size</th><th>Inner ⌀ (mm)</th></tr></thead>
-        <tbody>${tableRows}</tbody>
-      </table>
-    </div>`;
-
-  fingerBreakdown.innerHTML = html;
+  </div>` + buildSizeRefTable();
 };
 
 const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
@@ -248,12 +230,10 @@ const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
     });
 
     if (!response.ok) {
-      clearInterval(timerId);
-      const error = await response.json();
+      const error = await response.json().catch(() => ({}));
       setStatus(error.error || "Measurement failed", { error: true });
       return;
     }
-    clearInterval(timerId);
 
     const data = await response.json();
     jsonOutput.textContent = JSON.stringify(data.result, null, 2);
@@ -275,8 +255,9 @@ const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
       setStatus(formatFailReasonStatus(failReason), { error: true });
     }
   } catch (error) {
-    clearInterval(timerId);
     setStatus("Network error. Please retry.", { error: true });
+  } finally {
+    clearInterval(timerId);
   }
 };