Upload folder using huggingface_hub

AGENTS.md

@@ -213,6 +213,7 @@ For optimal results:
 - `hand_not_detected` — MediaPipe did not locate a hand
 - `card_not_detected` — classical or SAM card detector returned nothing
 - `card_not_parallel` — card detected but `scale_confidence ≤ 0.9` (too much perspective)
+- `card_too_small` — card detected but `longer_side_px / shorter_image_px < 0.25` (camera held too far from the table; see `doc/report/framing_ratio_survey.md`)
 - `finger_isolation_failed`, `finger_mask_too_small`, `contour_extraction_failed` — finger segmentation stages
 - `axis_estimation_failed` — landmarks missing or failed quality checks (NaN, collapsed, non-monotonic, below min length)
 - `zone_localization_failed` — ring zone could not be derived

CLAUDE.md

@@ -213,6 +213,7 @@ For optimal results:
 - `hand_not_detected` — MediaPipe did not locate a hand
 - `card_not_detected` — classical or SAM card detector returned nothing
 - `card_not_parallel` — card detected but `scale_confidence ≤ 0.9` (too much perspective)
+- `card_too_small` — card detected but `longer_side_px / shorter_image_px < 0.25` (camera held too far from the table; see `doc/report/framing_ratio_survey.md`)
 - `finger_isolation_failed`, `finger_mask_too_small`, `contour_extraction_failed` — finger segmentation stages
 - `axis_estimation_failed` — landmarks missing or failed quality checks (NaN, collapsed, non-monotonic, below min length)
 - `zone_localization_failed` — ring zone could not be derived

measure_finger.py

@@ -61,6 +61,14 @@ def apply_calibration(raw_diameter_cm: float) -> float:
     cal = _load_calibration()
     return cal["slope"] * raw_diameter_cm + cal["intercept"]
 
+# Minimum ratio of (longer card side) / (shorter image side). Below this
+# the camera is too far from the table: the card and finger occupy so few
+# pixels that edge refinement noise and calibration extrapolation both
+# start to dominate. See doc/report/framing_ratio_survey.md — calibration
+# was fit at ~0.48, production median is ~0.33; 0.25 flags the egregious
+# tail (~4% of historical uploads).
+MIN_CARD_LONG_SIDE_RATIO = 0.25
+
 # Type alias for finger selection
 FingerIndex = Literal["auto", "index", "middle", "ring", "pinky"]
 
@@ -672,6 +680,28 @@ def measure_finger(
                 fail_reason="card_not_parallel",
             )
 
+        longer_card_px = max(
+            float(card_result["width_px"]), float(card_result["height_px"])
+        )
+        shorter_image_px = float(min(image_canonical.shape[:2]))
+        card_long_side_ratio = longer_card_px / shorter_image_px
+        logger.info("card framing: long_side/short_image=%.3f", card_long_side_ratio)
+        if card_long_side_ratio < MIN_CARD_LONG_SIDE_RATIO:
+            logger.warning(
+                "card too small in frame (ratio=%.3f, required>=%.2f)",
+                card_long_side_ratio, MIN_CARD_LONG_SIDE_RATIO,
+            )
+            _write_card_failure_viz(
+                result_png_path, image_canonical, hand_data, card_result=card_result
+            )
+            return create_output(
+                card_detected=True,
+                finger_detected=False,
+                scale_px_per_cm=px_per_cm,
+                view_angle_ok=view_angle_ok,
+                fail_reason="card_too_small",
+            )
+
     # Phase 5: Finger isolation (hand already segmented in Phase 3).
     h_can, w_can = image_canonical.shape[:2]
     # Keep a reference to the raw SAM hand mask (pre-isolation polygon clip).
@@ -1302,6 +1332,22 @@ def measure_multi_finger(
             )
             return {"fail_reason": "card_not_parallel", "per_finger": {}, "fingers_measured": 0, "fingers_succeeded": 0}
 
+        longer_card_px = max(
+            float(card_result["width_px"]), float(card_result["height_px"])
+        )
+        shorter_image_px = float(min(image_canonical.shape[:2]))
+        card_long_side_ratio = longer_card_px / shorter_image_px
+        logger.info("[multi] card framing: long_side/short_image=%.3f", card_long_side_ratio)
+        if card_long_side_ratio < MIN_CARD_LONG_SIDE_RATIO:
+            logger.warning(
+                "[multi] card too small in frame (ratio=%.3f, required>=%.2f)",
+                card_long_side_ratio, MIN_CARD_LONG_SIDE_RATIO,
+            )
+            _write_card_failure_viz(
+                result_png_path, image_canonical, hand_data, card_result=card_result
+            )
+            return {"fail_reason": "card_too_small", "per_finger": {}, "fingers_measured": 0, "fingers_succeeded": 0}
+
         card_frame = check_card_in_frame(card_result["corners"], image_canonical.shape)
         if not card_frame["in_frame"]:
             logger.warning("[multi] card near edge (min_margin=%.0fpx)",

script/card_to_image_ratio.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Measure "longer card side / shorter image side" across an image dir.
+
+This metric approximates how large the reference card is in the frame: a
+low value means the camera was held far from the table (small card, thin
+edges, poorer calibration fit); a high value means close framing. Used to
+recommend a minimum framing ratio before the web demo accepts an upload.
+
+Runs the same SAM hand + SAM card pipeline as the web demo. Prints per-image
+values and a distribution summary (n, min, p10/25/50/75/90, max, mean, std,
+a coarse histogram, and success/failure counts).
+
+Usage:
+    source .venv/bin/activate
+    python3 script/card_to_image_ratio.py input/calibration_dataset/jpg
+    python3 script/card_to_image_ratio.py input/kol_success
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import statistics as stats
+import sys
+import time
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import cv2
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from src.finger_segmentation import segment_hand  # noqa: E402
+from src.sam_card_detection import (  # noqa: E402
+    detect_credit_card_sam_prompt,
+    suggest_card_seeds,
+)
+
+IMG_EXTS = {".jpg", ".jpeg", ".png"}
+
+
+def _process_image(path: Path) -> Tuple[Optional[float], str]:
+    """Return (ratio_or_None, status_tag) for a single image."""
+    img = cv2.imread(str(path))
+    if img is None:
+        return None, "load_failed"
+
+    try:
+        hand_data = segment_hand(img)
+    except Exception as e:
+        return None, f"hand_error:{type(e).__name__}"
+    if hand_data is None:
+        return None, "hand_not_detected"
+
+    canonical = hand_data.get("canonical_image", img)
+    hand_mask = hand_data.get("mask")
+    landmarks = hand_data.get("landmarks")
+    if hand_mask is None or landmarks is None or len(landmarks) <= 9:
+        return None, "no_landmarks"
+
+    y_limit = int(round(landmarks[9, 1]))
+    seed_info = suggest_card_seeds(hand_mask, canonical.shape[:2], y_limit)
+    seeds = seed_info["kept"]
+    if not seeds:
+        return None, "no_seeds"
+
+    palm_c = np.mean(landmarks[[0, 5, 9, 13, 17], :2], axis=0)
+    negatives = [(int(round(palm_c[0])), int(round(palm_c[1])))]
+
+    try:
+        card = detect_credit_card_sam_prompt(
+            canonical,
+            seed_points=seeds,
+            negative_points=negatives,
+            hand_mask=hand_mask,
+        )
+    except Exception as e:
+        return None, f"card_error:{type(e).__name__}"
+    if card is None:
+        return None, "card_not_detected"
+
+    longer = max(float(card["width_px"]), float(card["height_px"]))
+    shorter_image = float(min(canonical.shape[0], canonical.shape[1]))
+    return longer / shorter_image, "ok"
+
+
+def _describe(values: List[float], label: str) -> None:
+    if not values:
+        print(f"\n{label}: no successful measurements.")
+        return
+
+    values_sorted = sorted(values)
+    n = len(values_sorted)
+
+    def pct(p: float) -> float:
+        if n == 1:
+            return values_sorted[0]
+        k = (n - 1) * p
+        lo = int(k)
+        hi = min(lo + 1, n - 1)
+        frac = k - lo
+        return values_sorted[lo] * (1 - frac) + values_sorted[hi] * frac
+
+    print(f"\n=== {label} (n={n}) ===")
+    print(f"  min    = {min(values_sorted):.3f}")
+    print(f"  p10    = {pct(0.10):.3f}")
+    print(f"  p25    = {pct(0.25):.3f}")
+    print(f"  median = {pct(0.50):.3f}")
+    print(f"  p75    = {pct(0.75):.3f}")
+    print(f"  p90    = {pct(0.90):.3f}")
+    print(f"  max    = {max(values_sorted):.3f}")
+    print(f"  mean   = {stats.mean(values_sorted):.3f}")
+    if n > 1:
+        print(f"  std    = {stats.stdev(values_sorted):.3f}")
+
+    # Coarse histogram, 0.05-wide bins across the realistic range.
+    lo_edge = 0.10
+    hi_edge = max(0.65, max(values_sorted) + 0.05)
+    bin_w = 0.05
+    edges = []
+    e = lo_edge
+    while e <= hi_edge + 1e-9:
+        edges.append(round(e, 2))
+        e += bin_w
+    counts = [0] * (len(edges) - 1)
+    under = over = 0
+    for v in values_sorted:
+        if v < edges[0]:
+            under += 1
+            continue
+        placed = False
+        for i in range(len(edges) - 1):
+            if edges[i] <= v < edges[i + 1]:
+                counts[i] += 1
+                placed = True
+                break
+        if not placed:
+            over += 1
+    print("  histogram:")
+    if under:
+        print(f"    <{edges[0]:.2f}         : {under}")
+    for i, c in enumerate(counts):
+        if c == 0:
+            continue
+        bar = "#" * c
+        print(f"    [{edges[i]:.2f},{edges[i+1]:.2f}) : {c:2d}  {bar}")
+    if over:
+        print(f"    >={edges[-1]:.2f}        : {over}")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("image_dir", type=Path)
+    ap.add_argument("--limit", type=int, default=None,
+                    help="optional cap on number of images processed")
+    args = ap.parse_args()
+
+    logging.getLogger().setLevel(logging.ERROR)  # silence pipeline chatter
+
+    if not args.image_dir.is_dir():
+        print(f"Not a directory: {args.image_dir}")
+        return 1
+
+    images = sorted(
+        p for p in args.image_dir.iterdir()
+        if p.suffix.lower() in IMG_EXTS
+    )
+    if args.limit:
+        images = images[: args.limit]
+    if not images:
+        print(f"No images found in {args.image_dir}")
+        return 1
+
+    print(f"Processing {len(images)} images from {args.image_dir}")
+    print(f"{'#':>3}  {'file':<60} {'ratio':>6}  status")
+
+    ratios: List[float] = []
+    status_counts = {}
+    t_start = time.time()
+    for i, path in enumerate(images, 1):
+        t0 = time.time()
+        ratio, status = _process_image(path)
+        dt = time.time() - t0
+        status_counts[status] = status_counts.get(status, 0) + 1
+        ratio_str = f"{ratio:.3f}" if ratio is not None else "  -  "
+        print(f"{i:>3}  {path.name:<60} {ratio_str:>6}  {status}  ({dt:.1f}s)")
+        if ratio is not None:
+            ratios.append(ratio)
+
+    total_dt = time.time() - t_start
+    print(f"\nElapsed: {total_dt:.1f}s ({total_dt / max(1, len(images)):.1f}s/img)")
+    print(f"Status summary: {status_counts}")
+    _describe(ratios, label=f"ratio = longer_card_px / shorter_image_px  ({args.image_dir})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

web_demo/static/app.js

@@ -20,6 +20,8 @@ const failReasonMessageMap = {
     "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.",
+  card_too_small:
+    "Card looks too small in the photo. Move your phone closer to the table so the card takes up a larger portion of the frame, then retake.",
   hand_not_detected:
     "Hand not detected. Place your hand flat on a plain white background (e.g. a sheet of paper), and spread your fingers naturally.",
   finger_isolation_failed: