Upload folder using huggingface_hub

.gitignore

@@ -5,6 +5,7 @@ __pycache__/
 *.so
 .Python
 .venv/
+.env/
 ENV/
 
 # IDE
@@ -36,3 +37,4 @@ input/*.heic
 # OS
 .DS_Store
 Thumbs.db
+

=1.0.0

@@ -0,0 +1,29 @@
+Collecting openai
+  Downloading openai-2.30.0-py3-none-any.whl (1.1 MB)
+Requirement already satisfied: typing-extensions<5,>=4.11 in ./.venv/lib/python3.9/site-packages (from openai) (4.15.0)
+Collecting jiter<1,>=0.10.0
+  Using cached jiter-0.13.0-cp39-cp39-macosx_11_0_arm64.whl (309 kB)
+Requirement already satisfied: httpx<1,>=0.23.0 in ./.venv/lib/python3.9/site-packages (from openai) (0.28.1)
+Requirement already satisfied: anyio<5,>=3.5.0 in ./.venv/lib/python3.9/site-packages (from openai) (4.12.1)
+Collecting distro<2,>=1.7.0
+  Using cached distro-1.9.0-py3-none-any.whl (20 kB)
+Collecting sniffio
+  Using cached sniffio-1.3.1-py3-none-any.whl (10 kB)
+Requirement already satisfied: tqdm>4 in ./.venv/lib/python3.9/site-packages (from openai) (4.67.3)
+Collecting pydantic<3,>=1.9.0
+  Using cached pydantic-2.12.5-py3-none-any.whl (463 kB)
+Requirement already satisfied: exceptiongroup>=1.0.2 in ./.venv/lib/python3.9/site-packages (from anyio<5,>=3.5.0->openai) (1.3.1)
+Requirement already satisfied: idna>=2.8 in ./.venv/lib/python3.9/site-packages (from anyio<5,>=3.5.0->openai) (3.11)
+Requirement already satisfied: httpcore==1.* in ./.venv/lib/python3.9/site-packages (from httpx<1,>=0.23.0->openai) (1.0.9)
+Requirement already satisfied: certifi in ./.venv/lib/python3.9/site-packages (from httpx<1,>=0.23.0->openai) (2026.1.4)
+Requirement already satisfied: h11>=0.16 in ./.venv/lib/python3.9/site-packages (from httpcore==1.*->httpx<1,>=0.23.0->openai) (0.16.0)
+Collecting annotated-types>=0.6.0
+  Using cached annotated_types-0.7.0-py3-none-any.whl (13 kB)
+Collecting typing-inspection>=0.4.2
+  Using cached typing_inspection-0.4.2-py3-none-any.whl (14 kB)
+Collecting pydantic-core==2.41.5
+  Using cached pydantic_core-2.41.5-cp39-cp39-macosx_11_0_arm64.whl (1.9 MB)
+Installing collected packages: typing-inspection, pydantic-core, annotated-types, sniffio, pydantic, jiter, distro, openai
+Successfully installed annotated-types-0.7.0 distro-1.9.0 jiter-0.13.0 openai-2.30.0 pydantic-2.12.5 pydantic-core-2.41.5 sniffio-1.3.1 typing-inspection-0.4.2
+WARNING: You are using pip version 21.2.4; however, version 26.0.1 is available.
+You should consider upgrading via the '/Users/fengxie/Build/ring-size-cv/.venv/bin/python3 -m pip install --upgrade pip' command.

README.md

@@ -9,7 +9,7 @@ app_port: 7860
 
 # Ring Sizer
 
-Local computer-vision CLI tool that measures **finger outer diameter** from a single image using a **credit card** as scale reference.
+Local computer-vision CLI tool that measures **finger outer diameter** from a single image using a **credit card** as scale reference. Achieves **±0.5 mm** diameter accuracy and **0% return rate** on a 10-subject evaluation (N=20 images).
 
 ## Live Demo
 - Hugging Face Space: [https://huggingface.co/spaces/feng-x/ring-sizer](https://huggingface.co/spaces/feng-x/ring-sizer)
@@ -21,6 +21,9 @@ Local computer-vision CLI tool that measures **finger outer diameter** from a si
 - Detects hand/finger with MediaPipe.
 - Measures finger width in the ring-wearing zone.
 - **Regression calibration** corrects systematic over-measurement (MAE: 0.158 → 0.060 cm).
+- **Ring size recommendation** maps calibrated diameter to China standard sizes 6–13 (best match + 2-size range).
+- **Multi-finger mode** measures index, middle, and ring fingers in one pass; consensus aggregation maximizes the chance at least one finger fits.
+- **Optional AI explanation** (OpenAI) generates a human-readable rationale for the recommendation (size selection is always deterministic).
 - Supports dual edge modes:
   - `contour` (v0 baseline)
   - `sobel` (v1 sub-pixel refinement)
@@ -40,7 +43,20 @@ Validated on 10 subjects × 3 fingers × 2 photos = 60 measurements against cali
 
 Pipeline stability: card detection CV = 0.44%, shot-to-shot repeatability = 0.028 cm.
 
-See full report: [`doc/report/calibration_report.md`](doc/report/calibration_report.md)
+### Ring Size Recommendation
+
+Evaluated on 10 subjects × 2 photos = 20 images in multi-finger mode.
+
+| Metric | Value |
+|--------|-------|
+| Return rate (fits no finger) | **0%** (0/20) |
+| Exact size match | 55% (11/20) |
+| Within ±1 size | 100% (20/20) |
+| A/B photo consistency | 90% (9/10 same size) |
+
+See full analysis: [`doc/algorithms/08-ring-size-recommendation.md`](doc/algorithms/08-ring-size-recommendation.md)
+
+See calibration report: [`doc/report/calibration_report.md`](doc/report/calibration_report.md)
 
 ## Install
 ```bash
@@ -51,7 +67,11 @@ pip install -r requirements.txt
 
 ## Run
 ```bash
+# Single finger (default)
 python measure_finger.py --input input/test_image.jpg --output output/result.json
+
+# Multi-finger (recommended) — measures index, middle, ring in one pass
+python measure_finger.py --input input/test_image.jpg --output output/result.json --mode multi
 ```
 
 ### Common options
@@ -83,7 +103,8 @@ python measure_finger.py --input image.jpg --output output/result.json \
 | `--input` | path | *(required)* | Input image (JPG/PNG) |
 | `--output` | path | *(required)* | Output JSON path |
 | `--debug` | flag | false | Save intermediate debug images |
-| `--finger-index` | auto, index, middle, ring, pinky | index | Which finger to measure |
+| `--finger-index` | auto, index, middle, ring, pinky | index | Which finger to measure (single mode) |
+| `--mode` | single, multi | single | Single finger or all 3 fingers |
 | `--confidence-threshold` | float | 0.7 | Minimum confidence threshold |
 | `--edge-method` | auto, contour, sobel, compare | auto | Edge detection method |
 | `--sobel-threshold` | float | 15.0 | Minimum gradient magnitude |
@@ -106,12 +127,20 @@ python measure_finger.py --input image.jpg --output output/result.json \
   "fail_reason": null,
   "edge_method_used": "sobel",
   "raw_diameter_cm": 1.92,
-  "calibration_applied": true
+  "calibration_applied": true,
+  "ring_size": {
+    "best_match": 8,
+    "best_match_inner_mm": 18.6,
+    "range_min": 8,
+    "range_max": 9,
+    "diameter_mm": 17.80
+  }
 }
 ```
 
 Notes:
 - `raw_diameter_cm` is the pre-calibration measurement (present when calibration is applied).
+- `ring_size` maps calibrated diameter to China standard sizes 6–13 (nearest match + 2-size recommended range).
 - `edge_method_used` and `method_comparison` are optional (present when relevant).
 - Result image path is auto-derived: `output/result.json` → `output/result.png`.
 
@@ -121,7 +150,8 @@ Notes:
 | [`doc/v0/`](doc/v0/) | v0 PRD, Plan, Progress (contour baseline) |
 | [`doc/v1/`](doc/v1/) | v1 PRD, Plan, Progress (Sobel edge refinement) |
 | [`doc/v2/`](doc/v2/) | v2 Plan, Progress (calibration & regression) |
-| [`doc/report/`](doc/report/) | Validation & calibration report |
+| [`doc/v3/`](doc/v3/) | v3 Progress (multi-finger, quality checks, AI explanation) |
+| [`doc/report/`](doc/report/) | Validation, calibration & ring size mapping reports |
 | [`doc/algorithms/`](doc/algorithms/) | Algorithm documentation |
 | [`script/`](script/) | Batch measurement & analysis scripts |
 | [`web_demo/`](web_demo/) | Web demo (Flask) |

measure_finger.py

@@ -31,7 +31,13 @@ from src.confidence import (
     compute_overall_confidence,
 )
 from src.debug_observer import draw_comprehensive_edge_overlay
-from src.ring_size import recommend_ring_size
+from src.ring_size import recommend_ring_size, aggregate_ring_sizes
+from src.image_quality import (
+    check_card_in_frame,
+    check_finger_landmarks_visible,
+    check_finger_spacing,
+    check_lighting_uniformity,
+)
 
 # Calibration coefficients (from regression on 60 measurements)
 _CALIBRATION_PATH = Path(__file__).parent / "src" / "calibration.json"
@@ -131,6 +137,15 @@ Examples:
         help="Disable sub-pixel edge refinement",
     )
 
+    # Measurement mode
+    parser.add_argument(
+        "--mode",
+        type=str,
+        choices=["single", "multi"],
+        default="single",
+        help="Measurement mode: single (one finger) or multi (index+middle+ring at once) (default: single)",
+    )
+
     # Calibration
     parser.add_argument(
         "--no-calibration",
@@ -752,6 +767,517 @@ def measure_finger(
     )
 
 
+MULTI_FINGERS = ["index", "middle", "ring"]
+
+
+def _measure_single_finger_from_shared(
+    image_canonical: np.ndarray,
+    hand_data: Dict[str, Any],
+    finger_name: str,
+    px_per_cm: float,
+    card_detected: bool,
+    view_angle_ok: bool,
+    card_result: Optional[Dict[str, Any]],
+    scale_confidence: float,
+    edge_method: str = "sobel",
+    sobel_threshold: float = 15.0,
+    sobel_kernel_size: int = 3,
+    use_subpixel: bool = True,
+) -> Dict[str, Any]:
+    """Measure a single finger using pre-computed hand/card data.
+
+    Internal helper for measure_multi_finger(). Runs phases 4-8 only.
+    """
+    from src.geometry import (
+        calculate_angle_from_vertical,
+        rotate_image_precise,
+        rotate_axis_data,
+        rotate_contour,
+        transform_points_rotation,
+    )
+
+    h_can, w_can = image_canonical.shape[:2]
+    finger_data = isolate_finger(hand_data, finger=finger_name, image_shape=(h_can, w_can))
+
+    if finger_data is None:
+        return create_output(
+            card_detected=card_detected, finger_detected=False,
+            scale_px_per_cm=px_per_cm, view_angle_ok=view_angle_ok,
+            fail_reason="finger_isolation_failed",
+        )
+
+    cleaned_mask = clean_mask(finger_data["mask"])
+    if cleaned_mask is None:
+        return create_output(
+            card_detected=card_detected, finger_detected=False,
+            scale_px_per_cm=px_per_cm, view_angle_ok=view_angle_ok,
+            fail_reason="finger_mask_too_small",
+        )
+
+    contour = get_finger_contour(cleaned_mask)
+    if contour is None:
+        return create_output(
+            card_detected=card_detected, finger_detected=False,
+            scale_px_per_cm=px_per_cm, view_angle_ok=view_angle_ok,
+            fail_reason="contour_extraction_failed",
+        )
+
+    # Axis estimation
+    try:
+        axis_data = estimate_finger_axis(
+            mask=cleaned_mask, landmarks=finger_data.get("landmarks"),
+        )
+    except Exception:
+        return create_output(
+            card_detected=card_detected, finger_detected=True,
+            scale_px_per_cm=px_per_cm, view_angle_ok=view_angle_ok,
+            fail_reason="axis_estimation_failed",
+        )
+
+    # Precise rotation to vertical
+    img_work = image_canonical.copy()
+    angle_from_vertical = calculate_angle_from_vertical(axis_data["direction"])
+    if abs(angle_from_vertical) >= 0.0:
+        rot_center = (w_can / 2.0, h_can / 2.0)
+        img_work, rotation_matrix = rotate_image_precise(img_work, angle_from_vertical, rot_center)
+        axis_data = rotate_axis_data(axis_data, rotation_matrix)
+        contour = rotate_contour(contour, rotation_matrix)
+        if finger_data.get("landmarks") is not None:
+            finger_data["landmarks"] = transform_points_rotation(finger_data["landmarks"], rotation_matrix)
+        cleaned_mask = cv2.warpAffine(
+            cleaned_mask, rotation_matrix, (w_can, h_can),
+            flags=cv2.INTER_NEAREST, borderMode=cv2.BORDER_CONSTANT, borderValue=0,
+        )
+
+    # Ring zone
+    try:
+        landmarks = finger_data.get("landmarks")
+        if landmarks is not None and len(landmarks) == 4:
+            zone_data = localize_ring_zone_from_landmarks(
+                landmarks=landmarks, axis_data=axis_data, zone_type="anatomical",
+            )
+        else:
+            zone_data = localize_ring_zone(axis_data)
+    except Exception:
+        return create_output(
+            card_detected=card_detected, finger_detected=True,
+            scale_px_per_cm=px_per_cm, view_angle_ok=view_angle_ok,
+            fail_reason="zone_localization_failed",
+        )
+
+    # Contour measurement
+    try:
+        contour_measurement = compute_cross_section_width(
+            contour=contour, axis_data=axis_data, zone_data=zone_data, num_samples=20,
+        )
+        contour_width_cm = contour_measurement["median_width_px"] / px_per_cm
+    except Exception:
+        return create_output(
+            card_detected=card_detected, finger_detected=True,
+            scale_px_per_cm=px_per_cm, view_angle_ok=view_angle_ok,
+            fail_reason="width_measurement_failed", edge_method_used="contour",
+        )
+
+    # Sobel measurement
+    sobel_measurement = None
+    sobel_failed = False
+    if edge_method in ["sobel", "auto", "compare"]:
+        try:
+            sobel_measurement = refine_edges_sobel(
+                image=img_work, axis_data=axis_data, zone_data=zone_data,
+                scale_px_per_cm=px_per_cm, finger_landmarks=finger_data.get("landmarks"),
+                sobel_threshold=sobel_threshold, kernel_size=sobel_kernel_size,
+                use_subpixel=use_subpixel,
+            )
+        except Exception:
+            sobel_failed = True
+            if edge_method == "sobel":
+                return create_output(
+                    card_detected=card_detected, finger_detected=True,
+                    scale_px_per_cm=px_per_cm, view_angle_ok=view_angle_ok,
+                    fail_reason="sobel_edge_refinement_failed", edge_method_used="sobel",
+                )
+
+    # Select method
+    if edge_method == "contour":
+        median_width_cm = contour_width_cm
+        edge_method_used = "contour"
+        final_measurement = contour_measurement
+    elif edge_method == "sobel" and sobel_measurement:
+        median_width_cm = sobel_measurement["median_width_cm"]
+        edge_method_used = "sobel"
+        final_measurement = sobel_measurement
+    elif edge_method == "auto":
+        if sobel_measurement and not sobel_failed:
+            should_use, _ = should_use_sobel_measurement(sobel_measurement, contour_measurement)
+            if should_use:
+                median_width_cm = sobel_measurement["median_width_cm"]
+                edge_method_used = "sobel"
+                final_measurement = sobel_measurement
+            else:
+                median_width_cm = contour_width_cm
+                edge_method_used = "contour_fallback"
+                final_measurement = contour_measurement
+        else:
+            median_width_cm = contour_width_cm
+            edge_method_used = "contour_fallback"
+            final_measurement = contour_measurement
+    else:
+        median_width_cm = contour_width_cm
+        edge_method_used = "contour_fallback"
+        final_measurement = contour_measurement
+
+    # Confidence
+    if card_result is not None:
+        card_conf = compute_card_confidence(card_result, scale_confidence)
+    else:
+        card_conf = scale_confidence
+    mask_area = int(np.sum(cleaned_mask > 0))
+    image_area = image_canonical.shape[0] * image_canonical.shape[1]
+    finger_conf = compute_finger_confidence(hand_data, finger_data, mask_area, image_area)
+    measurement_conf = compute_measurement_confidence(final_measurement, median_width_cm)
+    edge_quality_conf = None
+    if edge_method_used in ["sobel", "compare"]:
+        edge_quality_conf = compute_edge_quality_confidence(final_measurement.get("edge_quality"))
+    confidence_breakdown = compute_overall_confidence(
+        card_conf, finger_conf, measurement_conf,
+        edge_method="sobel" if edge_method_used in ["sobel", "compare"] else "contour",
+        edge_quality_confidence=edge_quality_conf,
+    )
+
+    result = create_output(
+        finger_diameter_cm=median_width_cm,
+        confidence=confidence_breakdown["overall"],
+        card_detected=card_detected, finger_detected=True,
+        scale_px_per_cm=px_per_cm, view_angle_ok=view_angle_ok,
+        edge_method_used=edge_method_used,
+    )
+    # Attach intermediate data for debug viz
+    result["_internal"] = {
+        "contour": contour, "axis_data": axis_data, "zone_data": zone_data,
+        "finger_data": finger_data, "cleaned_mask": cleaned_mask,
+        "sobel_measurement": sobel_measurement, "contour_measurement": contour_measurement,
+        "final_measurement": final_measurement, "image_work": img_work,
+        "rotation_matrix": rotation_matrix,
+    }
+    return result
+
+
+def measure_multi_finger(
+    image: np.ndarray,
+    confidence_threshold: float = 0.7,
+    result_png_path: Optional[str] = None,
+    save_debug: bool = False,
+    edge_method: str = "sobel",
+    sobel_threshold: float = 15.0,
+    sobel_kernel_size: int = 3,
+    use_subpixel: bool = True,
+    skip_card_detection: bool = False,
+    no_calibration: bool = False,
+) -> Dict[str, Any]:
+    """Measure index, middle, and ring fingers from a single image.
+
+    Runs shared setup (image quality, hand detection, card detection) once,
+    then measures each finger independently.
+
+    Returns:
+        Dict with aggregated ring size recommendation + per-finger breakdown.
+    """
+    from src.finger_segmentation import FINGER_LANDMARKS
+
+    # Phase 1: Image quality
+    quality = assess_image_quality(image)
+    print(f"[multi] Image quality: blur={quality['blur_score']:.1f}, "
+          f"brightness={quality['brightness']:.1f}, contrast={quality['contrast']:.1f}")
+    if not quality["passed"]:
+        for issue in quality["issues"]:
+            print(f"  Warning: {issue}")
+        return {"fail_reason": quality["fail_reason"], "per_finger": {}, "fingers_measured": 0, "fingers_succeeded": 0}
+
+    # Lighting uniformity check
+    lighting = check_lighting_uniformity(image)
+    if not lighting["uniform"]:
+        print(f"[multi] Warning: Uneven lighting (range={lighting['brightness_range']:.1f})")
+
+    # Phase 2: Hand detection (use "index" for orientation — canonical for all)
+    finger_debug_dir = None
+    if save_debug and result_png_path is not None:
+        finger_debug_dir = str(Path(result_png_path).parent / "finger_segmentation_debug")
+
+    hand_data = segment_hand(image, finger="index", debug_dir=finger_debug_dir)
+    if hand_data is None:
+        print("[multi] No hand detected")
+        return {"fail_reason": "hand_not_detected", "per_finger": {}, "fingers_measured": 0, "fingers_succeeded": 0}
+
+    print(f"[multi] Hand detected: {hand_data['handedness']}, confidence={hand_data['confidence']:.2f}")
+    image_canonical = hand_data.get("canonical_image", image)
+
+    # Phase 3: Card detection
+    card_debug_dir = None
+    if save_debug and result_png_path is not None:
+        card_debug_dir = str(Path(result_png_path).parent / "card_detection_debug")
+
+    if skip_card_detection:
+        card_result = None
+        px_per_cm = 100.0
+        scale_confidence = 0.5
+        view_angle_ok = True
+        card_detected = False
+    else:
+        card_result = detect_credit_card(image_canonical, debug_dir=card_debug_dir)
+        if card_result is None:
+            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:
+            return {"fail_reason": "card_not_parallel", "per_finger": {}, "fingers_measured": 0, "fingers_succeeded": 0}
+
+        # Card in-frame check
+        card_frame = check_card_in_frame(card_result["corners"], image_canonical.shape)
+        if not card_frame["in_frame"]:
+            print(f"[multi] Warning: Card near edge (min_margin={card_frame['min_margin_px']:.0f}px)")
+
+    # Multi-finger quality: check spacing
+    h_can, w_can = image_canonical.shape[:2]
+    all_finger_landmarks = {}
+    for fn in MULTI_FINGERS:
+        indices = FINGER_LANDMARKS[fn]
+        lm = hand_data["landmarks"][indices]
+        all_finger_landmarks[fn] = lm
+
+    spacing = check_finger_spacing(all_finger_landmarks, image_canonical.shape)
+    if not spacing["well_spaced"]:
+        pair = spacing.get("closest_pair", ("", ""))
+        print(f"[multi] Warning: Fingers too close ({pair[0]}, {pair[1]}, {spacing['min_spacing_px']:.0f}px)")
+
+    # Measure each finger
+    per_finger_raw: Dict[str, Dict] = {}
+    for fn in MULTI_FINGERS:
+        print(f"\n[multi] === Measuring {fn} finger ===")
+        result = _measure_single_finger_from_shared(
+            image_canonical=image_canonical,
+            hand_data=hand_data,
+            finger_name=fn,
+            px_per_cm=px_per_cm,
+            card_detected=card_detected,
+            view_angle_ok=view_angle_ok,
+            card_result=card_result,
+            scale_confidence=scale_confidence,
+            edge_method=edge_method,
+            sobel_threshold=sobel_threshold,
+            sobel_kernel_size=sobel_kernel_size,
+            use_subpixel=use_subpixel,
+        )
+
+        # Apply calibration
+        raw_diam = result.get("finger_outer_diameter_cm")
+        if raw_diam is not None and not no_calibration:
+            calibrated = apply_calibration(raw_diam)
+            result["finger_outer_diameter_cm"] = round(calibrated, 4)
+            result["raw_diameter_cm"] = round(raw_diam, 4)
+            result["calibration_applied"] = True
+        else:
+            result["calibration_applied"] = False
+
+        # Ring size per finger
+        diam = result.get("finger_outer_diameter_cm")
+        if diam is not None:
+            rec = recommend_ring_size(diam)
+            if rec:
+                result["ring_size"] = rec
+
+        per_finger_raw[fn] = result
+
+    # Aggregate
+    aggregated = aggregate_ring_sizes(per_finger_raw)
+
+    # Build debug visualization
+    if result_png_path is not None:
+        _draw_multi_finger_debug(
+            image_canonical=image_canonical,
+            per_finger_raw=per_finger_raw,
+            aggregated=aggregated,
+            card_result=card_result,
+            px_per_cm=px_per_cm,
+            result_png_path=result_png_path,
+        )
+
+    # Clean internal data from output
+    for fn, r in per_finger_raw.items():
+        r.pop("_internal", None)
+
+    aggregated["scale_px_per_cm"] = round(px_per_cm, 2)
+    aggregated["quality_flags"] = {
+        "card_detected": card_detected,
+        "view_angle_ok": view_angle_ok,
+        "lighting_uniform": lighting.get("uniform", True),
+        "fingers_well_spaced": spacing.get("well_spaced", True),
+    }
+    return aggregated
+
+
+def _draw_multi_finger_debug(
+    image_canonical: np.ndarray,
+    per_finger_raw: Dict[str, Dict],
+    aggregated: Dict[str, Any],
+    card_result: Optional[Dict[str, Any]],
+    px_per_cm: float,
+    result_png_path: str,
+) -> None:
+    """Generate debug visualization for multi-finger measurement.
+
+    Draws per-finger Sobel edge detection overlays (edge dots, width lines,
+    ROI boxes) on the canonical image, matching single-finger viz quality.
+    """
+    from src.visualization import draw_card_overlay, get_scaled_font_params
+    from src.viz_constants import Color, FONT_FACE
+
+    FINGER_COLORS = {
+        "index": (255, 255, 0),    # Cyan (BGR)
+        "middle": (0, 255, 0),     # Green
+        "ring": (255, 0, 255),     # Magenta
+    }
+
+    vis = image_canonical.copy()
+    h, w = vis.shape[:2]
+
+    # Draw card
+    if card_result is not None:
+        vis = draw_card_overlay(vis, card_result, px_per_cm)
+
+    # Draw per-finger Sobel edge overlays
+    for fn, result in per_finger_raw.items():
+        internal = result.get("_internal")
+        if internal is None:
+            continue
+        color = FINGER_COLORS.get(fn, Color.FINGER)
+        sobel = internal.get("sobel_measurement")
+        rot_mat = internal.get("rotation_matrix")
+        axis_data = internal["axis_data"]
+        zone_data = internal["zone_data"]
+        contour = internal["contour"]
+
+        # Compute inverse rotation to map per-finger coords back to canonical
+        inv_mat = None
+        if rot_mat is not None:
+            inv_mat = cv2.invertAffineTransform(rot_mat)
+
+        def to_canonical(pt):
+            """Transform a point from per-finger rotated coords to canonical."""
+            if inv_mat is None:
+                return pt
+            p = np.array([pt[0], pt[1], 1.0], dtype=np.float64)
+            return inv_mat @ p
+
+        # Draw Sobel edge detection details if available
+        if sobel is not None and "edge_data" in sobel and "roi_data" in sobel:
+            edge_data = sobel["edge_data"]
+            roi_bounds = sobel["roi_data"]["roi_bounds"]
+            left_edges = edge_data["left_edges"]
+            right_edges = edge_data["right_edges"]
+            valid_rows = edge_data["valid_rows"]
+            x_min, y_min, x_max, y_max = roi_bounds
+
+            # ROI box (transform corners to canonical)
+            roi_corners = np.array([
+                [x_min, y_min], [x_max, y_min],
+                [x_max, y_max], [x_min, y_max],
+            ], dtype=np.float64)
+            if inv_mat is not None:
+                roi_hom = np.hstack([roi_corners, np.ones((4, 1))]).T
+                roi_can = (inv_mat @ roi_hom).T.astype(np.int32).reshape((-1, 1, 2))
+            else:
+                roi_can = roi_corners.astype(np.int32).reshape((-1, 1, 2))
+            cv2.polylines(vis, [roi_can], isClosed=True, color=color, thickness=1, lineType=cv2.LINE_AA)
+
+            # Edge dots and width measurement lines
+            valid_count = int(np.sum(valid_rows))
+            line_spacing = max(1, valid_count // 20)
+            count = 0
+            for row_idx, valid in enumerate(valid_rows):
+                if not valid:
+                    continue
+                gy = y_min + row_idx
+                lx = x_min + int(left_edges[row_idx])
+                rx = x_min + int(right_edges[row_idx])
+
+                left_can = to_canonical(np.array([lx, gy])).astype(np.int32)
+                right_can = to_canonical(np.array([rx, gy])).astype(np.int32)
+
+                # Edge dots (small, using finger color)
+                cv2.circle(vis, tuple(left_can), 2, Color.BLUE, -1)
+                cv2.circle(vis, tuple(right_can), 2, Color.MAGENTA, -1)
+
+                # Width measurement lines (every Nth row)
+                if count % line_spacing == 0:
+                    cv2.line(vis, tuple(left_can), tuple(right_can),
+                             Color.GREEN, 1, cv2.LINE_AA)
+                count += 1
+
+    # --- Text overlay panel ---
+    params = get_scaled_font_params(h)
+    lh = params["line_height"]
+    fs = params["font_scale"]
+    th = params["text_thickness"]
+
+    # Build text lines
+    lines = []
+    lines.append(("=== MULTI-FINGER MEASUREMENT ===", Color.TEXT_PRIMARY))
+    if aggregated.get("fail_reason") is None:
+        lines.append((f"Overall Best Size: {aggregated['overall_best_size']}", Color.TEXT_SUCCESS))
+        lines.append((f"Recommended Range: {aggregated['overall_range_min']}-{aggregated['overall_range_max']}", Color.TEXT_PRIMARY))
+    lines.append(("", None))
+
+    for fn in MULTI_FINGERS:
+        pf = aggregated.get("per_finger", {}).get(fn, {})
+        fcolor = FINGER_COLORS.get(fn, Color.TEXT_PRIMARY)
+        status = pf.get("status", "failed")
+        if status == "ok":
+            text = f"{fn.capitalize()}: {pf['diameter_cm']:.2f}cm -> Size {pf['best_match']} ({pf['range'][0]}-{pf['range'][1]})"
+        else:
+            reason = pf.get("fail_reason", "unknown")
+            text = f"{fn.capitalize()}: FAILED ({reason})"
+        lines.append((text, fcolor))
+
+    lines.append(("", None))
+    succeeded = aggregated.get("fingers_succeeded", 0)
+    measured = aggregated.get("fingers_measured", 0)
+    lines.append((f"Fingers: {succeeded}/{measured} succeeded", Color.TEXT_PRIMARY))
+    lines.append(("", None))
+    lines.append(("Legend:", Color.YELLOW))
+    lines.append(("  Blue dots = Left edges", Color.WHITE))
+    lines.append(("  Magenta dots = Right edges", Color.WHITE))
+    lines.append(("  Green lines = Width measurements", Color.WHITE))
+
+    # Compute text panel size
+    panel_h = lh * len(lines) + 20
+    panel_w = 0
+    for text, _ in lines:
+        if text:
+            (tw, _), _ = cv2.getTextSize(text, FONT_FACE, fs, th)
+            panel_w = max(panel_w, tw)
+    panel_w += 40
+
+    # Draw semi-transparent background
+    overlay = vis.copy()
+    cv2.rectangle(overlay, (10, 10), (10 + panel_w, 10 + panel_h), (0, 0, 0), -1)
+    cv2.addWeighted(overlay, 0.7, vis, 0.3, 0, vis)
+
+    # Draw text
+    x = params["x_offset"]
+    y = params["y_start"]
+    for text, text_color in lines:
+        if text:
+            cv2.putText(vis, text, (x, y), FONT_FACE, fs, text_color, th, cv2.LINE_AA)
+        y += lh
+
+    Path(result_png_path).parent.mkdir(parents=True, exist_ok=True)
+    cv2.imwrite(result_png_path, vis)
+    print(f"\n[multi] Debug visualization saved to: {result_png_path}")
+
+
 def main() -> int:
     """Main entry point."""
     args = parse_args()
@@ -773,7 +1299,41 @@ def main() -> int:
     # Derive result PNG path from output JSON path
     result_png_path = str(Path(args.output).with_suffix(".png"))
 
-    # Run measurement pipeline
+    if args.mode == "multi":
+        # Multi-finger mode
+        result = measure_multi_finger(
+            image=image,
+            confidence_threshold=args.confidence_threshold,
+            result_png_path=result_png_path,
+            save_debug=args.debug,
+            edge_method=args.edge_method,
+            sobel_threshold=args.sobel_threshold,
+            sobel_kernel_size=args.sobel_kernel_size,
+            use_subpixel=not args.no_subpixel,
+            skip_card_detection=args.skip_card_detection,
+            no_calibration=args.no_calibration,
+        )
+
+        save_output(result, args.output)
+        print(f"Results saved to: {args.output}")
+
+        if result.get("fail_reason"):
+            print(f"Measurement failed: {result['fail_reason']}")
+            return 1
+
+        print(f"\n=== Multi-Finger Results ===")
+        print(f"Fingers: {result.get('fingers_succeeded', 0)}/{result.get('fingers_measured', 0)} succeeded")
+        for fn, pf in result.get("per_finger", {}).items():
+            if pf.get("status") == "ok":
+                print(f"  {fn.capitalize()}: {pf['diameter_cm']:.2f}cm -> Size {pf['best_match']} (range {pf['range'][0]}-{pf['range'][1]})")
+            else:
+                print(f"  {fn.capitalize()}: FAILED ({pf.get('fail_reason', 'unknown')})")
+        if result.get("overall_best_size"):
+            print(f"\nOverall Best Size: {result['overall_best_size']}")
+            print(f"Recommended Range: {result['overall_range_min']}-{result['overall_range_max']}")
+        return 0
+
+    # Single-finger mode (default, backward compatible)
     result = measure_finger(
         image=image,
         finger_index=args.finger_index,

requirements.txt

@@ -5,3 +5,4 @@ scipy>=1.11.0
 scikit-learn>=1.3.0
 flask>=3.0.0
 gunicorn>=21.2.0
+openai>=1.0.0

script/batch_measure.py

@@ -91,8 +91,8 @@ def main():
     done = 0
 
     for img_path in images:
-        stem = img_path.stem           # e.g. "黄漫玉A"
-        person = stem[:-1]             # e.g. "黄漫玉"
+        stem = img_path.stem           # e.g. "S01A"
+        person = stem[:-1]             # e.g. "S01"
         shot = stem[-1]                # e.g. "A"
 
         if person not in gt_by_name:

script/eval_return_rate.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""Evaluate ring size recommendation effectiveness against ground truth.
+
+Measures return rate: probability that recommended size fits NO finger.
+"""
+import csv
+import sys
+import os
+import json
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from measure_finger import measure_multi_finger
+from src.ring_size import RING_SIZE_CHART
+
+# --- Load ground truth ---
+GT_CSV = ROOT / "input" / "sample" / "finger-size.csv"
+IMG_DIR = ROOT / "input" / "sample" / "jpg"
+
+# Name → subject_id mapping (from CSV)
+NAME_TO_ID = {}
+# subject_id → {finger: {"diameter_mm": float, "gt_size": int}}
+GT = {}
+
+FINGER_MAP = {"食指": "index", "中指": "middle", "无名指": "ring"}
+
+with open(GT_CSV, encoding="utf-8-sig") as f:
+    reader = csv.DictReader(f)
+    for row in reader:
+        sid = row["subject_id"]
+        name = row["姓名"]
+        finger_cn = row["手指"]
+        diameter_cm = float(row["直径（cm）"])
+        gt_size_raw = row["指环尺寸"].strip()
+
+        NAME_TO_ID[name] = sid
+
+        if sid not in GT:
+            GT[sid] = {}
+
+        finger_en = FINGER_MAP.get(finger_cn)
+        if not finger_en:
+            continue
+
+        gt_size = int(gt_size_raw) if gt_size_raw.isdigit() else None
+        GT[sid][finger_en] = {
+            "diameter_mm": diameter_cm * 10,
+            "gt_size": gt_size,
+        }
+
+# --- Find images per subject ---
+# Images named like: 黄漫玉A.jpg, 黄漫玉B.jpg
+SUBJECT_IMAGES = {}  # sid → [path, ...]
+for img_file in sorted(IMG_DIR.glob("*.jpg")):
+    stem = img_file.stem  # e.g. "黄漫玉A"
+    if stem == "空白":
+        continue
+    # Last char is A or B
+    name_part = stem[:-1]
+    variant = stem[-1]
+    sid = NAME_TO_ID.get(name_part)
+    if sid is None:
+        print(f"  [skip] No ground truth for {name_part}")
+        continue
+    SUBJECT_IMAGES.setdefault(sid, []).append(img_file)
+
+print(f"Ground truth: {len(GT)} subjects, Images: {len(SUBJECT_IMAGES)} subjects")
+print()
+
+# --- Ring size inner diameters ---
+SIZE_TO_INNER = RING_SIZE_CHART  # {size: inner_diameter_mm}
+
+# --- Run measurements ---
+results = []  # list of dicts
+
+for sid in sorted(GT.keys()):
+    images = SUBJECT_IMAGES.get(sid, [])
+    if not images:
+        print(f"  [skip] {sid}: no images found")
+        continue
+
+    gt_fingers = GT[sid]
+    gt_sizes = {fn: info["gt_size"] for fn, info in gt_fingers.items() if info["gt_size"] is not None}
+    gt_diameters = {fn: info["diameter_mm"] for fn, info in gt_fingers.items()}
+
+    for img_path in images:
+        variant = img_path.stem[-1]
+        label = f"{sid}-{variant}"
+        print(f"Processing {label} ({img_path.name})...", end=" ", flush=True)
+
+        image = cv2.imread(str(img_path))
+        if image is None:
+            print("FAILED to load")
+            continue
+
+        try:
+            result = measure_multi_finger(
+                image=image,
+                edge_method="sobel",
+                save_debug=False,
+                no_calibration=False,
+            )
+        except Exception as e:
+            print(f"ERROR: {e}")
+            continue
+
+        rec_size = result.get("overall_best_size")
+        rec_min = result.get("overall_range_min")
+        rec_max = result.get("overall_range_max")
+        fail = result.get("fail_reason")
+        per_finger = result.get("per_finger", {})
+
+        # Per-finger measured diameters
+        measured = {}
+        for fn in ("index", "middle", "ring"):
+            pf = per_finger.get(fn, {})
+            if pf.get("status") == "ok" and pf.get("diameter_cm") is not None:
+                measured[fn] = pf["diameter_cm"] * 10  # mm
+                per_size = pf.get("best_match")
+                measured[f"{fn}_size"] = per_size
+
+        if fail or rec_size is None:
+            print(f"FAIL ({fail})")
+            results.append({
+                "label": label, "sid": sid, "variant": variant,
+                "rec_size": None, "fail": fail,
+                "gt_sizes": gt_sizes, "gt_diameters": gt_diameters,
+                "measured": measured,
+                "fits_any": False, "return": True,
+            })
+            continue
+
+        # Check if recommended size fits at least one finger
+        rec_inner = SIZE_TO_INNER.get(rec_size, 0)
+
+        fits_any = False
+        fit_details = {}
+        for fn, gt_sz in gt_sizes.items():
+            gt_inner = SIZE_TO_INNER.get(gt_sz, 0)
+            gt_diam = gt_diameters.get(fn, 0)
+
+            # "Fits" = ring can go on (rec inner >= finger diameter)
+            # AND not absurdly loose (rec size <= gt_size + 2)
+            can_go_on = rec_inner >= gt_diam
+            not_too_loose = rec_size <= gt_sz + 2
+            fits = can_go_on and not_too_loose
+
+            fit_details[fn] = {
+                "gt_size": gt_sz,
+                "gt_diam_mm": gt_diam,
+                "rec_inner_mm": rec_inner,
+                "can_go_on": can_go_on,
+                "not_too_loose": not_too_loose,
+                "fits": fits,
+            }
+            if fits:
+                fits_any = True
+
+        status = "OK" if fits_any else "RETURN"
+        print(f"rec={rec_size} ({rec_min}-{rec_max}) → {status}")
+        for fn, fd in fit_details.items():
+            tag = "✓" if fd["fits"] else "✗"
+            print(f"    {fn}: gt_size={fd['gt_size']} gt_diam={fd['gt_diam_mm']:.1f}mm "
+                  f"rec_inner={fd['rec_inner_mm']:.1f}mm [{tag}]")
+
+        results.append({
+            "label": label, "sid": sid, "variant": variant,
+            "rec_size": rec_size, "rec_min": rec_min, "rec_max": rec_max,
+            "fail": None,
+            "gt_sizes": gt_sizes, "gt_diameters": gt_diameters,
+            "measured": measured, "fit_details": fit_details,
+            "fits_any": fits_any, "return": not fits_any,
+        })
+
+# --- Summary ---
+print("\n" + "=" * 70)
+print("EVALUATION SUMMARY")
+print("=" * 70)
+
+total = len(results)
+failed = sum(1 for r in results if r["fail"])
+succeeded = total - failed
+returns = sum(1 for r in results if r["return"] and not r["fail"])
+fits = sum(1 for r in results if r["fits_any"])
+
+print(f"\nTotal images:     {total}")
+print(f"Measurement OK:   {succeeded}")
+print(f"Measurement FAIL: {failed}")
+print()
+print(f"Of {succeeded} successful measurements:")
+print(f"  Fits ≥1 finger: {fits}  ({fits/succeeded*100:.1f}%)" if succeeded else "")
+print(f"  Would RETURN:   {returns}  ({returns/succeeded*100:.1f}%)" if succeeded else "")
+print()
+
+# Detailed table
+print(f"{'Label':<10} {'Rec':>4} {'Range':>7} {'GT(I)':>6} {'GT(M)':>6} {'GT(R)':>6} {'Result':<8}")
+print("-" * 55)
+for r in results:
+    if r["fail"]:
+        print(f"{r['label']:<10} {'FAIL':>4} {'':>7} "
+              f"{r['gt_sizes'].get('index',''):>6} "
+              f"{r['gt_sizes'].get('middle',''):>6} "
+              f"{r['gt_sizes'].get('ring',''):>6} "
+              f"{'FAIL':<8}")
+        continue
+    gt = r["gt_sizes"]
+    rng = f"{r['rec_min']}-{r['rec_max']}"
+    status = "OK" if r["fits_any"] else "RETURN"
+    print(f"{r['label']:<10} {r['rec_size']:>4} {rng:>7} "
+          f"{gt.get('index',''):>6} {gt.get('middle',''):>6} {gt.get('ring',''):>6} "
+          f"{status:<8}")
+
+# Per-subject analysis (best of A/B)
+print("\n\nPER-SUBJECT (best of A/B photos):")
+print(f"{'Subject':<8} {'A_rec':>5} {'A_fit':>5} {'B_rec':>5} {'B_fit':>5} {'Best':>5} {'Result':<8}")
+print("-" * 52)
+for sid in sorted(GT.keys()):
+    subj_results = [r for r in results if r["sid"] == sid]
+    a_results = [r for r in subj_results if r["variant"] == "A"]
+    b_results = [r for r in subj_results if r["variant"] == "B"]
+
+    def fmt(rlist):
+        if not rlist:
+            return ("—", "—")
+        r = rlist[0]
+        if r["fail"]:
+            return ("FAIL", "—")
+        return (str(r["rec_size"]), "✓" if r["fits_any"] else "✗")
+
+    a_rec, a_fit = fmt(a_results)
+    b_rec, b_fit = fmt(b_results)
+    best = "OK" if any(r["fits_any"] for r in subj_results) else "RETURN"
+    print(f"{sid:<8} {a_rec:>5} {a_fit:>5} {b_rec:>5} {b_fit:>5} {'':>5} {best:<8}")
+
+subj_with_any_ok = sum(
+    1 for sid in GT
+    if any(r["fits_any"] for r in results if r["sid"] == sid)
+)
+subj_total = len([sid for sid in GT if any(r["sid"] == sid for r in results)])
+print(f"\nSubjects with ≥1 fitting result: {subj_with_any_ok}/{subj_total}")
+print(f"Effective return rate (per-subject): {(1 - subj_with_any_ok/subj_total)*100:.1f}%" if subj_total else "N/A")
+
+# Size error analysis
+print("\n\nSIZE ERROR ANALYSIS (recommended vs closest GT size):")
+errors = []
+for r in results:
+    if r["fail"] or r["rec_size"] is None:
+        continue
+    gt = r["gt_sizes"]
+    gt_vals = [v for v in gt.values() if v is not None]
+    if not gt_vals:
+        continue
+    # Error = rec - closest GT
+    closest_gt = min(gt_vals, key=lambda s: abs(s - r["rec_size"]))
+    err = r["rec_size"] - closest_gt
+    errors.append(err)
+    
+if errors:
+    import statistics
+    print(f"  Mean error: {statistics.mean(errors):+.2f} sizes")
+    print(f"  Median error: {statistics.median(errors):+.1f} sizes")
+    print(f"  Std dev: {statistics.stdev(errors):.2f} sizes")
+    print(f"  Range: [{min(errors):+d}, {max(errors):+d}]")
+    
+    # Distribution
+    from collections import Counter
+    dist = Counter(errors)
+    print(f"\n  Error distribution:")
+    for e in sorted(dist.keys()):
+        bar = "█" * dist[e]
+        print(f"    {e:+d}: {bar} ({dist[e]})")

src/ai_recommendation.py

@@ -0,0 +1,99 @@
+"""AI-powered ring size explanation using OpenAI.
+
+Size selection is handled by deterministic logic in ring_size.py.
+This module only generates a human-friendly explanation for the recommendation.
+"""
+
+import os
+import logging
+from typing import Dict, Optional
+
+from src.ring_size import RING_SIZE_CHART
+
+logger = logging.getLogger(__name__)
+
+_SIZE_TABLE_TEXT = "\n".join(
+    f"  Size {size}: inner diameter {diameter_mm:.1f} mm"
+    for size, diameter_mm in sorted(RING_SIZE_CHART.items())
+)
+
+_SYSTEM_PROMPT = """You are a sizing explanation assistant for Femometer Smart Ring.
+
+You are given measured finger widths and a pre-computed ring size recommendation.
+Your ONLY job is to explain WHY the recommended size is a good fit, in 1-2 concise sentences.
+
+Do NOT suggest a different size. The size decision has already been made by the system.
+
+Guidelines:
+- Mention which finger(s) would fit best at this size
+- Include specific diameter when first referencing a size, e.g. "Size 8 (18.6mm)"
+- Priority context: index finger fit is slightly preferred over middle, then ring
+- Keep it concise and actionable
+
+Ring Size Chart (China Standard):
+{size_table}
+
+Respond in plain text (1-2 sentences). Do NOT use JSON or markdown.
+""".format(size_table=_SIZE_TABLE_TEXT)
+
+
+def ai_explain_recommendation(
+    finger_widths: Dict[str, Optional[float]],
+    recommended_size: int,
+    range_min: int,
+    range_max: int,
+) -> Optional[str]:
+    """Call OpenAI to explain an already-computed ring size recommendation.
+
+    Args:
+        finger_widths: Dict mapping finger name to diameter in cm (or None if failed).
+            Example: {"index": 1.93, "middle": 1.84, "ring": 1.93}
+        recommended_size: The deterministic best-match size from ring_size.py.
+        range_min: Lower bound of recommended size range.
+        range_max: Upper bound of recommended size range.
+
+    Returns:
+        A plain-text explanation string, or None if the API call fails.
+    """
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        logger.warning("OPENAI_API_KEY not set, skipping AI explanation")
+        return None
+
+    # Build user message with measurements and pre-computed recommendation
+    lines = ["Measured finger outer diameters:"]
+    for finger, width in finger_widths.items():
+        if width is not None:
+            lines.append(f"  {finger.capitalize()}: {width:.2f} cm ({width * 10:.1f} mm)")
+        else:
+            lines.append(f"  {finger.capitalize()}: measurement failed")
+    lines.append("")
+    lines.append(f"Recommended size: {recommended_size} (range {range_min}–{range_max})")
+    lines.append("")
+    lines.append("Explain why this size is a good fit.")
+    user_msg = "\n".join(lines)
+
+    try:
+        import openai
+
+        client = openai.OpenAI(api_key=api_key)
+        response = client.chat.completions.create(
+            model="gpt-5.4",
+            messages=[
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=0.3,
+            max_completion_tokens=200,
+        )
+
+        content = response.choices[0].message.content.strip()
+        if not content:
+            logger.warning("AI returned empty explanation")
+            return None
+
+        return content
+
+    except Exception as e:
+        logger.error("AI explanation failed: %s", e)
+        return None

src/finger_segmentation.py

@@ -162,26 +162,31 @@ def detect_hand_orientation(
     
     Canonical orientation: wrist at bottom, fingers pointing upward.
     
+    Uses the centroid of index, middle, and ring fingertips for robust
+    orientation detection, regardless of which finger is being measured.
+    Individual fingers (especially index/pinky) can lean away from the
+    hand's central axis, causing borderline rotation errors.
+    
     Args:
         landmarks_normalized: MediaPipe hand landmarks (21x2) in normalized [0-1] coordinates
-        finger: Which finger to use for orientation detection (default: "index")
+        finger: Which finger is being measured (kept for API compat, not used for orientation)
     
     Returns:
         Angle in degrees to rotate image clockwise to achieve canonical orientation.
         Returns one of: 0, 90, 180, 270
     """
-    # Get wrist (landmark 0) and specified finger tip
     wrist = landmarks_normalized[WRIST_LANDMARK]
     
-    # Use specified finger, fallback to middle if invalid
-    if finger in FINGER_LANDMARKS:
-        finger_tip = landmarks_normalized[FINGER_LANDMARKS[finger][3]]
-    else:
-        # Fallback to middle finger for "auto" or invalid values
-        finger_tip = landmarks_normalized[FINGER_LANDMARKS["middle"][3]]
+    # Use centroid of index, middle, ring fingertips for robust orientation
+    fingertip_indices = [
+        FINGER_LANDMARKS["index"][3],   # 8
+        FINGER_LANDMARKS["middle"][3],  # 12
+        FINGER_LANDMARKS["ring"][3],    # 16
+    ]
+    fingertip_center = np.mean(landmarks_normalized[fingertip_indices], axis=0)
     
-    # Compute vector from wrist to fingertip
-    direction = finger_tip - wrist
+    # Compute vector from wrist to fingertip centroid
+    direction = fingertip_center - wrist
     
     # Compute angle from vertical upward direction
     # In image coordinates: y increases downward, x increases rightward

src/image_quality.py

@@ -179,3 +179,186 @@ def assess_image_quality(image: np.ndarray) -> Dict[str, Any]:
         "issues": issues,
         "fail_reason": fail_reason,
     }
+
+
+def check_card_in_frame(
+    card_corners: np.ndarray,
+    image_shape: tuple,
+    margin_pct: float = 0.02,
+) -> Dict[str, Any]:
+    """Check if credit card is fully within the image frame.
+
+    Args:
+        card_corners: 4x2 array of card corner coordinates (x, y)
+        image_shape: (height, width) of image
+        margin_pct: minimum margin from edge as fraction of image dimension
+
+    Returns:
+        Dict with:
+            - in_frame: bool
+            - min_margin_px: float (smallest distance from any corner to any edge)
+            - fail_reason: str or None
+    """
+    h, w = image_shape[:2]
+    margin_x = w * margin_pct
+    margin_y = h * margin_pct
+
+    min_margin_px = float("inf")
+    in_frame = True
+
+    for corner in card_corners:
+        x, y = float(corner[0]), float(corner[1])
+        dist_left = x
+        dist_right = w - x
+        dist_top = y
+        dist_bottom = h - y
+        corner_min = min(dist_left, dist_right, dist_top, dist_bottom)
+        min_margin_px = min(min_margin_px, corner_min)
+
+        if x < margin_x or x > w - margin_x or y < margin_y or y > h - margin_y:
+            in_frame = False
+
+    fail_reason = None if in_frame else "card_near_edge"
+
+    return {
+        "in_frame": in_frame,
+        "min_margin_px": min_margin_px,
+        "fail_reason": fail_reason,
+    }
+
+
+def check_finger_landmarks_visible(
+    landmarks: np.ndarray,
+    image_shape: tuple,
+    margin_pct: float = 0.02,
+) -> Dict[str, Any]:
+    """Check if finger landmarks are fully visible in image.
+
+    Args:
+        landmarks: 4x2 array of finger landmarks [MCP, PIP, DIP, TIP]
+        image_shape: (height, width) of image
+        margin_pct: minimum margin from edge
+
+    Returns:
+        Dict with:
+            - all_visible: bool
+            - num_visible: int (0-4)
+            - fail_reason: str or None
+    """
+    h, w = image_shape[:2]
+    margin_x = w * margin_pct
+    margin_y = h * margin_pct
+
+    num_visible = 0
+    for lm in landmarks:
+        x, y = float(lm[0]), float(lm[1])
+        if margin_x <= x <= w - margin_x and margin_y <= y <= h - margin_y:
+            num_visible += 1
+
+    all_visible = num_visible == len(landmarks)
+    fail_reason = None if all_visible else "finger_not_fully_visible"
+
+    return {
+        "all_visible": all_visible,
+        "num_visible": num_visible,
+        "fail_reason": fail_reason,
+    }
+
+
+def check_finger_spacing(
+    all_landmarks: Dict[str, np.ndarray],
+    image_shape: tuple,
+    min_spacing_pct: float = 0.03,
+) -> Dict[str, Any]:
+    """Check if fingers are spread apart enough for accurate measurement.
+
+    Args:
+        all_landmarks: Dict mapping finger name to 4x2 landmarks array
+        image_shape: (height, width) of image
+        min_spacing_pct: minimum spacing between adjacent fingers as fraction of image width
+
+    Returns:
+        Dict with:
+            - well_spaced: bool
+            - min_spacing_px: float
+            - closest_pair: tuple of finger names or None
+            - fail_reason: str or None
+    """
+    min_spacing = image_shape[1] * min_spacing_pct
+    finger_names = list(all_landmarks.keys())
+
+    min_spacing_px = float("inf")
+    closest_pair = None
+    well_spaced = True
+
+    for i in range(len(finger_names) - 1):
+        name_a = finger_names[i]
+        name_b = finger_names[i + 1]
+        pip_a = np.array(all_landmarks[name_a][1], dtype=float)
+        pip_b = np.array(all_landmarks[name_b][1], dtype=float)
+        dist = float(np.linalg.norm(pip_a - pip_b))
+
+        if dist < min_spacing_px:
+            min_spacing_px = dist
+            closest_pair = (name_a, name_b)
+
+    if min_spacing_px < min_spacing:
+        well_spaced = False
+
+    fail_reason = None if well_spaced else "fingers_too_close"
+
+    return {
+        "well_spaced": well_spaced,
+        "min_spacing_px": min_spacing_px,
+        "closest_pair": closest_pair,
+        "fail_reason": fail_reason,
+    }
+
+
+def check_lighting_uniformity(
+    image: np.ndarray,
+    threshold: float = 0.4,
+) -> Dict[str, Any]:
+    """Check for even lighting across the image.
+
+    Args:
+        image: Input BGR image
+        threshold: maximum allowed ratio between darkest and brightest quadrant means
+
+    Returns:
+        Dict with:
+            - uniform: bool
+            - brightness_range: float (max_quadrant - min_quadrant)
+            - fail_reason: str or None
+    """
+    if len(image.shape) == 3:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    else:
+        gray = image
+
+    h, w = gray.shape[:2]
+    mid_y, mid_x = h // 2, w // 2
+
+    quadrants = [
+        gray[:mid_y, :mid_x],
+        gray[:mid_y, mid_x:],
+        gray[mid_y:, :mid_x],
+        gray[mid_y:, mid_x:],
+    ]
+    means = [float(np.mean(q)) for q in quadrants]
+
+    max_mean = max(means)
+    min_mean = min(means)
+    brightness_range = max_mean - min_mean
+
+    uniform = True
+    if max_mean > 0 and brightness_range / max_mean > threshold:
+        uniform = False
+
+    fail_reason = None if uniform else "image_quality_low_lighting"
+
+    return {
+        "uniform": uniform,
+        "brightness_range": brightness_range,
+        "fail_reason": fail_reason,
+    }

src/ring_size.py

@@ -1,6 +1,6 @@
 """Ring size recommendation from calibrated finger width."""
 
-from typing import Dict, Optional, Tuple
+from typing import Dict, List, Optional, Tuple
 
 # China standard ring size chart: size → inner diameter (mm)
 RING_SIZE_CHART = {
@@ -52,3 +52,95 @@ def recommend_ring_size(diameter_cm: float) -> Optional[Dict]:
         "range_max": range_max,
         "diameter_mm": round(diameter_mm, 2),
     }
+
+
+def aggregate_ring_sizes(per_finger_results: Dict[str, Dict]) -> Dict:
+    """Aggregate ring size recommendations from multiple fingers.
+
+    Args:
+        per_finger_results: Dict mapping finger name to measurement result dict.
+            Each value must have keys:
+                - "finger_outer_diameter_cm": float or None
+                - "confidence": float
+                - "ring_size": dict from recommend_ring_size() or None
+                - "fail_reason": str or None
+
+    Returns:
+        Dict with:
+            - overall_best_size: int (consensus size if one exists in all
+              fingers' ranges, otherwise confidence-weighted best size)
+            - overall_range_min: int (min of all per-finger range_min)
+            - overall_range_max: int (max of all per-finger range_max)
+            - fingers_measured: int (total attempted)
+            - fingers_succeeded: int (with valid measurement)
+            - per_finger: dict of per-finger details
+            - fail_reason: str or None (only if ALL fingers failed)
+    """
+    fingers_measured = len(per_finger_results)
+
+    # Build per_finger summary
+    per_finger: Dict[str, Dict] = {}
+    for name, result in per_finger_results.items():
+        failed = result.get("fail_reason") is not None or result.get("ring_size") is None
+        rs = result.get("ring_size")
+        per_finger[name] = {
+            "diameter_cm": result.get("finger_outer_diameter_cm"),
+            "confidence": result.get("confidence", 0.0),
+            "best_match": rs["best_match"] if rs else None,
+            "range": [rs["range_min"], rs["range_max"]] if rs else None,
+            "status": "failed" if failed else "ok",
+            "fail_reason": result.get("fail_reason"),
+        }
+
+    # Filter to succeeded fingers
+    succeeded = {
+        name: info for name, info in per_finger.items() if info["status"] == "ok"
+    }
+
+    if not succeeded:
+        return {
+            "fail_reason": "all_fingers_failed",
+            "fingers_measured": fingers_measured,
+            "fingers_succeeded": 0,
+            "per_finger": per_finger,
+        }
+
+    # Confidence-weighted voting for best size
+    vote_tally: Dict[int, float] = {}
+    for info in succeeded.values():
+        size = info["best_match"]
+        vote_tally[size] = vote_tally.get(size, 0.0) + info["confidence"]
+
+    weighted_best_size = max(vote_tally, key=lambda s: vote_tally[s])
+
+    # Intersection-first override: if a size falls in every finger's range, prefer it
+    all_ranges = [set(range(info["range"][0], info["range"][1] + 1))
+                  for info in succeeded.values()]
+    consensus_sizes = set.intersection(*all_ranges) if all_ranges else set()
+
+    if consensus_sizes:
+        # Pick the consensus size closest to the confidence-weighted winner
+        overall_best_size = min(consensus_sizes,
+                                key=lambda s: abs(s - weighted_best_size))
+    else:
+        overall_best_size = weighted_best_size
+
+    # Aggregate range
+    overall_range_min = min(info["range"][0] for info in succeeded.values())
+    overall_range_max = max(info["range"][1] for info in succeeded.values())
+
+    # Ensure range covers best size
+    if overall_best_size < overall_range_min:
+        overall_range_min = overall_best_size
+    if overall_best_size > overall_range_max:
+        overall_range_max = overall_best_size
+
+    return {
+        "overall_best_size": overall_best_size,
+        "overall_range_min": overall_range_min,
+        "overall_range_max": overall_range_max,
+        "fingers_measured": fingers_measured,
+        "fingers_succeeded": len(succeeded),
+        "per_finger": per_finger,
+        "fail_reason": None,
+    }

web_demo/app.py

@@ -13,14 +13,16 @@ from pathlib import Path
 from typing import Dict, Any
 
 import cv2
+import numpy as np
 from flask import Flask, jsonify, render_template, request, send_from_directory
 from werkzeug.utils import secure_filename
 
 ROOT_DIR = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(ROOT_DIR))
 
-from measure_finger import measure_finger, apply_calibration
+from measure_finger import measure_finger, measure_multi_finger, apply_calibration
 from src.ring_size import recommend_ring_size
+from src.ai_recommendation import ai_explain_recommendation
 
 APP_ROOT = Path(__file__).resolve().parent
 UPLOAD_DIR = APP_ROOT / "uploads"
@@ -37,10 +39,45 @@ def _allowed_file(filename: str) -> bool:
     return Path(filename).suffix.lower() in ALLOWED_EXTENSIONS
 
 
+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."""
+    if isinstance(obj, dict):
+        return {k: _numpy_safe(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_numpy_safe(v) for v in 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 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)
+        json.dump(data, f, indent=2, ensure_ascii=False, cls=_NumpyEncoder)
 
 
 @app.route("/")
@@ -71,6 +108,7 @@ def api_measure():
         return jsonify({"success": False, "error": "Unsupported file type"}), 400
 
     finger_index = request.form.get("finger_index", "index")
+    mode = request.form.get("mode", "single")
     run_id = uuid.uuid4().hex[:12]
     safe_name = secure_filename(file.filename)
     upload_name = f"{run_id}__{safe_name}"
@@ -82,6 +120,12 @@ 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}",
+        )
+
     return _run_measurement(
         image=image,
         finger_index=finger_index,
@@ -92,6 +136,7 @@ def api_measure():
 @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")
     if not DEFAULT_SAMPLE_PATH.exists():
         return jsonify({"success": False, "error": "Default sample image not found"}), 500
 
@@ -99,6 +144,12 @@ def api_measure_default():
     if image is None:
         return jsonify({"success": False, "error": "Failed to load default sample image"}), 500
 
+    if mode == "multi":
+        return _run_multi_measurement(
+            image=image,
+            input_image_url=DEFAULT_SAMPLE_URL,
+        )
+
     return _run_measurement(
         image=image,
         finger_index=finger_index,
@@ -135,12 +186,72 @@ def _run_measurement(
         if rec:
             result["ring_size"] = rec
 
+    result = _numpy_safe(result)
+
+    result_json_name = f"{run_id}__result.json"
+    result_json_path = RESULTS_DIR / result_json_name
+    _save_json(result_json_path, result)
+
+    payload = {
+        "success": result.get("fail_reason") is None,
+        "result": result,
+        "result_image_url": f"/results/{result_png_name}",
+        "input_image_url": input_image_url,
+        "result_json_url": f"/results/{result_json_name}",
+    }
+
+    return jsonify(payload)
+
+
+def _run_multi_measurement(
+    image,
+    input_image_url: str,
+):
+    """Run multi-finger measurement pipeline."""
+    run_id = uuid.uuid4().hex[:12]
+
+    result_png_name = f"{run_id}__result.png"
+    result_png_path = RESULTS_DIR / result_png_name
+
+    result = measure_multi_finger(
+        image=image,
+        edge_method=DEMO_EDGE_METHOD,
+        result_png_path=str(result_png_path),
+        save_debug=False,
+        no_calibration=False,
+    )
+
+    result = _numpy_safe(result)
+
+    # Collect finger widths for AI recommendation
+    per_finger = result.get("per_finger", {})
+    finger_widths = {}
+    for fn in ("index", "middle", "ring"):
+        pf = per_finger.get(fn, {})
+        if pf.get("status") == "ok" and pf.get("diameter_cm") is not None:
+            finger_widths[fn] = pf["diameter_cm"]
+        else:
+            finger_widths[fn] = None
+
+    ai_reason = None
+    ai_explain = request.form.get("ai_explain", "0") == "1"
+    if ai_explain and result.get("overall_best_size") is not None:
+        ai_reason = ai_explain_recommendation(
+            finger_widths,
+            recommended_size=result["overall_best_size"],
+            range_min=result["overall_range_min"],
+            range_max=result["overall_range_max"],
+        )
+    if ai_reason:
+        result["ai_explanation"] = ai_reason
+
     result_json_name = f"{run_id}__result.json"
     result_json_path = RESULTS_DIR / result_json_name
     _save_json(result_json_path, result)
 
     payload = {
         "success": result.get("fail_reason") is None,
+        "mode": "multi",
         "result": result,
         "result_image_url": f"/results/{result_png_name}",
         "input_image_url": input_image_url,

web_demo/static/app.js

@@ -7,18 +7,29 @@ const inputFrame = document.getElementById("inputFrame");
 const debugFrame = document.getElementById("debugFrame");
 const jsonOutput = document.getElementById("jsonOutput");
 const jsonLink = document.getElementById("jsonLink");
+const modeSelect = document.getElementById("modeSelect");
+const fingerSelectGroup = document.getElementById("fingerSelectGroup");
+const multiResultPanel = document.getElementById("multiResultPanel");
+const overallSize = document.getElementById("overallSize");
+const fingerBreakdown = document.getElementById("fingerBreakdown");
 const defaultSampleUrl = window.DEFAULT_SAMPLE_URL || "";
 const failReasonMessageMap = {
   card_not_detected:
     "Credit card not detected. Place a full card flat beside your hand.",
   card_not_parallel:
     "Card is not parallel to the camera. Keep your phone directly above and parallel to the card.",
+  card_near_edge:
+    "Card appears cropped. Place the entire card within the photo frame.",
   hand_not_detected:
     "Hand not detected. Include your full palm in frame and keep fingers fully visible.",
   finger_isolation_failed:
     "Could not isolate the selected finger. Keep one target finger extended and separated.",
+  finger_not_fully_visible:
+    "Finger is partially out of frame. Move hand to center of photo.",
   finger_mask_too_small:
     "Finger region is too small. Move closer and use a higher-resolution photo.",
+  fingers_too_close:
+    "Fingers are too close together. Spread your fingers apart naturally.",
   contour_extraction_failed:
     "Finger contour extraction failed. Improve lighting and reduce background clutter.",
   axis_estimation_failed:
@@ -33,6 +44,20 @@ const failReasonMessageMap = {
     "Measured width is out of range. Retake with the phone parallel to the table.",
   disagreement_with_contour:
     "Edge methods disagree too much. Retake with cleaner edges and more even lighting.",
+  all_fingers_failed:
+    "Could not measure any fingers. Ensure hand is flat with fingers spread and well-lit.",
+  image_too_blurry:
+    "Photo is blurry. Hold your phone steady or use a tripod.",
+  image_underexposed:
+    "Photo is too dark. Turn on flash or improve lighting.",
+  image_overexposed:
+    "Photo is too bright. Avoid direct sunlight or strong overhead light.",
+  image_low_contrast:
+    "Photo has low contrast. Use a different background color.",
+  image_resolution_too_low:
+    "Photo resolution is too low. Use the rear camera at full resolution.",
+  image_quality_low_lighting:
+    "Lighting is uneven. Turn on flash and shoot from directly above.",
 };
 
 const formatFailReasonStatus = (failReason) => {
@@ -69,15 +94,74 @@ const showImage = (imgEl, frameEl, url) => {
 
 const buildMeasureSettings = () => {
   const fingerSelect = form.querySelector('select[name="finger_index"]');
+  const aiToggle = document.getElementById("aiExplainToggle");
+  const mode = modeSelect ? modeSelect.value : "single";
   return {
     finger_index: fingerSelect ? fingerSelect.value : "index",
     edge_method: "sobel",
+    mode: mode,
+    ai_explain: aiToggle && aiToggle.checked ? "1" : "0",
   };
 };
 
+const renderMultiResult = (result) => {
+  if (!result || !result.per_finger) {
+    multiResultPanel.style.display = "none";
+    return;
+  }
+
+  multiResultPanel.style.display = "";
+
+  const aiExplanation = result.ai_explanation;
+
+  // Always show deterministic recommendation as hero
+  if (result.overall_best_size) {
+    overallSize.innerHTML = `
+      <div class="size-hero">
+        <span class="size-label">Recommended Size</span>
+        <span class="size-number">${result.overall_best_size}</span>
+        <span class="size-range">Range: ${result.overall_range_min} – ${result.overall_range_max}</span>
+        ${aiExplanation ? `<p class="ai-reason">${aiExplanation}</p>` : ""}
+      </div>`;
+  } else {
+    overallSize.innerHTML = `<div class="size-hero"><span class="size-label">Measurement Failed</span></div>`;
+  }
+
+  // Per-finger cards: size + range + width
+  const fingerNames = { index: "Index", middle: "Middle", ring: "Ring" };
+  const fingerColors = { index: "#00dddd", middle: "#00cc44", ring: "#dd44dd" };
+  let html = '<div class="finger-cards">';
+  for (const [fn, label] of Object.entries(fingerNames)) {
+    const pf = result.per_finger[fn];
+    if (!pf) continue;
+    const color = fingerColors[fn] || "#888";
+    const ok = pf.status === "ok";
+    html += `<div class="finger-card" style="border-top: 3px solid ${color};">
+      <div class="finger-name">${label}</div>`;
+    if (ok) {
+      const size = pf.best_match;
+      const range = pf.range;
+      html += `<div class="finger-size-label">Size</div>`;
+      html += `<div class="finger-size">${size}</div>`;
+      if (range) {
+        html += `<div class="finger-range">${range[0]} – ${range[1]}</div>`;
+      }
+      html += `<div class="finger-width">${(pf.diameter_cm * 10).toFixed(1)} mm</div>`;
+    } else {
+      html += `<div class="finger-failed">Failed</div>
+        <div class="finger-fail-reason">${pf.fail_reason || "unknown"}</div>`;
+    }
+    html += `</div>`;
+  }
+  html += "</div>";
+  html += `<div class="finger-count">${result.fingers_succeeded}/${result.fingers_measured} fingers measured</div>`;
+  fingerBreakdown.innerHTML = html;
+};
+
 const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
   setStatus("Measuring… Please wait.");
-  jsonOutput.textContent = "{\n  \"status\": \"processing\"\n}";
+  jsonOutput.textContent = '{\n  "status": "processing"\n}';
+  multiResultPanel.style.display = "none";
 
   try {
     const response = await fetch(endpoint, {
@@ -98,6 +182,10 @@ const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
     showImage(inputPreview, inputFrame, data.input_image_url || inputUrlFallback);
     showImage(debugPreview, debugFrame, data.result_image_url);
 
+    if (data.mode === "multi") {
+      renderMultiResult(data.result);
+    }
+
     if (data.success) {
       setStatus("Measurement complete. Results updated.");
     } else {
@@ -123,6 +211,17 @@ imageInput.addEventListener("change", () => {
   setStatus("Image ready. Click to start measurement.");
 });
 
+// Mode toggle: show/hide finger selector
+if (modeSelect) {
+  const updateFingerVisibility = () => {
+    if (fingerSelectGroup) {
+      fingerSelectGroup.style.display = modeSelect.value === "multi" ? "none" : "";
+    }
+  };
+  modeSelect.addEventListener("change", updateFingerVisibility);
+  updateFingerVisibility();
+}
+
 form.addEventListener("submit", async (event) => {
   event.preventDefault();
 
@@ -130,6 +229,8 @@ form.addEventListener("submit", async (event) => {
   const formData = new FormData();
   formData.append("finger_index", settings.finger_index);
   formData.append("edge_method", settings.edge_method);
+  formData.append("mode", settings.mode);
+  formData.append("ai_explain", settings.ai_explain);
 
   const file = imageInput.files[0];
   if (file) {

web_demo/static/styles.css

@@ -286,3 +286,151 @@ pre {
     font-size: 2.4rem;
   }
 }
+
+/* Multi-finger result styles */
+.multi-result {
+  padding: 8px 0;
+}
+
+.size-hero {
+  text-align: center;
+  padding: 20px 0 16px;
+  border-bottom: 1px solid var(--border);
+  margin-bottom: 16px;
+}
+
+.size-hero .size-label {
+  display: block;
+  font-size: 0.85rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--ink-soft);
+  margin-bottom: 4px;
+}
+
+.size-hero .size-number {
+  display: block;
+  font-size: 3.2rem;
+  font-weight: 700;
+  color: var(--accent);
+  line-height: 1.1;
+}
+
+.size-hero .size-range {
+  display: block;
+  font-size: 1rem;
+  color: var(--ink-soft);
+  margin-top: 4px;
+}
+
+.finger-cards {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 12px;
+  margin-bottom: 12px;
+}
+
+.finger-card {
+  background: var(--sand);
+  border-radius: 8px;
+  padding: 12px;
+  text-align: center;
+  box-shadow: 0 1px 4px var(--shadow);
+}
+
+.finger-card .finger-name {
+  font-weight: 600;
+  font-size: 0.9rem;
+  margin-bottom: 6px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.finger-card .finger-width {
+  font-size: 0.85rem;
+  color: var(--ink-soft);
+  margin-top: 6px;
+}
+
+.finger-card .finger-size-label {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--ink-soft);
+  margin-top: 6px;
+}
+
+.finger-card .finger-size {
+  font-size: 1.6rem;
+  font-weight: 700;
+  color: var(--accent);
+  line-height: 1.1;
+}
+
+.finger-card .finger-range {
+  font-size: 0.8rem;
+  color: var(--ink-soft);
+  margin-top: 2px;
+}
+
+.ai-reason {
+  font-size: 0.9rem;
+  color: var(--ink-soft);
+  margin: 12px auto 0;
+  max-width: 40ch;
+  line-height: 1.5;
+  font-style: italic;
+}
+
+.finger-card .finger-failed {
+  font-size: 1.1rem;
+  font-weight: 600;
+  color: #721c24;
+  margin: 8px 0 4px;
+}
+
+.finger-card .finger-fail-reason {
+  font-size: 0.75rem;
+  color: var(--ink-soft);
+  word-break: break-word;
+}
+
+.finger-count {
+  text-align: center;
+  font-size: 0.85rem;
+  color: var(--ink-soft);
+}
+
+@media (max-width: 600px) {
+  .finger-cards {
+    grid-template-columns: 1fr;
+  }
+}
+
+.toggle-label {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 0.9rem;
+  color: var(--ink-soft);
+}
+
+.toggle-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  height: 42px;
+}
+
+.toggle-row input[type="checkbox"] {
+  width: 18px;
+  height: 18px;
+  accent-color: var(--accent);
+  cursor: pointer;
+}
+
+.toggle-hint {
+  font-size: 0.75rem;
+  color: var(--ink-soft);
+  opacity: 0.7;
+}

web_demo/templates/index.html

@@ -28,6 +28,13 @@
 
         <div class="controls">
           <label>
+            <span>Mode</span>
+            <select name="mode" id="modeSelect">
+              <option value="multi" selected>All Fingers (Recommended)</option>
+              <option value="single">Single Finger</option>
+            </select>
+          </label>
+          <label id="fingerSelectGroup">
             <span>Finger Selection</span>
             <select name="finger_index">
               <option value="index" selected>Index (Default)</option>
@@ -43,6 +50,13 @@
               <option value="sobel" selected>Sobel (Locked)</option>
             </select>
           </label>
+          <label class="toggle-label">
+            <span>AI Explanation</span>
+            <div class="toggle-row">
+              <input type="checkbox" id="aiExplainToggle" />
+              <span class="toggle-hint">Uses OpenAI tokens</span>
+            </div>
+          </label>
         </div>
 
         <button class="primary" type="submit">Start Measurement</button>
@@ -71,6 +85,14 @@
     </section>
 
     <section class="result">
+      <div class="panel" id="multiResultPanel" style="display:none;">
+        <h2>Ring Size Recommendation</h2>
+        <div id="multiResult" class="multi-result">
+          <div class="overall-size" id="overallSize"></div>
+          <div class="finger-breakdown" id="fingerBreakdown"></div>
+        </div>
+      </div>
+
       <div class="panel">
         <div class="panel-head">
           <h2>JSON Output</h2>
@@ -80,11 +102,15 @@
       </div>
 
       <div class="panel tips">
-        <h2>Photo Tips</h2>
+        <h2>📸 Photo Tips</h2>
         <ul>
-          <li>✓ Turn on flash</li>
-          <li>✓ Keep phone parallel to table</li>
-          <li>✓ Include full palm in frame</li>
+          <li>✅ Place credit card flat next to your hand</li>
+          <li>✅ Shoot from directly above (bird's-eye view)</li>
+          <li>✅ Turn on flash for even lighting</li>
+          <li>✅ Keep all fingers and card fully within frame</li>
+          <li>✅ Spread index, middle, and ring fingers apart</li>
+          <li>✅ Use a plain, light-colored background</li>
+          <li>✅ Hold phone steady — avoid blur</li>
         </ul>
       </div>
     </section>