Upload folder using huggingface_hub

.dockerignore

@@ -0,0 +1,9 @@
+.venv/
+.git/
+__pycache__/
+*.pyc
+output/
+web_demo/uploads/
+web_demo/results/
+doc/
+.claude/

.gitattributes

@@ -1,35 +1,3 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+\*.png filter=lfs diff=lfs merge=lfs -text
+\*.jpg filter=lfs diff=lfs merge=lfs -text
+web_demo/static/examples/default_sample.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Project outputs (keep structure, ignore contents)
+output/
+output/*.json
+output/*.png
+output/*.jpg
+output/intermediate/
+output/card_detection_debug/
+output/finger_segmentation_debug/
+output/edge_refinement_debug/
+web_demo/uploads/
+web_demo/results/
+
+# Downloaded models (auto-downloaded on first run)
+.model/*.task
+
+# Test artifacts
+input/
+input/test*.jpg
+input/*.heic
+
+# OS
+.DS_Store
+Thumbs.db

AGENTS.md

@@ -0,0 +1,364 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Standard Task Workflow
+
+For tasks of implementing **new features**:
+1. Read PRD.md, Plan.md, Progress.md before coding
+2. Summarize current project state before implementation
+3. Carry out the implementatation; after that, build and test if possible
+4. Update Progress.md after changes
+5. Commit with a clear, concise message
+
+For tasks of **bug fixing**:
+1. Summarize the bug, reason and solution before implementation
+2. Carry out the implementation to fix the bug; build and test afterwards;
+3. Update Progress.md after changes
+4. Commit with a clear, concise message
+
+For tasks of **reboot** from a new codex session:
+1. Read doc/v0/PRD.md, doc/v0/Plan.md, doc/v0/Progress.md for baseline implementation
+2. Read doc/v1/PRD.md, doc/v1/Plan.md, doc/v1/Progress.md for edge refinement (v1)
+3. Assume this is a continuation of an existing project.
+4. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
+
+## Project Overview
+
+Ring Sizer is a **local, terminal-executable computer vision program** that measures the outer width (diameter) of a finger at the ring-wearing zone using a single RGB image. It uses a standard credit card (ISO/IEC 7810 ID-1: 85.60mm × 53.98mm) as a physical size reference for scale calibration.
+
+**Key characteristics:**
+- Single image input (JPG/PNG)
+- **v1: Dual edge detection** - Landmark-based axis + Sobel gradient refinement
+- MediaPipe-based hand and finger segmentation
+- MediaPipe-based hand and finger segmentation
+- Outputs JSON measurement data and optional debug visualization
+- No cloud processing, runs entirely locally
+- Python 3.8+ with OpenCV, NumPy, MediaPipe, and SciPy
+
+## Development Commands
+
+### Installation
+```bash
+# Create virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### Running the Program
+```bash
+# Basic measurement (defaults to index finger, auto edge detection)
+python measure_finger.py --input input/test_image.jpg --output output/result.json
+
+# Measure specific finger (index, middle, ring, or auto)
+python measure_finger.py \
+  --input input/test_image.jpg \
+  --output output/result.json \
+  --finger-index ring
+
+# With debug visualization
+python measure_finger.py \
+  --input input/test_image.jpg \
+  --output output/result.json \
+  --finger-index middle \
+  --debug output/debug_overlay.png
+
+# Force Sobel edge refinement (v1)
+python measure_finger.py \
+  --input image.jpg \
+  --output result.json \
+  --finger-index ring \
+  --edge-method sobel \
+  --sobel-threshold 15.0 \
+  --debug output/debug.png
+
+# Compare both methods
+python measure_finger.py \
+  --input image.jpg \
+  --output result.json \
+  --finger-index middle \
+  --edge-method compare \
+  --debug output/debug.png
+
+# Force contour method (v0)
+python measure_finger.py \
+  --input image.jpg \
+  --output result.json \
+  --finger-index index \
+  --edge-method contour
+```
+
+## Architecture Overview
+
+### Processing Pipeline (9 Phases)
+
+The measurement pipeline follows a strict sequential flow:
+
+1. **Image Quality Check** - Blur detection, exposure validation, resolution check
+2. **Credit Card Detection & Scale Calibration** - Detects card, verifies aspect ratio (~1.586), computes `px_per_cm`
+3. **Hand & Finger Segmentation** - MediaPipe hand detection, finger isolation, mask generation
+4. **Finger Contour Extraction** - Extracts outer contour from cleaned mask
+5. **Finger Axis Estimation** - PCA-based principal axis calculation, determines palm-end vs tip-end
+6. **Ring-Wearing Zone Localization** - Defines zone at 15%-25% of finger length from palm-side
+7. **Width Measurement** - Samples 20 cross-sections perpendicular to axis, uses median width
+8. **Confidence Scoring** - Multi-factor scoring (card 30%, finger 30%, measurement 40%)
+9. **Debug Visualization** - Generates annotated overlay image
+
+### Module Structure
+
+The codebase is organized into focused utility modules in `src/`:
+
+| Module | Primary Responsibilities |
+|--------|--------------------------|
+| `card_detection.py` | Credit card detection, perspective correction, scale calibration (`px_per_cm`) |
+| `finger_segmentation.py` | MediaPipe integration, hand/finger isolation, mask cleaning, contour extraction |
+| `geometry.py` | PCA axis estimation, ring zone localization, cross-section width measurement, line-contour intersections |
+| `image_quality.py` | Blur detection (Laplacian variance), exposure checks, resolution validation |
+| `confidence.py` | Component confidence scoring (card, finger, measurement), overall confidence computation |
+| `visualization.py` | Debug overlay generation with contours, zones, measurements, and annotations |
+
+### Key Design Decisions
+
+**Ring-Wearing Zone Definition:**
+- Located at 15%-25% of finger length from palm-side end
+- Width measured by sampling 20 cross-sections within this zone
+- Final measurement is the **median width** (robust to outliers)
+
+**Axis Estimation:**
+- Uses PCA (Principal Component Analysis) on finger mask points
+- Determines palm-end vs tip-end using either:
+  1. MediaPipe landmarks (preferred, if available)
+  2. Thickness heuristic (thinner end is likely the tip)
+
+**Confidence Scoring:**
+- 3-component weighted average: Card (30%) + Finger (30%) + Measurement (40%)
+- Confidence levels: HIGH (>0.85), MEDIUM (0.6-0.85), LOW (<0.6)
+- Factors: card detection quality, finger mask area, width variance, aspect ratios
+
+**Measurement Approach:**
+- Perpendicular cross-sections to finger axis
+- Line-contour intersection algorithm finds left/right edges
+- Uses farthest pair of intersections to handle complex contours
+- Converts pixels to cm using calibrated scale factor
+
+---
+
+## v1 Architecture (Edge Refinement)
+
+### What's New in v1
+
+v1 improves measurement accuracy by replacing contour-based edge detection with gradient-based Sobel edge refinement. Key improvements:
+
+- **Landmark-based axis**: Uses MediaPipe finger landmarks (MCP→PIP→DIP→TIP) for more anatomically consistent axis estimation
+- **Sobel edge detection**: Bidirectional gradient filtering for pixel-precise edge localization
+- **Sub-pixel refinement**: Parabola fitting achieves <0.5px precision (~0.003cm at typical resolution)
+- **Quality-based fallback**: Automatically uses v0 contour method if Sobel quality insufficient
+- **Enhanced confidence**: Adds edge quality component (gradient strength, consistency, smoothness, symmetry)
+
+### v1 Processing Pipeline (Enhanced Phases)
+
+**Phase 5a: Landmark-Based Axis Estimation (v1)**
+- Uses MediaPipe finger landmarks directly (4 points: MCP, PIP, DIP, TIP)
+- **Finger selection**: Defaults to index finger, can specify middle or ring finger via `--finger-index`
+- Orientation detection uses the **specified finger** for axis calculation (wrist → finger tip)
+- Image automatically rotated to canonical orientation (wrist at bottom, fingers pointing up)
+- Three axis calculation methods:
+  - `endpoints`: Simple MCP→TIP vector
+  - `linear_fit`: Linear regression on all 4 landmarks (default, most robust)
+  - `median_direction`: Median of segment directions
+- Falls back to PCA if landmarks unavailable or quality check fails
+- Validation checks: NaN/inf, minimum spacing, monotonic progression, minimum length
+
+**Phase 7b: Sobel Edge Refinement (v1)**
+```
+1. Extract ROI around ring zone → 2. Apply bidirectional Sobel filters →
+3. Detect edges per cross-section → 4. Sub-pixel refinement → 5. Measure width
+```
+
+1. **ROI Extraction**
+   - Rectangular region around ring zone with padding (50px for gradient context)
+   - Width estimation: `finger_length / 3.0` (conservative)
+   - Optional rotation alignment (not used by default)
+
+2. **Bidirectional Sobel Filtering**
+   - Applies `cv2.Sobel` with configurable kernel size (3, 5, or 7)
+   - Computes gradient_x (horizontal edges), gradient_y (vertical edges)
+   - Calculates gradient magnitude and direction
+   - Auto-detects filter orientation from ROI aspect ratio
+
+3. **Edge Detection Per Cross-Section**
+   - **Mask-constrained mode** (primary):
+     - Finds leftmost/rightmost finger mask pixels (finger boundaries)
+     - Searches ±10px around boundaries for strongest gradient
+     - Combines anatomical accuracy (mask) with sub-pixel precision (gradient)
+   - **Gradient-only mode** (fallback): Pure Sobel without mask constraint
+
+4. **Sub-Pixel Edge Localization**
+   - Parabola fitting: f(x) = ax² + bx + c
+   - Samples gradient at x-1, x, x+1
+   - Finds parabola peak: x_peak = -b/(2a)
+   - Constrains refinement to ±0.5 pixels
+   - Achieves <0.5px precision (~0.003cm at 185 px/cm)
+
+5. **Width Measurement**
+   - Calculates width for each valid row
+   - Outlier filtering using Median Absolute Deviation (MAD)
+   - Removes measurements >3 MAD from median
+   - Computes median, mean, std dev
+   - Converts pixels to cm using scale factor
+
+**Phase 8b: Enhanced Confidence Scoring (v1)**
+- Adds 4th component: Edge Quality (20% weight)
+  - Gradient strength: Avg magnitude at detected edges
+  - Consistency: % of rows with valid edge pairs
+  - Smoothness: Edge position variance (lower = better)
+  - Symmetry: Left/right edge strength balance
+- Reweights other components: Card 25%, Finger 25%, Measurement 30%
+
+### v1 Module Structure
+
+| Module | v1 Enhancements |
+|--------|-----------------|
+| `geometry.py` | Added `estimate_finger_axis_from_landmarks()`, `_validate_landmark_quality()`, landmark-based zone localization |
+| **`edge_refinement.py`** | **[NEW]** Complete Sobel edge refinement pipeline with sub-pixel precision |
+| `confidence.py` | Added `compute_edge_quality_confidence()`, dual-mode confidence calculation |
+| `debug_observer.py` | Added 9 edge refinement drawing functions for visualization |
+| `measure_finger.py` | CLI flags for edge method selection, method comparison mode |
+
+### v1 CLI Flags
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--finger-index` | auto, index, middle, ring, pinky | **index** | Which finger to measure and use for orientation |
+| `--edge-method` | auto, contour, sobel, compare | auto | Edge detection method |
+| `--sobel-threshold` | float | 15.0 | Minimum gradient magnitude |
+| `--sobel-kernel-size` | 3, 5, 7 | 3 | Sobel kernel size |
+| `--no-subpixel` | flag | False | Disable sub-pixel refinement |
+
+### v1 Auto Mode Behavior
+
+When `--edge-method auto` (default):
+1. Always computes contour measurement (v0 baseline)
+2. Attempts Sobel edge refinement
+3. Evaluates Sobel quality score (threshold: 0.7)
+4. Checks consistency (>50% success rate required)
+5. Verifies width reasonableness (0.8-3.5 cm)
+6. Checks agreement with contour (<50% difference)
+7. Uses Sobel if all checks pass, otherwise falls back to contour
+8. Reports method used in `edge_method_used` field
+
+### v1 Debug Output
+
+When `--debug` flag used, generates:
+- Main debug overlay (same as v0, shows final result)
+- `output/edge_refinement_debug/` subdirectory with 12 images:
+  - **Stage A** (3): Landmark axis, ring zone, ROI extraction
+  - **Stage B** (5): Sobel gradients, candidates, selected edges
+  - **Stage C** (4): Sub-pixel refinement, widths, distribution, outliers
+
+### v1 Failure Modes (Additional)
+
+- `sobel_edge_refinement_failed` - Sobel method explicitly requested but failed
+- `quality_score_low_X.XX` - Edge quality below threshold (auto fallback)
+- `consistency_low_X.XX` - Too few valid edge detections
+- `width_unreasonable` - Measured width outside realistic range
+- `disagreement_with_contour` - Sobel and contour differ by >50%
+
+---
+
+## Important Technical Details
+
+### What This Measures
+The system measures the **external horizontal width** (outer diameter) of the finger at the ring-wearing zone. This is:
+- ✅ The width of soft tissue + bone at the ring-wearing position
+- ❌ NOT the inner diameter of a ring
+- Used as a geometric proxy for downstream ring size mapping (out of scope for v0)
+
+### Coordinate Systems
+- Images use standard OpenCV format: (row, col) = (y, x)
+- Most geometry functions work in (x, y) format
+- Contours are Nx2 arrays in (x, y) format
+- Careful conversion needed between formats (see `geometry.py:35`)
+
+### MediaPipe Integration
+- Uses pretrained hand landmark detection model (no custom training)
+- Provides 21 hand landmarks per hand
+- Each finger has 4 landmarks: MCP (base), PIP, DIP, TIP
+- Finger indices: 0=thumb, 1=index, 2=middle, 3=ring, 4=pinky
+- **Orientation detection**: Uses wrist → specified finger tip to determine hand rotation
+- **Automatic rotation**: Image rotated to canonical orientation (wrist at bottom, fingers up) based on selected finger
+
+### Input Requirements
+For optimal results:
+- Resolution: 1080p or higher recommended
+- View angle: Near top-down view
+- **Finger**: One finger extended (index, middle, or ring). Specify with `--finger-index`
+- Credit card: Must show at least 3 corners, aspect ratio ~1.586
+- Finger and card must be on the same plane
+- Good lighting, minimal blur
+
+### Failure Modes
+The system can fail at various stages:
+- `card_not_detected` - Credit card not found or aspect ratio invalid
+- `hand_not_detected` - No hand detected by MediaPipe
+- `finger_isolation_failed` - Could not isolate specified finger
+- `finger_mask_too_small` - Mask area too small after cleaning
+- `contour_extraction_failed` - Could not extract valid contour
+- `axis_estimation_failed` - PCA failed or insufficient points
+- `zone_localization_failed` - Could not define ring zone
+- `width_measurement_failed` - No valid cross-section intersections
+
+## Output Format
+
+### JSON Output Structure
+```json
+{
+  "finger_outer_diameter_cm": 1.78,
+  "confidence": 0.86,
+  "scale_px_per_cm": 42.3,
+  "quality_flags": {
+    "card_detected": true,
+    "finger_detected": true,
+    "view_angle_ok": true
+  },
+  "fail_reason": null
+}
+```
+
+### Debug Visualization Features
+When `--debug` flag is used, generates an annotated image with:
+- Credit card contour and corners (green)
+- Finger contour (magenta, thick lines)
+- Finger axis and endpoints (cyan/yellow)
+- Ring-wearing zone band (yellow, semi-transparent)
+- Cross-section sampling lines (orange)
+- Measurement intersection points (blue circles)
+- Final measurement and confidence text (large, readable font)
+
+## Code Patterns and Conventions
+
+### Error Handling
+- Functions return `None` or raise exceptions on failure
+- Main pipeline (`measure_finger()`) returns structured output dict with `fail_reason`
+- Console logging provides detailed progress information
+
+### Type Hints
+- Extensive use of type hints throughout
+- Dict return types with `Dict[str, Any]` for structured data
+- NumPy arrays typed as `np.ndarray`
+- Literal types for enums (e.g., `FingerIndex`)
+
+### Data Flow
+- All major functions return dictionaries with consistent keys
+- Downstream functions accept upstream outputs directly
+- Debug visualization receives all intermediate results
+- Clean separation between detection, computation, and visualization
+
+### Validation and Sanity Checks
+- Finger width should be in realistic range: 1.0-3.0 cm (typical: 1.4-2.4 cm)
+- Credit card aspect ratio should be close to 1.586
+- View angle check: scale confidence should be >0.9 for accurate measurements
+- Minimum mask area threshold prevents false detections

CLAUDE.md

@@ -0,0 +1,364 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Standard Task Workflow
+
+For tasks of implementing **new features**:
+1. Read PRD.md, Plan.md, Progress.md before coding
+2. Summarize current project state before implementation
+3. Carry out the implementatation; after that, build and test if possible
+4. Update Progress.md after changes
+5. Commit with a clear, concise message
+
+For tasks of **bug fixing**:
+1. Summarize the bug, reason and solution before implementation
+2. Carry out the implementation to fix the bug; build and test afterwards;
+3. Update Progress.md after changes
+4. Commit with a clear, concise message
+
+For tasks of **reboot** from a new codex session:
+1. Read doc/v0/PRD.md, doc/v0/Plan.md, doc/v0/Progress.md for baseline implementation
+2. Read doc/v1/PRD.md, doc/v1/Plan.md, doc/v1/Progress.md for edge refinement (v1)
+3. Assume this is a continuation of an existing project.
+4. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
+
+## Project Overview
+
+Ring Sizer is a **local, terminal-executable computer vision program** that measures the outer width (diameter) of a finger at the ring-wearing zone using a single RGB image. It uses a standard credit card (ISO/IEC 7810 ID-1: 85.60mm × 53.98mm) as a physical size reference for scale calibration.
+
+**Key characteristics:**
+- Single image input (JPG/PNG)
+- **v1: Dual edge detection** - Landmark-based axis + Sobel gradient refinement
+- MediaPipe-based hand and finger segmentation
+- MediaPipe-based hand and finger segmentation
+- Outputs JSON measurement data and optional debug visualization
+- No cloud processing, runs entirely locally
+- Python 3.8+ with OpenCV, NumPy, MediaPipe, and SciPy
+
+## Development Commands
+
+### Installation
+```bash
+# Create virtual environment (recommended)
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### Running the Program
+```bash
+# Basic measurement (defaults to index finger, auto edge detection)
+python measure_finger.py --input input/test_image.jpg --output output/result.json
+
+# Measure specific finger (index, middle, ring, or auto)
+python measure_finger.py \
+  --input input/test_image.jpg \
+  --output output/result.json \
+  --finger-index ring
+
+# With debug visualization
+python measure_finger.py \
+  --input input/test_image.jpg \
+  --output output/result.json \
+  --finger-index middle \
+  --debug output/debug_overlay.png
+
+# Force Sobel edge refinement (v1)
+python measure_finger.py \
+  --input image.jpg \
+  --output result.json \
+  --finger-index ring \
+  --edge-method sobel \
+  --sobel-threshold 15.0 \
+  --debug output/debug.png
+
+# Compare both methods
+python measure_finger.py \
+  --input image.jpg \
+  --output result.json \
+  --finger-index middle \
+  --edge-method compare \
+  --debug output/debug.png
+
+# Force contour method (v0)
+python measure_finger.py \
+  --input image.jpg \
+  --output result.json \
+  --finger-index index \
+  --edge-method contour
+```
+
+## Architecture Overview
+
+### Processing Pipeline (9 Phases)
+
+The measurement pipeline follows a strict sequential flow:
+
+1. **Image Quality Check** - Blur detection, exposure validation, resolution check
+2. **Credit Card Detection & Scale Calibration** - Detects card, verifies aspect ratio (~1.586), computes `px_per_cm`
+3. **Hand & Finger Segmentation** - MediaPipe hand detection, finger isolation, mask generation
+4. **Finger Contour Extraction** - Extracts outer contour from cleaned mask
+5. **Finger Axis Estimation** - PCA-based principal axis calculation, determines palm-end vs tip-end
+6. **Ring-Wearing Zone Localization** - Defines zone at 15%-25% of finger length from palm-side
+7. **Width Measurement** - Samples 20 cross-sections perpendicular to axis, uses median width
+8. **Confidence Scoring** - Multi-factor scoring (card 30%, finger 30%, measurement 40%)
+9. **Debug Visualization** - Generates annotated overlay image
+
+### Module Structure
+
+The codebase is organized into focused utility modules in `src/`:
+
+| Module | Primary Responsibilities |
+|--------|--------------------------|
+| `card_detection.py` | Credit card detection, perspective correction, scale calibration (`px_per_cm`) |
+| `finger_segmentation.py` | MediaPipe integration, hand/finger isolation, mask cleaning, contour extraction |
+| `geometry.py` | PCA axis estimation, ring zone localization, cross-section width measurement, line-contour intersections |
+| `image_quality.py` | Blur detection (Laplacian variance), exposure checks, resolution validation |
+| `confidence.py` | Component confidence scoring (card, finger, measurement), overall confidence computation |
+| `visualization.py` | Debug overlay generation with contours, zones, measurements, and annotations |
+
+### Key Design Decisions
+
+**Ring-Wearing Zone Definition:**
+- Located at 15%-25% of finger length from palm-side end
+- Width measured by sampling 20 cross-sections within this zone
+- Final measurement is the **median width** (robust to outliers)
+
+**Axis Estimation:**
+- Uses PCA (Principal Component Analysis) on finger mask points
+- Determines palm-end vs tip-end using either:
+  1. MediaPipe landmarks (preferred, if available)
+  2. Thickness heuristic (thinner end is likely the tip)
+
+**Confidence Scoring:**
+- 3-component weighted average: Card (30%) + Finger (30%) + Measurement (40%)
+- Confidence levels: HIGH (>0.85), MEDIUM (0.6-0.85), LOW (<0.6)
+- Factors: card detection quality, finger mask area, width variance, aspect ratios
+
+**Measurement Approach:**
+- Perpendicular cross-sections to finger axis
+- Line-contour intersection algorithm finds left/right edges
+- Uses farthest pair of intersections to handle complex contours
+- Converts pixels to cm using calibrated scale factor
+
+---
+
+## v1 Architecture (Edge Refinement)
+
+### What's New in v1
+
+v1 improves measurement accuracy by replacing contour-based edge detection with gradient-based Sobel edge refinement. Key improvements:
+
+- **Landmark-based axis**: Uses MediaPipe finger landmarks (MCP→PIP→DIP→TIP) for more anatomically consistent axis estimation
+- **Sobel edge detection**: Bidirectional gradient filtering for pixel-precise edge localization
+- **Sub-pixel refinement**: Parabola fitting achieves <0.5px precision (~0.003cm at typical resolution)
+- **Quality-based fallback**: Automatically uses v0 contour method if Sobel quality insufficient
+- **Enhanced confidence**: Adds edge quality component (gradient strength, consistency, smoothness, symmetry)
+
+### v1 Processing Pipeline (Enhanced Phases)
+
+**Phase 5a: Landmark-Based Axis Estimation (v1)**
+- Uses MediaPipe finger landmarks directly (4 points: MCP, PIP, DIP, TIP)
+- **Finger selection**: Defaults to index finger, can specify middle or ring finger via `--finger-index`
+- Orientation detection uses the **specified finger** for axis calculation (wrist → finger tip)
+- Image automatically rotated to canonical orientation (wrist at bottom, fingers pointing up)
+- Three axis calculation methods:
+  - `endpoints`: Simple MCP→TIP vector
+  - `linear_fit`: Linear regression on all 4 landmarks (default, most robust)
+  - `median_direction`: Median of segment directions
+- Falls back to PCA if landmarks unavailable or quality check fails
+- Validation checks: NaN/inf, minimum spacing, monotonic progression, minimum length
+
+**Phase 7b: Sobel Edge Refinement (v1)**
+```
+1. Extract ROI around ring zone → 2. Apply bidirectional Sobel filters →
+3. Detect edges per cross-section → 4. Sub-pixel refinement → 5. Measure width
+```
+
+1. **ROI Extraction**
+   - Rectangular region around ring zone with padding (50px for gradient context)
+   - Width estimation: `finger_length / 3.0` (conservative)
+   - Optional rotation alignment (not used by default)
+
+2. **Bidirectional Sobel Filtering**
+   - Applies `cv2.Sobel` with configurable kernel size (3, 5, or 7)
+   - Computes gradient_x (horizontal edges), gradient_y (vertical edges)
+   - Calculates gradient magnitude and direction
+   - Auto-detects filter orientation from ROI aspect ratio
+
+3. **Edge Detection Per Cross-Section**
+   - **Mask-constrained mode** (primary):
+     - Finds leftmost/rightmost finger mask pixels (finger boundaries)
+     - Searches ±10px around boundaries for strongest gradient
+     - Combines anatomical accuracy (mask) with sub-pixel precision (gradient)
+   - **Gradient-only mode** (fallback): Pure Sobel without mask constraint
+
+4. **Sub-Pixel Edge Localization**
+   - Parabola fitting: f(x) = ax² + bx + c
+   - Samples gradient at x-1, x, x+1
+   - Finds parabola peak: x_peak = -b/(2a)
+   - Constrains refinement to ±0.5 pixels
+   - Achieves <0.5px precision (~0.003cm at 185 px/cm)
+
+5. **Width Measurement**
+   - Calculates width for each valid row
+   - Outlier filtering using Median Absolute Deviation (MAD)
+   - Removes measurements >3 MAD from median
+   - Computes median, mean, std dev
+   - Converts pixels to cm using scale factor
+
+**Phase 8b: Enhanced Confidence Scoring (v1)**
+- Adds 4th component: Edge Quality (20% weight)
+  - Gradient strength: Avg magnitude at detected edges
+  - Consistency: % of rows with valid edge pairs
+  - Smoothness: Edge position variance (lower = better)
+  - Symmetry: Left/right edge strength balance
+- Reweights other components: Card 25%, Finger 25%, Measurement 30%
+
+### v1 Module Structure
+
+| Module | v1 Enhancements |
+|--------|-----------------|
+| `geometry.py` | Added `estimate_finger_axis_from_landmarks()`, `_validate_landmark_quality()`, landmark-based zone localization |
+| **`edge_refinement.py`** | **[NEW]** Complete Sobel edge refinement pipeline with sub-pixel precision |
+| `confidence.py` | Added `compute_edge_quality_confidence()`, dual-mode confidence calculation |
+| `debug_observer.py` | Added 9 edge refinement drawing functions for visualization |
+| `measure_finger.py` | CLI flags for edge method selection, method comparison mode |
+
+### v1 CLI Flags
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--finger-index` | auto, index, middle, ring, pinky | **index** | Which finger to measure and use for orientation |
+| `--edge-method` | auto, contour, sobel, compare | auto | Edge detection method |
+| `--sobel-threshold` | float | 15.0 | Minimum gradient magnitude |
+| `--sobel-kernel-size` | 3, 5, 7 | 3 | Sobel kernel size |
+| `--no-subpixel` | flag | False | Disable sub-pixel refinement |
+
+### v1 Auto Mode Behavior
+
+When `--edge-method auto` (default):
+1. Always computes contour measurement (v0 baseline)
+2. Attempts Sobel edge refinement
+3. Evaluates Sobel quality score (threshold: 0.7)
+4. Checks consistency (>50% success rate required)
+5. Verifies width reasonableness (0.8-3.5 cm)
+6. Checks agreement with contour (<50% difference)
+7. Uses Sobel if all checks pass, otherwise falls back to contour
+8. Reports method used in `edge_method_used` field
+
+### v1 Debug Output
+
+When `--debug` flag used, generates:
+- Main debug overlay (same as v0, shows final result)
+- `output/edge_refinement_debug/` subdirectory with 12 images:
+  - **Stage A** (3): Landmark axis, ring zone, ROI extraction
+  - **Stage B** (5): Sobel gradients, candidates, selected edges
+  - **Stage C** (4): Sub-pixel refinement, widths, distribution, outliers
+
+### v1 Failure Modes (Additional)
+
+- `sobel_edge_refinement_failed` - Sobel method explicitly requested but failed
+- `quality_score_low_X.XX` - Edge quality below threshold (auto fallback)
+- `consistency_low_X.XX` - Too few valid edge detections
+- `width_unreasonable` - Measured width outside realistic range
+- `disagreement_with_contour` - Sobel and contour differ by >50%
+
+---
+
+## Important Technical Details
+
+### What This Measures
+The system measures the **external horizontal width** (outer diameter) of the finger at the ring-wearing zone. This is:
+- ✅ The width of soft tissue + bone at the ring-wearing position
+- ❌ NOT the inner diameter of a ring
+- Used as a geometric proxy for downstream ring size mapping (out of scope for v0)
+
+### Coordinate Systems
+- Images use standard OpenCV format: (row, col) = (y, x)
+- Most geometry functions work in (x, y) format
+- Contours are Nx2 arrays in (x, y) format
+- Careful conversion needed between formats (see `geometry.py:35`)
+
+### MediaPipe Integration
+- Uses pretrained hand landmark detection model (no custom training)
+- Provides 21 hand landmarks per hand
+- Each finger has 4 landmarks: MCP (base), PIP, DIP, TIP
+- Finger indices: 0=thumb, 1=index, 2=middle, 3=ring, 4=pinky
+- **Orientation detection**: Uses wrist → specified finger tip to determine hand rotation
+- **Automatic rotation**: Image rotated to canonical orientation (wrist at bottom, fingers up) based on selected finger
+
+### Input Requirements
+For optimal results:
+- Resolution: 1080p or higher recommended
+- View angle: Near top-down view
+- **Finger**: One finger extended (index, middle, or ring). Specify with `--finger-index`
+- Credit card: Must show at least 3 corners, aspect ratio ~1.586
+- Finger and card must be on the same plane
+- Good lighting, minimal blur
+
+### Failure Modes
+The system can fail at various stages:
+- `card_not_detected` - Credit card not found or aspect ratio invalid
+- `hand_not_detected` - No hand detected by MediaPipe
+- `finger_isolation_failed` - Could not isolate specified finger
+- `finger_mask_too_small` - Mask area too small after cleaning
+- `contour_extraction_failed` - Could not extract valid contour
+- `axis_estimation_failed` - PCA failed or insufficient points
+- `zone_localization_failed` - Could not define ring zone
+- `width_measurement_failed` - No valid cross-section intersections
+
+## Output Format
+
+### JSON Output Structure
+```json
+{
+  "finger_outer_diameter_cm": 1.78,
+  "confidence": 0.86,
+  "scale_px_per_cm": 42.3,
+  "quality_flags": {
+    "card_detected": true,
+    "finger_detected": true,
+    "view_angle_ok": true
+  },
+  "fail_reason": null
+}
+```
+
+### Debug Visualization Features
+When `--debug` flag is used, generates an annotated image with:
+- Credit card contour and corners (green)
+- Finger contour (magenta, thick lines)
+- Finger axis and endpoints (cyan/yellow)
+- Ring-wearing zone band (yellow, semi-transparent)
+- Cross-section sampling lines (orange)
+- Measurement intersection points (blue circles)
+- Final measurement and confidence text (large, readable font)
+
+## Code Patterns and Conventions
+
+### Error Handling
+- Functions return `None` or raise exceptions on failure
+- Main pipeline (`measure_finger()`) returns structured output dict with `fail_reason`
+- Console logging provides detailed progress information
+
+### Type Hints
+- Extensive use of type hints throughout
+- Dict return types with `Dict[str, Any]` for structured data
+- NumPy arrays typed as `np.ndarray`
+- Literal types for enums (e.g., `FingerIndex`)
+
+### Data Flow
+- All major functions return dictionaries with consistent keys
+- Downstream functions accept upstream outputs directly
+- Debug visualization receives all intermediate results
+- Clean separation between detection, computation, and visualization
+
+### Validation and Sanity Checks
+- Finger width should be in realistic range: 1.0-3.0 cm (typical: 1.4-2.4 cm)
+- Credit card aspect ratio should be close to 1.586
+- View angle check: scale confidence should be >0.9 for accurate measurements
+- Minimum mask area threshold prevents false detections

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.11-slim
+
+# System deps required by OpenCV and MediaPipe
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends libgl1 libglib2.0-0 && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Ensure upload/result dirs exist
+RUN mkdir -p web_demo/uploads web_demo/results
+
+ENV PORT=7860
+
+EXPOSE ${PORT}
+
+CMD gunicorn --bind 0.0.0.0:${PORT} --timeout 120 --workers 2 web_demo.app:app

README.md

@@ -1,10 +1,135 @@
 ---
 title: Ring Sizer
-emoji: 🌍
+emoji: "\U0001F48D"
 colorFrom: blue
-colorTo: red
+colorTo: purple
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Ring Sizer
+
+Local computer-vision CLI tool that measures **finger outer diameter** from a single image using a **credit card** as scale reference.
+
+## What it does
+- Detects a credit card and computes `px/cm` scale.
+- Detects hand/finger with MediaPipe.
+- Measures finger width in the ring-wearing zone.
+- Supports dual edge modes:
+  - `contour` (v0 baseline)
+  - `sobel` (v1 refinement)
+  - `auto` (default, Sobel with quality fallback)
+  - `compare` (returns both method stats)
+- Writes JSON output and always writes a result PNG next to it.
+
+## Install
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Run
+```bash
+python measure_finger.py --input input/test_image.jpg --output output/result.json
+```
+
+### Common options
+```bash
+# Enable intermediate debug folders (card/finger/edge stages)
+python measure_finger.py --input image.jpg --output output/result.json --debug
+
+# Finger selection
+python measure_finger.py --input image.jpg --output output/result.json --finger-index ring
+
+# Force method
+python measure_finger.py --input image.jpg --output output/result.json --edge-method contour
+python measure_finger.py --input image.jpg --output output/result.json --edge-method sobel
+
+# Compare contour vs sobel
+python measure_finger.py --input image.jpg --output output/result.json --edge-method compare
+
+# Sobel tuning
+python measure_finger.py --input image.jpg --output output/result.json \
+  --edge-method sobel --sobel-threshold 15 --sobel-kernel-size 3 --no-subpixel
+```
+
+## CLI flags (current)
+- `--input` (required)
+- `--output` (required)
+- `--debug` (boolean; saves intermediate debug folders)
+- `--save-intermediate`
+- `--finger-index {auto,index,middle,ring,pinky}` (default `index`)
+- `--confidence-threshold` (default `0.7`)
+- `--edge-method {auto,contour,sobel,compare}` (default `auto`)
+- `--sobel-threshold` (default `15.0`)
+- `--sobel-kernel-size {3,5,7}` (default `3`)
+- `--no-subpixel`
+- `--skip-card-detection` (testing only)
+
+## Output JSON
+```json
+{
+  "finger_outer_diameter_cm": 1.78,
+  "confidence": 0.91,
+  "scale_px_per_cm": 203.46,
+  "quality_flags": {
+    "card_detected": true,
+    "finger_detected": true,
+    "view_angle_ok": true
+  },
+  "fail_reason": null,
+  "edge_method_used": "contour_fallback",
+  "method_comparison": {
+    "contour": {
+      "width_cm": 1.82,
+      "width_px": 371.2,
+      "std_dev_px": 3.8,
+      "coefficient_variation": 0.01,
+      "num_samples": 20,
+      "method": "contour"
+    },
+    "sobel": {
+      "width_cm": 1.78,
+      "width_px": 362.0,
+      "std_dev_px": 3.1,
+      "coefficient_variation": 0.008,
+      "num_samples": 140,
+      "subpixel_used": true,
+      "success_rate": 0.42,
+      "edge_quality_score": 0.81,
+      "method": "sobel"
+    },
+    "difference": {
+      "absolute_cm": -0.04,
+      "absolute_px": -9.2,
+      "relative_pct": -2.2,
+      "precision_improvement": 0.7
+    },
+    "recommendation": {
+      "use_sobel": true,
+      "reason": "quality_acceptable",
+      "preferred_method": "sobel"
+    },
+    "quality_comparison": {
+      "contour_cv": 0.01,
+      "sobel_cv": 0.008,
+      "sobel_quality_score": 0.81,
+      "sobel_gradient_strength": 0.82,
+      "sobel_consistency": 0.42,
+      "sobel_smoothness": 0.91,
+      "sobel_symmetry": 0.95
+    }
+  }
+}
+```
+
+Notes:
+- `edge_method_used` and `method_comparison` are optional (present when relevant).
+- Result image path is auto-derived: `output/result.json` -> `output/result.png`.
+
+## Documentation map
+- Requirement docs: `doc/v{i}/PRD.md`, `doc/v{i}/Plan.md`, `doc/v{i}/Progress.md`
+- Algorithms index: `doc/algorithms/README.md`
+- Scripts: `script/README.md`
+- Web demo: `web_demo/README.md`

fly.toml

@@ -0,0 +1,16 @@
+app = 'ring-size-cv'
+primary_region = 'sjc'
+
+[build]
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = 'stop'
+  auto_start_machines = true
+  min_machines_running = 0
+
+[[vm]]
+  memory = '1gb'
+  cpu_kind = 'shared'
+  cpus = 1

measure_finger.py

@@ -0,0 +1,763 @@
+#!/usr/bin/env python3
+"""
+Finger Outer Diameter Measurement Tool
+
+Measures the outer width (diameter) of a finger at the ring-wearing zone
+using a single RGB image with a credit card as a physical size reference.
+
+Usage:
+    python measure_finger.py --input image.jpg --output result.json [--debug]
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any, Literal
+
+import cv2
+import numpy as np
+
+from src.image_quality import assess_image_quality
+from src.card_detection import detect_credit_card, compute_scale_factor
+from src.finger_segmentation import segment_hand, isolate_finger, clean_mask, get_finger_contour
+from src.geometry import estimate_finger_axis, localize_ring_zone, localize_ring_zone_from_landmarks, compute_cross_section_width
+from src.edge_refinement import refine_edges_sobel, should_use_sobel_measurement, compare_edge_methods
+from src.confidence import (
+    compute_card_confidence,
+    compute_finger_confidence,
+    compute_measurement_confidence,
+    compute_edge_quality_confidence,
+    compute_overall_confidence,
+)
+from src.debug_observer import draw_comprehensive_edge_overlay
+
+# Type alias for finger selection
+FingerIndex = Literal["auto", "index", "middle", "ring", "pinky"]
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Measure finger outer diameter from an image with credit card reference.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    python measure_finger.py --input photo.jpg --output result.json
+    python measure_finger.py --input photo.jpg --output result.json --debug
+    python measure_finger.py --input photo.jpg --output result.json --finger-index ring
+    python measure_finger.py --input photo.jpg --output result.json --finger-index middle
+        """,
+    )
+
+    # Required arguments
+    parser.add_argument(
+        "--input",
+        type=str,
+        required=True,
+        help="Path to input image (JPG/PNG)",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        required=True,
+        help="Path to output JSON file",
+    )
+
+    # Optional arguments
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        default=False,
+        help="Save intermediate debug images (card_detection_debug/, edge_refinement_debug/, etc.)",
+    )
+    parser.add_argument(
+        "--save-intermediate",
+        action="store_true",
+        help="Save intermediate processing artifacts",
+    )
+    parser.add_argument(
+        "--finger-index",
+        type=str,
+        choices=["auto", "index", "middle", "ring", "pinky"],
+        default="index",
+        help="Which finger to measure (default: index). 'auto' detects the most extended finger.",
+    )
+    parser.add_argument(
+        "--confidence-threshold",
+        type=float,
+        default=0.7,
+        help="Minimum confidence threshold (default: 0.7)",
+    )
+
+    # v1 edge refinement options
+    parser.add_argument(
+        "--edge-method",
+        type=str,
+        default="auto",
+        choices=["auto", "contour", "sobel", "compare"],
+        help="Edge detection method: auto (quality-based), contour (v0), sobel (v1), compare (both) (default: auto)",
+    )
+    parser.add_argument(
+        "--sobel-threshold",
+        type=float,
+        default=15.0,
+        help="Minimum gradient magnitude for valid edge (default: 15.0)",
+    )
+    parser.add_argument(
+        "--sobel-kernel-size",
+        type=int,
+        default=3,
+        choices=[3, 5, 7],
+        help="Sobel kernel size (default: 3)",
+    )
+    parser.add_argument(
+        "--no-subpixel",
+        action="store_true",
+        help="Disable sub-pixel edge refinement",
+    )
+
+    # Testing/debugging options
+    parser.add_argument(
+        "--skip-card-detection",
+        action="store_true",
+        help="[TESTING ONLY] Skip card detection and use dummy scale (allows testing finger segmentation without card)",
+    )
+
+    return parser.parse_args()
+
+
+def validate_input(input_path: str) -> Optional[str]:
+    """
+    Validate input file exists and is a supported image format.
+
+    Args:
+        input_path: Path to input image
+
+    Returns:
+        Error message if validation fails, None if valid
+    """
+    path = Path(input_path)
+
+    if not path.exists():
+        return f"Input file not found: {input_path}"
+
+    if not path.is_file():
+        return f"Input path is not a file: {input_path}"
+
+    suffix = path.suffix.lower()
+    if suffix not in [".jpg", ".jpeg", ".png"]:
+        return f"Unsupported image format: {suffix}. Use JPG or PNG."
+
+    return None
+
+
+def load_image(input_path: str) -> Optional[np.ndarray]:
+    """
+    Load image from file.
+
+    Args:
+        input_path: Path to input image
+
+    Returns:
+        BGR image as numpy array, or None if load fails
+    """
+    image = cv2.imread(input_path)
+    return image
+
+
+def create_output(
+    finger_diameter_cm: Optional[float] = None,
+    confidence: float = 0.0,
+    scale_px_per_cm: Optional[float] = None,
+    card_detected: bool = False,
+    finger_detected: bool = False,
+    view_angle_ok: bool = True,
+    fail_reason: Optional[str] = None,
+    edge_method_used: Optional[str] = None,
+    method_comparison: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Create output dictionary in the specified format.
+
+    Args:
+        finger_diameter_cm: Measured finger diameter in cm
+        confidence: Confidence score [0, 1]
+        scale_px_per_cm: Computed scale factor
+        card_detected: Whether credit card was detected
+        finger_detected: Whether finger was detected
+        view_angle_ok: Whether view angle is acceptable
+        fail_reason: Reason for failure if applicable
+        edge_method_used: Edge detection method used (v1)
+        method_comparison: Comparison data when using compare mode (v1)
+
+    Returns:
+        Output dictionary matching PRD specification
+    """
+    output = {
+        "finger_outer_diameter_cm": float(finger_diameter_cm) if finger_diameter_cm is not None else None,
+        "confidence": float(round(confidence, 3)),
+        "scale_px_per_cm": round(float(scale_px_per_cm), 2) if scale_px_per_cm is not None else None,
+        "quality_flags": {
+            "card_detected": bool(card_detected),
+            "finger_detected": bool(finger_detected),
+            "view_angle_ok": bool(view_angle_ok),
+        },
+        "fail_reason": fail_reason,
+    }
+
+    # Add v1 fields if applicable
+    if edge_method_used is not None:
+        output["edge_method_used"] = edge_method_used
+
+    if method_comparison is not None:
+        output["method_comparison"] = method_comparison
+
+    return output
+
+
+def save_output(output: Dict[str, Any], output_path: str) -> None:
+    """Save output dictionary to JSON file."""
+    # Ensure output directory exists
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+
+    with open(output_path, "w") as f:
+        json.dump(output, f, indent=2)
+
+
+def measure_finger(
+    image: np.ndarray,
+    finger_index: FingerIndex = "index",
+    confidence_threshold: float = 0.7,
+    save_intermediate: bool = False,
+    result_png_path: Optional[str] = None,
+    save_debug: bool = False,
+    edge_method: str = "auto",
+    sobel_threshold: float = 15.0,
+    sobel_kernel_size: int = 3,
+    use_subpixel: bool = True,
+    skip_card_detection: bool = False,
+) -> Dict[str, Any]:
+    """
+    Main measurement pipeline.
+
+    Args:
+        image: Input BGR image
+        finger_index: Which finger to measure
+        confidence_threshold: Minimum confidence threshold
+        save_intermediate: Whether to save intermediate artifacts
+        result_png_path: Path to save result visualization PNG (always generated)
+        save_debug: Whether to save intermediate debug images
+        edge_method: Edge detection method (auto, contour, sobel, compare)
+        sobel_threshold: Minimum gradient magnitude for valid edge
+        sobel_kernel_size: Sobel kernel size (3, 5, or 7)
+        use_subpixel: Enable sub-pixel edge refinement
+
+    Returns:
+        Output dictionary with measurement results
+    """
+    # Phase 2: Image quality check
+    quality = assess_image_quality(image)
+    print(f"Image quality: blur={quality['blur_score']:.1f}, "
+          f"brightness={quality['brightness']:.1f}, "
+          f"contrast={quality['contrast']:.1f}")
+
+    if not quality["passed"]:
+        for issue in quality["issues"]:
+            print(f"  Warning: {issue}")
+        return create_output(fail_reason=quality["fail_reason"])
+
+    # Phase 3: Hand & finger segmentation (MOVED BEFORE CARD DETECTION)
+    # This allows us to rotate the image to canonical orientation first
+    # Create finger segmentation debug subdirectory if debug enabled
+    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=finger_index, debug_dir=finger_debug_dir)
+
+    if hand_data is None:
+        print("No hand detected in image")
+        return create_output(
+            card_detected=False,  # Card not yet detected
+            finger_detected=False,
+            fail_reason="hand_not_detected",
+        )
+
+    print(f"Hand detected: {hand_data['handedness']}, confidence={hand_data['confidence']:.2f}")
+    if "orientation_rotation" in hand_data:
+        print(f"Hand orientation normalized: {hand_data['orientation_rotation']}° rotation applied")
+    
+    # Use canonical image for all downstream processing
+    # This ensures finger edges are vertical for optimal Sobel detection
+    if "canonical_image" in hand_data:
+        image_canonical = hand_data["canonical_image"]
+        print(f"Using canonical orientation image: {image_canonical.shape[1]}x{image_canonical.shape[0]}")
+    else:
+        image_canonical = image  # Fallback if not available
+        print("Warning: Canonical image not available, using original")
+
+    # Phase 4: Credit card detection & scale calibration (NOW ON CANONICAL IMAGE)
+    # Create card detection debug subdirectory if debug enabled
+    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")
+
+    # Allow skipping card detection for testing finger segmentation
+    if skip_card_detection:
+        print("⚠️  TESTING MODE: Skipping card detection (using dummy scale factor)")
+        card_result = None
+        px_per_cm = 100.0  # Dummy scale: 100 pixels/cm (measurements will be inaccurate)
+        scale_confidence = 0.5  # Low confidence to indicate dummy value
+        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:
+            print("Credit card not detected in image")
+            return create_output(
+                card_detected=False,
+                fail_reason="card_not_detected",
+            )
+
+        # Compute scale factor
+        px_per_cm, scale_confidence = compute_scale_factor(card_result["corners"])
+        print(f"Card detected: {card_result['width_px']:.0f}x{card_result['height_px']:.0f}px, "
+              f"aspect={card_result['aspect_ratio']:.3f}, confidence={card_result['confidence']:.2f}")
+        print(f"Scale: {px_per_cm:.2f} px/cm (confidence={scale_confidence:.2f})")
+
+        # Check for excessive perspective distortion (view angle)
+        view_angle_ok = scale_confidence > 0.9
+        card_detected = True
+
+    # Phase 5: Finger isolation (hand already segmented in Phase 3)
+    h_can, w_can = image_canonical.shape[:2]
+    finger_data = isolate_finger(hand_data, finger=finger_index, image_shape=(h_can, w_can))
+
+    if finger_data is None:
+        print(f"Could not isolate finger: {finger_index}")
+        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",
+        )
+
+    print(f"Finger isolated: {finger_data['finger_name']}")
+
+    # Clean the finger mask
+    cleaned_mask = clean_mask(finger_data["mask"])
+
+    if cleaned_mask is None:
+        print("Finger mask too small or invalid")
+        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",
+        )
+
+    # Extract finger contour
+    contour = get_finger_contour(cleaned_mask)
+
+    if contour is None:
+        print("Could not extract finger contour")
+        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",
+        )
+
+    print(f"Finger contour extracted: {len(contour)} points")
+
+    # Phase 5: Estimate finger axis using PCA
+    try:
+        axis_data = estimate_finger_axis(
+            mask=cleaned_mask,
+            landmarks=finger_data.get("landmarks"),
+        )
+        print(f"Finger axis estimated: length={axis_data['length']:.1f}px, "
+              f"center=({axis_data['center'][0]:.0f}, {axis_data['center'][1]:.0f})")
+    except Exception as e:
+        print(f"Failed to estimate finger axis: {e}")
+        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",
+        )
+
+    # Phase 5b: Precise finger alignment rotation
+    # Rotate image to make finger axis perfectly vertical for accurate width measurement
+    from src.geometry import (
+        calculate_angle_from_vertical,
+        rotate_image_precise,
+        rotate_axis_data,
+        rotate_contour,
+        transform_points_rotation
+    )
+
+    angle_from_vertical = calculate_angle_from_vertical(axis_data["direction"])
+    #rotation_threshold = 2.0  # Only rotate if > 2° off vertical
+    rotation_threshold = 0.0  # always rorate to upright
+
+    rotation_matrix = None  # Track rotation for card corner transform in debug
+
+    if abs(angle_from_vertical) >= rotation_threshold:
+        print(f"Finger axis is {angle_from_vertical:.1f}° from vertical, applying precise rotation...")
+
+        # Rotate image
+        h_can, w_can = image_canonical.shape[:2]
+        rotation_center = (w_can / 2.0, h_can / 2.0)
+        image_canonical, rotation_matrix = rotate_image_precise(
+            image_canonical, angle_from_vertical, rotation_center
+        )
+
+        # Update axis data
+        axis_data = rotate_axis_data(axis_data, rotation_matrix)
+
+        # Update contour
+        contour = rotate_contour(contour, rotation_matrix)
+
+        # Update landmarks if available
+        if finger_data.get("landmarks") is not None:
+            landmarks_rotated = transform_points_rotation(
+                finger_data["landmarks"], rotation_matrix
+            )
+            finger_data["landmarks"] = landmarks_rotated
+
+        # Update cleaned mask
+        cleaned_mask = cv2.warpAffine(
+            cleaned_mask, rotation_matrix, (w_can, h_can),
+            flags=cv2.INTER_NEAREST,
+            borderMode=cv2.BORDER_CONSTANT,
+            borderValue=0
+        )
+
+        print(f"Rotation applied: {angle_from_vertical:.1f}° CW, finger now vertical")
+    else:
+        print(f"Finger axis is {angle_from_vertical:.1f}° from vertical (within {rotation_threshold}° threshold, no rotation needed)")
+
+    # Phase 6: Localize ring-wearing zone
+    try:
+        # Use anatomical mode if landmarks available, otherwise use percentage-based
+        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"
+            )
+            zone_length_cm = zone_data["length"] / px_per_cm
+            print(f"Ring zone localized (anatomical): PIP to PIP-(DIP-PIP), "
+                  f"length={zone_data['length']:.1f}px ({zone_length_cm:.2f}cm)")
+        else:
+            zone_data = localize_ring_zone(axis_data)
+            zone_length_cm = zone_data["length"] / px_per_cm
+            print(f"Ring zone localized (percentage): {zone_data['start_pct']*100:.0f}%-{zone_data['end_pct']*100:.0f}% "
+                  f"from palm, length={zone_data['length']:.1f}px ({zone_length_cm:.2f}cm)")
+    except Exception as e:
+        print(f"Failed to localize ring zone: {e}")
+        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",
+        )
+
+    # Phase 7: Measure finger width at ring zone
+
+    # Phase 7a: Contour-based measurement (v0 method)
+    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
+        print(f"Contour width: {contour_width_cm:.4f}cm "
+              f"({contour_measurement['num_samples']} samples, "
+              f"std={contour_measurement['std_width_px']:.2f}px)")
+
+    except Exception as e:
+        print(f"Failed to measure finger width (contour): {e}")
+        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",
+        )
+
+    # Phase 7b: Sobel-based measurement (v1 method)
+    sobel_measurement = None
+    sobel_failed = False
+
+    if edge_method in ["sobel", "auto", "compare"]:
+        try:
+            print(f"Running Sobel edge refinement (threshold={sobel_threshold}, kernel={sobel_kernel_size})...")
+            
+            # Create debug directory for edge refinement if debug enabled
+            edge_debug_dir = None
+            if save_debug and result_png_path is not None:
+                edge_debug_dir = str(Path(result_png_path).parent / "edge_refinement_debug")
+            
+            sobel_measurement = refine_edges_sobel(
+                image=image_canonical,  # Use canonical orientation
+                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,
+                debug_dir=edge_debug_dir,
+            )
+
+            sobel_width_cm = sobel_measurement["median_width_cm"]
+            print(f"Sobel width: {sobel_width_cm:.4f}cm "
+                  f"({sobel_measurement['num_samples']} samples, "
+                  f"std={sobel_measurement['std_width_px']:.2f}px, "
+                  f"quality={sobel_measurement['edge_quality']['overall_score']:.3f})")
+
+        except Exception as e:
+            print(f"Sobel edge refinement failed: {e}")
+            sobel_failed = True
+            if edge_method == "sobel":
+                # User explicitly requested Sobel, fail if it doesn't work
+                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 measurement method based on edge_method flag
+    method_comparison_data = None
+
+    if edge_method == "contour":
+        # Use contour method only
+        final_measurement = contour_measurement
+        median_width_cm = contour_width_cm
+        edge_method_used = "contour"
+
+    elif edge_method == "sobel":
+        # Use Sobel method only (already handled failure case above)
+        final_measurement = sobel_measurement
+        median_width_cm = sobel_measurement["median_width_cm"]
+        edge_method_used = "sobel"
+
+    elif edge_method == "auto":
+        # Automatic selection based on quality
+        if sobel_measurement and not sobel_failed:
+            should_use_sobel, reason = should_use_sobel_measurement(sobel_measurement, contour_measurement)
+
+            if should_use_sobel:
+                final_measurement = sobel_measurement
+                median_width_cm = sobel_measurement["median_width_cm"]
+                edge_method_used = "sobel"
+                print(f"Auto-selected: Sobel (reason: {reason})")
+            else:
+                final_measurement = contour_measurement
+                median_width_cm = contour_width_cm
+                edge_method_used = "contour_fallback"
+                print(f"Auto-selected: Contour fallback (reason: {reason})")
+        else:
+            # Sobel failed, use contour
+            final_measurement = contour_measurement
+            median_width_cm = contour_width_cm
+            edge_method_used = "contour_fallback"
+            print(f"Auto-selected: Contour (Sobel not available)")
+
+    elif edge_method == "compare":
+        # Comparison mode: prefer Sobel if available, include comparison data
+        if sobel_measurement and not sobel_failed:
+            method_comparison_data = compare_edge_methods(
+                contour_measurement, sobel_measurement, px_per_cm
+            )
+
+            # Prefer Sobel in compare mode for output
+            final_measurement = sobel_measurement
+            median_width_cm = sobel_measurement["median_width_cm"]
+            edge_method_used = "compare"
+
+            print(f"Method comparison:")
+            print(f"  Contour: {method_comparison_data['contour']['width_cm']:.4f}cm")
+            print(f"  Sobel:   {method_comparison_data['sobel']['width_cm']:.4f}cm")
+            print(f"  Diff:    {method_comparison_data['difference']['relative_pct']:+.2f}%")
+            print(f"  Recommendation: {method_comparison_data['recommendation']['preferred_method']}")
+        else:
+            # Sobel failed, can't compare
+            final_measurement = contour_measurement
+            median_width_cm = contour_width_cm
+            edge_method_used = "contour"
+            print(f"Compare mode: Sobel failed, using contour only")
+
+    # Sanity check: finger width should be in realistic range (1.4-2.4 cm)
+    if median_width_cm < 1.0 or median_width_cm > 3.0:
+        print(f"Warning: Measured width {median_width_cm:.2f}cm is outside realistic range")
+
+    # Phase 8: Comprehensive confidence scoring
+    # Calculate component confidences
+    if card_result is not None:
+        card_conf = compute_card_confidence(card_result, scale_confidence)
+    else:
+        # Dummy card confidence when card detection skipped (testing mode)
+        card_conf = scale_confidence  # Use dummy scale confidence (0.5)
+
+    # Calculate mask area for finger confidence
+    mask_area = np.sum(cleaned_mask > 0)
+    image_area = image.shape[0] * image.shape[1]
+    finger_conf = compute_finger_confidence(hand_data, finger_data, mask_area, image_area)
+
+    # Calculate measurement confidence
+    measurement_conf = compute_measurement_confidence(final_measurement, median_width_cm)
+
+    # Calculate edge quality confidence (v1)
+    edge_quality_conf = None
+    if edge_method_used in ["sobel", "compare"]:
+        edge_quality_conf = compute_edge_quality_confidence(
+            final_measurement.get("edge_quality")
+        )
+
+    # Compute overall confidence (v0 or v1 based on edge method)
+    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,
+    )
+
+    # Print confidence breakdown
+    conf_parts = [
+        f"card={confidence_breakdown['card']:.2f}",
+        f"finger={confidence_breakdown['finger']:.2f}",
+        f"measurement={confidence_breakdown['measurement']:.2f}",
+    ]
+    if confidence_breakdown.get('edge_quality') is not None:
+        conf_parts.append(f"edge={confidence_breakdown['edge_quality']:.2f}")
+
+    print(f"Confidence: {confidence_breakdown['overall']:.3f} ({confidence_breakdown['level']}) "
+          f"[{', '.join(conf_parts)}]")
+    if confidence_breakdown["overall"] < confidence_threshold:
+        print(f"Warning: Confidence {confidence_breakdown['overall']:.3f} is below threshold {confidence_threshold:.3f}")
+
+    # Phase 9: Result visualization (always generated)
+    if result_png_path is not None:
+        print(f"Generating result visualization...")
+
+        # Use comprehensive edge overlay (based on Sobel data) + card bounding box
+        if edge_method_used in ["sobel", "compare"] and sobel_measurement and not sobel_failed:
+            edge_data = sobel_measurement["edge_data"]
+            roi_bounds = sobel_measurement["roi_data"]["roi_bounds"]
+            width_data = sobel_measurement["width_data"]
+            width_data["median_width_cm"] = sobel_measurement["median_width_cm"]
+
+            debug_image = draw_comprehensive_edge_overlay(
+                full_image=image_canonical,
+                edge_data=edge_data,
+                roi_bounds=roi_bounds,
+                axis_data=axis_data,
+                zone_data=zone_data,
+                width_data=width_data,
+                scale_px_per_cm=px_per_cm,
+            )
+        else:
+            # Fallback: plain image with axis/zone annotations when Sobel unavailable
+            debug_image = image_canonical.copy()
+
+        # Draw card bounding box (transform corners if image was rotated)
+        if card_result is not None and "corners" in card_result:
+            corners = card_result["corners"]
+            if corners is not None:
+                pts = np.array(corners, dtype=np.float32)
+                if rotation_matrix is not None:
+                    pts = transform_points_rotation(pts, rotation_matrix)
+                pts = pts.astype(np.int32).reshape((-1, 1, 2))
+                cv2.polylines(debug_image, [pts], isClosed=True,
+                              color=(0, 255, 0), thickness=3, lineType=cv2.LINE_AA)
+
+        # Save result image
+        Path(result_png_path).parent.mkdir(parents=True, exist_ok=True)
+        cv2.imwrite(result_png_path, debug_image)
+        print(f"Result visualization saved to: {result_png_path}")
+
+
+    return 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,
+        fail_reason=None,
+        edge_method_used=edge_method_used,
+        method_comparison=method_comparison_data,
+    )
+
+
+def main() -> int:
+    """Main entry point."""
+    args = parse_args()
+
+    # Validate input
+    error = validate_input(args.input)
+    if error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+
+    # Load image
+    image = load_image(args.input)
+    if image is None:
+        print(f"Error: Failed to load image: {args.input}", file=sys.stderr)
+        return 1
+
+    print(f"Loaded image: {args.input} ({image.shape[1]}x{image.shape[0]})")
+
+    # Derive result PNG path from output JSON path
+    result_png_path = str(Path(args.output).with_suffix(".png"))
+
+    # Run measurement pipeline
+    result = measure_finger(
+        image=image,
+        finger_index=args.finger_index,
+        confidence_threshold=args.confidence_threshold,
+        save_intermediate=args.save_intermediate,
+        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,
+    )
+
+    # Save output
+    save_output(result, args.output)
+    print(f"Results saved to: {args.output}")
+
+    # Report result
+    if result["fail_reason"]:
+        print(f"Measurement failed: {result['fail_reason']}")
+        return 1
+    else:
+        print(f"Finger diameter: {result['finger_outer_diameter_cm']} cm")
+        print(f"Confidence: {result['confidence']}")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

requirements.txt

@@ -0,0 +1,7 @@
+opencv-python>=4.8.0
+numpy>=1.24.0
+mediapipe>=0.10.0
+scipy>=1.11.0
+scikit-learn>=1.3.0
+flask>=3.0.0
+gunicorn>=21.2.0

script/README.md

@@ -0,0 +1,25 @@
+# Scripts
+
+Utilities for local development/testing.
+
+## `script/test.sh`
+Quick runner for `measure_finger.py`.
+
+### Usage
+```bash
+./script/test.sh
+./script/test.sh input/my_image.jpg
+./script/test.sh --no-debug
+./script/test.sh --skip-card-detection
+./script/test.sh --help
+```
+
+### Behavior
+- Uses first image in `input/` when no image is passed.
+- Creates `.venv` and installs deps if missing.
+- Writes JSON to `output/test_result.json`.
+- Result PNG is auto-generated as `output/test_result.png` by the main tool.
+- `--debug` in this script toggles intermediate debug folders (default: enabled).
+
+## `script/build.sh`
+Reserved for packaging/build automation (currently empty).

script/test.sh

@@ -0,0 +1,171 @@
+#!/bin/bash
+# Quick test script for ring-sizer
+# Usage:
+#   ./script/test.sh              - Run basic test with debug output
+#   ./script/test.sh [image]      - Test with specific image
+#   ./script/test.sh --no-debug   - Run without debug visualization
+
+set -e  # Exit on error
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Get script directory and project root
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_ROOT="$( cd "$SCRIPT_DIR/.." && pwd )"
+
+# Change to project root
+cd "$PROJECT_ROOT"
+
+# Python executable
+PYTHON=".venv/bin/python"
+
+# Check if virtual environment exists
+if [ ! -f "$PYTHON" ]; then
+    echo -e "${YELLOW}Virtual environment not found. Creating...${NC}"
+    python3 -m venv .venv
+    echo -e "${GREEN}Installing dependencies...${NC}"
+    .venv/bin/pip install -r requirements.txt
+fi
+
+# Default values
+INPUT_IMAGE=""
+OUTPUT_JSON="output/test_result.json"
+ENABLE_DEBUG=true
+SKIP_CARD=false
+FINGER_INDEX="index"
+
+# Parse arguments
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --no-debug)
+            ENABLE_DEBUG=false
+            shift
+            ;;
+        --skip-card-detection|--skip-card)
+            SKIP_CARD=true
+            shift
+            ;;
+        --finger-index|--finger|-f)
+            if [ -z "$2" ]; then
+                echo -e "${YELLOW}Error: --finger-index requires a value: auto|index|middle|ring|pinky${NC}"
+                exit 1
+            fi
+            case "$2" in
+                auto|index|middle|ring|pinky)
+                    FINGER_INDEX="$2"
+                    ;;
+                *)
+                    echo -e "${YELLOW}Error: Invalid finger index '$2'. Use: auto|index|middle|ring|pinky${NC}"
+                    exit 1
+                    ;;
+            esac
+            shift 2
+            ;;
+        --help|-h)
+            echo "Usage: ./script/test.sh [OPTIONS] [IMAGE]"
+            echo ""
+            echo "Options:"
+            echo "  --no-debug              Run without debug visualization"
+            echo "  --skip-card-detection   Skip card detection (testing mode for finger segmentation)"
+            echo "  --finger-index, -f      Finger to measure: auto|index|middle|ring|pinky (default: index)"
+            echo "  --help, -h              Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  ./script/test.sh                        # Use first available test image"
+            echo "  ./script/test.sh input/my_image.jpg     # Test with specific image"
+            echo "  ./script/test.sh --no-debug             # Skip debug output"
+            echo "  ./script/test.sh --skip-card-detection  # Test finger segmentation without card"
+            echo "  ./script/test.sh -f ring                # Measure ring finger"
+            exit 0
+            ;;
+        *)
+            INPUT_IMAGE="$1"
+            shift
+            ;;
+    esac
+done
+
+# Find first available test image if not specified
+if [ -z "$INPUT_IMAGE" ]; then
+    echo -e "${BLUE}Looking for test images in input/...${NC}"
+
+    # Try to find any image file
+    for ext in jpg jpeg png heic; do
+        INPUT_IMAGE=$(find input/ -maxdepth 1 -type f -iname "*.$ext" | head -1)
+        if [ -n "$INPUT_IMAGE" ]; then
+            break
+        fi
+    done
+
+    if [ -z "$INPUT_IMAGE" ]; then
+        echo -e "${YELLOW}No test images found in input/ directory${NC}"
+        echo "Please add a test image to input/ or specify one as an argument:"
+        echo "  ./script/test.sh path/to/image.jpg"
+        exit 1
+    fi
+fi
+
+# Check if input file exists
+if [ ! -f "$INPUT_IMAGE" ]; then
+    echo -e "${YELLOW}Error: Input file not found: $INPUT_IMAGE${NC}"
+    exit 1
+fi
+
+# Create output directory if it doesn't exist
+mkdir -p output
+rm -rf output/*_debug/*
+
+# Build command
+#CMD="$PYTHON measure_finger.py --input $INPUT_IMAGE --output $OUTPUT_JSON --edge-method sobel --edge-detection-method canny_contour"
+CMD="$PYTHON measure_finger.py --input $INPUT_IMAGE --output $OUTPUT_JSON --finger-index $FINGER_INDEX"
+
+if [ "$ENABLE_DEBUG" = true ]; then
+    CMD="$CMD --debug"
+fi
+
+if [ "$SKIP_CARD" = true ]; then
+    CMD="$CMD --skip-card-detection"
+fi
+
+# Print test info
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}Ring Sizer Quick Test${NC}"
+echo -e "${GREEN}========================================${NC}"
+echo -e "${BLUE}Input:${NC}  $INPUT_IMAGE"
+echo -e "${BLUE}Output:${NC} $OUTPUT_JSON"
+echo -e "${BLUE}Finger:${NC} $FINGER_INDEX"
+RESULT_PNG="${OUTPUT_JSON%.json}.png"
+if [ "$ENABLE_DEBUG" = true ]; then
+    echo -e "${BLUE}Debug:${NC}  enabled"
+fi
+if [ "$SKIP_CARD" = true ]; then
+    echo -e "${YELLOW}Mode:${NC}   TESTING (card detection skipped)"
+fi
+echo -e "${GREEN}========================================${NC}"
+echo ""
+
+# Run the measurement
+$CMD
+
+# Print results
+echo ""
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}Test Complete!${NC}"
+echo -e "${GREEN}========================================${NC}"
+
+if [ -f "$OUTPUT_JSON" ]; then
+    echo -e "${BLUE}Results:${NC}"
+    cat "$OUTPUT_JSON" | python3 -m json.tool
+    echo ""
+fi
+
+if [ -f "$RESULT_PNG" ]; then
+    echo -e "${BLUE}Result image saved to:${NC} $RESULT_PNG"
+    echo ""
+fi
+
+echo -e "${GREEN}========================================${NC}"

src/__init__.py

@@ -0,0 +1,35 @@
+"""
+Utility modules for finger measurement.
+"""
+
+from .card_detection import detect_credit_card, compute_scale_factor
+from .finger_segmentation import segment_hand, isolate_finger, clean_mask, get_finger_contour
+from .geometry import estimate_finger_axis, localize_ring_zone, compute_cross_section_width
+from .image_quality import assess_image_quality, detect_blur, check_exposure
+from .confidence import (
+    compute_card_confidence,
+    compute_finger_confidence,
+    compute_measurement_confidence,
+    compute_overall_confidence,
+)
+from .visualization import create_debug_visualization
+
+__all__ = [
+    "detect_credit_card",
+    "compute_scale_factor",
+    "segment_hand",
+    "isolate_finger",
+    "clean_mask",
+    "get_finger_contour",
+    "estimate_finger_axis",
+    "localize_ring_zone",
+    "compute_cross_section_width",
+    "assess_image_quality",
+    "detect_blur",
+    "check_exposure",
+    "compute_card_confidence",
+    "compute_finger_confidence",
+    "compute_measurement_confidence",
+    "compute_overall_confidence",
+    "create_debug_visualization",
+]

src/card_detection.py

@@ -0,0 +1,612 @@
+"""
+Credit card detection and scale calibration utilities.
+
+This module handles:
+- Detecting credit card contour in an image
+- Verifying aspect ratio matches standard credit card
+- Perspective rectification
+- Computing pixels-per-cm scale factor
+"""
+
+import cv2
+import numpy as np
+from typing import Optional, Tuple, Dict, Any, List
+from pathlib import Path
+
+# Import debug observer and drawing functions
+from .debug_observer import DebugObserver, draw_contours_overlay, draw_candidates_with_scores
+
+# Import shared visualization constants
+from .viz_constants import (
+    FONT_FACE,
+    Color,
+    StrategyColor,
+    FontScale,
+    FontThickness,
+    Size,
+    Layout,
+)
+
+# Standard credit card dimensions (ISO/IEC 7810 ID-1)
+CARD_WIDTH_MM = 85.60
+CARD_HEIGHT_MM = 53.98
+CARD_WIDTH_CM = CARD_WIDTH_MM / 10
+CARD_HEIGHT_CM = CARD_HEIGHT_MM / 10
+CARD_ASPECT_RATIO = CARD_WIDTH_MM / CARD_HEIGHT_MM  # ~1.586
+
+# Detection parameters
+MIN_CARD_AREA_RATIO = 0.01  # Card must be at least 1% of image area
+MAX_CARD_AREA_RATIO = 0.5   # Card must be at most 50% of image area
+
+
+def order_corners(corners: np.ndarray) -> np.ndarray:
+    """
+    Order corners as: top-left, top-right, bottom-right, bottom-left.
+
+    Args:
+        corners: 4x2 array of corner points
+
+    Returns:
+        Ordered 4x2 array of corners
+    """
+    corners = corners.reshape(4, 2).astype(np.float32)
+
+    # Sort by sum (x+y): smallest = top-left, largest = bottom-right
+    s = corners.sum(axis=1)
+    tl_idx = np.argmin(s)
+    br_idx = np.argmax(s)
+
+    # Sort by diff (y-x): smallest = top-right, largest = bottom-left
+    d = np.diff(corners, axis=1).flatten()
+    tr_idx = np.argmin(d)
+    bl_idx = np.argmax(d)
+
+    return np.array([
+        corners[tl_idx],
+        corners[tr_idx],
+        corners[br_idx],
+        corners[bl_idx],
+    ], dtype=np.float32)
+
+
+def get_quad_dimensions(corners: np.ndarray) -> Tuple[float, float]:
+    """
+    Get width and height of a quadrilateral from ordered corners.
+
+    Args:
+        corners: Ordered 4x2 array (TL, TR, BR, BL)
+
+    Returns:
+        Tuple of (width, height) in pixels
+    """
+    # Width: average of top and bottom edges
+    top_width = np.linalg.norm(corners[1] - corners[0])
+    bottom_width = np.linalg.norm(corners[2] - corners[3])
+    width = (top_width + bottom_width) / 2
+
+    # Height: average of left and right edges
+    left_height = np.linalg.norm(corners[3] - corners[0])
+    right_height = np.linalg.norm(corners[2] - corners[1])
+    height = (left_height + right_height) / 2
+
+    return width, height
+
+
+def score_card_candidate(
+    contour: np.ndarray,
+    corners: np.ndarray,
+    image_area: float,
+    aspect_ratio_tolerance: float = 0.15,
+) -> Tuple[float, Dict[str, Any]]:
+    """
+    Score a quadrilateral candidate for being a credit card.
+
+    Since candidates come from minAreaRect, corners are always a perfect
+    rectangle. Scoring focuses on aspect ratio match and area coverage.
+
+    Args:
+        contour: Original contour (minAreaRect box points)
+        corners: 4 corner points
+        image_area: Total image area for relative sizing
+        aspect_ratio_tolerance: Allowed deviation from standard ratio
+
+    Returns:
+        Tuple of (score, details_dict)
+    """
+    ordered = order_corners(corners)
+    width, height = get_quad_dimensions(ordered)
+    area = cv2.contourArea(corners)
+
+    details = {
+        "corners": ordered,
+        "width": width,
+        "height": height,
+        "area": area,
+    }
+
+    # Check area ratio
+    area_ratio = area / image_area
+    if area_ratio < MIN_CARD_AREA_RATIO or area_ratio > MAX_CARD_AREA_RATIO:
+        details["reject_reason"] = f"area_ratio={area_ratio:.3f}"
+        return 0.0, details
+
+    # Safeguard against zero dimensions
+    if width <= 0 or height <= 0:
+        details["reject_reason"] = "invalid_dimensions"
+        return 0.0, details
+
+    # Calculate aspect ratio (always use larger/smaller for consistency)
+    if width > height:
+        aspect_ratio = width / height
+    else:
+        aspect_ratio = height / width
+    details["aspect_ratio"] = aspect_ratio
+
+    # Check aspect ratio against credit card standard
+    ratio_diff = abs(aspect_ratio - CARD_ASPECT_RATIO) / CARD_ASPECT_RATIO
+    if ratio_diff > aspect_ratio_tolerance:
+        details["reject_reason"] = f"aspect_ratio={aspect_ratio:.3f}, expected~{CARD_ASPECT_RATIO:.3f}"
+        return 0.0, details
+
+    # Compute score (higher is better)
+    # minAreaRect always produces perfect rectangles, so no angle check needed.
+    # Score based on area size and aspect ratio match.
+    area_score = min(area_ratio / 0.1, 1.0)  # Normalize to max at 10% of image
+    ratio_score = 1.0 - ratio_diff / aspect_ratio_tolerance
+
+    score = 0.5 * area_score + 0.5 * ratio_score
+    details["score_components"] = {
+        "area": area_score,
+        "ratio": ratio_score,
+    }
+
+    return score, details
+
+
+def find_card_contours(
+    image: np.ndarray,
+    image_area: float,
+    aspect_ratio_tolerance: float = 0.15,
+    min_score: float = 0.3,
+    debug_dir: Optional[str] = None,
+) -> List[np.ndarray]:
+    """
+    Find potential card contours using a waterfall of detection strategies.
+
+    Strategies are tried in order: Canny → Adaptive → Otsu → Color.
+    If a strategy produces a candidate scoring above min_score, subsequent
+    strategies are skipped.
+
+    Args:
+        image: Input BGR image
+        image_area: Total image area in pixels
+        aspect_ratio_tolerance: Allowed deviation from standard aspect ratio
+        min_score: Minimum score to accept a strategy's candidates
+        debug_dir: Optional directory to save debug images
+
+    Returns:
+        List of 4-point contour approximations from the first successful strategy
+    """
+    # Create debug observer if debug mode enabled
+    observer = DebugObserver(debug_dir) if debug_dir else None
+
+    h, w = image.shape[:2]
+    min_area = h * w * 0.01  # At least 1% of image
+    max_area = h * w * 0.5   # At most 50% of image
+
+    # Save original image
+    if observer:
+        observer.save_stage("01_original", image)
+
+    # Convert to grayscale
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    if observer:
+        observer.save_stage("02_grayscale", gray)
+
+    # Apply bilateral filter to reduce noise while keeping edges
+    filtered = cv2.bilateralFilter(gray, 11, 75, 75)
+    if observer:
+        observer.save_stage("03_bilateral_filtered", filtered)
+
+    def extract_quads(contours, epsilon_factor=0.02, min_rectangularity=0.7,
+                       aspect_tolerance=0.15):
+        """Extract quadrilaterals from contours using minAreaRect.
+
+        Shape constraints:
+        - Rectangularity (contour_area / rect_area): rejects irregular shapes
+        - Aspect ratio: rejects rectangles that don't match card proportions
+        """
+        quads = []
+        for contour in contours:
+            contour_area = cv2.contourArea(contour)
+            if contour_area < min_area or contour_area > max_area:
+                continue
+
+            peri = cv2.arcLength(contour, True)
+            approx = cv2.approxPolyDP(contour, epsilon_factor * peri, True)
+
+            if len(approx) < 4:
+                continue
+
+            rect = cv2.minAreaRect(contour)
+            box = cv2.boxPoints(rect).astype(np.float32)
+
+            rect_area = cv2.contourArea(box)
+            if rect_area <= 0:
+                continue
+            rectangularity = contour_area / rect_area
+            if rectangularity < min_rectangularity:
+                continue
+
+            (_, _), (bw, bh), _ = rect
+            if bw <= 0 or bh <= 0:
+                continue
+            aspect = max(bw, bh) / min(bw, bh)
+            if abs(aspect - CARD_ASPECT_RATIO) / CARD_ASPECT_RATIO > aspect_tolerance:
+                continue
+
+            quads.append(box.reshape(4, 1, 2))
+
+        return quads
+
+    def dedup_quads(quads, center_threshold=50):
+        """Remove near-duplicate boxes, keeping the largest when centers overlap.
+
+        Two boxes are considered duplicates if their centers are within
+        center_threshold pixels of each other.
+        """
+        if len(quads) <= 1:
+            return quads
+
+        # Sort by area descending so largest comes first
+        quads_with_area = [(q, cv2.contourArea(q)) for q in quads]
+        quads_with_area.sort(key=lambda x: x[1], reverse=True)
+
+        kept = []
+        for quad, area in quads_with_area:
+            center = quad.reshape(4, 2).mean(axis=0)
+            is_dup = False
+            for kept_quad in kept:
+                kept_center = kept_quad.reshape(4, 2).mean(axis=0)
+                dist = np.linalg.norm(center - kept_center)
+                if dist < center_threshold:
+                    is_dup = True
+                    break
+            if not is_dup:
+                kept.append(quad)
+
+        return kept
+
+    def score_best(quads):
+        """Return the best score among quads."""
+        best = 0.0
+        for q in quads:
+            corners = q.reshape(4, 2)
+            score, _ = score_card_candidate(
+                q, corners, image_area, aspect_ratio_tolerance
+            )
+            best = max(best, score)
+        return best
+
+    # --- Waterfall: try strategies in order, stop on first success ---
+
+    # Strategy 1: Canny edge detection with various thresholds
+    canny_candidates = []
+    canny_configs = [(20, 60), (30, 100), (50, 150), (75, 200), (100, 250)]
+    saved_canny_indices = [0, 2, 4]
+
+    for idx, (canny_low, canny_high) in enumerate(canny_configs):
+        edges = cv2.Canny(filtered, canny_low, canny_high)
+
+        if idx in saved_canny_indices and observer:
+            observer.save_stage(f"04_canny_{canny_low}_{canny_high}", edges)
+
+        kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (5, 5))
+        edges_morphed = cv2.morphologyEx(edges, cv2.MORPH_CLOSE, kernel)
+
+        if idx == 2 and observer:
+            observer.save_stage("07_canny_morphology", edges_morphed)
+
+        contours, _ = cv2.findContours(edges_morphed, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+        canny_candidates.extend(extract_quads(contours))
+
+    canny_candidates = dedup_quads(canny_candidates)
+
+    if observer and canny_candidates:
+        observer.draw_and_save("08_canny_contours", image,
+                             draw_contours_overlay, canny_candidates, "Canny Edge Detection", StrategyColor.CANNY)
+
+    if canny_candidates and score_best(canny_candidates) >= min_score:
+        return canny_candidates
+
+    # Strategy 2: Adaptive thresholding (for varying lighting)
+    adaptive_candidates = []
+    adaptive_configs = [(11, 2), (21, 5), (31, 10), (51, 10)]
+    saved_adaptive = [0, 2]
+
+    for idx, (block_size, C) in enumerate(adaptive_configs):
+        thresh = cv2.adaptiveThreshold(
+            filtered, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+            cv2.THRESH_BINARY, block_size, C
+        )
+
+        if idx in saved_adaptive and observer:
+            if idx == 0:
+                observer.save_stage("09_adaptive_11_2", thresh)
+            elif idx == 2:
+                observer.save_stage("10_adaptive_31_10", thresh)
+
+        for img in [thresh, 255 - thresh]:
+            contours, _ = cv2.findContours(img, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+            adaptive_candidates.extend(extract_quads(contours))
+
+    adaptive_candidates = dedup_quads(adaptive_candidates)
+
+    if observer and adaptive_candidates:
+        observer.draw_and_save("11_adaptive_contours", image,
+                             draw_contours_overlay, adaptive_candidates, "Adaptive Thresholding", StrategyColor.ADAPTIVE)
+
+    if adaptive_candidates and score_best(adaptive_candidates) >= min_score:
+        return adaptive_candidates
+
+    # Strategy 3: Otsu's thresholding
+    otsu_candidates = []
+    _, otsu = cv2.threshold(filtered, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+    if observer:
+        observer.save_stage("12_otsu_binary", otsu)
+
+    otsu_inverted = 255 - otsu
+    if observer:
+        observer.save_stage("13_otsu_inverted", otsu_inverted)
+
+    for img in [otsu, otsu_inverted]:
+        kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3))
+        img_morphed = cv2.morphologyEx(img, cv2.MORPH_CLOSE, kernel)
+        contours, _ = cv2.findContours(img_morphed, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+        otsu_candidates.extend(extract_quads(contours))
+
+    otsu_candidates = dedup_quads(otsu_candidates)
+
+    if observer and otsu_candidates:
+        observer.draw_and_save("14_otsu_contours", image,
+                             draw_contours_overlay, otsu_candidates, "Otsu Thresholding", StrategyColor.OTSU)
+
+    if otsu_candidates and score_best(otsu_candidates) >= min_score:
+        return otsu_candidates
+
+    # Strategy 4: Color-based segmentation (gray card on light background)
+    color_candidates = []
+    hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)
+    sat = hsv[:, :, 1]
+    if observer:
+        observer.save_stage("15_hsv_saturation", sat)
+
+    _, low_sat_mask = cv2.threshold(sat, 30, 255, cv2.THRESH_BINARY_INV)
+    if observer:
+        observer.save_stage("16_low_sat_mask", low_sat_mask)
+
+    val = hsv[:, :, 2]
+    gray_mask = cv2.bitwise_and(low_sat_mask, cv2.inRange(val, 80, 200))
+
+    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (7, 7))
+    gray_mask = cv2.morphologyEx(gray_mask, cv2.MORPH_CLOSE, kernel)
+    gray_mask = cv2.morphologyEx(gray_mask, cv2.MORPH_OPEN, kernel)
+    if observer:
+        observer.save_stage("17_gray_mask", gray_mask)
+
+    contours, _ = cv2.findContours(gray_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    color_candidates = dedup_quads(extract_quads(contours, epsilon_factor=0.03))
+
+    if observer and color_candidates:
+        observer.draw_and_save("18_color_contours", image,
+                             draw_contours_overlay, color_candidates, "Color-Based Detection", StrategyColor.COLOR_BASED)
+
+    if color_candidates and score_best(color_candidates) >= min_score:
+        return color_candidates
+
+    # No strategy succeeded — return all collected candidates as last resort
+    all_candidates = canny_candidates + adaptive_candidates + otsu_candidates + color_candidates
+    if observer and all_candidates:
+        observer.draw_and_save("19_all_candidates", image,
+                             draw_contours_overlay, all_candidates, "All Candidates (fallback)", StrategyColor.ALL_CANDIDATES)
+    return all_candidates
+
+
+def detect_credit_card(
+    image: np.ndarray,
+    aspect_ratio_tolerance: float = 0.15,
+    debug_dir: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """
+    Detect a credit card in the image.
+
+    Args:
+        image: Input BGR image
+        aspect_ratio_tolerance: Allowed deviation from standard aspect ratio
+        debug_dir: Optional directory to save debug images
+
+    Returns:
+        Dictionary containing:
+        - corners: 4x2 array of corner points (ordered)
+        - contour: Full contour points
+        - confidence: Detection confidence score
+        - width_px, height_px: Detected dimensions
+        - aspect_ratio: Detected aspect ratio
+        Or None if no card detected
+    """
+    # Create debug observer if debug mode enabled
+    observer = DebugObserver(debug_dir) if debug_dir else None
+    
+    if observer:
+        print(f"Saving card detection debug images to: {debug_dir}")
+
+    h, w = image.shape[:2]
+    image_area = h * w
+
+    # Find candidate contours (waterfall: stops after first successful strategy)
+    candidates = find_card_contours(
+        image, image_area=image_area,
+        aspect_ratio_tolerance=aspect_ratio_tolerance,
+        debug_dir=debug_dir,
+    )
+
+    if not candidates:
+        if observer:
+            print("  No candidates found")
+        return None
+
+    # Score each candidate
+    best_score = 0.0
+    best_result = None
+    all_scored = []
+
+    for contour in candidates:
+        corners = contour.reshape(4, 2)
+        score, details = score_card_candidate(
+            contour, corners, image_area, aspect_ratio_tolerance
+        )
+
+        all_scored.append((corners, score, details))
+
+        if score > best_score:
+            best_score = score
+            best_result = details
+
+    # Sort by score (descending) and take top 5
+    all_scored.sort(key=lambda x: x[1], reverse=True)
+    top_candidates = all_scored[:5]
+
+    # Save scored candidates visualization
+    if observer and top_candidates:
+        observer.draw_and_save("20_scored_candidates", image,
+                             draw_candidates_with_scores, top_candidates, "Top 5 Candidates")
+
+    if best_result is None or best_score < 0.3:
+        if observer:
+            print(f"  Best score {best_score:.2f} below threshold 0.3")
+        return None
+
+    # Save final detection
+    if observer:
+        final_overlay = image.copy()
+        corners = best_result["corners"].astype(np.int32)
+        cv2.polylines(final_overlay, [corners], True, Color.GREEN, Size.CONTOUR_THICK)
+
+        # Draw corners
+        for pt in corners:
+            cv2.circle(final_overlay, tuple(pt), Size.CORNER_RADIUS + 2, Color.RED, -1)
+
+        # Add details text
+        text_y = Layout.TITLE_Y
+        details_text = [
+            "Final Detection",
+            f"Score: {best_score:.3f}",
+            f"Aspect Ratio: {best_result['aspect_ratio']:.3f}",
+            f"Dimensions: {best_result['width']:.0f}x{best_result['height']:.0f}px",
+        ]
+
+        for text in details_text:
+            cv2.putText(
+                final_overlay, text, (Layout.TEXT_OFFSET_X, text_y),
+                FONT_FACE, FontScale.SUBTITLE, Color.WHITE,
+                FontThickness.SUBTITLE_OUTLINE, cv2.LINE_AA
+            )
+            cv2.putText(
+                final_overlay, text, (Layout.TEXT_OFFSET_X, text_y),
+                FONT_FACE, FontScale.SUBTITLE, Color.GREEN,
+                FontThickness.SUBTITLE, cv2.LINE_AA
+            )
+            text_y += Layout.LINE_SPACING
+
+        observer.save_stage("21_final_detection", final_overlay)
+        print(f"  Saved 21 debug images")
+
+    return {
+        "corners": best_result["corners"],
+        "contour": best_result["corners"],
+        "confidence": best_score,
+        "width_px": best_result["width"],
+        "height_px": best_result["height"],
+        "aspect_ratio": best_result["aspect_ratio"],
+    }
+
+
+def rectify_card(
+    image: np.ndarray,
+    corners: np.ndarray,
+    output_width: int = 856,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Apply perspective transform to rectify the card region.
+
+    Args:
+        image: Input BGR image
+        corners: Ordered 4x2 array of corner points (TL, TR, BR, BL)
+        output_width: Width of output image (height computed from aspect ratio)
+
+    Returns:
+        Tuple of (rectified_image, transform_matrix)
+    """
+    corners = corners.astype(np.float32)
+
+    # Determine if card is in portrait or landscape orientation
+    width, height = get_quad_dimensions(corners)
+
+    if width > height:
+        # Landscape orientation
+        out_w = output_width
+        out_h = int(output_width / CARD_ASPECT_RATIO)
+    else:
+        # Portrait orientation (rotated 90°)
+        out_h = output_width
+        out_w = int(output_width / CARD_ASPECT_RATIO)
+
+    # Destination points
+    dst = np.array([
+        [0, 0],
+        [out_w - 1, 0],
+        [out_w - 1, out_h - 1],
+        [0, out_h - 1],
+    ], dtype=np.float32)
+
+    # Compute perspective transform
+    M = cv2.getPerspectiveTransform(corners, dst)
+
+    # Apply transform
+    rectified = cv2.warpPerspective(image, M, (out_w, out_h))
+
+    return rectified, M
+
+
+def compute_scale_factor(
+    corners: np.ndarray,
+) -> Tuple[float, float]:
+    """
+    Compute pixels-per-cm scale factor from detected card corners.
+
+    Args:
+        corners: Ordered 4x2 array of corner points
+
+    Returns:
+        Tuple of (px_per_cm, confidence)
+    """
+    width_px, height_px = get_quad_dimensions(corners)
+
+    # Determine orientation and compute scale
+    if width_px > height_px:
+        # Landscape: width corresponds to card width (8.56 cm)
+        px_per_cm_w = width_px / CARD_WIDTH_CM
+        px_per_cm_h = height_px / CARD_HEIGHT_CM
+    else:
+        # Portrait: width corresponds to card height (5.398 cm)
+        px_per_cm_w = width_px / CARD_HEIGHT_CM
+        px_per_cm_h = height_px / CARD_WIDTH_CM
+
+    # Average the two estimates
+    px_per_cm = (px_per_cm_w + px_per_cm_h) / 2
+
+    # Confidence based on consistency between width and height estimates
+    consistency = 1.0 - abs(px_per_cm_w - px_per_cm_h) / max(px_per_cm_w, px_per_cm_h)
+    confidence = max(0.0, min(1.0, consistency))
+
+    return px_per_cm, confidence

src/confidence.py

@@ -0,0 +1,311 @@
+"""
+Confidence scoring utilities.
+
+This module handles:
+- Card detection confidence
+- Finger detection confidence
+- Measurement stability confidence
+- Edge quality confidence (v1)
+- Aggregate confidence calculation
+
+All thresholds and weights are imported from confidence_constants.py.
+"""
+
+import logging
+import numpy as np
+from typing import Dict, Any, Optional, Literal
+
+from .confidence_constants import (
+    # Card confidence constants
+    CARD_IDEAL_ASPECT_RATIO,
+    CARD_MAX_ASPECT_DEVIATION,
+    CARD_WEIGHT_DETECTION,
+    CARD_WEIGHT_ASPECT,
+    CARD_WEIGHT_SCALE,
+    # Finger confidence constants
+    FINGER_IDEAL_MIN_AREA_FRACTION,
+    FINGER_IDEAL_MAX_AREA_FRACTION,
+    FINGER_WEIGHT_HAND_DETECTION,
+    FINGER_WEIGHT_MASK_VALIDITY,
+    # Measurement confidence constants
+    MEASUREMENT_CV_POOR,
+    MEASUREMENT_CONSISTENCY_THRESHOLD,
+    MEASUREMENT_OUTLIER_STD_MULTIPLIER,
+    MEASUREMENT_WIDTH_TYPICAL_MIN,
+    MEASUREMENT_WIDTH_TYPICAL_MAX,
+    MEASUREMENT_WIDTH_ABSOLUTE_MIN,
+    MEASUREMENT_WIDTH_ABSOLUTE_MAX,
+    MEASUREMENT_WEIGHT_VARIANCE,
+    MEASUREMENT_WEIGHT_CONSISTENCY,
+    MEASUREMENT_WEIGHT_OUTLIERS,
+    MEASUREMENT_WEIGHT_RANGE,
+    MEASUREMENT_RANGE_SCORE_IDEAL,
+    MEASUREMENT_RANGE_SCORE_BORDERLINE,
+    MEASUREMENT_RANGE_SCORE_OUTSIDE,
+    # Overall confidence constants
+    V0_WEIGHT_CARD,
+    V0_WEIGHT_FINGER,
+    V0_WEIGHT_MEASUREMENT,
+    V1_WEIGHT_CARD,
+    V1_WEIGHT_FINGER,
+    V1_WEIGHT_EDGE_QUALITY,
+    V1_WEIGHT_MEASUREMENT,
+    CONFIDENCE_LEVEL_HIGH_THRESHOLD,
+    CONFIDENCE_LEVEL_MEDIUM_THRESHOLD,
+)
+
+logger = logging.getLogger(__name__)
+
+EdgeMethod = Literal["contour", "sobel", "sobel_fallback"]
+
+
+def compute_card_confidence(
+    card_result: Dict[str, Any],
+    scale_confidence: float,
+) -> float:
+    """
+    Compute confidence score from card detection.
+
+    Uses constants:
+    - CARD_IDEAL_ASPECT_RATIO: ISO/IEC 7810 ID-1 aspect ratio
+    - CARD_MAX_ASPECT_DEVIATION: Maximum acceptable deviation (0.15)
+    - CARD_WEIGHT_*: Component weights (detection: 50%, aspect: 25%, scale: 25%)
+
+    Args:
+        card_result: Output from detect_credit_card()
+        scale_confidence: Scale calibration confidence
+
+    Returns:
+        Card confidence score [0, 1]
+    """
+    # Base confidence from card detection
+    detection_conf = card_result.get("confidence", 0.0)
+
+    # Aspect ratio deviation penalty
+    aspect_ratio = card_result.get("aspect_ratio", 0.0)
+    aspect_deviation = abs(aspect_ratio - CARD_IDEAL_ASPECT_RATIO) / CARD_IDEAL_ASPECT_RATIO
+
+    # Penalize deviation beyond threshold
+    aspect_score = max(0, 1.0 - (aspect_deviation / CARD_MAX_ASPECT_DEVIATION))
+
+    # Combine components with weights
+    card_conf = (
+        CARD_WEIGHT_DETECTION * detection_conf +
+        CARD_WEIGHT_ASPECT * aspect_score +
+        CARD_WEIGHT_SCALE * scale_confidence
+    )
+
+    return float(np.clip(card_conf, 0, 1))
+
+
+def compute_finger_confidence(
+    hand_data: Dict[str, Any],
+    finger_data: Dict[str, Any],
+    mask_area: int,
+    image_area: int,
+) -> float:
+    """
+    Compute confidence score from finger detection.
+
+    Uses constants:
+    - FINGER_IDEAL_MIN_AREA_FRACTION: Minimum ideal mask area (0.5% of image)
+    - FINGER_IDEAL_MAX_AREA_FRACTION: Maximum ideal mask area (5% of image)
+    - FINGER_WEIGHT_*: Component weights (hand: 70%, mask: 30%)
+
+    Args:
+        hand_data: Output from segment_hand()
+        finger_data: Output from isolate_finger()
+        mask_area: Area of cleaned finger mask in pixels
+        image_area: Total image area in pixels
+
+    Returns:
+        Finger confidence score [0, 1]
+    """
+    # Hand landmark detection confidence from MediaPipe
+    hand_conf = hand_data.get("confidence", 0.0)
+
+    # Mask area validity (should be reasonable fraction of image)
+    mask_fraction = mask_area / image_area
+    # Ideal range: FINGER_IDEAL_MIN_AREA_FRACTION to FINGER_IDEAL_MAX_AREA_FRACTION
+    if mask_fraction < FINGER_IDEAL_MIN_AREA_FRACTION:
+        area_score = mask_fraction / FINGER_IDEAL_MIN_AREA_FRACTION
+    elif mask_fraction > FINGER_IDEAL_MAX_AREA_FRACTION:
+        area_score = max(0, 1.0 - (mask_fraction - FINGER_IDEAL_MAX_AREA_FRACTION) / FINGER_IDEAL_MAX_AREA_FRACTION)
+    else:
+        area_score = 1.0
+
+    # Combine components with weights
+    finger_conf = FINGER_WEIGHT_HAND_DETECTION * hand_conf + FINGER_WEIGHT_MASK_VALIDITY * area_score
+
+    return float(np.clip(finger_conf, 0, 1))
+
+
+def compute_measurement_confidence(
+    width_data: Dict[str, Any],
+    median_width_cm: float,
+) -> float:
+    """
+    Compute confidence score from measurement stability.
+
+    Uses constants:
+    - MEASUREMENT_CV_POOR: Coefficient of variation threshold (0.15)
+    - MEASUREMENT_CONSISTENCY_THRESHOLD: Median-mean difference threshold (0.1)
+    - MEASUREMENT_OUTLIER_STD_MULTIPLIER: Outlier detection threshold (2.0)
+    - MEASUREMENT_WIDTH_*: Realistic width ranges (1.0-3.0 cm)
+    - MEASUREMENT_WEIGHT_*: Component weights (variance: 40%, consistency: 20%, outliers: 20%, range: 20%)
+    - MEASUREMENT_RANGE_SCORE_*: Range score values
+
+    Args:
+        width_data: Output from compute_cross_section_width()
+        median_width_cm: Median width in centimeters
+
+    Returns:
+        Measurement confidence score [0, 1]
+    """
+    widths_px = np.array(width_data.get("widths_px", []))
+
+    if len(widths_px) == 0:
+        return 0.0
+
+    median_px = width_data.get("median_width_px", 0.0)
+    mean_px = width_data.get("mean_width_px", 0.0)
+    std_px = width_data.get("std_width_px", 0.0)
+
+    # 1. Variance score (lower variance = higher confidence)
+    coefficient_of_variation = std_px / (median_px + 1e-8)
+    # CV < MEASUREMENT_CV_POOR is acceptable
+    variance_score = max(0, 1.0 - coefficient_of_variation / MEASUREMENT_CV_POOR)
+
+    # 2. Median-Mean consistency
+    median_mean_diff = abs(median_px - mean_px) / (median_px + 1e-8)
+    consistency_score = max(0, 1.0 - median_mean_diff / MEASUREMENT_CONSISTENCY_THRESHOLD)
+
+    # 3. Outlier ratio (measurements far from median)
+    outlier_threshold = MEASUREMENT_OUTLIER_STD_MULTIPLIER * std_px
+    outliers = np.sum(np.abs(widths_px - median_px) > outlier_threshold)
+    outlier_ratio = outliers / len(widths_px)
+    outlier_score = max(0, 1.0 - outlier_ratio)
+
+    # 4. Realistic range check
+    if MEASUREMENT_WIDTH_TYPICAL_MIN <= median_width_cm <= MEASUREMENT_WIDTH_TYPICAL_MAX:
+        range_score = MEASUREMENT_RANGE_SCORE_IDEAL
+    elif MEASUREMENT_WIDTH_ABSOLUTE_MIN <= median_width_cm <= MEASUREMENT_WIDTH_ABSOLUTE_MAX:
+        # Borderline acceptable
+        range_score = MEASUREMENT_RANGE_SCORE_BORDERLINE
+    else:
+        # Outside realistic range
+        range_score = MEASUREMENT_RANGE_SCORE_OUTSIDE
+
+    # Combine components with weights
+    measurement_conf = (
+        MEASUREMENT_WEIGHT_VARIANCE * variance_score +
+        MEASUREMENT_WEIGHT_CONSISTENCY * consistency_score +
+        MEASUREMENT_WEIGHT_OUTLIERS * outlier_score +
+        MEASUREMENT_WEIGHT_RANGE * range_score
+    )
+
+    return float(np.clip(measurement_conf, 0, 1))
+
+
+def compute_edge_quality_confidence(
+    edge_quality_data: Optional[Dict[str, Any]] = None
+) -> float:
+    """
+    Compute confidence score from edge quality (v1 Sobel method).
+
+    Args:
+        edge_quality_data: Output from compute_edge_quality_score()
+                          None if using contour method (v0)
+
+    Returns:
+        Edge quality confidence score [0, 1]
+        Returns 1.0 for contour method (not applicable)
+    """
+    if edge_quality_data is None:
+        # Contour method - edge quality not applicable
+        return 1.0
+
+    # Use overall edge quality score directly
+    # It's already a weighted combination of 4 metrics
+    edge_conf = edge_quality_data.get("overall_score", 0.0)
+
+    return float(np.clip(edge_conf, 0, 1))
+
+
+def compute_overall_confidence(
+    card_confidence: float,
+    finger_confidence: float,
+    measurement_confidence: float,
+    edge_method: EdgeMethod = "contour",
+    edge_quality_confidence: Optional[float] = None,
+) -> Dict[str, Any]:
+    """
+    Compute overall confidence by combining component scores.
+
+    Supports both v0 (contour) and v1 (Sobel) confidence calculation:
+    - v0 (contour): 3 components with V0_WEIGHT_* constants
+    - v1 (sobel): 4 components with V1_WEIGHT_* constants
+
+    Uses constants:
+    - V0_WEIGHT_*: v0 component weights (card: 30%, finger: 30%, measurement: 40%)
+    - V1_WEIGHT_*: v1 component weights (card: 25%, finger: 25%, edge: 20%, measurement: 30%)
+    - CONFIDENCE_LEVEL_*_THRESHOLD: Level thresholds (high: >0.85, medium: >=0.6)
+
+    Args:
+        card_confidence: Card detection confidence
+        finger_confidence: Finger detection confidence
+        measurement_confidence: Measurement stability confidence
+        edge_method: Edge detection method used
+        edge_quality_confidence: Edge quality confidence (v1 only)
+
+    Returns:
+        Dictionary containing:
+        - overall: Overall confidence [0, 1]
+        - card: Card component score
+        - finger: Finger component score
+        - measurement: Measurement component score
+        - edge_quality: Edge quality score (v1 only, None for v0)
+        - level: "high", "medium", or "low"
+        - method: Edge method used
+    """
+    result = {
+        "card": float(card_confidence),
+        "finger": float(finger_confidence),
+        "measurement": float(measurement_confidence),
+        "method": edge_method,
+    }
+
+    # Calculate overall confidence based on method
+    if edge_method == "sobel" and edge_quality_confidence is not None:
+        # v1 scoring: 4 components with V1_WEIGHT_* constants
+        overall = (
+            V1_WEIGHT_CARD * card_confidence +
+            V1_WEIGHT_FINGER * finger_confidence +
+            V1_WEIGHT_EDGE_QUALITY * edge_quality_confidence +
+            V1_WEIGHT_MEASUREMENT * measurement_confidence
+        )
+        result["edge_quality"] = float(edge_quality_confidence)
+
+    else:
+        # v0 scoring: 3 components with V0_WEIGHT_* constants (contour method or sobel fallback)
+        overall = (
+            V0_WEIGHT_CARD * card_confidence +
+            V0_WEIGHT_FINGER * finger_confidence +
+            V0_WEIGHT_MEASUREMENT * measurement_confidence
+        )
+        result["edge_quality"] = None
+
+    overall = float(np.clip(overall, 0, 1))
+
+    # Classify confidence level using threshold constants
+    if overall > CONFIDENCE_LEVEL_HIGH_THRESHOLD:
+        level = "high"
+    elif overall >= CONFIDENCE_LEVEL_MEDIUM_THRESHOLD:
+        level = "medium"
+    else:
+        level = "low"
+
+    result["overall"] = overall
+    result["level"] = level
+
+    return result

src/confidence_constants.py

@@ -0,0 +1,87 @@
+"""
+Constants for confidence scoring module.
+
+This module contains thresholds and weights used in confidence calculation
+for card detection, finger detection, and measurement stability.
+"""
+
+# =============================================================================
+# Card Confidence Constants
+# =============================================================================
+
+# Ideal credit card aspect ratio (ISO/IEC 7810 ID-1)
+CARD_IDEAL_ASPECT_RATIO = 85.60 / 53.98  # ≈ 1.586
+
+# Maximum acceptable aspect ratio deviation (fraction)
+CARD_MAX_ASPECT_DEVIATION = 0.15  # 15%
+
+# Card confidence component weights
+CARD_WEIGHT_DETECTION = 0.5    # Detection quality: 50%
+CARD_WEIGHT_ASPECT = 0.25      # Aspect ratio: 25%
+CARD_WEIGHT_SCALE = 0.25       # Scale calibration: 25%
+
+
+# =============================================================================
+# Finger Confidence Constants
+# =============================================================================
+
+# Ideal mask area fraction of total image area
+FINGER_IDEAL_MIN_AREA_FRACTION = 0.005  # 0.5% of image
+FINGER_IDEAL_MAX_AREA_FRACTION = 0.05   # 5% of image
+
+# Finger confidence component weights
+FINGER_WEIGHT_HAND_DETECTION = 0.7  # Hand detection: 70%
+FINGER_WEIGHT_MASK_VALIDITY = 0.3   # Mask validity: 30%
+
+
+# =============================================================================
+# Measurement Confidence Constants
+# =============================================================================
+
+# Coefficient of variation thresholds
+# CV = std_dev / mean
+MEASUREMENT_CV_EXCELLENT = 0.05  # CV < 0.05 is excellent
+MEASUREMENT_CV_POOR = 0.15       # CV < 0.15 is acceptable
+
+# Median-mean consistency threshold (fractional difference)
+MEASUREMENT_CONSISTENCY_THRESHOLD = 0.1  # 10% difference acceptable
+
+# Outlier detection threshold (multiples of std dev)
+MEASUREMENT_OUTLIER_STD_MULTIPLIER = 2.0
+
+# Realistic finger width range (cm)
+MEASUREMENT_WIDTH_TYPICAL_MIN = 1.4  # Typical minimum
+MEASUREMENT_WIDTH_TYPICAL_MAX = 2.4  # Typical maximum
+MEASUREMENT_WIDTH_ABSOLUTE_MIN = 1.0  # Absolute minimum (borderline)
+MEASUREMENT_WIDTH_ABSOLUTE_MAX = 3.0  # Absolute maximum (borderline)
+
+# Measurement confidence component weights
+MEASUREMENT_WEIGHT_VARIANCE = 0.4      # Variance: 40%
+MEASUREMENT_WEIGHT_CONSISTENCY = 0.2   # Consistency: 20%
+MEASUREMENT_WEIGHT_OUTLIERS = 0.2      # Outliers: 20%
+MEASUREMENT_WEIGHT_RANGE = 0.2         # Range: 20%
+
+# Range score values
+MEASUREMENT_RANGE_SCORE_IDEAL = 1.0        # Within typical range
+MEASUREMENT_RANGE_SCORE_BORDERLINE = 0.7   # Within absolute range
+MEASUREMENT_RANGE_SCORE_OUTSIDE = 0.3      # Outside realistic range
+
+
+# =============================================================================
+# Overall Confidence Constants
+# =============================================================================
+
+# v0 (Contour method) component weights
+V0_WEIGHT_CARD = 0.30          # Card: 30%
+V0_WEIGHT_FINGER = 0.30        # Finger: 30%
+V0_WEIGHT_MEASUREMENT = 0.40   # Measurement: 40%
+
+# v1 (Sobel method) component weights
+V1_WEIGHT_CARD = 0.25          # Card: 25%
+V1_WEIGHT_FINGER = 0.25        # Finger: 25%
+V1_WEIGHT_EDGE_QUALITY = 0.20  # Edge quality: 20%
+V1_WEIGHT_MEASUREMENT = 0.30   # Measurement: 30%
+
+# Confidence level thresholds
+CONFIDENCE_LEVEL_HIGH_THRESHOLD = 0.85   # > 0.85 = high
+CONFIDENCE_LEVEL_MEDIUM_THRESHOLD = 0.6  # >= 0.6 = medium, < 0.6 = low

src/debug_observer.py

@@ -0,0 +1,1283 @@
+"""
+Debug visualization observer for the ring measurement pipeline.
+
+This module provides a non-intrusive way to capture and visualize intermediate
+processing stages without polluting core algorithm implementations.
+
+It also contains all drawing utility functions used for debug visualizations.
+"""
+
+import cv2
+import numpy as np
+from typing import Optional, Dict, Any, Callable, List, Tuple
+from pathlib import Path
+
+# Import visualization constants
+from src.viz_constants import (
+    FONT_FACE, FontScale, FontThickness, Color, Size, Layout
+)
+
+
+class DebugObserver:
+    """
+    Observer for capturing and saving intermediate processing stages.
+    
+    This class provides methods to save images and visualizations during
+    algorithm execution without requiring core functions to handle I/O directly.
+    """
+    
+    def __init__(self, debug_dir: str):
+        """
+        Initialize debug observer.
+        
+        Args:
+            debug_dir: Directory where debug images will be saved
+        """
+        self.debug_dir = Path(debug_dir)
+        self.debug_dir.mkdir(parents=True, exist_ok=True)
+        self._stage_counter = {}
+    
+    def save_stage(self, name: str, image: np.ndarray) -> None:
+        """
+        Save an intermediate processing stage image.
+        
+        Args:
+            name: Stage name (used as filename prefix)
+            image: Image to save
+        """
+        if image is None or image.size == 0:
+            return
+        
+        # Add counter for stages with multiple saves
+        if name in self._stage_counter:
+            self._stage_counter[name] += 1
+            filename = f"{name}_{self._stage_counter[name]}.png"
+        else:
+            self._stage_counter[name] = 0
+            filename = f"{name}.png"
+        
+        self._save_with_compression(image, filename)
+    
+    def draw_and_save(self, name: str, image: np.ndarray,
+                      draw_func: Callable, *args, **kwargs) -> None:
+        """
+        Apply a drawing function to an image and save the result.
+        
+        Args:
+            name: Stage name for the output file
+            image: Base image to draw on
+            draw_func: Function that takes (image, *args, **kwargs) and returns annotated image
+            *args, **kwargs: Arguments to pass to draw_func
+        """
+        if image is None or image.size == 0:
+            return
+        
+        annotated = draw_func(image, *args, **kwargs)
+        self.save_stage(name, annotated)
+    
+    def _save_with_compression(self, image: np.ndarray, filename: str) -> None:
+        """
+        Save image with compression and optional downsampling.
+        
+        Args:
+            image: Image to save
+            filename: Output filename
+        """
+        output_path = self.debug_dir / filename
+        
+        # Downsample if too large (max 1920px dimension)
+        h, w = image.shape[:2]
+        max_dim = 1920
+        if max(h, w) > max_dim:
+            scale = max_dim / max(h, w)
+            new_w = int(w * scale)
+            new_h = int(h * scale)
+            image = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_AREA)
+        
+        # PNG compression
+        cv2.imwrite(str(output_path), image, [cv2.IMWRITE_PNG_COMPRESSION, 6])
+
+
+# Backward compatibility helper
+def save_debug_image(image: np.ndarray, filename: str, debug_dir: Optional[str]) -> None:
+    """
+    Legacy function for saving debug images.
+    
+    This function is kept for backward compatibility during migration.
+    New code should use DebugObserver directly.
+    
+    Args:
+        image: Image to save
+        filename: Output filename
+        debug_dir: Directory to save to (if None, skip saving)
+    """
+    if debug_dir is None:
+        return
+    
+    observer = DebugObserver(debug_dir)
+    observer._save_with_compression(image, filename)
+
+
+# =============================================================================
+# Drawing Functions for Debug Visualization
+# =============================================================================
+
+# Hand landmark and finger constants (from finger_segmentation.py)
+FINGER_LANDMARKS = {
+    "index": [5, 6, 7, 8],
+    "middle": [9, 10, 11, 12],
+    "ring": [13, 14, 15, 16],
+    "pinky": [17, 18, 19, 20],
+}
+
+THUMB_LANDMARKS = [1, 2, 3, 4]
+
+HAND_CONNECTIONS = [
+    # Palm
+    (0, 1), (0, 5), (0, 17), (5, 9), (9, 13), (13, 17),
+    # Thumb
+    (1, 2), (2, 3), (3, 4),
+    # Index
+    (5, 6), (6, 7), (7, 8),
+    # Middle
+    (9, 10), (10, 11), (11, 12),
+    # Ring
+    (13, 14), (14, 15), (15, 16),
+    # Pinky
+    (17, 18), (18, 19), (19, 20),
+]
+
+FINGER_COLORS = {
+    "thumb": Color.RED,
+    "index": Color.CYAN,
+    "middle": Color.YELLOW,
+    "ring": Color.MAGENTA,
+    "pinky": Color.ORANGE,
+}
+
+
+# --- Finger Segmentation Drawing Functions ---
+
+def draw_landmarks_overlay(image: np.ndarray, landmarks: np.ndarray, label: bool = True) -> np.ndarray:
+    """
+    Draw hand landmarks as numbered circles.
+
+    Args:
+        image: Input image
+        landmarks: 21x2 array of landmark positions
+        label: Whether to draw landmark numbers
+
+    Returns:
+        Image with landmarks drawn
+    """
+    overlay = image.copy()
+
+    for i, (x, y) in enumerate(landmarks):
+        # Draw circle
+        cv2.circle(overlay, (int(x), int(y)), Size.ENDPOINT_RADIUS, Color.GREEN, -1)
+        cv2.circle(overlay, (int(x), int(y)), Size.ENDPOINT_RADIUS, Color.BLACK, 2)
+
+        # Draw number
+        if label:
+            text = str(i)
+            text_size = cv2.getTextSize(text, FONT_FACE, FontScale.SMALL, FontThickness.BODY)[0]
+            text_x = int(x - text_size[0] / 2)
+            text_y = int(y + text_size[1] / 2)
+
+            # Black outline
+            cv2.putText(overlay, text, (text_x, text_y), FONT_FACE, FontScale.SMALL,
+                       Color.BLACK, FontThickness.BODY + 2, cv2.LINE_AA)
+            # White text
+            cv2.putText(overlay, text, (text_x, text_y), FONT_FACE, FontScale.SMALL,
+                       Color.WHITE, FontThickness.BODY, cv2.LINE_AA)
+
+    return overlay
+
+
+def draw_hand_skeleton(image: np.ndarray, landmarks: np.ndarray) -> np.ndarray:
+    """
+    Draw hand skeleton with connections between landmarks.
+
+    Args:
+        image: Input image
+        landmarks: 21x2 array of landmark positions
+
+    Returns:
+        Image with skeleton drawn
+    """
+    overlay = image.copy()
+
+    # Draw connections
+    for idx1, idx2 in HAND_CONNECTIONS:
+        pt1 = (int(landmarks[idx1, 0]), int(landmarks[idx1, 1]))
+        pt2 = (int(landmarks[idx2, 0]), int(landmarks[idx2, 1]))
+        cv2.line(overlay, pt1, pt2, Color.CYAN, Size.LINE_THICK, cv2.LINE_AA)
+
+    # Draw landmarks on top
+    for i, (x, y) in enumerate(landmarks):
+        cv2.circle(overlay, (int(x), int(y)), Size.CORNER_RADIUS, Color.GREEN, -1)
+        cv2.circle(overlay, (int(x), int(y)), Size.CORNER_RADIUS, Color.BLACK, 2)
+
+    return overlay
+
+
+def draw_detection_info(image: np.ndarray, confidence: float, handedness: str, rotation: int) -> np.ndarray:
+    """
+    Draw detection metadata on image.
+
+    Args:
+        image: Input image
+        confidence: Detection confidence (0-1)
+        handedness: "Left" or "Right"
+        rotation: Rotation code (0, 1, 2, 3)
+
+    Returns:
+        Image with text overlay
+    """
+    overlay = image.copy()
+
+    rotation_names = {0: "None", 1: "90° CW", 2: "180°", 3: "90° CCW"}
+    rotation_name = rotation_names.get(rotation, "Unknown")
+
+    lines = [
+        f"Confidence: {confidence:.3f}",
+        f"Hand: {handedness}",
+        f"Rotation: {rotation_name}",
+    ]
+
+    y = Layout.TITLE_Y
+    for line in lines:
+        # Black outline
+        cv2.putText(overlay, line, (Layout.TEXT_OFFSET_X, y), FONT_FACE, FontScale.BODY,
+                   Color.BLACK, FontThickness.LABEL_OUTLINE, cv2.LINE_AA)
+        # White text
+        cv2.putText(overlay, line, (Layout.TEXT_OFFSET_X, y), FONT_FACE, FontScale.BODY,
+                   Color.WHITE, FontThickness.LABEL, cv2.LINE_AA)
+        y += Layout.LINE_SPACING
+
+    return overlay
+
+
+def draw_finger_regions(image: np.ndarray, landmarks: np.ndarray) -> np.ndarray:
+    """
+    Draw individual finger regions in different colors.
+
+    Args:
+        image: Input image
+        landmarks: 21x2 array of landmark positions
+
+    Returns:
+        Image with colored finger regions
+    """
+    h, w = image.shape[:2]
+    overlay = image.copy()
+    mask_overlay = np.zeros((h, w, 3), dtype=np.uint8)
+
+    # Draw thumb
+    thumb_pts = landmarks[THUMB_LANDMARKS].astype(np.int32)
+    cv2.fillConvexPoly(mask_overlay, thumb_pts, FINGER_COLORS["thumb"])
+
+    # Draw each finger
+    for finger_name, indices in FINGER_LANDMARKS.items():
+        finger_pts = landmarks[indices].astype(np.int32)
+        cv2.fillConvexPoly(mask_overlay, finger_pts, FINGER_COLORS[finger_name])
+
+    # Blend with original
+    overlay = cv2.addWeighted(overlay, 0.6, mask_overlay, 0.4, 0)
+
+    return overlay
+
+
+def draw_extension_scores(image: np.ndarray, scores: Dict[str, float], selected: str) -> np.ndarray:
+    """
+    Draw finger extension scores.
+
+    Args:
+        image: Input image
+        scores: Dict mapping finger name to extension score
+        selected: Name of selected finger
+
+    Returns:
+        Image with scores drawn
+    """
+    overlay = image.copy()
+
+    # Sort by score
+    sorted_fingers = sorted(scores.items(), key=lambda x: x[1], reverse=True)
+
+    y = Layout.TITLE_Y
+    for finger_name, score in sorted_fingers:
+        is_selected = (finger_name == selected)
+        color = Color.GREEN if is_selected else Color.WHITE
+        text = f"{finger_name.capitalize()}: {score:.1f}" + (" ✓" if is_selected else "")
+
+        # Black outline
+        cv2.putText(overlay, text, (Layout.TEXT_OFFSET_X, y), FONT_FACE, FontScale.BODY,
+                   Color.BLACK, FontThickness.LABEL_OUTLINE, cv2.LINE_AA)
+        # Colored text
+        cv2.putText(overlay, text, (Layout.TEXT_OFFSET_X, y), FONT_FACE, FontScale.BODY,
+                   color, FontThickness.LABEL, cv2.LINE_AA)
+        y += Layout.LINE_SPACING
+
+    return overlay
+
+
+def draw_component_stats(image: np.ndarray, labels: np.ndarray, stats: np.ndarray,
+                         selected_idx: int) -> np.ndarray:
+    """
+    Draw connected component statistics.
+
+    Args:
+        image: Input image
+        labels: Connected component labels
+        stats: Component statistics from cv2.connectedComponentsWithStats
+        selected_idx: Index of selected component
+
+    Returns:
+        Image with colored components and stats
+    """
+    overlay = image.copy()
+
+    # Create colored component visualization
+    num_labels = stats.shape[0]
+    colors = np.random.randint(0, 255, size=(num_labels, 3), dtype=np.uint8)
+    colors[0] = [0, 0, 0]  # Background is black
+    colors[selected_idx] = Color.GREEN  # Selected is green
+
+    colored = colors[labels]
+    overlay = cv2.addWeighted(overlay, 0.5, colored, 0.5, 0)
+
+    # Draw text stats
+    y = Layout.TITLE_Y
+    lines = [
+        f"Components: {num_labels - 1}",  # Exclude background
+        f"Selected area: {stats[selected_idx, cv2.CC_STAT_AREA]} px",
+    ]
+
+    for line in lines:
+        cv2.putText(overlay, line, (Layout.TEXT_OFFSET_X, y), FONT_FACE, FontScale.BODY,
+                   Color.BLACK, FontThickness.LABEL_OUTLINE, cv2.LINE_AA)
+        cv2.putText(overlay, line, (Layout.TEXT_OFFSET_X, y), FONT_FACE, FontScale.BODY,
+                   Color.WHITE, FontThickness.LABEL, cv2.LINE_AA)
+        y += Layout.LINE_SPACING
+
+    return overlay
+
+
+# --- Card Detection Drawing Functions ---
+
+def draw_contours_overlay(
+    image: np.ndarray,
+    contours: List[np.ndarray],
+    title: str,
+    color: Optional[Tuple[int, int, int]] = None,
+) -> np.ndarray:
+    """
+    Draw contours on an image overlay.
+
+    Args:
+        image: Original image
+        contours: List of contours to draw
+        title: Title for the visualization
+        color: BGR color for contours (default: Color.GREEN)
+
+    Returns:
+        Annotated image
+    """
+    if color is None:
+        color = Color.GREEN
+
+    overlay = image.copy()
+
+    # Draw all contours
+    for contour in contours:
+        if len(contour) == 4:
+            # Draw quadrilateral
+            pts = contour.reshape(4, 2).astype(np.int32)
+            cv2.polylines(overlay, [pts], True, color, Size.CONTOUR_NORMAL)
+
+    # Add title with outline for visibility
+    cv2.putText(
+        overlay, title, (Layout.TEXT_OFFSET_X, Layout.TITLE_Y),
+        FONT_FACE, FontScale.TITLE, Color.WHITE,
+        FontThickness.TITLE_OUTLINE, cv2.LINE_AA
+    )
+    cv2.putText(
+        overlay, title, (Layout.TEXT_OFFSET_X, Layout.TITLE_Y),
+        FONT_FACE, FontScale.TITLE, color,
+        FontThickness.TITLE, cv2.LINE_AA
+    )
+
+    # Add count with outline
+    count_text = f"Candidates: {len(contours)}"
+    cv2.putText(
+        overlay, count_text, (Layout.TEXT_OFFSET_X, Layout.SUBTITLE_Y),
+        FONT_FACE, FontScale.SUBTITLE, Color.WHITE,
+        FontThickness.SUBTITLE_OUTLINE, cv2.LINE_AA
+    )
+    cv2.putText(
+        overlay, count_text, (Layout.TEXT_OFFSET_X, Layout.SUBTITLE_Y),
+        FONT_FACE, FontScale.SUBTITLE, color,
+        FontThickness.SUBTITLE, cv2.LINE_AA
+    )
+
+    return overlay
+
+
+def draw_candidates_with_scores(
+    image: np.ndarray,
+    candidates: List[Tuple[np.ndarray, float, Dict[str, Any]]],
+    title: str,
+) -> np.ndarray:
+    """
+    Draw candidate contours with scores and details.
+
+    Args:
+        image: Original image
+        candidates: List of (corners, score, details) tuples
+        title: Title for the visualization
+
+    Returns:
+        Annotated image
+    """
+    overlay = image.copy()
+
+    # Color palette for candidates (different colors for ranking)
+    colors = [
+        Color.GREEN,    # Green - best
+        Color.YELLOW,   # Yellow
+        Color.ORANGE,   # Orange
+        Color.MAGENTA,  # Magenta
+        Color.PINK      # Pink
+    ]
+
+    for idx, (corners, score, details) in enumerate(candidates):
+        color = colors[idx % len(colors)]
+
+        # Draw quadrilateral
+        pts = corners.reshape(4, 2).astype(np.int32)
+        cv2.polylines(overlay, [pts], True, color, Size.CONTOUR_NORMAL)
+
+        # Draw corner circles
+        for pt in pts:
+            cv2.circle(overlay, tuple(pt), Size.CORNER_RADIUS, color, -1)
+
+        # Prepare annotation text
+        if score > 0:
+            aspect_ratio = details.get("aspect_ratio", 0)
+            area_ratio = details.get("area", 0) / (image.shape[0] * image.shape[1])
+            text = f"#{idx+1} Score:{score:.2f} AR:{aspect_ratio:.2f} Area:{area_ratio:.2%}"
+        else:
+            reject_reason = details.get("reject_reason", "unknown")
+            text = f"#{idx+1} REJECT: {reject_reason}"
+
+        # Position text near first corner
+        text_pos = (int(pts[0][0]) + 10, int(pts[0][1]) - 10)
+
+        # Draw text with outline for visibility
+        cv2.putText(
+            overlay, text, text_pos,
+            FONT_FACE, FontScale.LABEL, Color.BLACK,
+            FontThickness.LABEL_OUTLINE, cv2.LINE_AA
+        )
+        cv2.putText(
+            overlay, text, text_pos,
+            FONT_FACE, FontScale.LABEL, color,
+            FontThickness.LABEL, cv2.LINE_AA
+        )
+
+    # Add title with outline
+    cv2.putText(
+        overlay, title, (Layout.TEXT_OFFSET_X, Layout.TITLE_Y),
+        FONT_FACE, FontScale.TITLE, Color.WHITE,
+        FontThickness.TITLE_OUTLINE, cv2.LINE_AA
+    )
+    cv2.putText(
+        overlay, title, (Layout.TEXT_OFFSET_X, Layout.TITLE_Y),
+        FONT_FACE, FontScale.TITLE, Color.CYAN,
+        FontThickness.TITLE, cv2.LINE_AA
+    )
+
+    return overlay
+
+
+# --- Edge Refinement Drawing Functions (v1 Phase 5) ---
+
+def draw_landmark_axis(
+    image: np.ndarray,
+    axis_data: Dict[str, Any],
+    finger_landmarks: Optional[np.ndarray]
+) -> np.ndarray:
+    """
+    Draw finger landmarks with axis overlay.
+    
+    Shows:
+    - 4 finger landmarks (MCP, PIP, DIP, TIP)
+    - Calculated finger axis
+    - Axis endpoints
+    - Landmark-based vs PCA method indicator
+    """
+    vis = image.copy()
+    
+    # Draw finger landmarks if available
+    if finger_landmarks is not None and len(finger_landmarks) == 4:
+        landmark_names = ["MCP", "PIP", "DIP", "TIP"]
+        for i, (landmark, name) in enumerate(zip(finger_landmarks, landmark_names)):
+            pt = tuple(landmark.astype(int))
+            # Draw landmark
+            cv2.circle(vis, pt, Size.ENDPOINT_RADIUS, Color.YELLOW, -1)
+            cv2.circle(vis, pt, Size.ENDPOINT_RADIUS, Color.BLACK, 2)
+            # Draw label
+            cv2.putText(
+                vis, name, (pt[0] + 20, pt[1] - 20),
+                FONT_FACE, FontScale.LABEL,
+                Color.BLACK, FontThickness.LABEL_OUTLINE
+            )
+            cv2.putText(
+                vis, name, (pt[0] + 20, pt[1] - 20),
+                FONT_FACE, FontScale.LABEL,
+                Color.YELLOW, FontThickness.LABEL
+            )
+    
+    # Draw axis line
+    # Use actual anatomical endpoints (MCP to TIP) if available
+    if "palm_end" in axis_data and "tip_end" in axis_data:
+        start = axis_data["palm_end"]  # MCP (palm-side)
+        end = axis_data["tip_end"]      # TIP (fingertip)
+    else:
+        # Fallback to geometric center method (for PCA or old data)
+        center = axis_data["center"]
+        direction = axis_data["direction"]
+        length = axis_data["length"]
+        start = center - direction * (length / 2.0)
+        end = center + direction * (length / 2.0)
+
+    # Draw axis
+    cv2.line(
+        vis,
+        tuple(start.astype(int)),
+        tuple(end.astype(int)),
+        Color.CYAN, Size.LINE_THICK
+    )
+
+    # Draw endpoints
+    cv2.circle(vis, tuple(start.astype(int)), Size.ENDPOINT_RADIUS, Color.CYAN, -1)
+    cv2.circle(vis, tuple(end.astype(int)), Size.ENDPOINT_RADIUS, Color.MAGENTA, -1)
+    
+    # Add method indicator
+    method = axis_data.get("method", "unknown")
+    text = f"Axis Method: {method}"
+    cv2.putText(
+        vis, text, (50, 100),
+        FONT_FACE, FontScale.TITLE,
+        Color.BLACK, FontThickness.TITLE_OUTLINE
+    )
+    cv2.putText(
+        vis, text, (50, 100),
+        FONT_FACE, FontScale.TITLE,
+        Color.CYAN, FontThickness.TITLE
+    )
+    
+    return vis
+
+
+def draw_ring_zone_roi(
+    image: np.ndarray,
+    zone_data: Dict[str, Any],
+    roi_bounds: Tuple[int, int, int, int]
+) -> np.ndarray:
+    """
+    Draw ring zone and ROI bounds.
+    
+    Shows:
+    - Ring-wearing zone band
+    - ROI bounding box
+    - Zone start/end points
+    """
+    vis = image.copy()
+    
+    # Draw ring zone
+    start_point = zone_data["start_point"]
+    end_point = zone_data["end_point"]
+    
+    cv2.circle(vis, tuple(start_point.astype(int)), Size.ENDPOINT_RADIUS, Color.GREEN, -1)
+    cv2.circle(vis, tuple(end_point.astype(int)), Size.ENDPOINT_RADIUS, Color.RED, -1)
+    cv2.line(
+        vis,
+        tuple(start_point.astype(int)),
+        tuple(end_point.astype(int)),
+        Color.YELLOW, Size.LINE_THICK * 2
+    )
+    
+    # Draw ROI bounding box
+    x_min, y_min, x_max, y_max = roi_bounds
+    cv2.rectangle(vis, (x_min, y_min), (x_max, y_max), Color.GREEN, Size.LINE_THICK)
+    
+    # Add labels
+    text = "Ring Zone + ROI Bounds"
+    cv2.putText(
+        vis, text, (50, 100),
+        FONT_FACE, FontScale.TITLE,
+        Color.BLACK, FontThickness.TITLE_OUTLINE
+    )
+    cv2.putText(
+        vis, text, (50, 100),
+        FONT_FACE, FontScale.TITLE,
+        Color.GREEN, FontThickness.TITLE
+    )
+    
+    return vis
+
+
+def draw_roi_extraction(
+    roi_image: np.ndarray,
+    roi_mask: Optional[np.ndarray]
+) -> np.ndarray:
+    """
+    Draw extracted ROI with optional mask overlay.
+    """
+    # Convert grayscale to BGR for visualization
+    if len(roi_image.shape) == 2:
+        vis = cv2.cvtColor(roi_image, cv2.COLOR_GRAY2BGR)
+    else:
+        vis = roi_image.copy()
+    
+    # Overlay mask if available
+    if roi_mask is not None:
+        mask_colored = np.zeros_like(vis)
+        mask_colored[:, :, 1] = roi_mask  # Green channel
+        vis = cv2.addWeighted(vis, 0.7, mask_colored, 0.3, 0)
+    
+    return vis
+
+
+def draw_gradient_visualization(
+    gradient: np.ndarray,
+    colormap: int = cv2.COLORMAP_JET
+) -> np.ndarray:
+    """
+    Visualize gradient with color mapping.
+    """
+    grad_vis = np.clip(gradient, 0, 255).astype(np.uint8)
+    return cv2.applyColorMap(grad_vis, colormap)
+
+
+def draw_edge_candidates(
+    roi_image: np.ndarray,
+    gradient_magnitude: np.ndarray,
+    threshold: float
+) -> np.ndarray:
+    """
+    Draw all pixels above gradient threshold (raw threshold, before spatial filtering).
+
+    This shows ALL pixels where gradient > threshold, including background noise.
+    Use draw_filtered_edge_candidates() to see only spatially-filtered candidates.
+    """
+    # Convert ROI to BGR
+    if len(roi_image.shape) == 2:
+        vis = cv2.cvtColor(roi_image, cv2.COLOR_GRAY2BGR)
+    else:
+        vis = roi_image.copy()
+
+    # Find edge candidates
+    candidates = gradient_magnitude > threshold
+
+    # Overlay candidates in cyan
+    vis[candidates] = Color.CYAN
+
+    # Add annotation explaining this is raw threshold
+    count = np.sum(candidates)
+    text1 = f"All pixels > {threshold:.1f}"
+    text2 = "(Before spatial filtering)"
+    text3 = f"Count: {count:,}"
+
+    cv2.putText(vis, text1, (20, 40), FONT_FACE, 1.5, Color.WHITE, 4)
+    cv2.putText(vis, text1, (20, 40), FONT_FACE, 1.5, Color.BLACK, 2)
+
+    cv2.putText(vis, text2, (20, 80), FONT_FACE, 1.2, Color.WHITE, 4)
+    cv2.putText(vis, text2, (20, 80), FONT_FACE, 1.2, Color.YELLOW, 2)
+
+    cv2.putText(vis, text3, (20, 120), FONT_FACE, 1.2, Color.WHITE, 4)
+    cv2.putText(vis, text3, (20, 120), FONT_FACE, 1.2, Color.CYAN, 2)
+
+    return vis
+
+
+def draw_filtered_edge_candidates(
+    roi_image: np.ndarray,
+    gradient_magnitude: np.ndarray,
+    threshold: float,
+    roi_mask: Optional[np.ndarray],
+    axis_center: np.ndarray,
+    axis_direction: np.ndarray
+) -> np.ndarray:
+    """
+    Draw only the spatially-filtered edge candidates that the algorithm actually considers.
+
+    Shows pixels that pass BOTH gradient threshold AND spatial filtering:
+    - Mask-constrained mode: Within finger mask boundaries
+    - Axis-expansion mode: Along search path from axis outward
+
+    This matches what detect_edges_per_row() actually evaluates.
+
+    Args:
+        roi_image: ROI image
+        gradient_magnitude: Gradient magnitude array
+        threshold: Gradient threshold
+        roi_mask: Optional finger mask in ROI coordinates
+        axis_center: Axis center point in ROI coordinates
+        axis_direction: Axis direction vector in ROI coordinates
+
+    Returns:
+        Visualization showing only filtered candidates
+    """
+    # Convert ROI to BGR
+    if len(roi_image.shape) == 2:
+        vis = cv2.cvtColor(roi_image, cv2.COLOR_GRAY2BGR)
+    else:
+        vis = roi_image.copy()
+
+    h, w = gradient_magnitude.shape
+
+    # Helper function to get axis x-coordinate at each row
+    def get_axis_x_at_row(y: int) -> int:
+        """Calculate axis x-coordinate at given y using axis center and direction."""
+        if abs(axis_direction[1]) < 1e-6:
+            # Axis is horizontal, use center x
+            return int(axis_center[0])
+
+        # Calculate offset from axis center
+        dy = y - axis_center[1]
+        dx = dy * (axis_direction[0] / axis_direction[1])
+        x = axis_center[0] + dx
+
+        return int(np.clip(x, 0, w - 1))
+
+    # MASK-CONSTRAINED MODE (if mask available)
+    if roi_mask is not None:
+        mode = "Mask-Constrained"
+        candidate_count = 0
+
+        for y in range(h):
+            row_gradient = gradient_magnitude[y, :]
+            row_mask = roi_mask[y, :]
+
+            if not np.any(row_mask):
+                continue
+
+            # Find mask boundaries
+            mask_indices = np.where(row_mask)[0]
+            if len(mask_indices) < 2:
+                continue
+
+            left_mask_boundary = mask_indices[0]
+            right_mask_boundary = mask_indices[-1]
+
+            # Get axis position
+            axis_x = get_axis_x_at_row(y)
+
+            # Search LEFT from axis to left mask boundary - find STRONGEST gradient
+            left_edge_x = None
+            left_strength = 0
+            search_start = max(left_mask_boundary, min(axis_x, w - 1))
+            for x in range(search_start, left_mask_boundary - 1, -1):
+                if x < 0 or x >= w:
+                    continue
+                if row_gradient[x] > threshold:
+                    # Update if this is stronger than previous
+                    if row_gradient[x] > left_strength:
+                        left_edge_x = x
+                        left_strength = row_gradient[x]
+
+            # If no edge found, try relaxed threshold
+            if left_edge_x is None:
+                relaxed_threshold = threshold * 0.5
+                for x in range(search_start, left_mask_boundary - 1, -1):
+                    if x < 0 or x >= w:
+                        continue
+                    if row_gradient[x] > relaxed_threshold:
+                        if row_gradient[x] > left_strength:
+                            left_edge_x = x
+                            left_strength = row_gradient[x]
+
+            # Search RIGHT from axis to right mask boundary - find STRONGEST gradient
+            right_edge_x = None
+            right_strength = 0
+            search_start = min(right_mask_boundary, max(axis_x, 0))
+            for x in range(search_start, right_mask_boundary + 1):
+                if x < 0 or x >= w:
+                    continue
+                if row_gradient[x] > threshold:
+                    # Update if this is stronger than previous
+                    if row_gradient[x] > right_strength:
+                        right_edge_x = x
+                        right_strength = row_gradient[x]
+
+            # If no edge found, try relaxed threshold
+            if right_edge_x is None:
+                relaxed_threshold = threshold * 0.5
+                for x in range(search_start, right_mask_boundary + 1):
+                    if x < 0 or x >= w:
+                        continue
+                    if row_gradient[x] > relaxed_threshold:
+                        if row_gradient[x] > right_strength:
+                            right_edge_x = x
+                            right_strength = row_gradient[x]
+
+            # Draw the SELECTED edges only (not all candidates)
+            if left_edge_x is not None:
+                cv2.circle(vis, (left_edge_x, y), 2, Color.CYAN, -1)
+                candidate_count += 1
+
+            if right_edge_x is not None:
+                cv2.circle(vis, (right_edge_x, y), 2, Color.MAGENTA, -1)
+                candidate_count += 1
+
+            # Draw axis position
+            cv2.circle(vis, (axis_x, y), 1, Color.YELLOW, -1)
+
+    # AXIS-EXPANSION MODE (no mask)
+    else:
+        mode = "Axis-Expansion"
+        candidate_count = 0
+
+        for y in range(h):
+            row_gradient = gradient_magnitude[y, :]
+            axis_x = get_axis_x_at_row(y)
+
+            if axis_x < 0 or axis_x >= w:
+                continue
+
+            # Draw axis position
+            cv2.circle(vis, (axis_x, y), 2, Color.YELLOW, -1)
+
+            # Search LEFT from axis until first edge
+            for x in range(axis_x, -1, -1):
+                if row_gradient[x] > threshold:
+                    cv2.circle(vis, (x, y), 2, Color.CYAN, -1)
+                    candidate_count += 1
+                    break  # Stop at first edge
+
+            # Search RIGHT from axis until first edge
+            for x in range(axis_x, w):
+                if row_gradient[x] > threshold:
+                    cv2.circle(vis, (x, y), 2, Color.MAGENTA, -1)
+                    candidate_count += 1
+                    break  # Stop at first edge
+
+    # Add annotation
+    text1 = f"Spatially-filtered candidates"
+    text2 = f"Mode: {mode}"
+    text3 = f"Count: {candidate_count:,}"
+
+    cv2.putText(vis, text1, (20, 40), FONT_FACE, 1.5, Color.WHITE, 4)
+    cv2.putText(vis, text1, (20, 40), FONT_FACE, 1.5, Color.GREEN, 2)
+
+    cv2.putText(vis, text2, (20, 80), FONT_FACE, 1.2, Color.WHITE, 4)
+    cv2.putText(vis, text2, (20, 80), FONT_FACE, 1.2, Color.YELLOW, 2)
+
+    cv2.putText(vis, text3, (20, 120), FONT_FACE, 1.2, Color.WHITE, 4)
+    cv2.putText(vis, text3, (20, 120), FONT_FACE, 1.2, Color.CYAN, 2)
+
+    # Add legend
+    legend_y = h - 80
+    cv2.putText(vis, "Yellow: Axis", (20, legend_y), FONT_FACE, 1.0, Color.YELLOW, 2)
+    cv2.putText(vis, "Cyan: Left edges", (20, legend_y + 30), FONT_FACE, 1.0, Color.CYAN, 2)
+    cv2.putText(vis, "Magenta: Right edges", (20, legend_y + 60), FONT_FACE, 1.0, Color.MAGENTA, 2)
+
+    return vis
+
+
+def draw_selected_edges(
+    roi_image: np.ndarray,
+    edge_data: Dict[str, Any]
+) -> np.ndarray:
+    """
+    Draw final selected left/right edges with enhanced visualization.
+    Shows edge points, connecting lines, and statistics.
+    """
+    # Convert ROI to BGR
+    if len(roi_image.shape) == 2:
+        vis = cv2.cvtColor(roi_image, cv2.COLOR_GRAY2BGR)
+    else:
+        vis = roi_image.copy()
+    
+    h, w = vis.shape[:2]
+    
+    left_edges = edge_data["left_edges"]
+    right_edges = edge_data["right_edges"]
+    valid_rows = edge_data["valid_rows"]
+    
+    # Calculate statistics for valid edges
+    valid_left = left_edges[valid_rows]
+    valid_right = right_edges[valid_rows]
+    valid_widths = valid_right - valid_left
+    
+    if len(valid_widths) > 0:
+        median_width = np.median(valid_widths)
+        
+        # Draw connecting lines for every Nth row (to avoid clutter)
+        line_spacing = max(1, int(len(valid_rows)) // 20)  # Show ~20 lines
+        
+        count = 0  # Count valid rows
+        for row_idx, valid in enumerate(valid_rows):
+            if not valid:
+                continue
+                
+            left_x = int(left_edges[row_idx])
+            right_x = int(right_edges[row_idx])
+            width = right_x - left_x
+            
+            # Draw connecting line (every Nth valid row)
+            if count % line_spacing == 0:
+                # Color based on width deviation
+                deviation = abs(width - median_width) / median_width if median_width > 0 else 0
+                if deviation < 0.05:
+                    line_color = Color.GREEN
+                elif deviation < 0.15:
+                    line_color = Color.YELLOW
+                else:
+                    line_color = Color.ORANGE
+                
+                cv2.line(vis, (left_x, row_idx), (right_x, row_idx), line_color, 1)
+            
+            count += 1  # Increment valid row counter
+        
+        # Draw edge points on top
+        for row_idx, valid in enumerate(valid_rows):
+            if valid:
+                # Draw left edge (blue)
+                left_x = int(left_edges[row_idx])
+                cv2.circle(vis, (left_x, row_idx), 2, Color.CYAN, -1)
+                
+                # Draw right edge (magenta)
+                right_x = int(right_edges[row_idx])
+                cv2.circle(vis, (right_x, row_idx), 2, Color.MAGENTA, -1)
+        
+        # Add text annotations
+        # Scale font size based on ROI height for readability
+        font_scale = max(0.3, h / 600.0)  # Scale based on ROI height, min 0.3
+        line_height = int(15 + h / 40.0)  # Scale line spacing too
+        thickness = 1
+
+        valid_pct = np.sum(valid_rows) / len(valid_rows) * 100
+        text_lines = [
+            f"Valid edges: {np.sum(valid_rows)}/{len(valid_rows)} ({valid_pct:.1f}%)",
+            f"Left range: {np.min(valid_left):.1f}-{np.max(valid_left):.1f}px",
+            f"Right range: {np.min(valid_right):.1f}-{np.max(valid_right):.1f}px",
+            f"Width: {np.min(valid_widths):.1f}-{np.max(valid_widths):.1f}px",
+            f"Median: {median_width:.1f}px"
+        ]
+
+        for i, text in enumerate(text_lines):
+            y = line_height + i * line_height
+            # Background for readability
+            (text_w, text_h), _ = cv2.getTextSize(text, FONT_FACE, font_scale, thickness)
+            cv2.rectangle(vis, (5, y - text_h - 2), (5 + text_w + 5, y + 2), (0, 0, 0), -1)
+            cv2.putText(vis, text, (8, y), FONT_FACE, font_scale, Color.WHITE, thickness)
+    
+    return vis
+
+
+def draw_width_measurements(
+    roi_image: np.ndarray,
+    edge_data: Dict[str, Any],
+    width_data: Dict[str, Any]
+) -> np.ndarray:
+    """
+    Draw width measurements with connecting lines.
+    """
+    # Convert ROI to BGR
+    if len(roi_image.shape) == 2:
+        vis = cv2.cvtColor(roi_image, cv2.COLOR_GRAY2BGR)
+    else:
+        vis = roi_image.copy()
+    
+    left_edges = edge_data["left_edges"]
+    right_edges = edge_data["right_edges"]
+    valid_rows = edge_data["valid_rows"]
+    
+    median_width_px = width_data["median_width_px"]
+    
+    # Draw width lines
+    for row_idx, valid in enumerate(valid_rows):
+        if valid:
+            left_x = int(left_edges[row_idx])
+            right_x = int(right_edges[row_idx])
+            width_px = right_x - left_x
+            
+            # Color based on deviation from median
+            deviation = abs(width_px - median_width_px) / median_width_px
+            if deviation < 0.05:
+                color = Color.GREEN  # Close to median
+            elif deviation < 0.10:
+                color = Color.YELLOW  # Moderate deviation
+            else:
+                color = Color.RED  # Large deviation
+            
+            # Draw line
+            cv2.line(vis, (left_x, row_idx), (right_x, row_idx), color, 1)
+    
+    # Add median width annotation
+    # Scale font size based on ROI height
+    h = vis.shape[0]
+    font_scale = max(0.4, h / 500.0)
+    thickness = max(1, int(h / 150.0))
+
+    median_cm = width_data["median_width_cm"]
+    text = f"Median: {median_cm:.2f} cm ({median_width_px:.1f} px)"
+    cv2.putText(
+        vis, text, (10, int(h * 0.15)),
+        FONT_FACE, font_scale,
+        Color.BLACK, thickness + 2
+    )
+    cv2.putText(
+        vis, text, (10, int(h * 0.15)),
+        FONT_FACE, font_scale,
+        Color.GREEN, thickness
+    )
+    
+    return vis
+
+
+def draw_outlier_detection(
+    roi_image: np.ndarray,
+    edge_data: Dict[str, Any],
+    width_data: Dict[str, Any]
+) -> np.ndarray:
+    """
+    Highlight outlier measurements.
+    """
+    # Convert ROI to BGR
+    if len(roi_image.shape) == 2:
+        vis = cv2.cvtColor(roi_image, cv2.COLOR_GRAY2BGR)
+    else:
+        vis = roi_image.copy()
+    
+    left_edges = edge_data["left_edges"]
+    right_edges = edge_data["right_edges"]
+    valid_rows = edge_data["valid_rows"]
+    
+    median_width_px = width_data["median_width_px"]
+    outliers_removed = width_data.get("outliers_removed", 0)
+    
+    # Calculate MAD threshold
+    all_widths = []
+    for row_idx, valid in enumerate(valid_rows):
+        if valid:
+            width_px = right_edges[row_idx] - left_edges[row_idx]
+            all_widths.append(width_px)
+    
+    if len(all_widths) > 0:
+        all_widths = np.array(all_widths)
+        mad = np.median(np.abs(all_widths - median_width_px))
+        outlier_threshold = 3.0 * mad
+        
+        # Draw width lines color-coded
+        for row_idx, valid in enumerate(valid_rows):
+            if valid:
+                left_x = int(left_edges[row_idx])
+                right_x = int(right_edges[row_idx])
+                width_px = right_x - left_x
+                
+                is_outlier = abs(width_px - median_width_px) > outlier_threshold
+                color = Color.RED if is_outlier else Color.GREEN
+                
+                cv2.line(vis, (left_x, row_idx), (right_x, row_idx), color, 2)
+    
+    # Add annotation with adaptive font scaling
+    h = vis.shape[0]
+    font_scale = max(0.4, h / 500.0)
+    thickness = max(1, int(h / 150.0))
+
+    text = f"Outliers: {outliers_removed}"
+    y_pos = int(h * 0.10)  # Position at 10% of image height
+
+    # Get text size for background
+    (text_w, text_h), baseline = cv2.getTextSize(text, FONT_FACE, font_scale, thickness)
+
+    # Draw background for readability
+    cv2.rectangle(vis, (5, y_pos - text_h - 5), (15 + text_w, y_pos + baseline),
+                  (0, 0, 0), -1)
+
+    # Draw text with outline
+    cv2.putText(vis, text, (10, y_pos), FONT_FACE, font_scale,
+                Color.BLACK, thickness + 2, cv2.LINE_AA)
+    cv2.putText(vis, text, (10, y_pos), FONT_FACE, font_scale,
+                Color.RED, thickness, cv2.LINE_AA)
+
+    return vis
+
+
+def draw_comprehensive_edge_overlay(
+    full_image: np.ndarray,
+    edge_data: Dict[str, Any],
+    roi_bounds: Tuple[int, int, int, int],
+    axis_data: Dict[str, Any],
+    zone_data: Dict[str, Any],
+    width_data: Dict[str, Any],
+    scale_px_per_cm: float
+) -> np.ndarray:
+    """
+    Comprehensive visualization showing detected edges overlaid on full image
+    with axis, zone, and measurement annotations.
+    """
+    vis = full_image.copy()
+    h, w = vis.shape[:2]
+    
+    x_min, y_min, x_max, y_max = roi_bounds
+    left_edges = edge_data["left_edges"]
+    right_edges = edge_data["right_edges"]
+    valid_rows = edge_data["valid_rows"]
+    
+    # 1. Draw axis line
+    # Handle both PCA (tip_point, palm_point) and landmark-based axis (center, direction)
+    if "center" in axis_data:
+        axis_center = axis_data["center"]
+    elif "tip_point" in axis_data and "palm_point" in axis_data:
+        axis_center = (axis_data["tip_point"] + axis_data["palm_point"]) / 2
+    else:
+        # Fallback: use midpoint of axis
+        axis_center = np.array([w//2, h//2])
+    
+    axis_direction = axis_data["direction"]
+    axis_length = axis_data["length"]
+    
+    axis_start = axis_center - axis_direction * (axis_length / 2)
+    axis_end = axis_center + axis_direction * (axis_length / 2)
+    cv2.line(vis, tuple(axis_start.astype(int)), tuple(axis_end.astype(int)), 
+             Color.YELLOW, 2, cv2.LINE_AA)
+    
+    # 2. Draw ring zone bounds as two lines perpendicular to axis at zone start/end
+    zone_start = zone_data["start_point"]
+    zone_end = zone_data["end_point"]
+    perp_direction = np.array([-axis_direction[1], axis_direction[0]])
+    # Use ROI half-width so the zone lines span the ROI
+    roi_half_width = (x_max - x_min) / 2.0
+
+    for zone_pt in [zone_start, zone_end]:
+        p1 = (zone_pt + perp_direction * roi_half_width).astype(int)
+        p2 = (zone_pt - perp_direction * roi_half_width).astype(int)
+        cv2.line(vis, tuple(p1), tuple(p2), Color.ORANGE, 2, cv2.LINE_AA)
+    
+    # 3. Draw ROI boundary
+    cv2.rectangle(vis, (x_min, y_min), (x_max, y_max), Color.CYAN, 2)
+    
+    # 4. Draw detected edges
+    line_spacing = max(1, int(np.sum(valid_rows)) // 25)  # Show ~25 lines
+    count = 0
+    
+    for row_idx, valid in enumerate(valid_rows):
+        if not valid:
+            continue
+        
+        # Map ROI coordinates to full image
+        global_y = y_min + row_idx
+        left_x_global = x_min + int(left_edges[row_idx])
+        right_x_global = x_min + int(right_edges[row_idx])
+        
+        # Draw edge points
+        cv2.circle(vis, (left_x_global, global_y), 3, Color.BLUE, -1)
+        cv2.circle(vis, (right_x_global, global_y), 3, Color.MAGENTA, -1)
+        
+        # Draw connecting lines for every Nth row
+        if count % line_spacing == 0:
+            cv2.line(vis, (left_x_global, global_y), (right_x_global, global_y),
+                    Color.GREEN, 2, cv2.LINE_AA)
+        count += 1
+    
+    # 5. Add text annotations in top-left corner with adaptive sizing
+    median_cm = width_data["median_width_cm"]
+    median_px = width_data["median_width_px"]
+    std_px = width_data["std_width_px"]
+    num_samples = width_data["num_samples"]
+    valid_pct = np.sum(valid_rows) / len(valid_rows) * 100
+
+    # Adaptive font scaling based on image height (more conservative for full-sized images)
+    font_scale = max(0.3, h / 1500.0)  # Scale for full-sized images
+    line_height = int(35 + h / 70.0)   # Scale line spacing (increased for better readability)
+    thickness = max(1, int(h / 500.0))
+
+    annotations = [
+        f"Sobel Edge Detection Results:",
+        f"  Median Width: {median_cm:.3f} cm ({median_px:.1f} px)",
+        f"  Std Dev: {std_px:.2f} px",
+        f"  Valid Edges: {np.sum(valid_rows)}/{len(valid_rows)} ({valid_pct:.1f}%)",
+        f"  Measurements: {num_samples}",
+        f"  Scale: {scale_px_per_cm:.2f} px/cm",
+        "",
+        "Legend:",
+        "  Yellow line = Finger axis",
+        "  Orange lines = Ring zone",
+        "  Cyan box = ROI",
+        "  Blue dots = Left edges",
+        "  Magenta dots = Right edges",
+        "  Green lines = Width measurements"
+    ]
+
+    # Draw text with background for readability
+    y_offset = line_height
+    for line in annotations:
+        if line:  # Skip empty lines for background
+            (text_w, text_h), baseline = cv2.getTextSize(line, FONT_FACE, font_scale, thickness)
+            # Black background
+            cv2.rectangle(vis, (15, y_offset - text_h - 5), (25 + text_w, y_offset + baseline),
+                         (0, 0, 0), -1)
+        # Draw text
+        if line.startswith("  "):
+            color = Color.WHITE
+        elif line.endswith(":"):
+            color = Color.YELLOW
+        else:
+            color = Color.CYAN
+        cv2.putText(vis, line, (20, y_offset), FONT_FACE, font_scale,
+                   color, thickness, cv2.LINE_AA)
+        y_offset += line_height
+
+    return vis
+
+
+def draw_contour_vs_sobel(
+    image: np.ndarray,
+    finger_contour: np.ndarray,
+    edge_data: Dict[str, Any],
+    roi_bounds: Tuple[int, int, int, int]
+) -> np.ndarray:
+    """
+    Side-by-side comparison of contour vs Sobel edges.
+    """
+    vis = image.copy()
+    
+    # Draw contour (v0 method)
+    cv2.drawContours(vis, [finger_contour], -1, Color.GREEN, Size.CONTOUR_THICK)
+    
+    # Draw Sobel edges (v1 method)
+    x_min, y_min, x_max, y_max = roi_bounds
+    left_edges = edge_data["left_edges"]
+    right_edges = edge_data["right_edges"]
+    valid_rows = edge_data["valid_rows"]
+    
+    for row_idx, valid in enumerate(valid_rows):
+        if valid:
+            # Map ROI coordinates back to original image
+            global_y = y_min + row_idx
+            left_x_global = x_min + int(left_edges[row_idx])
+            right_x_global = x_min + int(right_edges[row_idx])
+            
+            # Draw edge points
+            cv2.circle(vis, (left_x_global, global_y), 2, Color.CYAN, -1)
+            cv2.circle(vis, (right_x_global, global_y), 2, Color.MAGENTA, -1)
+    
+    # Add legend
+    cv2.putText(
+        vis, "Green: Contour | Cyan/Magenta: Sobel Edges", (50, 100),
+        FONT_FACE, FontScale.TITLE,
+        Color.BLACK, FontThickness.TITLE_OUTLINE
+    )
+    cv2.putText(
+        vis, "Green: Contour | Cyan/Magenta: Sobel Edges", (50, 100),
+        FONT_FACE, FontScale.TITLE,
+        Color.WHITE, FontThickness.TITLE
+    )
+    
+    return vis

src/edge_refinement.py

@@ -0,0 +1,1335 @@
+"""
+Edge refinement using Sobel gradient filtering.
+
+This module implements v1's core innovation: replacing contour-based width
+measurement with gradient-based edge detection for improved accuracy.
+
+Functions:
+- extract_ring_zone_roi: Extract ROI around ring zone
+- apply_sobel_filters: Bidirectional Sobel filtering
+- detect_edges_per_row: Find left/right edges in each cross-section
+- refine_edge_subpixel: Sub-pixel edge localization (Phase 3)
+- measure_width_from_edges: Compute width from edge positions
+- compute_edge_quality_score: Assess edge detection quality (Phase 3)
+- should_use_sobel_measurement: Auto fallback logic (Phase 3)
+- refine_edges_sobel: Main entry point for edge refinement
+"""
+
+import cv2
+import numpy as np
+import logging
+from typing import Dict, Any, Optional, Tuple, List
+
+from src.edge_refinement_constants import (
+    # Sobel Filter
+    DEFAULT_KERNEL_SIZE,
+    VALID_KERNEL_SIZES,
+    # Edge Detection
+    DEFAULT_GRADIENT_THRESHOLD,
+    MIN_FINGER_WIDTH_CM,
+    MAX_FINGER_WIDTH_CM,
+    WIDTH_TOLERANCE_FACTOR,
+    # Sub-Pixel Refinement
+    MAX_SUBPIXEL_OFFSET,
+    MIN_PARABOLA_DENOMINATOR,
+    # Outlier Filtering
+    MAD_OUTLIER_THRESHOLD,
+    # Edge Quality Scoring
+    GRADIENT_STRENGTH_NORMALIZER,
+    SMOOTHNESS_VARIANCE_NORMALIZER,
+    QUALITY_WEIGHT_GRADIENT,
+    QUALITY_WEIGHT_CONSISTENCY,
+    QUALITY_WEIGHT_SMOOTHNESS,
+    QUALITY_WEIGHT_SYMMETRY,
+    # Auto Fallback Decision
+    MIN_QUALITY_SCORE_THRESHOLD,
+    MIN_CONSISTENCY_THRESHOLD,
+    MIN_REALISTIC_WIDTH_CM,
+    MAX_REALISTIC_WIDTH_CM,
+    MAX_CONTOUR_DIFFERENCE_PCT,
+)
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Helper Functions (extracted from nested scope)
+# =============================================================================
+
+def _get_axis_x_at_row(row_y: float, axis_center: Optional[np.ndarray],
+                       axis_direction: Optional[np.ndarray], width: int) -> float:
+    """
+    Get axis x-coordinate at given row y-coordinate.
+
+    Args:
+        row_y: Row y-coordinate
+        axis_center: Axis center point (x, y)
+        axis_direction: Axis direction vector (dx, dy)
+        width: Image width (for fallback)
+
+    Returns:
+        X-coordinate of axis at given row
+    """
+    if axis_center is None or axis_direction is None:
+        return width / 2  # Fallback to center
+
+    if abs(axis_direction[1]) < 1e-6:
+        # Nearly horizontal axis
+        return axis_center[0]
+    else:
+        # Parametric line: P = axis_center + t * axis_direction
+        t = (row_y - axis_center[1]) / axis_direction[1]
+        return axis_center[0] + t * axis_direction[0]
+
+
+def _find_edges_from_axis(
+    row_gradient: np.ndarray,
+    row_y: float,
+    axis_x: float,
+    threshold: float,
+    min_width_px: Optional[float],
+    max_width_px: Optional[float],
+    row_mask: Optional[np.ndarray] = None,
+    row_gradient_left_to_right: Optional[np.ndarray] = None,
+    row_gradient_right_to_left: Optional[np.ndarray] = None,
+) -> Optional[Tuple[float, float, float, float]]:
+    """
+    Find left and right edges by expanding from axis position.
+
+    Strategy:
+    - MASK-CONSTRAINED MODE (when row_mask provided):
+      1. Find leftmost/rightmost mask pixels (finger boundaries)
+      2. Search for strongest gradient within ±10px of mask boundaries
+      3. Combines anatomical accuracy (mask) with sub-pixel precision (gradient)
+
+    - AXIS-EXPANSION MODE (when row_mask is None):
+      1. Start at axis x-coordinate (INSIDE the finger)
+      2. Search LEFT/RIGHT from axis for closest salient edge
+      3. Validate width is within realistic range
+
+    Args:
+        row_gradient: Gradient magnitude for this row
+        row_y: Row y-coordinate
+        axis_x: Axis x-coordinate at this row
+        threshold: Gradient threshold for valid edge
+        min_width_px: Minimum valid width in pixels (None to skip)
+        max_width_px: Maximum valid width in pixels (None to skip)
+        row_mask: Optional mask row (True = finger pixel) for constrained search
+        row_gradient_left_to_right: Optional directional gradient map for right edge search
+        row_gradient_right_to_left: Optional directional gradient map for left edge search
+
+    Returns:
+        Tuple of (left_x, right_x, left_strength, right_strength) or None if invalid
+    """
+    if axis_x < 0 or axis_x >= len(row_gradient):
+        return None
+
+    # Direction-aware gradient maps (preferred when available):
+    # - left boundary should come from right-to-left transition
+    # - right boundary should come from left-to-right transition
+    left_search_gradient = row_gradient_right_to_left if row_gradient_right_to_left is not None else row_gradient
+    right_search_gradient = row_gradient_left_to_right if row_gradient_left_to_right is not None else row_gradient
+
+    # MASK-CONSTRAINED MODE (preferred when available)
+    if row_mask is not None and np.any(row_mask):
+        # Strategy: Search FROM axis OUTWARD, constrained by mask
+        # This avoids picking background edges while using gradient precision
+
+        mask_indices = np.where(row_mask)[0]
+        if len(mask_indices) < 2:
+            return None  # Mask too small
+
+        left_mask_boundary = mask_indices[0]
+        right_mask_boundary = mask_indices[-1]
+
+        # Search LEFT from axis, stopping at mask boundary
+        left_edge_x = None
+        left_strength = 0
+
+        # Start from axis, go left until we reach left mask boundary
+        search_start = max(left_mask_boundary, int(axis_x))
+        for x in range(search_start, left_mask_boundary - 1, -1):
+            if x < 0 or x >= len(row_gradient):
+                continue
+            if left_search_gradient[x] > threshold:
+                # Found a strong edge - update if stronger than previous
+                if left_search_gradient[x] > left_strength:
+                    left_edge_x = x
+                    left_strength = left_search_gradient[x]
+
+        # If no edge found with full threshold, try with relaxed threshold
+        if left_edge_x is None:
+            relaxed_threshold = threshold * 0.5
+            for x in range(search_start, left_mask_boundary - 1, -1):
+                if x < 0 or x >= len(row_gradient):
+                    continue
+                if left_search_gradient[x] > relaxed_threshold:
+                    if left_search_gradient[x] > left_strength:
+                        left_edge_x = x
+                        left_strength = left_search_gradient[x]
+
+        # Search RIGHT from axis, stopping at mask boundary
+        right_edge_x = None
+        right_strength = 0
+
+        # Start from axis, go right until we reach right mask boundary
+        search_start = min(right_mask_boundary, int(axis_x))
+        for x in range(search_start, right_mask_boundary + 1):
+            if x < 0 or x >= len(row_gradient):
+                continue
+            if right_search_gradient[x] > threshold:
+                # Found a strong edge - update if stronger than previous
+                if right_search_gradient[x] > right_strength:
+                    right_edge_x = x
+                    right_strength = right_search_gradient[x]
+
+        # If no edge found with full threshold, try with relaxed threshold
+        if right_edge_x is None:
+            relaxed_threshold = threshold * 0.5
+            for x in range(search_start, right_mask_boundary + 1):
+                if x < 0 or x >= len(row_gradient):
+                    continue
+                if right_search_gradient[x] > relaxed_threshold:
+                    if right_search_gradient[x] > right_strength:
+                        right_edge_x = x
+                        right_strength = right_search_gradient[x]
+
+        if left_edge_x is None or right_edge_x is None:
+            return None  # No valid edges found
+
+    else:
+        # AXIS-EXPANSION MODE (fallback when no mask)
+        # Search LEFT from axis (go leftward)
+        left_edge_x = None
+        left_strength = 0
+        for x in range(int(axis_x), -1, -1):
+            if left_search_gradient[x] > threshold:
+                # Found a salient edge - this is our left boundary
+                left_edge_x = x
+                left_strength = left_search_gradient[x]
+                break
+
+        # Search RIGHT from axis (go rightward)
+        right_edge_x = None
+        right_strength = 0
+        for x in range(int(axis_x), len(row_gradient)):
+            if right_search_gradient[x] > threshold:
+                # Found a salient edge - this is our right boundary
+                right_edge_x = x
+                right_strength = right_search_gradient[x]
+                break
+
+        if left_edge_x is None or right_edge_x is None:
+            return None
+
+    # Validate width is within realistic finger range
+    width = right_edge_x - left_edge_x
+    if min_width_px is not None and max_width_px is not None:
+        if width < min_width_px or width > max_width_px:
+            return None  # Width out of realistic range
+
+    return (left_edge_x, right_edge_x, left_strength, right_strength)
+
+
+# =============================================================================
+# Main Functions
+# =============================================================================
+
+def extract_ring_zone_roi(
+    image: np.ndarray,
+    axis_data: Dict[str, Any],
+    zone_data: Dict[str, Any],
+    rotate_align: bool = False
+) -> Dict[str, Any]:
+    """
+    Extract ROI around ring zone.
+
+    The ROI is sized from the zone length (|DIP - PIP|): 1.5x wide, 0.5x tall,
+    centered on the ring zone center. This scales naturally with camera
+    distance since it's derived from anatomical landmarks.
+
+    Args:
+        image: Input BGR image
+        axis_data: Output from estimate_finger_axis()
+        zone_data: Output from localize_ring_zone()
+        rotate_align: If True, rotate ROI so finger axis is vertical
+
+    Returns:
+        Dictionary containing:
+        - roi_image: Extracted ROI (grayscale)
+        - roi_mask: Full ROI mask (all 255)
+        - roi_bounds: (x_min, y_min, x_max, y_max) in original image
+        - transform_matrix: 3x3 matrix to map ROI coords -> original coords
+        - inverse_transform: 3x3 matrix to map original -> ROI coords
+        - rotation_angle: Rotation angle applied (degrees)
+        - roi_width: ROI width in pixels
+        - roi_height: ROI height in pixels
+    """
+    h, w = image.shape[:2]
+
+    # ROI centered on ring zone center, sized from |DIP - PIP| distance:
+    #   height = 0.5x zone length (along finger axis)
+    #   width  = 1.5x zone length (perpendicular, wider to capture full finger edges)
+    zone_length = zone_data["length"]
+    center = zone_data["center_point"]
+    direction = axis_data["direction"]
+    half_height = zone_length * 0.25 # 0.5x / 2
+    half_width = zone_length * 0.6  # 1.5x / 2
+
+    x_min = int(np.clip(center[0] - half_width, 0, w - 1))
+    x_max = int(np.clip(center[0] + half_width, 0, w - 1))
+    y_min = int(np.clip(center[1] - half_height, 0, h - 1))
+    y_max = int(np.clip(center[1] + half_height, 0, h - 1))
+
+    roi_width = x_max - x_min
+    roi_height = y_max - y_min
+
+    if roi_width < 10 or roi_height < 10:
+        raise ValueError(f"ROI too small: {roi_width}x{roi_height}")
+
+    # Extract ROI
+    roi_bgr = image[y_min:y_max, x_min:x_max].copy()
+
+    # Convert to grayscale for edge detection
+    roi_gray = cv2.cvtColor(roi_bgr, cv2.COLOR_BGR2GRAY)
+
+    # Full ROI mask — the ROI rectangle itself is the search constraint
+    roi_mask = np.ones((roi_height, roi_width), dtype=np.uint8) * 255
+
+    # Create transform matrix (ROI coords -> original coords)
+    # Simple translation for non-rotated case
+    transform = np.eye(3, dtype=np.float32)
+    transform[0, 2] = x_min  # Translation in x
+    transform[1, 2] = y_min  # Translation in y
+
+    inverse_transform = np.linalg.inv(transform)
+
+    rotation_angle = 0.0
+
+    # Optional rotation alignment
+    if rotate_align:
+        # Calculate rotation angle to make finger vertical
+        # Finger direction -> make it point upward (0, -1)
+        # Current direction is (dx, dy), want to rotate to (0, -1)
+        rotation_angle = np.degrees(np.arctan2(-direction[0], direction[1]))
+
+        # Get rotation matrix
+        roi_center = (roi_width / 2.0, roi_height / 2.0)
+        rotation_matrix = cv2.getRotationMatrix2D(roi_center, rotation_angle, 1.0)
+
+        # Rotate ROI
+        roi_gray = cv2.warpAffine(
+            roi_gray, rotation_matrix, (roi_width, roi_height),
+            flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_REPLICATE
+        )
+
+        # Update transform matrices
+        # Rotation matrix is 2x3, convert to 3x3 for composition
+        rotation_matrix_3x3 = np.eye(3, dtype=np.float32)
+        rotation_matrix_3x3[:2, :] = rotation_matrix
+
+        # Compose: translate then rotate
+        transform = np.dot(rotation_matrix_3x3, transform)
+        inverse_transform = np.linalg.inv(transform)
+
+    # Convert axis center point and direction to ROI coordinates
+    axis_center = axis_data.get("center", center)
+    roi_offset = np.array([x_min, y_min], dtype=np.float32)
+    axis_center_in_roi = axis_center - roi_offset
+
+    # Direction vector stays the same (it's not affected by translation)
+    axis_direction_in_roi = direction.copy()
+
+    zone_start = zone_data["start_point"]
+    zone_end = zone_data["end_point"]
+
+    return {
+        "roi_image": roi_gray,
+        "roi_mask": roi_mask,
+        "roi_bgr": roi_bgr,  # Keep BGR for debug visualization
+        "roi_bounds": (x_min, y_min, x_max, y_max),
+        "transform_matrix": transform,
+        "inverse_transform": inverse_transform,
+        "rotation_angle": rotation_angle,
+        "roi_width": roi_width,
+        "roi_height": roi_height,
+        "zone_start_in_roi": zone_start - roi_offset,
+        "zone_end_in_roi": zone_end - roi_offset,
+        "axis_center_in_roi": axis_center_in_roi,
+        "axis_direction_in_roi": axis_direction_in_roi,
+    }
+
+
+def apply_sobel_filters(
+    roi_image: np.ndarray,
+    kernel_size: int = DEFAULT_KERNEL_SIZE,
+    axis_direction: str = "auto"
+) -> Dict[str, Any]:
+    """
+    Apply bidirectional Sobel filters to detect edges.
+
+    For vertical finger (axis_direction="vertical"):
+    - Use horizontal Sobel kernels (detect left/right edges)
+
+    For horizontal finger (axis_direction="horizontal"):
+    - Use vertical Sobel kernels (detect top/bottom edges)
+
+    Auto mode detects orientation from ROI aspect ratio.
+
+    Args:
+        roi_image: Grayscale ROI image
+        kernel_size: Sobel kernel size (3, 5, or 7)
+        axis_direction: Finger axis direction ("auto", "vertical", "horizontal")
+
+    Returns:
+        Dictionary containing:
+        - gradient_x: Horizontal gradient (Sobel X)
+        - gradient_y: Vertical gradient (Sobel Y)
+        - gradient_left_to_right: Positive X-gradient map (right-half gated in horizontal mode)
+        - gradient_right_to_left: Negative X-gradient map (left-half gated in horizontal mode)
+        - gradient_magnitude: Combined gradient magnitude
+        - gradient_direction: Edge orientation (radians)
+        - kernel_size: Kernel size used
+        - filter_orientation: "horizontal" or "vertical"
+    """
+    if kernel_size not in VALID_KERNEL_SIZES:
+        raise ValueError(f"Invalid kernel_size: {kernel_size}. Use {VALID_KERNEL_SIZES}")
+
+    h, w = roi_image.shape
+
+    # Determine filter orientation
+    if axis_direction == "auto":
+        # After rotation normalization, finger is always vertical (upright)
+        # Finger runs vertically → detect left/right edges → use horizontal filter
+        #
+        # NOTE: ROI aspect ratio is NOT reliable after rotation normalization!
+        # The ROI may be wider than tall even when finger is vertical.
+        # Always use horizontal filter orientation for upright hands.
+        filter_orientation = "horizontal"  # Detect left/right edges for vertical finger
+    elif axis_direction == "vertical":
+        filter_orientation = "horizontal"
+    elif axis_direction == "horizontal":
+        filter_orientation = "vertical"
+    else:
+        raise ValueError(f"Invalid axis_direction: {axis_direction}")
+
+    # Apply Sobel filters
+    # Sobel X detects vertical edges (left/right boundaries)
+    # Sobel Y detects horizontal edges (top/bottom boundaries)
+
+    # Use cv2.Sobel for standard implementation
+    grad_x = cv2.Sobel(roi_image, cv2.CV_64F, 1, 0, ksize=kernel_size)
+    grad_y = cv2.Sobel(roi_image, cv2.CV_64F, 0, 1, ksize=kernel_size)
+
+    # Directional Sobel responses along X:
+    # - left_to_right: rising intensity while moving left -> right
+    # - right_to_left: falling intensity while moving left -> right
+    gradient_left_to_right = np.maximum(grad_x, 0.0)
+    gradient_right_to_left = np.maximum(-grad_x, 0.0)
+
+    # Spatial gating to reduce nearby non-target finger interference:
+    # - left_to_right only on ROI right half
+    # - right_to_left only on ROI left half
+    roi_split_x = w // 2
+    if filter_orientation == "horizontal":
+        gradient_left_to_right[:, :roi_split_x] = 0.0
+        gradient_right_to_left[:, roi_split_x:] = 0.0
+        gradient_magnitude = np.sqrt(gradient_left_to_right**2 + gradient_right_to_left**2)
+    else:
+        # Vertical mode fallback keeps the original behavior.
+        gradient_magnitude = np.sqrt(grad_x**2 + grad_y**2)
+
+    # Calculate gradient direction (angle)
+    gradient_direction = np.arctan2(grad_y, grad_x)
+
+    # Normalize gradients to 0-255 for visualization
+    grad_x_normalized = np.clip(np.abs(grad_x), 0, 255).astype(np.uint8)
+    grad_y_normalized = np.clip(np.abs(grad_y), 0, 255).astype(np.uint8)
+    grad_mag_normalized = np.clip(gradient_magnitude, 0, 255).astype(np.uint8)
+    grad_l2r_normalized = np.clip(gradient_left_to_right, 0, 255).astype(np.uint8)
+    grad_r2l_normalized = np.clip(gradient_right_to_left, 0, 255).astype(np.uint8)
+
+    return {
+        "gradient_x": grad_x,
+        "gradient_y": grad_y,
+        "gradient_left_to_right": gradient_left_to_right,
+        "gradient_right_to_left": gradient_right_to_left,
+        "gradient_magnitude": gradient_magnitude,
+        "gradient_direction": gradient_direction,
+        "gradient_x_normalized": grad_x_normalized,
+        "gradient_y_normalized": grad_y_normalized,
+        "gradient_left_to_right_normalized": grad_l2r_normalized,
+        "gradient_right_to_left_normalized": grad_r2l_normalized,
+        "gradient_mag_normalized": grad_mag_normalized,
+        "kernel_size": kernel_size,
+        "filter_orientation": filter_orientation,
+        "roi_split_x": roi_split_x,
+    }
+
+
+def detect_edges_per_row(
+    gradient_data: Dict[str, Any],
+    roi_data: Dict[str, Any],
+    threshold: float = DEFAULT_GRADIENT_THRESHOLD,
+    expected_width_px: Optional[float] = None,
+    scale_px_per_cm: Optional[float] = None
+) -> Dict[str, Any]:
+    """
+    Detect left and right finger edges for each row (cross-section).
+
+    Uses mask-constrained mode when roi_mask is available:
+    1. Find leftmost/rightmost mask pixels (anatomical finger boundaries)
+    2. Search for gradient peaks within ±10px of mask boundaries
+    3. Combines anatomical accuracy with sub-pixel gradient precision
+
+    Falls back to axis-expansion mode when no mask:
+    1. Start at finger axis (guaranteed inside finger)
+    2. Expand left/right to find nearest salient edges
+    3. Validate width is within realistic range
+
+    Args:
+        gradient_data: Output from apply_sobel_filters()
+        roi_data: Output from extract_ring_zone_roi()
+        threshold: Minimum gradient magnitude for valid edge
+        expected_width_px: Expected finger width from contour (optional)
+        scale_px_per_cm: Scale factor for width validation (optional)
+
+    Returns:
+        Dictionary containing:
+        - left_edges: Array of left edge x-coordinates (one per row)
+        - right_edges: Array of right edge x-coordinates (one per row)
+        - edge_strengths_left: Gradient magnitude at left edges
+        - edge_strengths_right: Gradient magnitude at right edges
+        - valid_rows: Boolean mask of rows with successful detection
+        - num_valid_rows: Count of successful detections
+        - mode_used: "mask_constrained" or "axis_expansion"
+    """
+    gradient_magnitude = gradient_data["gradient_magnitude"]
+    gradient_left_to_right = gradient_data.get("gradient_left_to_right")
+    gradient_right_to_left = gradient_data.get("gradient_right_to_left")
+    filter_orientation = gradient_data["filter_orientation"]
+
+    h, w = gradient_magnitude.shape
+
+    # Calculate realistic finger width range in pixels
+    min_width_px = None
+    max_width_px = None
+    if scale_px_per_cm is not None:
+        min_width_px = MIN_FINGER_WIDTH_CM * scale_px_per_cm
+        max_width_px = MAX_FINGER_WIDTH_CM * scale_px_per_cm
+        logger.debug(f"Width constraint: {min_width_px:.1f}-{max_width_px:.1f}px ({MIN_FINGER_WIDTH_CM}-{MAX_FINGER_WIDTH_CM}cm)")
+    elif expected_width_px is not None:
+        # Use expected width with tolerance
+        min_width_px = expected_width_px * (1 - WIDTH_TOLERANCE_FACTOR)
+        max_width_px = expected_width_px * (1 + WIDTH_TOLERANCE_FACTOR)
+        logger.debug(f"Width constraint: {min_width_px:.1f}-{max_width_px:.1f}px (±{WIDTH_TOLERANCE_FACTOR*100}% of expected)")
+    else:
+        logger.debug("No width constraint (scale and expected width both None)")
+
+    # Get axis information - this is our strong anchor point (INSIDE the finger)
+    axis_center = roi_data.get("axis_center_in_roi")
+    axis_direction = roi_data.get("axis_direction_in_roi")
+    zone_start = roi_data.get("zone_start_in_roi")
+    zone_end = roi_data.get("zone_end_in_roi")
+
+    # Get finger mask for constrained edge detection (if available)
+    roi_mask = roi_data.get("roi_mask")
+    mode_used = "mask_constrained" if roi_mask is not None else "axis_expansion"
+
+    if roi_mask is not None:
+        logger.debug(f"Using MASK-CONSTRAINED edge detection (mask shape: {roi_mask.shape})")
+    else:
+        logger.debug("Using AXIS-EXPANSION edge detection (no mask available)")
+
+    # For horizontal filter orientation (detecting left/right edges)
+    # Process each row to find left and right edges
+    if filter_orientation == "horizontal":
+        num_rows = h
+        left_edges = np.full(num_rows, -1.0, dtype=np.float32)
+        right_edges = np.full(num_rows, -1.0, dtype=np.float32)
+        edge_strengths_left = np.zeros(num_rows, dtype=np.float32)
+        edge_strengths_right = np.zeros(num_rows, dtype=np.float32)
+        valid_rows = np.zeros(num_rows, dtype=bool)
+
+        for row in range(num_rows):
+            # Get axis position (our anchor point INSIDE the finger)
+            axis_x = _get_axis_x_at_row(row, axis_center, axis_direction, w)
+
+            # Get gradient for this row
+            row_gradient = gradient_magnitude[row, :]
+            row_gradient_l2r = gradient_left_to_right[row, :] if gradient_left_to_right is not None else None
+            row_gradient_r2l = gradient_right_to_left[row, :] if gradient_right_to_left is not None else None
+
+            # Get mask for this row (if available)
+            row_mask = roi_mask[row, :] if roi_mask is not None else None
+
+            # Find edges using mask-constrained or axis-expansion method
+            result = _find_edges_from_axis(row_gradient, row, axis_x, threshold,
+                                          min_width_px, max_width_px, row_mask,
+                                          row_gradient_left_to_right=row_gradient_l2r,
+                                          row_gradient_right_to_left=row_gradient_r2l)
+
+            if result is None:
+                continue  # No valid edges found
+
+            left_edge_x, right_edge_x, left_strength, right_strength = result
+
+            # Mark as valid
+            left_edges[row] = float(left_edge_x)
+            right_edges[row] = float(right_edge_x)
+            edge_strengths_left[row] = left_strength
+            edge_strengths_right[row] = right_strength
+            valid_rows[row] = True
+
+    else:
+        # Vertical filter orientation (detecting top/bottom edges)
+        # Process each column
+        num_cols = w
+        left_edges = np.full(num_cols, -1.0, dtype=np.float32)
+        right_edges = np.full(num_cols, -1.0, dtype=np.float32)
+        edge_strengths_left = np.zeros(num_cols, dtype=np.float32)
+        edge_strengths_right = np.zeros(num_cols, dtype=np.float32)
+        valid_rows = np.zeros(num_cols, dtype=bool)
+
+        roi_center_y = h / 2.0
+
+        for col in range(num_cols):
+            col_gradient = gradient_magnitude[:, col]
+
+            strong_edges = np.where(col_gradient > threshold)[0]
+
+            if len(strong_edges) < 2:
+                continue
+
+            top_candidates = strong_edges[strong_edges < roi_center_y]
+            bottom_candidates = strong_edges[strong_edges >= roi_center_y]
+
+            if len(top_candidates) == 0 or len(bottom_candidates) == 0:
+                continue
+
+            # Select edges closest to center (finger boundaries)
+            top_edge_y = top_candidates[-1]  # Bottommost of top candidates
+            bottom_edge_y = bottom_candidates[0]  # Topmost of bottom candidates
+
+            top_strength = col_gradient[top_edge_y]
+            bottom_strength = col_gradient[bottom_edge_y]
+
+            height = bottom_edge_y - top_edge_y
+
+            if expected_width_px is not None:
+                if height < expected_width_px * 0.5 or height > expected_width_px * 1.5:
+                    continue
+
+            left_edges[col] = float(top_edge_y)
+            right_edges[col] = float(bottom_edge_y)
+            edge_strengths_left[col] = top_strength
+            edge_strengths_right[col] = bottom_strength
+            valid_rows[col] = True
+
+    num_valid = np.sum(valid_rows)
+
+    return {
+        "left_edges": left_edges,
+        "right_edges": right_edges,
+        "edge_strengths_left": edge_strengths_left,
+        "edge_strengths_right": edge_strengths_right,
+        "valid_rows": valid_rows,
+        "num_valid_rows": int(num_valid),
+        "filter_orientation": filter_orientation,
+        "mode_used": mode_used,  # "mask_constrained" or "axis_expansion"
+    }
+
+
+def refine_edge_subpixel(
+    gradient_magnitude: np.ndarray,
+    edge_positions: np.ndarray,
+    valid_mask: np.ndarray,
+    method: str = "parabola"
+) -> np.ndarray:
+    """
+    Refine edge positions to sub-pixel precision.
+
+    Uses parabola fitting on gradient magnitude to find peak position
+    with <0.5 pixel accuracy.
+
+    Args:
+        gradient_magnitude: 2D gradient magnitude array
+        edge_positions: Integer edge positions (one per row/col)
+        valid_mask: Boolean mask indicating which positions are valid
+        method: Refinement method ("parabola" or "gaussian")
+
+    Returns:
+        Refined edge positions (float, sub-pixel precision)
+    """
+    refined_positions = edge_positions.copy()
+
+    if method == "parabola":
+        # Parabola fitting: fit f(x) = ax^2 + bx + c to 3 points
+        # Peak at x = -b/(2a)
+
+        for i in range(len(edge_positions)):
+            if not valid_mask[i]:
+                continue
+
+            edge_pos = int(edge_positions[i])
+
+            # Get gradient magnitude at edge and neighbors
+            # Handle edge cases (pun intended)
+            if edge_pos <= 0 or edge_pos >= gradient_magnitude.shape[1] - 1:
+                continue  # Can't refine at image boundaries
+
+            # For horizontal orientation (row-wise edge detection)
+            if len(gradient_magnitude.shape) == 2 and i < gradient_magnitude.shape[0]:
+                # Sample gradient at x-1, x, x+1
+                x_minus = edge_pos - 1
+                x_center = edge_pos
+                x_plus = edge_pos + 1
+
+                g_minus = gradient_magnitude[i, x_minus]
+                g_center = gradient_magnitude[i, x_center]
+                g_plus = gradient_magnitude[i, x_plus]
+
+                # Fit parabola: f(x) = ax^2 + bx + c
+                # Using x = -1, 0, 1 for simplicity
+                # f(-1) = a - b + c = g_minus
+                # f(0) = c = g_center
+                # f(1) = a + b + c = g_plus
+
+                c = g_center
+                a = (g_plus + g_minus - 2 * c) / 2.0
+                b = (g_plus - g_minus) / 2.0
+
+                # Peak at x_peak = -b/(2a)
+                if abs(a) > MIN_PARABOLA_DENOMINATOR:  # Avoid division by zero
+                    x_peak = -b / (2.0 * a)
+
+                    # Constrain to reasonable range
+                    if abs(x_peak) <= MAX_SUBPIXEL_OFFSET:
+                        refined_positions[i] = edge_pos + x_peak
+
+    elif method == "gaussian":
+        # Gaussian fitting (more complex, not implemented yet)
+        # Would fit Gaussian to 5-pixel window
+        # For now, fall back to parabola
+        return refine_edge_subpixel(gradient_magnitude, edge_positions, valid_mask, method="parabola")
+
+    else:
+        raise ValueError(f"Unknown refinement method: {method}")
+
+    return refined_positions
+
+
+def measure_width_from_edges(
+    edge_data: Dict[str, Any],
+    roi_data: Dict[str, Any],
+    scale_px_per_cm: float,
+    gradient_data: Optional[Dict[str, Any]] = None,
+    use_subpixel: bool = True
+) -> Dict[str, Any]:
+    """
+    Compute finger width from detected edges.
+
+    Steps:
+    1. Apply sub-pixel refinement if gradient data available
+    2. Calculate width for each valid row: width_px = right_edge - left_edge
+    3. Filter outliers (>3 MAD from median)
+    4. Compute statistics (median, mean, std)
+    5. Convert width from pixels to cm
+
+    Args:
+        edge_data: Output from detect_edges_per_row()
+        roi_data: Output from extract_ring_zone_roi()
+        scale_px_per_cm: Pixels per cm from card detection
+        gradient_data: Optional gradient data for sub-pixel refinement
+        use_subpixel: Enable sub-pixel refinement (default True)
+
+    Returns:
+        Dictionary containing:
+        - widths_px: Array of width measurements (pixels)
+        - median_width_px: Median width in pixels
+        - median_width_cm: Median width in cm (final measurement)
+        - mean_width_px: Mean width in pixels
+        - std_width_px: Standard deviation of widths
+        - num_samples: Number of valid width measurements
+        - outliers_removed: Number of outliers filtered
+        - subpixel_refinement_used: Whether sub-pixel refinement was applied
+    """
+    left_edges = edge_data["left_edges"].copy()
+    right_edges = edge_data["right_edges"].copy()
+    valid_rows = edge_data["valid_rows"]
+
+    # Apply sub-pixel refinement if available
+    subpixel_used = False
+    if use_subpixel and gradient_data is not None:
+        try:
+            gradient_magnitude = gradient_data["gradient_magnitude"]
+
+            # Refine left edges
+            left_edges = refine_edge_subpixel(
+                gradient_magnitude, left_edges, valid_rows, method="parabola"
+            )
+
+            # Refine right edges
+            right_edges = refine_edge_subpixel(
+                gradient_magnitude, right_edges, valid_rows, method="parabola"
+            )
+
+            subpixel_used = True
+        except Exception as e:
+            logger.warning(f"Sub-pixel refinement failed: {e}, using integer positions")
+            # Fall back to integer positions
+            left_edges = edge_data["left_edges"]
+            right_edges = edge_data["right_edges"]
+
+    # Calculate widths for valid rows
+    widths_px = []
+    for i in range(len(valid_rows)):
+        if valid_rows[i]:
+            width = right_edges[i] - left_edges[i]
+            if width > 0:
+                widths_px.append(width)
+
+    if len(widths_px) == 0:
+        raise ValueError("No valid width measurements found")
+
+    widths_px = np.array(widths_px)
+
+    # Filter outliers using median absolute deviation (MAD)
+    median = np.median(widths_px)
+    mad = np.median(np.abs(widths_px - median))
+
+    # Outliers are >3 MAD from median (more robust than std dev)
+    if mad > 0:
+        is_outlier = np.abs(widths_px - median) > (MAD_OUTLIER_THRESHOLD * mad)
+        widths_filtered = widths_px[~is_outlier]
+        outliers_removed = np.sum(is_outlier)
+    else:
+        widths_filtered = widths_px
+        outliers_removed = 0
+
+    if len(widths_filtered) == 0:
+        # All measurements were outliers, use original
+        widths_filtered = widths_px
+        outliers_removed = 0
+
+    # Calculate statistics
+    median_width_px = float(np.median(widths_filtered))
+    mean_width_px = float(np.mean(widths_filtered))
+    std_width_px = float(np.std(widths_filtered))
+
+    # Convert to cm
+    median_width_cm = median_width_px / scale_px_per_cm
+
+    # Log measurements
+    logger.debug(f"Raw median width: {median_width_px:.2f}px, scale: {scale_px_per_cm:.2f} px/cm → {median_width_cm:.4f}cm")
+    logger.debug(f"Width range: {np.min(widths_filtered):.1f}-{np.max(widths_filtered):.1f}px, std: {std_width_px:.1f}px")
+
+    return {
+        "widths_px": widths_filtered.tolist(),
+        "median_width_px": median_width_px,
+        "median_width_cm": median_width_cm,
+        "mean_width_px": mean_width_px,
+        "std_width_px": std_width_px,
+        "num_samples": len(widths_filtered),
+        "outliers_removed": int(outliers_removed),
+        "subpixel_refinement_used": subpixel_used,
+    }
+
+
+def compute_edge_quality_score(
+    gradient_data: Dict[str, Any],
+    edge_data: Dict[str, Any],
+    width_data: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Assess quality of edge detection for confidence scoring.
+
+    Computes 4 quality metrics:
+    1. Gradient strength: Average gradient magnitude at detected edges
+    2. Edge consistency: Percentage of rows with valid edge pairs
+    3. Edge smoothness: Variance of edge positions along finger
+    4. Bilateral symmetry: Correlation between left/right edge quality
+
+    Args:
+        gradient_data: Output from apply_sobel_filters()
+        edge_data: Output from detect_edges_per_row()
+        width_data: Output from measure_width_from_edges()
+
+    Returns:
+        Dictionary containing:
+        - overall_score: Weighted average (0-1)
+        - gradient_strength_score: Gradient strength metric (0-1)
+        - consistency_score: Edge detection success rate (0-1)
+        - smoothness_score: Edge position smoothness (0-1)
+        - symmetry_score: Left/right balance (0-1)
+        - metrics: Dict with raw metric values
+    """
+    gradient_magnitude = gradient_data["gradient_magnitude"]
+    left_edges = edge_data["left_edges"]
+    right_edges = edge_data["right_edges"]
+    valid_rows = edge_data["valid_rows"]
+    edge_strengths_left = edge_data["edge_strengths_left"]
+    edge_strengths_right = edge_data["edge_strengths_right"]
+
+    # Metric 1: Gradient Strength
+    # Average gradient magnitude at detected edges, normalized
+    valid_left_strengths = edge_strengths_left[valid_rows]
+    valid_right_strengths = edge_strengths_right[valid_rows]
+
+    if len(valid_left_strengths) > 0:
+        avg_gradient_strength = (np.mean(valid_left_strengths) + np.mean(valid_right_strengths)) / 2.0
+        # Normalize: typical strong edge is 20-50, weak is <10
+        gradient_strength_score = min(avg_gradient_strength / GRADIENT_STRENGTH_NORMALIZER, 1.0)
+    else:
+        avg_gradient_strength = 0.0
+        gradient_strength_score = 0.0
+
+    # Metric 2: Edge Consistency
+    # Percentage of rows with valid edge pairs
+    total_rows = len(valid_rows)
+    num_valid = np.sum(valid_rows)
+    consistency_score = num_valid / total_rows if total_rows > 0 else 0.0
+
+    # Metric 3: Edge Smoothness
+    # Measure variance of edge positions (smoother = better)
+    # Lower variance = higher score
+    if num_valid > 1:
+        # Calculate variance of left and right edges separately
+        valid_left = left_edges[valid_rows]
+        valid_right = right_edges[valid_rows]
+
+        left_variance = np.var(valid_left)
+        right_variance = np.var(valid_right)
+        avg_variance = (left_variance + right_variance) / 2.0
+
+        # Normalize: typical finger has variance <100, noisy edges >500
+        smoothness_score = np.exp(-avg_variance / SMOOTHNESS_VARIANCE_NORMALIZER)
+    else:
+        avg_variance = 0.0
+        smoothness_score = 0.0
+
+    # Metric 4: Bilateral Symmetry
+    # Correlation between left and right edge quality (strength balance)
+    if len(valid_left_strengths) > 1:
+        # Calculate ratio of average strengths
+        avg_left = np.mean(valid_left_strengths)
+        avg_right = np.mean(valid_right_strengths)
+
+        if avg_left > 0 and avg_right > 0:
+            # Symmetric ratio close to 1.0 is good
+            ratio = min(avg_left, avg_right) / max(avg_left, avg_right)
+            symmetry_score = ratio  # Already 0-1
+        else:
+            symmetry_score = 0.0
+    else:
+        symmetry_score = 0.0
+
+    # Weighted overall score
+    overall_score = (
+        QUALITY_WEIGHT_GRADIENT * gradient_strength_score +
+        QUALITY_WEIGHT_CONSISTENCY * consistency_score +
+        QUALITY_WEIGHT_SMOOTHNESS * smoothness_score +
+        QUALITY_WEIGHT_SYMMETRY * symmetry_score
+    )
+
+    return {
+        "overall_score": float(overall_score),
+        "gradient_strength_score": float(gradient_strength_score),
+        "consistency_score": float(consistency_score),
+        "smoothness_score": float(smoothness_score),
+        "symmetry_score": float(symmetry_score),
+        "metrics": {
+            "avg_gradient_strength": float(avg_gradient_strength),
+            "edge_consistency_pct": float(consistency_score * 100),
+            "avg_variance": float(avg_variance) if num_valid > 1 else 0.0,
+            "left_right_strength_ratio": float(symmetry_score),
+        }
+    }
+
+
+def should_use_sobel_measurement(
+    sobel_result: Dict[str, Any],
+    contour_result: Optional[Dict[str, Any]] = None,
+    min_quality_score: float = MIN_QUALITY_SCORE_THRESHOLD,
+    min_consistency: float = MIN_CONSISTENCY_THRESHOLD,
+    max_difference_pct: float = MAX_CONTOUR_DIFFERENCE_PCT
+) -> Tuple[bool, str]:
+    """
+    Decide whether to use Sobel measurement or fall back to contour.
+
+    Decision criteria:
+    1. Edge quality score > min_quality_score (default 0.7)
+    2. Edge consistency > min_consistency (default 0.5 = 50%)
+    3. If contour available: Sobel and contour agree within max_difference_pct
+
+    Args:
+        sobel_result: Output from refine_edges_sobel()
+        contour_result: Optional output from compute_cross_section_width()
+        min_quality_score: Minimum acceptable quality score
+        min_consistency: Minimum edge detection success rate
+        max_difference_pct: Maximum allowed difference from contour (%)
+
+    Returns:
+        Tuple of (should_use_sobel, reason)
+    """
+    # Check if edge quality data available
+    if "edge_quality" not in sobel_result:
+        return False, "edge_quality_data_missing"
+
+    edge_quality = sobel_result["edge_quality"]
+
+    # Check 1: Overall quality score
+    if edge_quality["overall_score"] < min_quality_score:
+        return False, f"quality_score_low_{edge_quality['overall_score']:.2f}"
+
+    # Check 2: Consistency (success rate)
+    if edge_quality["consistency_score"] < min_consistency:
+        return False, f"consistency_low_{edge_quality['consistency_score']:.2f}"
+
+    # Check 3: Measurement reasonableness
+    sobel_width = sobel_result.get("median_width_cm")
+    if sobel_width is None or sobel_width <= 0:
+        return False, "invalid_measurement"
+
+    # Typical finger width range
+    if sobel_width < MIN_REALISTIC_WIDTH_CM or sobel_width > MAX_REALISTIC_WIDTH_CM:
+        return False, f"unrealistic_width_{sobel_width:.2f}cm"
+
+    # Check 4: Agreement with contour (if available)
+    if contour_result is not None:
+        contour_width = contour_result.get("median_width_px")
+        sobel_width_px = sobel_result.get("median_width_px")
+
+        if contour_width and sobel_width_px:
+            diff_pct = abs(sobel_width_px - contour_width) / contour_width * 100
+
+            if diff_pct > max_difference_pct:
+                return False, f"disagrees_with_contour_{diff_pct:.1f}pct"
+
+    # All checks passed
+    return True, "quality_acceptable"
+
+
+def refine_edges_sobel(
+    image: np.ndarray,
+    axis_data: Dict[str, Any],
+    zone_data: Dict[str, Any],
+    scale_px_per_cm: float,
+    finger_landmarks: Optional[np.ndarray] = None,
+    sobel_threshold: float = DEFAULT_GRADIENT_THRESHOLD,
+    kernel_size: int = DEFAULT_KERNEL_SIZE,
+    rotate_align: bool = False,
+    use_subpixel: bool = True,
+    expected_width_px: Optional[float] = None,
+    debug_dir: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Main entry point for Sobel-based edge refinement.
+
+    Replaces contour-based width measurement with gradient-based edge detection.
+
+    Pipeline:
+    1. Extract ROI around ring zone
+    2. Apply bidirectional Sobel filters
+    3. Detect left/right edges per row
+    4. Measure width from edges
+    5. Convert to cm and return measurement
+
+    Args:
+        image: Input BGR image
+        axis_data: Output from estimate_finger_axis()
+        zone_data: Output from localize_ring_zone()
+        scale_px_per_cm: Pixels per cm from card detection
+        finger_landmarks: Optional 4x2 array of finger landmarks for debug
+        sobel_threshold: Minimum gradient magnitude for valid edge
+        kernel_size: Sobel kernel size (3, 5, or 7)
+        rotate_align: Rotate ROI for vertical finger alignment
+        use_subpixel: Enable sub-pixel edge localization
+        expected_width_px: Expected width for validation (optional)
+        debug_dir: Directory to save debug visualizations (None to skip)
+
+    Returns:
+        Dictionary containing:
+        - median_width_cm: Final measurement in cm
+        - median_width_px: Measurement in pixels
+        - std_width_px: Standard deviation
+        - num_samples: Number of valid measurements
+        - edge_detection_success_rate: % of rows with valid edges
+        - roi_data: ROI extraction data
+        - gradient_data: Sobel filter data
+        - edge_data: Edge detection data
+        - method: "sobel"
+    """
+    # Initialize debug observer if debug_dir provided
+    if debug_dir:
+        from src.debug_observer import DebugObserver, draw_landmark_axis, draw_ring_zone_roi
+        from src.debug_observer import draw_roi_extraction, draw_gradient_visualization
+        from src.debug_observer import draw_edge_candidates, draw_filtered_edge_candidates
+        from src.debug_observer import draw_selected_edges
+        from src.debug_observer import draw_width_measurements, draw_outlier_detection
+        from src.debug_observer import draw_comprehensive_edge_overlay
+        observer = DebugObserver(debug_dir)
+
+    # Stage A: Axis & Zone Visualization
+    if debug_dir:
+        # A.1: Landmark axis
+        observer.draw_and_save("01_landmark_axis", image, draw_landmark_axis, axis_data, finger_landmarks)
+
+        # A.2: Ring zone + ROI bounds (need to extract bounds first)
+        # We'll save this after ROI extraction
+
+    # Step 1: Extract ROI
+    roi_data = extract_ring_zone_roi(
+        image, axis_data, zone_data,
+        rotate_align=rotate_align
+    )
+
+    logger.debug(f"ROI size: {roi_data['roi_width']}x{roi_data['roi_height']}px")
+    logger.debug(f"ROI bounds: {roi_data['roi_bounds']}")
+
+    if debug_dir:
+        # A.2: Ring zone + ROI bounds
+        roi_bounds = roi_data["roi_bounds"]
+        observer.draw_and_save("02_ring_zone_roi", image, draw_ring_zone_roi, zone_data, roi_bounds)
+
+        # A.3: ROI extraction
+        observer.draw_and_save("03_roi_extraction", roi_data["roi_image"], draw_roi_extraction, roi_data.get("roi_mask"))
+
+    # Step 2: Apply Sobel filters
+    gradient_data = apply_sobel_filters(
+        roi_data["roi_image"],
+        kernel_size=kernel_size,
+        axis_direction="auto"
+    )
+
+    if debug_dir:
+        # Stage B: Sobel Filtering
+        # B.1: Left-to-right gradient
+        grad_left = draw_gradient_visualization(gradient_data["gradient_left_to_right"], cv2.COLORMAP_JET)
+        observer.save_stage("04_sobel_left_to_right", grad_left)
+
+        # B.2: Right-to-left gradient
+        grad_right = draw_gradient_visualization(gradient_data["gradient_right_to_left"], cv2.COLORMAP_JET)
+        observer.save_stage("05_sobel_right_to_left", grad_right)
+
+        # B.3: Gradient magnitude
+        grad_mag = draw_gradient_visualization(gradient_data["gradient_magnitude"], cv2.COLORMAP_HOT)
+        observer.save_stage("06_gradient_magnitude", grad_mag)
+
+    # Step 3: Detect edges per row
+    edge_data = detect_edges_per_row(
+        gradient_data, roi_data,
+        threshold=sobel_threshold,
+        expected_width_px=expected_width_px,
+        scale_px_per_cm=scale_px_per_cm
+    )
+
+    logger.debug(f"Valid rows: {edge_data['num_valid_rows']}/{len(edge_data['valid_rows'])} ({edge_data['num_valid_rows']/len(edge_data['valid_rows'])*100:.1f}%)")
+    if edge_data['num_valid_rows'] > 0:
+        valid_left = edge_data['left_edges'][edge_data['valid_rows']]
+        valid_right = edge_data['right_edges'][edge_data['valid_rows']]
+        logger.debug(f"Left edges range: {np.min(valid_left):.1f}-{np.max(valid_left):.1f}px")
+        logger.debug(f"Right edges range: {np.min(valid_right):.1f}-{np.max(valid_right):.1f}px")
+        widths = valid_right - valid_left
+        logger.debug(f"Raw widths range: {np.min(widths):.1f}-{np.max(widths):.1f}px, median: {np.median(widths):.1f}px")
+
+    if debug_dir:
+        # B.4a: All edge candidates (raw threshold, shows noise)
+        observer.draw_and_save("07a_all_candidates", roi_data["roi_image"],
+                             draw_edge_candidates, gradient_data["gradient_magnitude"], sobel_threshold)
+
+        # B.4b: Filtered edge candidates (spatially-filtered, what algorithm uses)
+        observer.draw_and_save("07b_filtered_candidates", roi_data["roi_image"],
+                             draw_filtered_edge_candidates,
+                             gradient_data["gradient_magnitude"],
+                             sobel_threshold,
+                             roi_data.get("roi_mask"),
+                             roi_data["axis_center_in_roi"],
+                             roi_data["axis_direction_in_roi"])
+
+        # B.5: Selected edges (final detected edges)
+        observer.draw_and_save("09_selected_edges", roi_data["roi_image"], draw_selected_edges, edge_data)
+
+    # Step 4: Measure width from edges (with sub-pixel refinement)
+    width_data = measure_width_from_edges(
+        edge_data, roi_data, scale_px_per_cm,
+        gradient_data=gradient_data,
+        use_subpixel=use_subpixel
+    )
+
+    if debug_dir:
+        # Stage C: Measurement
+        # C.1: Sub-pixel refinement (use selected edges for now)
+        observer.draw_and_save("10_subpixel_refinement", roi_data["roi_image"], draw_selected_edges, edge_data)
+
+        # C.2: Width measurements
+        observer.draw_and_save("11_width_measurements", roi_data["roi_image"],
+                             draw_width_measurements, edge_data, width_data)
+
+        # C.3: Width distribution (histogram - requires matplotlib)
+        try:
+            _save_width_distribution(width_data, debug_dir)
+        except:
+            pass  # Skip if matplotlib not available
+
+        # C.4: Outlier detection
+        observer.draw_and_save("13_outlier_detection", roi_data["roi_image"],
+                             draw_outlier_detection, edge_data, width_data)
+
+        # C.5: Comprehensive edge overlay on full image
+        observer.draw_and_save("14_comprehensive_overlay", image,
+                             draw_comprehensive_edge_overlay,
+                             edge_data, roi_data["roi_bounds"], axis_data, zone_data,
+                             width_data, scale_px_per_cm)
+
+    # Step 5: Compute edge quality score
+    edge_quality = compute_edge_quality_score(
+        gradient_data, edge_data, width_data
+    )
+
+    # Calculate success rate
+    total_rows = len(edge_data["valid_rows"])
+    success_rate = edge_data["num_valid_rows"] / total_rows if total_rows > 0 else 0.0
+
+    # Combine results
+    return {
+        "median_width_cm": width_data["median_width_cm"],
+        "median_width_px": width_data["median_width_px"],
+        "mean_width_px": width_data["mean_width_px"],
+        "std_width_px": width_data["std_width_px"],
+        "num_samples": width_data["num_samples"],
+        "outliers_removed": width_data["outliers_removed"],
+        "subpixel_refinement_used": width_data["subpixel_refinement_used"],
+        "edge_detection_success_rate": success_rate,
+        "edge_quality": edge_quality,
+        "roi_data": roi_data,
+        "gradient_data": gradient_data,
+        "edge_data": edge_data,
+        "width_data": width_data,
+        "method": "sobel",
+    }
+
+
+def _save_width_distribution(width_data: Dict[str, Any], debug_dir: str) -> None:
+    """Helper to save width distribution histogram."""
+    try:
+        import matplotlib
+        matplotlib.use('Agg')
+        import matplotlib.pyplot as plt
+        import os
+    except ImportError:
+        return
+
+    widths_px = width_data.get("widths_px", [])
+    if len(widths_px) == 0:
+        return
+
+    median_width_px = width_data["median_width_px"]
+    mean_width_px = width_data["mean_width_px"]
+
+    # Create histogram
+    fig, ax = plt.subplots(figsize=(10, 6))
+    ax.hist(widths_px, bins=30, color='skyblue', edgecolor='black', alpha=0.7)
+    ax.axvline(median_width_px, color='red', linestyle='--', linewidth=2, label=f'Median: {median_width_px:.1f} px')
+    ax.axvline(mean_width_px, color='orange', linestyle='--', linewidth=2, label=f'Mean: {mean_width_px:.1f} px')
+
+    ax.set_xlabel('Width (pixels)', fontsize=12)
+    ax.set_ylabel('Frequency', fontsize=12)
+    ax.set_title('Distribution of Cross-Section Widths', fontsize=14, fontweight='bold')
+    ax.legend(fontsize=10)
+    ax.grid(True, alpha=0.3)
+
+    # Save
+    output_path = os.path.join(debug_dir, "12_width_distribution.png")
+    plt.savefig(output_path, dpi=150, bbox_inches='tight')
+    plt.close()
+
+
+def compare_edge_methods(
+    contour_result: Dict[str, Any],
+    sobel_result: Dict[str, Any],
+    scale_px_per_cm: float
+) -> Dict[str, Any]:
+    """
+    Compare contour-based and Sobel-based edge detection methods.
+
+    Provides detailed analysis of differences, quality metrics, and
+    recommendation on which method to use.
+
+    Args:
+        contour_result: Output from compute_cross_section_width()
+        sobel_result: Output from refine_edges_sobel()
+        scale_px_per_cm: Scale factor for unit conversion
+
+    Returns:
+        Dictionary containing:
+        - contour: Summary of contour method results
+        - sobel: Summary of Sobel method results
+        - difference: Comparison metrics
+        - recommendation: Which method to use and why
+        - quality_comparison: Quality metrics comparison
+    """
+    # Extract measurements
+    contour_width_cm = contour_result["median_width_px"] / scale_px_per_cm
+    sobel_width_cm = sobel_result["median_width_cm"]
+
+    contour_width_px = contour_result["median_width_px"]
+    sobel_width_px = sobel_result["median_width_px"]
+
+    # Calculate differences
+    diff_cm = sobel_width_cm - contour_width_cm
+    diff_px = sobel_width_px - contour_width_px
+    diff_pct = (diff_cm / contour_width_cm) * 100 if contour_width_cm > 0 else 0.0
+
+    # Quality comparison
+    contour_cv = (contour_result["std_width_px"] / contour_result["median_width_px"]) if contour_result["median_width_px"] > 0 else 0.0
+    sobel_cv = (sobel_result["std_width_px"] / sobel_result["median_width_px"]) if sobel_result["median_width_px"] > 0 else 0.0
+
+    # Determine recommendation
+    should_use_sobel, reason = should_use_sobel_measurement(sobel_result, contour_result)
+
+    # Build summary
+    result = {
+        "contour": {
+            "width_cm": float(contour_width_cm),
+            "width_px": float(contour_width_px),
+            "std_dev_px": float(contour_result["std_width_px"]),
+            "coefficient_variation": float(contour_cv),
+            "num_samples": int(contour_result["num_samples"]),
+            "method": "contour",
+        },
+        "sobel": {
+            "width_cm": float(sobel_width_cm),
+            "width_px": float(sobel_width_px),
+            "std_dev_px": float(sobel_result["std_width_px"]),
+            "coefficient_variation": float(sobel_cv),
+            "num_samples": int(sobel_result["num_samples"]),
+            "subpixel_used": bool(sobel_result["subpixel_refinement_used"]),
+            "success_rate": float(sobel_result["edge_detection_success_rate"]),
+            "edge_quality_score": float(sobel_result["edge_quality"]["overall_score"]),
+            "method": "sobel",
+        },
+        "difference": {
+            "absolute_cm": float(diff_cm),
+            "absolute_px": float(diff_px),
+            "relative_pct": float(diff_pct),
+            "precision_improvement": float(contour_result["std_width_px"] - sobel_result["std_width_px"]),
+        },
+        "recommendation": {
+            "use_sobel": bool(should_use_sobel),
+            "reason": str(reason),
+            "preferred_method": "sobel" if should_use_sobel else "contour",
+        },
+        "quality_comparison": {
+            "contour_cv": float(contour_cv),
+            "sobel_cv": float(sobel_cv),
+            "sobel_quality_score": float(sobel_result["edge_quality"]["overall_score"]),
+            "sobel_gradient_strength": float(sobel_result["edge_quality"]["gradient_strength_score"]),
+            "sobel_consistency": float(sobel_result["edge_quality"]["consistency_score"]),
+            "sobel_smoothness": float(sobel_result["edge_quality"]["smoothness_score"]),
+            "sobel_symmetry": float(sobel_result["edge_quality"]["symmetry_score"]),
+        },
+    }
+
+    return result

src/edge_refinement_constants.py

@@ -0,0 +1,98 @@
+"""
+Constants for Sobel edge refinement algorithm.
+
+This module contains all configurable parameters and thresholds used
+in the edge refinement pipeline to make them easy to tune and maintain.
+"""
+
+# =============================================================================
+# ROI Extraction Constants
+# =============================================================================
+
+# ROI padding around zone for gradient context
+ROI_PADDING_PX = 50
+
+# Finger width estimation factor (conservative to ensure full capture)
+# Typical finger aspect ratio is 3:1 to 5:1 (length:width)
+FINGER_WIDTH_RATIO = 3.0  # length / width
+
+
+# =============================================================================
+# Sobel Filter Constants
+# =============================================================================
+
+# Default Sobel kernel size
+DEFAULT_KERNEL_SIZE = 3
+
+# Valid kernel sizes
+VALID_KERNEL_SIZES = [3, 5, 7]
+
+
+# =============================================================================
+# Edge Detection Constants
+# =============================================================================
+
+# Default gradient threshold for valid edge
+DEFAULT_GRADIENT_THRESHOLD = 15.0
+
+# Realistic finger width range for validation
+# Based on typical adult finger widths across ring sizes
+MIN_FINGER_WIDTH_CM = 1.6  # Size 6 (16mm)
+MAX_FINGER_WIDTH_CM = 2.5  # Size 13 (23mm)
+
+# Tolerance for expected width comparison (when contour available)
+WIDTH_TOLERANCE_FACTOR = 0.25  # ±25%
+
+
+# =============================================================================
+# Sub-Pixel Refinement Constants
+# =============================================================================
+
+# Maximum sub-pixel refinement offset from integer position
+MAX_SUBPIXEL_OFFSET = 0.5  # ±0.5 pixels
+
+# Minimum denominator value to avoid division by zero in parabola fitting
+MIN_PARABOLA_DENOMINATOR = 1e-6
+
+
+# =============================================================================
+# Outlier Filtering Constants
+# =============================================================================
+
+# MAD (Median Absolute Deviation) threshold multiplier
+MAD_OUTLIER_THRESHOLD = 3.0  # Outliers are >3 MAD from median
+
+
+# =============================================================================
+# Edge Quality Scoring Constants
+# =============================================================================
+
+# Gradient strength normalization (typical strong edge magnitude)
+GRADIENT_STRENGTH_NORMALIZER = 30.0
+
+# Smoothness scoring (variance to exponential mapping)
+SMOOTHNESS_VARIANCE_NORMALIZER = 200.0
+
+# Quality score component weights
+QUALITY_WEIGHT_GRADIENT = 0.4  # Gradient strength: 40%
+QUALITY_WEIGHT_CONSISTENCY = 0.3  # Edge consistency: 30%
+QUALITY_WEIGHT_SMOOTHNESS = 0.2  # Edge smoothness: 20%
+QUALITY_WEIGHT_SYMMETRY = 0.1  # Bilateral symmetry: 10%
+
+
+# =============================================================================
+# Auto Fallback Decision Constants
+# =============================================================================
+
+# Minimum quality score to use Sobel (otherwise fall back to contour)
+MIN_QUALITY_SCORE_THRESHOLD = 0.65  # Lowered from 0.7 for mask-constrained mode
+
+# Minimum edge detection success rate
+MIN_CONSISTENCY_THRESHOLD = 0.30  # 30% (lowered from 50% for mask-constrained mode)
+
+# Realistic measurement range for validation
+MIN_REALISTIC_WIDTH_CM = 0.8
+MAX_REALISTIC_WIDTH_CM = 3.5
+
+# Maximum allowed difference from contour measurement (percentage)
+MAX_CONTOUR_DIFFERENCE_PCT = 50.0

src/finger_segmentation.py

@@ -0,0 +1,949 @@
+"""
+Hand and finger segmentation utilities.
+
+This module handles:
+- Hand detection using MediaPipe
+- Hand mask generation
+- Individual finger isolation
+- Mask cleanup and validation
+"""
+
+import cv2
+import numpy as np
+from typing import Optional, Dict, Any, Literal, List, Tuple
+import mediapipe as mp
+from mediapipe.tasks import python
+from mediapipe.tasks.python import vision
+import urllib.request
+import os
+from pathlib import Path
+
+# Import debug observer and drawing functions
+from src.debug_observer import (
+    DebugObserver,
+    draw_landmarks_overlay,
+    draw_hand_skeleton,
+    draw_detection_info,
+)
+
+FingerIndex = Literal["auto", "index", "middle", "ring", "pinky"]
+
+# MediaPipe hand landmark indices for each finger
+# Each finger has 4 landmarks: MCP (knuckle), PIP, DIP, TIP
+FINGER_LANDMARKS = {
+    "index": [5, 6, 7, 8],
+    "middle": [9, 10, 11, 12],
+    "ring": [13, 14, 15, 16],
+    "pinky": [17, 18, 19, 20],
+}
+
+# Thumb landmarks (special case - not typically used for ring measurement)
+THUMB_LANDMARKS = [1, 2, 3, 4]
+
+# Wrist landmark
+WRIST_LANDMARK = 0
+
+# Palm landmarks (for creating hand mask)
+PALM_LANDMARKS = [0, 1, 5, 9, 13, 17]
+
+# Model path
+MODEL_PATH = os.path.join(os.path.dirname(__file__), "..", ".model", "hand_landmarker.task")
+MODEL_URL = "https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task"
+
+# Initialize MediaPipe Hands (lazy loading)
+_hands_detector = None
+
+
+def _download_model():
+    """Download the hand landmarker model if not present."""
+    if not os.path.exists(MODEL_PATH):
+        os.makedirs(os.path.dirname(MODEL_PATH), exist_ok=True)
+        print(f"Downloading hand landmarker model...")
+        urllib.request.urlretrieve(MODEL_URL, MODEL_PATH)
+        print(f"Model downloaded to {MODEL_PATH}")
+
+
+def _get_hands_detector(force_new: bool = False):
+    """Get or initialize the MediaPipe Hands detector."""
+    global _hands_detector
+    if _hands_detector is None or force_new:
+        _download_model()
+        base_options = python.BaseOptions(model_asset_path=MODEL_PATH)
+        options = vision.HandLandmarkerOptions(
+            base_options=base_options,
+            num_hands=2,
+            min_hand_detection_confidence=0.3,  # Lower threshold for better detection
+            min_tracking_confidence=0.3,
+        )
+        _hands_detector = vision.HandLandmarker.create_from_options(options)
+    return _hands_detector
+
+
+def _try_detect_hand(detector, image: np.ndarray) -> Optional[Tuple[Any, int]]:
+    """
+    Try to detect hand in image, returns (results, rotation_code) or None.
+    rotation_code: 0=none, 1=90cw, 2=180, 3=90ccw
+    """
+    # Try different rotations to handle various image orientations
+    rotations = [
+        (image, 0),
+        (cv2.rotate(image, cv2.ROTATE_90_CLOCKWISE), 1),
+        (cv2.rotate(image, cv2.ROTATE_90_COUNTERCLOCKWISE), 3),
+        (cv2.rotate(image, cv2.ROTATE_180), 2),
+    ]
+
+    best_result = None
+    best_confidence = 0
+    best_rotation = 0
+
+    for rotated, rot_code in rotations:
+        # Convert to RGB and ensure contiguous memory layout
+        rgb = cv2.cvtColor(rotated, cv2.COLOR_BGR2RGB)
+        rgb = np.ascontiguousarray(rgb)
+        mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb)
+        results = detector.detect(mp_image)
+
+        if results.hand_landmarks:
+            # Get best confidence among detected hands
+            for i, handedness in enumerate(results.handedness):
+                conf = handedness[0].score
+                if conf > best_confidence:
+                    best_confidence = conf
+                    best_result = results
+                    best_rotation = rot_code
+
+    if best_result is None:
+        return None
+
+    return best_result, best_rotation
+
+
+def _transform_landmarks_for_rotation(
+    landmarks: np.ndarray,
+    rotation_code: int,
+    original_h: int,
+    original_w: int,
+) -> np.ndarray:
+    """
+    Transform landmarks from rotated coordinates back to original image coordinates.
+    """
+    if rotation_code == 0:
+        # No rotation
+        return landmarks
+    elif rotation_code == 1:
+        # Was rotated 90 CW, so transform back (90 CCW)
+        # In rotated: (x, y) with size (h, w) -> original: (y, w-1-x) with size (w, h)
+        new_landmarks = np.zeros_like(landmarks)
+        new_landmarks[:, 0] = landmarks[:, 1] * original_w  # y -> x
+        new_landmarks[:, 1] = (1 - landmarks[:, 0]) * original_h  # (1-x) -> y
+        return new_landmarks
+    elif rotation_code == 2:
+        # Was rotated 180
+        new_landmarks = np.zeros_like(landmarks)
+        new_landmarks[:, 0] = (1 - landmarks[:, 0]) * original_w
+        new_landmarks[:, 1] = (1 - landmarks[:, 1]) * original_h
+        return new_landmarks
+    elif rotation_code == 3:
+        # Was rotated 90 CCW, so transform back (90 CW)
+        new_landmarks = np.zeros_like(landmarks)
+        new_landmarks[:, 0] = (1 - landmarks[:, 1]) * original_w
+        new_landmarks[:, 1] = landmarks[:, 0] * original_h
+        return new_landmarks
+
+    return landmarks
+
+
+def detect_hand_orientation(
+    landmarks_normalized: np.ndarray,
+    finger: FingerIndex = "index"
+) -> float:
+    """
+    Detect hand orientation angle from vertical (canonical orientation).
+    
+    Canonical orientation: wrist at bottom, fingers pointing upward.
+    
+    Args:
+        landmarks_normalized: MediaPipe hand landmarks (21x2) in normalized [0-1] coordinates
+        finger: Which finger to use for orientation detection (default: "index")
+    
+    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]]
+    
+    # Compute vector from wrist to fingertip
+    direction = finger_tip - wrist
+    
+    # Compute angle from vertical upward direction
+    # In image coordinates: y increases downward, x increases rightward
+    # Vertical upward = (0, -1) in (x, y)
+    # angle = atan2(cross, dot) where cross = dx*(-1) - dy*0, dot = dx*0 + dy*(-1)
+    angle_rad = np.arctan2(direction[0], -direction[1])
+    angle_deg = angle_rad * 180.0 / np.pi
+    
+    # angle_deg is now in range [-180, 180]:
+    # 0° = fingers pointing up (canonical)
+    # 90° = fingers pointing right
+    # 180° = fingers pointing down
+    # -90° = fingers pointing left
+    
+    # Convert to [0, 360] range
+    if angle_deg < 0:
+        angle_deg += 360
+    
+    # Snap to nearest 90° increment
+    # We want to return how much to rotate CW to get to canonical (0°)
+    rotation_needed = _snap_to_orthogonal(angle_deg)
+    
+    return rotation_needed
+
+
+def _snap_to_orthogonal(angle_deg: float) -> int:
+    """
+    Snap angle to nearest orthogonal rotation (0, 90, 180, 270).
+    
+    Args:
+        angle_deg: Angle in degrees [0, 360]
+    
+    Returns:
+        Rotation needed in degrees (0, 90, 180, 270) to rotate CW to canonical orientation
+    """
+    # If angle is 0±45°, no rotation needed
+    # If angle is 90±45°, need to rotate 270° CW (or 90° CCW) to get to 0°
+    # If angle is 180±45°, need to rotate 180°
+    # If angle is 270±45°, need to rotate 90° CW
+    
+    # Determine which quadrant (with 45° tolerance)
+    if angle_deg < 45 or angle_deg >= 315:
+        return 0  # Already upright
+    elif 45 <= angle_deg < 135:
+        return 270  # Pointing right, rotate 270° CW (= 90° CCW)
+    elif 135 <= angle_deg < 225:
+        return 180  # Upside down, rotate 180°
+    else:  # 225 <= angle_deg < 315
+        return 90   # Pointing left, rotate 90° CW
+
+
+def normalize_hand_orientation(
+    image: np.ndarray,
+    landmarks_normalized: np.ndarray,
+    finger: FingerIndex = "index",
+) -> Tuple[np.ndarray, int]:
+    """
+    Rotate image to canonical hand orientation (wrist at bottom, fingers up).
+    
+    Args:
+        image: Input BGR image
+        landmarks_normalized: MediaPipe landmarks in normalized [0-1] coordinates
+        finger: Which finger to use for orientation detection (default: "index")
+    
+    Returns:
+        Tuple of (rotated_image, rotation_angle_degrees)
+        rotation_angle_degrees is one of: 0, 90, 180, 270
+    """
+    # Detect hand orientation based on specified finger
+    rotation_needed = detect_hand_orientation(landmarks_normalized, finger)
+
+    # Rotate image if needed
+    if rotation_needed == 0:
+        return image, 0
+    elif rotation_needed == 90:
+        return cv2.rotate(image, cv2.ROTATE_90_CLOCKWISE), 90
+    elif rotation_needed == 180:
+        return cv2.rotate(image, cv2.ROTATE_180), 180
+    elif rotation_needed == 270:
+        return cv2.rotate(image, cv2.ROTATE_90_COUNTERCLOCKWISE), 270
+    else:
+        # Shouldn't happen, but return original as fallback
+        print(f"Warning: Unexpected rotation angle {rotation_needed}, skipping rotation")
+        return image, 0
+
+
+def segment_hand(
+    image: np.ndarray,
+    finger: FingerIndex = "index",
+    max_dimension: int = 1280,
+    debug_dir: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """
+    Detect and segment hand from image using MediaPipe.
+
+    Args:
+        image: Input BGR image
+        finger: Which finger to use for orientation detection (default: "index")
+        max_dimension: Maximum dimension for processing (large images are resized)
+        debug_dir: Optional directory to save debug images
+
+    Returns:
+        Dictionary containing:
+        - landmarks: 21x2 array of landmark positions (pixel coordinates)
+        - landmarks_normalized: 21x2 array of normalized coordinates [0-1]
+        - mask: Binary hand mask
+        - confidence: Detection confidence
+        - handedness: "Left" or "Right"
+        Or None if no hand detected
+    """
+    # Create debug observer if debug mode enabled
+    observer = DebugObserver(debug_dir) if debug_dir else None
+    
+    h, w = image.shape[:2]
+
+    # Debug: Save original image
+    if observer:
+        observer.save_stage("01_original", image)
+
+    # Resize if image is too large (MediaPipe works better with smaller images)
+    scale = 1.0
+    if max(h, w) > max_dimension:
+        scale = max_dimension / max(h, w)
+        new_w = int(w * scale)
+        new_h = int(h * scale)
+        resized = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_AREA)
+    else:
+        resized = image
+        new_h, new_w = h, w
+
+    # Debug: Save resized image (if resized)
+    if scale != 1.0 and observer:
+        observer.save_stage("02_resized_for_detection", resized)
+
+    # Process with MediaPipe (try multiple rotations)
+    detector = _get_hands_detector()
+    detection_result = _try_detect_hand(detector, resized)
+
+    if detection_result is None:
+        return None
+
+    results, rotation_code = detection_result
+
+    # Select the best hand (highest confidence)
+    best_hand_idx = 0
+    best_conf = 0
+    for i, handedness in enumerate(results.handedness):
+        if handedness[0].score > best_conf:
+            best_conf = handedness[0].score
+            best_hand_idx = i
+
+    hand_landmarks = results.hand_landmarks[best_hand_idx]
+    handedness = results.handedness[best_hand_idx]
+
+    # Extract landmark coordinates (normalized 0-1 in rotated image)
+    landmarks_normalized_rotated = np.array([
+        [lm.x, lm.y] for lm in hand_landmarks
+    ])
+
+    # NEW: Normalize hand orientation to canonical (wrist at bottom, fingers up)
+    # This is done in the detected-rotation space first
+    if rotation_code == 1:
+        # Was rotated 90 CW
+        rotated_image = cv2.rotate(resized, cv2.ROTATE_90_CLOCKWISE)
+    elif rotation_code == 2:
+        # Was rotated 180
+        rotated_image = cv2.rotate(resized, cv2.ROTATE_180)
+    elif rotation_code == 3:
+        # Was rotated 90 CCW
+        rotated_image = cv2.rotate(resized, cv2.ROTATE_90_COUNTERCLOCKWISE)
+    else:
+        rotated_image = resized
+    
+    # Now normalize orientation based on hand direction
+    canonical_image, orientation_rotation = normalize_hand_orientation(
+        rotated_image, landmarks_normalized_rotated, finger
+    )
+    
+    # Update landmarks for orientation normalization
+    if orientation_rotation != 0:
+        rot_h, rot_w = rotated_image.shape[:2]
+        landmarks_px_rotated = landmarks_normalized_rotated.copy()
+        landmarks_px_rotated[:, 0] *= rot_w
+        landmarks_px_rotated[:, 1] *= rot_h
+        
+        # Apply rotation transform to landmarks
+        if orientation_rotation == 90:
+            # Rotate 90 CW: (x, y) -> (h-1-y, x)
+            new_landmarks = np.zeros_like(landmarks_px_rotated)
+            new_landmarks[:, 0] = rot_h - 1 - landmarks_px_rotated[:, 1]
+            new_landmarks[:, 1] = landmarks_px_rotated[:, 0]
+            landmarks_px_canonical = new_landmarks
+        elif orientation_rotation == 180:
+            # Rotate 180: (x, y) -> (w-1-x, h-1-y)
+            new_landmarks = np.zeros_like(landmarks_px_rotated)
+            new_landmarks[:, 0] = rot_w - 1 - landmarks_px_rotated[:, 0]
+            new_landmarks[:, 1] = rot_h - 1 - landmarks_px_rotated[:, 1]
+            landmarks_px_canonical = new_landmarks
+        elif orientation_rotation == 270:
+            # Rotate 90 CCW: (x, y) -> (y, w-1-x)
+            new_landmarks = np.zeros_like(landmarks_px_rotated)
+            new_landmarks[:, 0] = landmarks_px_rotated[:, 1]
+            new_landmarks[:, 1] = rot_w - 1 - landmarks_px_rotated[:, 0]
+            landmarks_px_canonical = new_landmarks
+        else:
+            landmarks_px_canonical = landmarks_px_rotated
+        
+        # Update normalized landmarks for canonical image
+        can_h, can_w = canonical_image.shape[:2]
+        landmarks_normalized_canonical = landmarks_px_canonical.copy()
+        landmarks_normalized_canonical[:, 0] /= can_w
+        landmarks_normalized_canonical[:, 1] /= can_h
+    else:
+        landmarks_normalized_canonical = landmarks_normalized_rotated
+    
+    # Scale landmarks back to original resolution if needed
+    if scale != 1.0:
+        canonical_full = cv2.resize(canonical_image, (int(canonical_image.shape[1] / scale), 
+                                                      int(canonical_image.shape[0] / scale)),
+                                   interpolation=cv2.INTER_CUBIC)
+    else:
+        canonical_full = canonical_image
+    
+    # Final landmarks in canonical full resolution
+    can_full_h, can_full_w = canonical_full.shape[:2]
+    landmarks_canonical = landmarks_normalized_canonical.copy()
+    landmarks_canonical[:, 0] *= can_full_w
+    landmarks_canonical[:, 1] *= can_full_h
+
+    # Debug: Draw landmarks overlay in canonical orientation
+    if observer:
+        observer.draw_and_save("03_landmarks_overlay_canonical", canonical_full,
+                             draw_landmarks_overlay, landmarks_canonical, label=True)
+        observer.draw_and_save("04_hand_skeleton_canonical", canonical_full,
+                             draw_hand_skeleton, landmarks_canonical)
+        observer.draw_and_save("05_detection_info_canonical", canonical_full,
+                             draw_detection_info, handedness[0].score,
+                             handedness[0].category_name, 
+                             f"det={rotation_code}, orient={orientation_rotation}")
+
+    # Generate hand mask at canonical resolution
+    mask = _create_hand_mask(landmarks_canonical, (can_full_h, can_full_w))
+
+    return {
+        "landmarks": landmarks_canonical,
+        "landmarks_normalized": landmarks_normalized_canonical,
+        "mask": mask,
+        "confidence": handedness[0].score,
+        "handedness": handedness[0].category_name,
+        "rotation_applied": rotation_code,
+        "orientation_rotation": orientation_rotation,
+        "canonical_image": canonical_full,  # Return the canonical image for downstream processing
+    }
+
+
+def _create_hand_mask(landmarks: np.ndarray, shape: Tuple[int, int]) -> np.ndarray:
+    """
+    Create a binary mask of the hand region from landmarks.
+
+    Args:
+        landmarks: 21x2 array of landmark pixel coordinates
+        shape: (height, width) of output mask
+
+    Returns:
+        Binary mask (uint8, 0 or 255)
+    """
+    h, w = shape
+    mask = np.zeros((h, w), dtype=np.uint8)
+
+    # Create convex hull of all landmarks
+    hull_points = cv2.convexHull(landmarks.astype(np.int32))
+    cv2.fillConvexPoly(mask, hull_points, 255)
+
+    # Also fill individual finger regions for better coverage
+    for finger_name, indices in FINGER_LANDMARKS.items():
+        finger_pts = landmarks[indices].astype(np.int32)
+        cv2.fillConvexPoly(mask, finger_pts, 255)
+
+    # Fill thumb
+    thumb_pts = landmarks[THUMB_LANDMARKS].astype(np.int32)
+    cv2.fillConvexPoly(mask, thumb_pts, 255)
+
+    # Apply morphological operations to smooth the mask
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (15, 15))
+    mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)
+    mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
+
+    return mask
+
+
+def _calculate_finger_extension(landmarks: np.ndarray, finger_indices: List[int]) -> float:
+    """
+    Calculate how extended a finger is based on landmark positions.
+
+    Returns a score where higher = more extended.
+    """
+    if len(finger_indices) < 4:
+        return 0.0
+
+    # Get finger landmarks
+    mcp = landmarks[finger_indices[0]]  # Knuckle
+    pip = landmarks[finger_indices[1]]  # First joint
+    dip = landmarks[finger_indices[2]]  # Second joint
+    tip = landmarks[finger_indices[3]]  # Fingertip
+
+    # Calculate vectors
+    mcp_to_tip = tip - mcp
+    mcp_to_pip = pip - mcp
+
+    # Extension score based on:
+    # 1. Distance from knuckle to tip (longer = more extended)
+    finger_length = np.linalg.norm(mcp_to_tip)
+
+    # 2. Straightness (how aligned are the joints)
+    pip_to_dip = dip - pip
+    dip_to_tip = tip - dip
+
+    # Dot products to check alignment (1 = straight, -1 = bent back)
+    if np.linalg.norm(mcp_to_pip) > 0 and np.linalg.norm(pip_to_dip) > 0:
+        align1 = np.dot(mcp_to_pip, pip_to_dip) / (np.linalg.norm(mcp_to_pip) * np.linalg.norm(pip_to_dip))
+    else:
+        align1 = 0
+
+    if np.linalg.norm(pip_to_dip) > 0 and np.linalg.norm(dip_to_tip) > 0:
+        align2 = np.dot(pip_to_dip, dip_to_tip) / (np.linalg.norm(pip_to_dip) * np.linalg.norm(dip_to_tip))
+    else:
+        align2 = 0
+
+    straightness = (align1 + align2) / 2
+
+    # Combined score
+    return finger_length * (0.5 + 0.5 * max(0, straightness))
+
+
+def _create_finger_roi_mask(
+    finger_landmarks: np.ndarray,
+    all_landmarks: np.ndarray,
+    shape: Tuple[int, int],
+    expansion_factor: float = 1.8,
+) -> np.ndarray:
+    """
+    Create a Region of Interest (ROI) mask around finger landmarks.
+
+    This creates a generous bounding region that should contain the entire finger
+    without cutting off edges, but excludes other fingers.
+
+    Args:
+        finger_landmarks: 4x2 array of finger landmark positions (MCP, PIP, DIP, TIP)
+        all_landmarks: 21x2 array of all hand landmarks
+        shape: (height, width) of output mask
+        expansion_factor: How much to expand perpendicular to finger axis
+
+    Returns:
+        Binary ROI mask
+    """
+    h, w = shape
+    roi_mask = np.zeros((h, w), dtype=np.uint8)
+
+    # Calculate finger axis direction
+    mcp = finger_landmarks[0]
+    tip = finger_landmarks[3]
+    finger_axis = tip - mcp
+    finger_length = np.linalg.norm(finger_axis)
+
+    if finger_length < 1:
+        return roi_mask
+
+    finger_direction = finger_axis / finger_length
+
+    # Perpendicular direction
+    perp = np.array([-finger_direction[1], finger_direction[0]])
+
+    # Estimate finger width from landmark spacing
+    # Use median distance between consecutive landmarks as width proxy
+    segment_lengths = []
+    for i in range(len(finger_landmarks) - 1):
+        seg_len = np.linalg.norm(finger_landmarks[i + 1] - finger_landmarks[i])
+        segment_lengths.append(seg_len)
+    avg_segment = np.median(segment_lengths) if segment_lengths else finger_length / 3
+
+    # Finger width is roughly 1/3 to 1/2 of segment length
+    base_width = avg_segment * 0.6 * expansion_factor
+
+    # Extend ROI slightly beyond landmarks (towards palm and beyond tip)
+    wrist = all_landmarks[WRIST_LANDMARK]
+    palm_direction = mcp - wrist
+    palm_direction = palm_direction / (np.linalg.norm(palm_direction) + 1e-8)
+
+    # Extend 20% beyond MCP toward palm
+    extended_base = mcp - palm_direction * finger_length * 0.2
+    # Extend 10% beyond tip
+    extended_tip = tip + finger_direction * finger_length * 0.1
+
+    # Create polygon along finger with wider margins
+    polygon_points = []
+    num_samples = 8  # More points for smoother ROI
+
+    for i in range(num_samples):
+        t = i / (num_samples - 1)
+        # Interpolate from extended base to extended tip
+        pt = extended_base + (extended_tip - extended_base) * t
+
+        # Width varies: wider at base, narrower at tip
+        width_scale = 1.0 - 0.2 * t
+        half_width = base_width * width_scale / 2
+
+        # Add left and right points
+        left = pt + perp * half_width
+        right = pt - perp * half_width
+        polygon_points.append((left, right))
+
+    # Build polygon
+    polygon = []
+    for left, right in polygon_points:
+        polygon.append(left)
+    for left, right in reversed(polygon_points):
+        polygon.append(right)
+
+    polygon = np.array(polygon, dtype=np.int32)
+    cv2.fillPoly(roi_mask, [polygon], 255)
+
+    return roi_mask
+
+
+def _isolate_finger_from_hand_mask(
+    hand_mask: np.ndarray,
+    finger_landmarks: np.ndarray,
+    all_landmarks: np.ndarray,
+    min_area: int = 500,
+) -> Optional[np.ndarray]:
+    """
+    Isolate finger using pixel-level intersection of hand mask with finger ROI.
+
+    This is the preferred method as it preserves actual finger edges from MediaPipe
+    rather than creating a synthetic polygon.
+
+    Args:
+        hand_mask: Full hand mask from MediaPipe (pixel-accurate)
+        finger_landmarks: 4x2 array of finger landmarks
+        all_landmarks: 21x2 array of all hand landmarks
+        min_area: Minimum valid finger area
+
+    Returns:
+        Binary finger mask, or None if isolation fails
+    """
+    h, w = hand_mask.shape
+
+    # Create ROI mask around finger
+    roi_mask = _create_finger_roi_mask(finger_landmarks, all_landmarks, (h, w))
+
+    # Intersect hand mask with finger ROI
+    # This preserves real pixel-level edges from MediaPipe
+    finger_mask = cv2.bitwise_and(hand_mask, roi_mask)
+
+    # Find connected components to remove fragments from other fingers
+    num_labels, labels, stats, centroids = cv2.connectedComponentsWithStats(
+        finger_mask, connectivity=8
+    )
+
+    if num_labels <= 1:
+        return None
+
+    # Select component closest to finger landmarks centroid
+    landmarks_centroid = np.mean(finger_landmarks, axis=0)
+
+    best_component = None
+    best_distance = float('inf')
+
+    for i in range(1, num_labels):  # Skip background (0)
+        area = stats[i, cv2.CC_STAT_AREA]
+        if area < min_area:
+            continue
+
+        component_centroid = centroids[i]
+        dist = np.linalg.norm(component_centroid - landmarks_centroid)
+
+        if dist < best_distance:
+            best_distance = dist
+            best_component = i
+
+    if best_component is None:
+        return None
+
+    # Create final mask with only the selected component
+    final_mask = np.zeros_like(finger_mask)
+    final_mask[labels == best_component] = 255
+
+    return final_mask
+
+
+def isolate_finger(
+    hand_data: Dict[str, Any],
+    finger: FingerIndex = "auto",
+    image_shape: Optional[Tuple[int, int]] = None,
+) -> Optional[Dict[str, Any]]:
+    """
+    Isolate a specific finger from hand segmentation data.
+
+    Args:
+        hand_data: Output from segment_hand()
+        finger: Which finger to isolate, or "auto" to select most extended
+        image_shape: (height, width) for mask generation
+
+    Returns:
+        Dictionary containing:
+        - mask: Binary finger mask
+        - landmarks: Finger landmark positions (4x2 array)
+        - base_point: Palm-side base of finger (MCP joint)
+        - tip_point: Fingertip position
+        - finger_name: Name of the isolated finger
+        Or None if finger cannot be isolated
+    """
+    landmarks = hand_data["landmarks"]
+
+    if image_shape is None:
+        if "mask" in hand_data:
+            image_shape = hand_data["mask"].shape[:2]
+        else:
+            return None
+
+    # Determine which finger to use
+    if finger == "auto":
+        best_finger = None
+        best_score = -1
+
+        for finger_name, indices in FINGER_LANDMARKS.items():
+            score = _calculate_finger_extension(landmarks, indices)
+            if score > best_score:
+                best_score = score
+                best_finger = finger_name
+
+        if best_finger is None:
+            return None
+        finger = best_finger
+
+    if finger not in FINGER_LANDMARKS:
+        return None
+
+    indices = FINGER_LANDMARKS[finger]
+    finger_landmarks = landmarks[indices]
+
+    # Create finger mask using pixel-level approach (preferred)
+    mask = None
+    method_used = "unknown"
+
+    if "mask" in hand_data and hand_data["mask"] is not None:
+        mask = _isolate_finger_from_hand_mask(
+            hand_data["mask"],
+            finger_landmarks,
+            landmarks,
+            min_area=500,
+        )
+        if mask is not None:
+            method_used = "pixel-level"
+            print(f"  Finger isolated using pixel-level segmentation")
+        else:
+            print(f"  Pixel-level segmentation failed, falling back to polygon")
+
+    # Fallback to polygon-based approach
+    if mask is None:
+        mask = _create_finger_mask(landmarks, indices, image_shape)
+        if mask is not None:
+            method_used = "polygon"
+            print(f"  Finger isolated using polygon-based segmentation (fallback)")
+        else:
+            print(f"  Both segmentation methods failed")
+            return None
+
+    return {
+        "mask": mask,
+        "landmarks": finger_landmarks,
+        "base_point": finger_landmarks[0],  # MCP joint
+        "tip_point": finger_landmarks[3],   # Fingertip
+        "finger_name": finger,
+        "method": method_used,
+    }
+
+
+def _create_finger_mask(
+    all_landmarks: np.ndarray,
+    finger_indices: List[int],
+    shape: Tuple[int, int],
+    width_factor: float = 2.5,
+) -> Optional[np.ndarray]:
+    """
+    Create a binary mask for a single finger using polygon approximation.
+
+    This is the fallback method when pixel-level segmentation fails.
+
+    Args:
+        all_landmarks: All 21 hand landmarks
+        finger_indices: Indices of the 4 finger landmarks
+        shape: (height, width) of output mask
+        width_factor: Multiplier for estimated finger width
+
+    Returns:
+        Binary mask of finger region
+    """
+    h, w = shape
+    mask = np.zeros((h, w), dtype=np.uint8)
+
+    finger_landmarks = all_landmarks[finger_indices]
+
+    # Estimate finger width based on joint spacing
+    mcp_idx = finger_indices[0]
+
+    adjacent_distances = []
+    for other_finger, other_indices in FINGER_LANDMARKS.items():
+        other_mcp = other_indices[0]
+        if other_mcp != mcp_idx:
+            dist = np.linalg.norm(all_landmarks[mcp_idx] - all_landmarks[other_mcp])
+            adjacent_distances.append(dist)
+
+    if adjacent_distances:
+        estimated_width = min(adjacent_distances) * 0.4 * width_factor
+    else:
+        finger_length = np.linalg.norm(finger_landmarks[3] - finger_landmarks[0])
+        estimated_width = finger_length / 6 * width_factor
+
+    # Create polygon along finger with estimated width
+    polygon_points = []
+
+    for i in range(len(finger_landmarks)):
+        pt = finger_landmarks[i]
+
+        if i < len(finger_landmarks) - 1:
+            direction = finger_landmarks[i + 1] - pt
+        else:
+            direction = pt - finger_landmarks[i - 1]
+
+        perp = np.array([-direction[1], direction[0]])
+        perp_norm = np.linalg.norm(perp)
+        if perp_norm > 0:
+            perp = perp / perp_norm
+
+        width_scale = 1.0 - 0.3 * (i / (len(finger_landmarks) - 1))
+        half_width = estimated_width * width_scale / 2
+
+        left = pt + perp * half_width
+        right = pt - perp * half_width
+        polygon_points.append((left, right))
+
+    # Build polygon: go up left side, then down right side
+    polygon = []
+    for left, right in polygon_points:
+        polygon.append(left)
+    for left, right in reversed(polygon_points):
+        polygon.append(right)
+
+    polygon = np.array(polygon, dtype=np.int32)
+    cv2.fillPoly(mask, [polygon], 255)
+
+    # Extend mask slightly towards palm
+    mcp = finger_landmarks[0]
+    wrist = all_landmarks[WRIST_LANDMARK]
+    palm_direction = mcp - wrist
+    palm_direction = palm_direction / (np.linalg.norm(palm_direction) + 1e-8)
+
+    finger_length = np.linalg.norm(finger_landmarks[3] - finger_landmarks[0])
+    extension = palm_direction * finger_length * 0.15
+    extended_base = mcp - extension
+
+    perp = np.array([-palm_direction[1], palm_direction[0]])
+    half_width = estimated_width / 2
+    ext_polygon = np.array([
+        mcp + perp * half_width,
+        mcp - perp * half_width,
+        extended_base - perp * half_width * 0.8,
+        extended_base + perp * half_width * 0.8,
+    ], dtype=np.int32)
+
+    cv2.fillPoly(mask, [ext_polygon], 255)
+
+    return mask
+
+
+def clean_mask(
+    mask: np.ndarray,
+    min_area: int = 1000,
+) -> Optional[np.ndarray]:
+    """
+    Clean a binary mask by extracting largest component and applying morphology.
+
+    Args:
+        mask: Input binary mask
+        min_area: Minimum valid area in pixels
+
+    Returns:
+        Cleaned binary mask, or None if no valid component found
+    """
+    if mask is None or mask.size == 0:
+        return None
+
+    # Find connected components
+    num_labels, labels, stats, centroids = cv2.connectedComponentsWithStats(mask, connectivity=8)
+
+    if num_labels <= 1:
+        return None
+
+    # Find largest component (excluding background at index 0)
+    largest_idx = 1
+    largest_area = 0
+
+    for i in range(1, num_labels):
+        area = stats[i, cv2.CC_STAT_AREA]
+        if area > largest_area:
+            largest_area = area
+            largest_idx = i
+
+    if largest_area < min_area:
+        return None
+
+    # Create mask with only the largest component
+    cleaned = np.zeros_like(mask)
+    cleaned[labels == largest_idx] = 255
+
+    # Apply morphological smoothing
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
+
+    cleaned = cv2.morphologyEx(cleaned, cv2.MORPH_CLOSE, kernel)
+    cleaned = cv2.morphologyEx(cleaned, cv2.MORPH_OPEN, kernel)
+
+    # Smooth edges with Gaussian blur and re-threshold
+    cleaned = cv2.GaussianBlur(cleaned, (5, 5), 0)
+    _, cleaned = cv2.threshold(cleaned, 127, 255, cv2.THRESH_BINARY)
+
+    return cleaned
+
+
+def get_finger_contour(
+    mask: np.ndarray,
+    smooth: bool = True,
+) -> Optional[np.ndarray]:
+    """
+    Extract outer contour from finger mask.
+
+    Args:
+        mask: Binary finger mask
+        smooth: Whether to apply contour smoothing
+
+    Returns:
+        Contour points as Nx2 array, or None if no contour found
+    """
+    if mask is None:
+        return None
+
+    # Find contours
+    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+    if not contours:
+        return None
+
+    # Get the largest contour
+    largest_contour = max(contours, key=cv2.contourArea)
+
+    # Reshape to Nx2
+    contour = largest_contour.reshape(-1, 2)
+
+    if smooth and len(contour) > 10:
+        # Apply contour smoothing using approximation
+        epsilon = 0.005 * cv2.arcLength(largest_contour, True)
+        smoothed = cv2.approxPolyDP(largest_contour, epsilon, True)
+        contour = smoothed.reshape(-1, 2)
+
+    return contour.astype(np.float32)

src/geometry.py

@@ -0,0 +1,791 @@
+"""
+Geometric computation utilities.
+
+This module handles:
+- Finger axis estimation (PCA and landmark-based)
+- Ring-wearing zone localization
+- Cross-section width measurement
+- Coordinate transformations
+"""
+
+import logging
+import cv2
+import numpy as np
+from typing import Tuple, List, Optional, Dict, Any, Literal
+
+from .geometry_constants import (
+    MIN_LANDMARK_SPACING_PX,
+    MIN_FINGER_LENGTH_PX,
+    EPSILON,
+    MIN_MASK_POINTS_FOR_PCA,
+    ENDPOINT_SAMPLE_DISTANCE_FACTOR,
+    DEFAULT_ZONE_START_PCT,
+    DEFAULT_ZONE_END_PCT,
+    ANATOMICAL_ZONE_WIDTH_FACTOR,
+    MIN_DETERMINANT_FOR_INTERSECTION,
+)
+
+logger = logging.getLogger(__name__)
+
+# Type for axis estimation method
+AxisMethod = Literal["auto", "landmarks", "pca"]
+
+
+def _validate_landmark_quality(landmarks: np.ndarray) -> Tuple[bool, str]:
+    """
+    Validate quality of finger landmarks for axis estimation.
+
+    Args:
+        landmarks: 4x2 array of finger landmarks [MCP, PIP, DIP, TIP]
+
+    Returns:
+        Tuple of (is_valid, reason)
+    """
+    if landmarks is None or len(landmarks) != 4:
+        return False, "landmarks_missing_or_incomplete"
+
+    # Check for NaN or infinite values
+    if not np.all(np.isfinite(landmarks)):
+        return False, "landmarks_contain_invalid_values"
+
+    # Check reasonable spacing (landmarks not collapsed)
+    # Calculate distances between consecutive landmarks
+    distances = []
+    for i in range(len(landmarks) - 1):
+        dist = np.linalg.norm(landmarks[i + 1] - landmarks[i])
+        distances.append(dist)
+
+    # Check if any distance is too small (collapsed landmarks)
+    min_distance = min(distances)
+    if min_distance < MIN_LANDMARK_SPACING_PX:
+        return False, "landmarks_too_close"
+
+    # Check for monotonically increasing progression (no crossovers)
+    # Calculate overall direction from MCP to TIP
+    overall_direction = landmarks[3] - landmarks[0]
+    overall_length = np.linalg.norm(overall_direction)
+
+    if overall_length < MIN_FINGER_LENGTH_PX:
+        return False, "finger_too_short"
+
+    overall_direction = overall_direction / overall_length
+
+    # Project each landmark onto overall direction
+    # They should be monotonically increasing from MCP to TIP
+    projections = []
+    for i in range(len(landmarks)):
+        proj = np.dot(landmarks[i] - landmarks[0], overall_direction)
+        projections.append(proj)
+
+    # Check monotonic increase
+    for i in range(len(projections) - 1):
+        if projections[i + 1] <= projections[i]:
+            return False, "landmarks_not_monotonic"
+
+    return True, "valid"
+
+
+def estimate_finger_axis_from_landmarks(
+    landmarks: np.ndarray,
+    method: str = "linear_fit"
+) -> Dict[str, Any]:
+    """
+    Calculate finger axis directly from anatomical landmarks.
+
+    OPTIMIZED: Focuses on DIP-PIP segment (ring-wearing zone) for better accuracy.
+
+    Args:
+        landmarks: 4x2 array of finger landmarks [MCP, PIP, DIP, TIP]
+        method: Calculation method
+            - "endpoints": MCP to TIP vector (legacy, less accurate)
+            - "linear_fit": DIP to PIP vector (DEFAULT, optimized for ring measurements)
+            - "median_direction": Median of 3 segment directions (robust to outliers)
+
+    Returns:
+        Dictionary containing:
+        - center: Axis center point at midpoint of PIP-DIP (x, y)
+        - direction: Unit direction vector (dx, dy) from PIP to DIP
+        - length: Full finger length in pixels (TIP to MCP, for reference)
+        - palm_end: Visualization endpoint (extended from PIP toward palm)
+        - tip_end: Visualization endpoint (extended from DIP toward tip)
+        - method: Method used ("landmarks")
+    """
+    # Validate landmarks
+    is_valid, reason = _validate_landmark_quality(landmarks)
+    if not is_valid:
+        raise ValueError(f"Invalid landmarks for axis estimation: {reason}")
+
+    # Extract landmark positions
+    mcp = landmarks[0]  # Metacarpophalangeal joint (knuckle, palm-side)
+    pip = landmarks[1]  # Proximal interphalangeal joint
+    dip = landmarks[2]  # Distal interphalangeal joint
+    tip = landmarks[3]  # Fingertip
+
+    # Calculate direction based on method
+    # OPTIMIZED: Focus on DIP-PIP segment (ring-wearing zone)
+    if method == "endpoints":
+        # Simple: vector from MCP to TIP (legacy, less accurate for ring zone)
+        direction = tip - mcp
+        direction_length = np.linalg.norm(direction)
+        direction = direction / direction_length
+
+    elif method == "linear_fit":
+        # OPTIMIZED: Use only DIP and PIP (most relevant for ring measurements)
+        # These two joints define the proximal phalanx where rings are worn
+        direction = dip - pip  # Vector from PIP to DIP
+        direction_length = np.linalg.norm(direction)
+        direction = direction / direction_length
+
+        # Ensure direction points from palm to tip (PIP to DIP)
+        # Direction should already be correct, but verify
+        if np.dot(direction, tip - mcp) < 0:
+            direction = -direction
+
+    elif method == "median_direction":
+        # Robust to outliers: median of segment directions
+        # Calculate direction vectors for each segment
+        seg1_dir = (pip - mcp) / np.linalg.norm(pip - mcp)
+        seg2_dir = (dip - pip) / np.linalg.norm(dip - pip)
+        seg3_dir = (tip - dip) / np.linalg.norm(tip - dip)
+
+        # Take median of each component
+        directions = np.array([seg1_dir, seg2_dir, seg3_dir])
+        median_dir = np.median(directions, axis=0)
+        direction = median_dir / np.linalg.norm(median_dir)
+
+    else:
+        raise ValueError(f"Unknown method: {method}. Use 'endpoints', 'linear_fit', or 'median_direction'")
+
+    # OPTIMIZED: Center at midpoint of DIP and PIP (ring zone focus)
+    center = (pip + dip) / 2.0
+
+    # Calculate finger length (still use full finger for reference)
+    length = np.linalg.norm(tip - mcp)
+
+    # OPTIMIZED: Visual endpoints are DIP and PIP (ring zone segment)
+    # Extended slightly for visualization clarity
+    segment_length = np.linalg.norm(dip - pip)
+    extension_factor = 0.5  # Extend 50% beyond each endpoint for visualization
+    palm_end = pip - direction * (segment_length * extension_factor)
+    tip_end = dip + direction * (segment_length * extension_factor)
+
+    return {
+        "center": center.astype(np.float32),
+        "direction": direction.astype(np.float32),
+        "length": float(length),
+        "palm_end": palm_end.astype(np.float32),
+        "tip_end": tip_end.astype(np.float32),
+        "method": "landmarks",
+    }
+
+
+def _estimate_axis_pca(
+    mask: np.ndarray,
+    landmarks: Optional[np.ndarray] = None,
+) -> Dict[str, Any]:
+    """
+    Estimate finger axis using PCA on mask points.
+
+    This is the original v0 implementation, now refactored as a helper function.
+
+    Args:
+        mask: Binary finger mask
+        landmarks: Optional finger landmarks for orientation (4x2 array)
+
+    Returns:
+        Dictionary containing axis data with method="pca"
+        Keys: center, direction, length, palm_end, tip_end, method
+    """
+    # Get all non-zero points in the mask
+    points = np.column_stack(np.where(mask > 0))  # Returns (row, col) i.e., (y, x)
+    points = points[:, [1, 0]]  # Convert to (x, y) format
+
+    if len(points) < MIN_MASK_POINTS_FOR_PCA:
+        raise ValueError("Not enough points in mask for axis estimation")
+
+    # Calculate center (centroid)
+    center = np.mean(points, axis=0)
+
+    # Center the points
+    centered = points - center
+
+    # Compute covariance matrix
+    cov = np.cov(centered.T)
+
+    # Compute eigenvalues and eigenvectors
+    eigenvalues, eigenvectors = np.linalg.eigh(cov)
+
+    # Principal axis is the eigenvector with largest eigenvalue
+    principal_idx = np.argmax(eigenvalues)
+    direction = eigenvectors[:, principal_idx]
+
+    # Ensure direction is a unit vector
+    direction = direction / np.linalg.norm(direction)
+
+    # Project all points onto the principal axis to find endpoints
+    projections = np.dot(centered, direction)
+    min_proj = np.min(projections)
+    max_proj = np.max(projections)
+
+    # Calculate finger length
+    length = max_proj - min_proj
+
+    # Calculate endpoints along the axis
+    endpoint1 = center + direction * min_proj
+    endpoint2 = center + direction * max_proj
+
+    # Determine which endpoint is palm vs tip
+    # If landmarks are provided, use them for orientation
+    if landmarks is not None and len(landmarks) == 4:
+        # landmarks[0] is MCP (palm side), landmarks[3] is tip
+        base_point = landmarks[0]
+        tip_point = landmarks[3]
+
+        # Determine which endpoint is closer to the base
+        dist1_to_base = np.linalg.norm(endpoint1 - base_point)
+        dist2_to_base = np.linalg.norm(endpoint2 - base_point)
+
+        if dist1_to_base < dist2_to_base:
+            palm_end = endpoint1
+            tip_end = endpoint2
+        else:
+            palm_end = endpoint2
+            tip_end = endpoint1
+            direction = -direction  # Flip direction to point from palm to tip
+    else:
+        # Without landmarks, use heuristic: tip is usually thinner
+        # Sample points near each endpoint
+        sample_distance = length * ENDPOINT_SAMPLE_DISTANCE_FACTOR
+
+        # Points near endpoint1
+        near_ep1 = points[np.abs(projections - min_proj) < sample_distance]
+        # Points near endpoint2
+        near_ep2 = points[np.abs(projections - max_proj) < sample_distance]
+
+        # Calculate average distance from axis for each end (proxy for thickness)
+        if len(near_ep1) > 0 and len(near_ep2) > 0:
+            # Project distances perpendicular to axis
+            perp_direction = np.array([-direction[1], direction[0]])
+            dist1 = np.mean(np.abs(np.dot(near_ep1 - center, perp_direction)))
+            dist2 = np.mean(np.abs(np.dot(near_ep2 - center, perp_direction)))
+
+            # Thinner end is likely the tip
+            if dist1 < dist2:
+                palm_end = endpoint2
+                tip_end = endpoint1
+                direction = -direction
+            else:
+                palm_end = endpoint1
+                tip_end = endpoint2
+        else:
+            # Fallback: assume endpoint2 is tip (positive direction)
+            palm_end = endpoint1
+            tip_end = endpoint2
+
+    return {
+        "center": center.astype(np.float32),
+        "direction": direction.astype(np.float32),
+        "length": float(length),
+        "palm_end": palm_end.astype(np.float32),
+        "tip_end": tip_end.astype(np.float32),
+        "method": "pca",
+    }
+
+
+def estimate_finger_axis(
+    mask: np.ndarray,
+    landmarks: Optional[np.ndarray] = None,
+    method: AxisMethod = "auto",
+    landmark_method: str = "linear_fit",
+) -> Dict[str, Any]:
+    """
+    Estimate the principal axis of a finger using landmarks (preferred) or PCA (fallback).
+
+    v1 Enhancement: Now supports landmark-based axis estimation for improved accuracy
+    on bent fingers. Auto mode (default) uses landmarks when available and valid,
+    falling back to PCA if needed.
+
+    Args:
+        mask: Binary finger mask
+        landmarks: Optional finger landmarks (4x2 array: [MCP, PIP, DIP, TIP])
+        method: Axis estimation method
+            - "auto": Use landmarks if available and valid, else PCA (recommended)
+            - "landmarks": Force landmark-based (fails if landmarks invalid)
+            - "pca": Force PCA-based (v0 behavior)
+        landmark_method: Method for landmark-based estimation
+            ("endpoints", "linear_fit", "median_direction")
+
+    Returns:
+        Dictionary containing:
+        - center: Axis center point (x, y)
+        - direction: Unit direction vector (dx, dy) pointing from palm to tip
+        - length: Estimated finger length in pixels
+        - palm_end: Palm-side endpoint
+        - tip_end: Fingertip endpoint
+        - method: Method actually used ("landmarks" or "pca")
+    """
+    if method == "pca":
+        # Force PCA method
+        return _estimate_axis_pca(mask, landmarks)
+
+    elif method == "landmarks":
+        # Force landmark method (fail if landmarks invalid)
+        if landmarks is None or len(landmarks) != 4:
+            raise ValueError("Landmark method requested but landmarks not available")
+        return estimate_finger_axis_from_landmarks(landmarks, method=landmark_method)
+
+    elif method == "auto":
+        # Auto mode: try landmarks first, fall back to PCA
+        try:
+            # Check if landmarks are available and valid
+            if landmarks is not None and len(landmarks) == 4:
+                is_valid, reason = _validate_landmark_quality(landmarks)
+                if is_valid:
+                    # Use landmark-based method
+                    logger.debug(f"Using landmark-based axis estimation ({landmark_method})")
+                    return estimate_finger_axis_from_landmarks(landmarks, method=landmark_method)
+                else:
+                    logger.debug(f"Landmarks available but quality check failed: {reason}")
+                    logger.debug("Falling back to PCA axis estimation")
+            else:
+                logger.debug("Landmarks not available, using PCA axis estimation")
+
+        except Exception as e:
+            logger.debug(f"Landmark-based axis estimation failed: {e}")
+            logger.debug("Falling back to PCA axis estimation")
+
+        # Fall back to PCA
+        return _estimate_axis_pca(mask, landmarks)
+
+    else:
+        raise ValueError(f"Unknown method: {method}. Use 'auto', 'landmarks', or 'pca'")
+
+
+def localize_ring_zone(
+    axis_data: Dict[str, Any],
+    zone_start_pct: float = DEFAULT_ZONE_START_PCT,
+    zone_end_pct: float = DEFAULT_ZONE_END_PCT,
+) -> Dict[str, Any]:
+    """
+    Localize the ring-wearing zone along the finger axis.
+
+    Args:
+        axis_data: Output from estimate_finger_axis() containing center,
+                   direction, length, palm_end, tip_end
+        zone_start_pct: Zone start as percentage from palm (default 15%)
+        zone_end_pct: Zone end as percentage from palm (default 25%)
+
+    Returns:
+        Dictionary containing:
+        - start_point: Zone start position (x, y)
+        - end_point: Zone end position (x, y)
+        - center_point: Zone center position (x, y)
+        - length: Zone length in pixels
+        - start_pct: Start percentage used
+        - end_pct: End percentage used
+        - localization_method: "percentage"
+    """
+    # Extract axis information
+    palm_end = axis_data["palm_end"]
+    tip_end = axis_data["tip_end"]
+    direction = axis_data["direction"]
+    finger_length = axis_data["length"]
+
+    # Calculate zone positions along the axis
+    # Start at zone_start_pct from palm end
+    start_distance = finger_length * zone_start_pct
+    start_point = palm_end + direction * start_distance
+
+    # End at zone_end_pct from palm end
+    end_distance = finger_length * zone_end_pct
+    end_point = palm_end + direction * end_distance
+
+    # Calculate zone center
+    center_point = (start_point + end_point) / 2.0
+
+    # Zone length
+    zone_length = end_distance - start_distance
+
+    return {
+        "start_point": start_point.astype(np.float32),
+        "end_point": end_point.astype(np.float32),
+        "center_point": center_point.astype(np.float32),
+        "length": float(zone_length),
+        "start_pct": zone_start_pct,
+        "end_pct": zone_end_pct,
+        "localization_method": "percentage",
+    }
+
+
+def localize_ring_zone_from_landmarks(
+    landmarks: np.ndarray,
+    axis_data: Dict[str, Any],
+    zone_type: str = "percentage",
+    zone_start_pct: float = DEFAULT_ZONE_START_PCT,
+    zone_end_pct: float = DEFAULT_ZONE_END_PCT,
+) -> Dict[str, Any]:
+    """
+    Localize ring-wearing zone using anatomical landmarks.
+
+    v1 Enhancement: Provides anatomical-based ring zone localization
+    as an alternative to percentage-based approach.
+
+    Args:
+        landmarks: 4x2 array of finger landmarks [MCP, PIP, DIP, TIP]
+        axis_data: Output from estimate_finger_axis() containing center,
+                   direction, length, palm_end, tip_end
+        zone_type: Zone localization method
+            - "percentage": 15-25% from palm (v0 compatible, default)
+            - "anatomical": Centered on PIP joint with proportional width
+        zone_start_pct: Zone start percentage (percentage mode only)
+        zone_end_pct: Zone end percentage (percentage mode only)
+
+    Returns:
+        Dictionary containing:
+        - start_point: Zone start position (x, y)
+        - end_point: Zone end position (x, y)
+        - center_point: Zone center position (x, y)
+        - length: Zone length in pixels
+        - localization_method: "percentage" or "anatomical"
+    """
+    if zone_type == "percentage":
+        # Use percentage-based method (v0 compatible)
+        result = localize_ring_zone(axis_data, zone_start_pct, zone_end_pct)
+        return result
+
+    elif zone_type == "anatomical":
+        # Anatomical mode: Target the proximal phalanx (ring-wearing segment)
+        # Upper bound: PIP joint (toward fingertip)
+        # Lower bound: PIP - (DIP - PIP) = one segment length below PIP (toward palm)
+        # This spans the proximal phalanx where rings are typically worn
+        pip = landmarks[1]
+        dip = landmarks[2]
+
+        # Calculate segment length (DIP to PIP distance)
+        segment_vector = dip - pip  # Vector from PIP to DIP
+
+        # Ring zone spans from PIP down toward palm by one segment length
+        # end_point is toward fingertip (PIP)
+        # start_point is toward palm (PIP - segment_vector = one segment below PIP)
+        end_point = pip.copy()  # Upper bound at PIP
+        start_point = pip - segment_vector  # Lower bound one segment below PIP
+
+        # Calculate zone center and length
+        center_point = (start_point + end_point) / 2.0
+        zone_length = np.linalg.norm(end_point - start_point)
+
+        return {
+            "start_point": start_point.astype(np.float32),
+            "end_point": end_point.astype(np.float32),
+            "center_point": center_point.astype(np.float32),
+            "length": float(zone_length),
+            "localization_method": "anatomical",
+        }
+
+    else:
+        raise ValueError(f"Unknown zone_type: {zone_type}. Use 'percentage' or 'anatomical'")
+
+
+def compute_cross_section_width(
+    contour: np.ndarray,
+    axis_data: Dict[str, Any],
+    zone_data: Dict[str, Any],
+    num_samples: int = 20,
+) -> Dict[str, Any]:
+    """
+    Measure finger width by sampling cross-sections perpendicular to axis.
+
+    Args:
+        contour: Finger contour points (Nx2 array in x,y format)
+        axis_data: Output from estimate_finger_axis() containing center,
+                   direction, length, palm_end, tip_end
+        zone_data: Output from localize_ring_zone() containing start_point,
+                   end_point, center_point
+        num_samples: Number of cross-section samples (default 20)
+
+    Returns:
+        Dictionary containing:
+        - widths_px: List of width measurements in pixels
+        - sample_points: List of (left, right) intersection point tuples
+        - median_width_px: Median width in pixels
+        - std_width_px: Standard deviation of widths
+        - mean_width_px: Mean width in pixels
+        - num_samples: Actual number of successful measurements
+    """
+    direction = axis_data["direction"]
+    start_point = zone_data["start_point"]
+    end_point = zone_data["end_point"]
+
+    # Perpendicular direction (rotate 90 degrees)
+    perp_direction = np.array([-direction[1], direction[0]], dtype=np.float32)
+
+    widths = []
+    sample_points_list = []
+
+    # Generate sample points along the zone
+    for i in range(num_samples):
+        # Interpolate between start and end
+        t = i / (num_samples - 1) if num_samples > 1 else 0.5
+        sample_center = start_point + t * (end_point - start_point)
+
+        # Find intersections with contour along perpendicular line
+        intersections = line_contour_intersections(
+            contour, sample_center, perp_direction
+        )
+
+        if len(intersections) >= 2:
+            # Convert to numpy array for distance calculations
+            pts = np.array(intersections)
+
+            # Find the two points that are farthest apart
+            # This handles cases where the line intersects multiple times
+            max_dist = 0
+            best_pair = None
+
+            for j in range(len(pts)):
+                for k in range(j + 1, len(pts)):
+                    dist = np.linalg.norm(pts[j] - pts[k])
+                    if dist > max_dist:
+                        max_dist = dist
+                        best_pair = (pts[j], pts[k])
+
+            if best_pair is not None:
+                widths.append(max_dist)
+                sample_points_list.append(best_pair)
+
+    if len(widths) == 0:
+        raise ValueError("No valid width measurements found in ring zone")
+
+    widths = np.array(widths)
+
+    # Calculate statistics
+    median_width = float(np.median(widths))
+    mean_width = float(np.mean(widths))
+    std_width = float(np.std(widths))
+
+    return {
+        "widths_px": widths.tolist(),
+        "sample_points": sample_points_list,
+        "median_width_px": median_width,
+        "mean_width_px": mean_width,
+        "std_width_px": std_width,
+        "num_samples": len(widths),
+    }
+
+
+def line_contour_intersections(
+    contour: np.ndarray,
+    point: Tuple[float, float],
+    direction: Tuple[float, float],
+) -> List[Tuple[float, float]]:
+    """
+    Find intersection points between a line and a contour.
+
+    Uses parametric line-segment intersection to find where an infinite line
+    intersects with the contour edges.
+
+    Args:
+        contour: Contour points (Nx2 array in x,y format)
+        point: A point on the line (x, y)
+        direction: Line direction vector (dx, dy), will be normalized
+
+    Returns:
+        List of intersection points as (x, y) tuples
+    """
+    intersections = []
+
+    # Normalize direction
+    direction = np.array(direction, dtype=np.float32)
+    direction = direction / (np.linalg.norm(direction) + EPSILON)
+
+    point = np.array(point, dtype=np.float32)
+
+    # Check each edge of the contour
+    n = len(contour)
+    for i in range(n):
+        p1 = contour[i]
+        p2 = contour[(i + 1) % n]
+
+        # Find intersection between line and edge segment
+        # Line: P = point + t * direction
+        # Segment: Q = p1 + s * (p2 - p1), where s ∈ [0, 1]
+
+        edge_vec = p2 - p1
+
+        # Solve: point + t * direction = p1 + s * edge_vec
+        # Rearranged: t * direction - s * edge_vec = p1 - point
+
+        # Create matrix [direction, -edge_vec] * [t, s]^T = p1 - point
+        A = np.column_stack([direction, -edge_vec])
+        b = p1 - point
+
+        # Check if matrix is singular (parallel lines)
+        det = A[0, 0] * A[1, 1] - A[0, 1] * A[1, 0]
+        if abs(det) < MIN_DETERMINANT_FOR_INTERSECTION:
+            continue
+
+        # Solve for t and s
+        try:
+            params = np.linalg.solve(A, b)
+            t, s = params[0], params[1]
+
+            # Check if intersection is on the edge segment (s ∈ [0, 1])
+            if 0 <= s <= 1:
+                intersection = point + t * direction
+                intersections.append(tuple(intersection))
+        except np.linalg.LinAlgError:
+            continue
+
+    return intersections
+
+
+# ============================================================================
+# Precise Image Rotation for Finger Alignment
+# ============================================================================
+
+def calculate_angle_from_vertical(direction: np.ndarray) -> float:
+    """
+    Calculate the rotation needed to align a direction vector to vertical (upward).
+
+    In image coordinates, vertical upward is (0, -1) in (x, y) format.
+
+    Args:
+        direction: Unit direction vector (dx, dy) in (x, y) format
+
+    Returns:
+        Rotation angle in degrees to apply to align direction to vertical.
+        Positive = need to rotate counter-clockwise (CCW) in image coordinates.
+        Range: [-180, 180]
+    """
+    # Vertical upward in image coordinates: (0, -1)
+    vertical = np.array([0.0, -1.0])
+
+    # Calculate angle using atan2(cross_product, dot_product)
+    # cross = dx * (-1) - dy * 0 = -dx
+    # dot = dx * 0 + dy * (-1) = -dy
+    cross = direction[0] * vertical[1] - direction[1] * vertical[0]
+    dot = np.dot(direction, vertical)
+
+    angle_rad = np.arctan2(cross, dot)
+    angle_deg = np.degrees(angle_rad)
+
+    # Negate the angle: if finger is tilted +10° CW from vertical,
+    # we need to rotate -10° (CCW) to straighten it
+    return -angle_deg
+
+
+def rotate_image_precise(
+    image: np.ndarray,
+    angle_degrees: float,
+    center: Optional[Tuple[float, float]] = None
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Rotate image by a precise angle around a center point.
+
+    Args:
+        image: Input image (grayscale or BGR)
+        angle_degrees: Rotation angle in degrees (positive = clockwise)
+        center: Rotation center (x, y). If None, uses image center.
+
+    Returns:
+        Tuple of:
+        - rotated_image: Rotated image (same size as input)
+        - rotation_matrix: 2x3 affine transformation matrix
+    """
+    h, w = image.shape[:2]
+
+    if center is None:
+        center = (w / 2.0, h / 2.0)
+
+    # Get rotation matrix (OpenCV uses clockwise positive)
+    rotation_matrix = cv2.getRotationMatrix2D(center, angle_degrees, scale=1.0)
+
+    # Apply rotation
+    rotated = cv2.warpAffine(
+        image, rotation_matrix, (w, h),
+        flags=cv2.INTER_LINEAR,
+        borderMode=cv2.BORDER_CONSTANT,
+        borderValue=0
+    )
+
+    return rotated, rotation_matrix
+
+
+def transform_points_rotation(
+    points: np.ndarray,
+    rotation_matrix: np.ndarray
+) -> np.ndarray:
+    """
+    Transform points using a rotation matrix from cv2.getRotationMatrix2D.
+
+    Args:
+        points: Nx2 array of points in (x, y) format
+        rotation_matrix: 2x3 affine transformation matrix from cv2.getRotationMatrix2D
+
+    Returns:
+        Nx2 array of transformed points in (x, y) format
+    """
+    # Add homogeneous coordinate (1) to each point: (x, y) -> (x, y, 1)
+    n_points = points.shape[0]
+    homogeneous = np.hstack([points, np.ones((n_points, 1))])
+
+    # Apply transformation: [2x3] @ [3xN]^T -> [2xN]^T
+    transformed = (rotation_matrix @ homogeneous.T).T
+
+    return transformed.astype(np.float32)
+
+
+def rotate_axis_data(
+    axis_data: Dict[str, Any],
+    rotation_matrix: np.ndarray
+) -> Dict[str, Any]:
+    """
+    Update axis data after image rotation.
+
+    Args:
+        axis_data: Axis data dictionary with center, direction, palm_end, tip_end
+        rotation_matrix: 2x3 rotation matrix
+
+    Returns:
+        Updated axis data with transformed coordinates
+    """
+    rotated = axis_data.copy()
+
+    # Transform center point
+    center = axis_data["center"].reshape(1, 2)
+    rotated["center"] = transform_points_rotation(center, rotation_matrix)[0]
+
+    # Transform direction vector (rotation only, no translation)
+    # For direction vectors, we only apply the rotation part (2x2)
+    rotation_only = rotation_matrix[:2, :2]
+    direction = axis_data["direction"].reshape(2, 1)
+    rotated_direction = (rotation_only @ direction).flatten()
+    rotated["direction"] = rotated_direction / np.linalg.norm(rotated_direction)
+
+    # Transform endpoints if they exist
+    if "palm_end" in axis_data:
+        palm_end = axis_data["palm_end"].reshape(1, 2)
+        rotated["palm_end"] = transform_points_rotation(palm_end, rotation_matrix)[0]
+
+    if "tip_end" in axis_data:
+        tip_end = axis_data["tip_end"].reshape(1, 2)
+        rotated["tip_end"] = transform_points_rotation(tip_end, rotation_matrix)[0]
+
+    return rotated
+
+
+def rotate_contour(
+    contour: np.ndarray,
+    rotation_matrix: np.ndarray
+) -> np.ndarray:
+    """
+    Rotate a contour using rotation matrix.
+
+    Args:
+        contour: Nx2 array of contour points in (x, y) format
+        rotation_matrix: 2x3 rotation matrix
+
+    Returns:
+        Rotated contour in same format
+    """
+    return transform_points_rotation(contour, rotation_matrix)

src/geometry_constants.py

@@ -0,0 +1,54 @@
+"""
+Constants for geometric computation module.
+
+This module contains thresholds and parameters used in finger axis
+estimation and ring zone localization.
+"""
+
+# =============================================================================
+# Landmark Quality Validation Constants
+# =============================================================================
+
+# Minimum distance between consecutive landmarks (pixels)
+# Less than this suggests collapsed/invalid landmarks
+MIN_LANDMARK_SPACING_PX = 5.0
+
+# Minimum total finger length from MCP to TIP (pixels)
+# Entire finger less than this suggests invalid detection
+MIN_FINGER_LENGTH_PX = 20.0
+
+
+# =============================================================================
+# Finger Axis Estimation Constants
+# =============================================================================
+
+# Epsilon for avoiding division by zero in normalization
+EPSILON = 1e-8
+
+# Minimum number of mask points required for PCA
+MIN_MASK_POINTS_FOR_PCA = 10
+
+# Sample distance factor for endpoint thickness heuristic
+# Used when determining palm vs tip end without landmarks
+ENDPOINT_SAMPLE_DISTANCE_FACTOR = 0.1  # 10% of finger length
+
+
+# =============================================================================
+# Ring Zone Localization Constants
+# =============================================================================
+
+# Default ring zone position as percentage of finger length from palm
+DEFAULT_ZONE_START_PCT = 0.15  # 15% from palm end
+DEFAULT_ZONE_END_PCT = 0.25    # 25% from palm end
+
+# Anatomical zone width factor (for anatomical localization mode)
+# Zone width = MCP-PIP distance * this factor
+ANATOMICAL_ZONE_WIDTH_FACTOR = 0.5  # 50% of MCP-PIP segment (25% each side)
+
+
+# =============================================================================
+# Line-Contour Intersection Constants
+# =============================================================================
+
+# Minimum determinant value to detect parallel lines
+MIN_DETERMINANT_FOR_INTERSECTION = 1e-8

src/image_quality.py

@@ -0,0 +1,181 @@
+"""
+Image quality assessment utilities.
+
+This module handles:
+- Blur detection using Laplacian variance
+- Exposure/contrast analysis
+- Overall quality scoring
+"""
+
+import cv2
+import numpy as np
+from typing import Dict, Any, Tuple
+
+
+# Quality thresholds
+BLUR_THRESHOLD = 20.0  # Laplacian variance below this is considered blurry
+MIN_BRIGHTNESS = 40  # Mean brightness below this is underexposed
+MAX_BRIGHTNESS = 220  # Mean brightness above this is overexposed
+MIN_CONTRAST = 30  # Std dev below this indicates low contrast
+
+
+def detect_blur(image: np.ndarray) -> Tuple[float, bool]:
+    """
+    Detect image blur using Laplacian variance method.
+
+    The Laplacian operator highlights regions of rapid intensity change,
+    so a well-focused image will have high variance in Laplacian response.
+
+    Args:
+        image: Input BGR image
+
+    Returns:
+        Tuple of (blur_score, is_sharp)
+        - blur_score: Laplacian variance (higher = sharper)
+        - is_sharp: True if image passes sharpness threshold
+    """
+    # Convert to grayscale if needed
+    if len(image.shape) == 3:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    else:
+        gray = image
+
+    # Compute Laplacian
+    laplacian = cv2.Laplacian(gray, cv2.CV_64F)
+
+    # Variance of Laplacian indicates focus quality
+    blur_score = laplacian.var()
+
+    is_sharp = blur_score >= BLUR_THRESHOLD
+
+    return blur_score, is_sharp
+
+
+def check_exposure(image: np.ndarray) -> Dict[str, Any]:
+    """
+    Check image exposure and contrast using histogram analysis.
+
+    Args:
+        image: Input BGR image
+
+    Returns:
+        Dictionary containing:
+        - brightness: Mean brightness (0-255)
+        - contrast: Standard deviation of brightness
+        - is_underexposed: True if image is too dark
+        - is_overexposed: True if image is too bright
+        - has_good_contrast: True if contrast is sufficient
+    """
+    # Convert to grayscale if needed
+    if len(image.shape) == 3:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    else:
+        gray = image
+
+    # Calculate statistics
+    brightness = float(np.mean(gray))
+    contrast = float(np.std(gray))
+
+    # Check exposure conditions
+    is_underexposed = brightness < MIN_BRIGHTNESS
+    is_overexposed = brightness > MAX_BRIGHTNESS
+    has_good_contrast = contrast >= MIN_CONTRAST
+
+    return {
+        "brightness": brightness,
+        "contrast": contrast,
+        "is_underexposed": is_underexposed,
+        "is_overexposed": is_overexposed,
+        "has_good_contrast": has_good_contrast,
+    }
+
+
+def check_resolution(image: np.ndarray, min_dimension: int = 720) -> Dict[str, Any]:
+    """
+    Check if image resolution is sufficient.
+
+    Args:
+        image: Input BGR image
+        min_dimension: Minimum acceptable dimension (default 720 for 720p)
+
+    Returns:
+        Dictionary containing:
+        - width: Image width in pixels
+        - height: Image height in pixels
+        - is_sufficient: True if resolution meets minimum
+    """
+    height, width = image.shape[:2]
+    min_dim = min(width, height)
+
+    return {
+        "width": width,
+        "height": height,
+        "is_sufficient": min_dim >= min_dimension,
+    }
+
+
+def assess_image_quality(image: np.ndarray) -> Dict[str, Any]:
+    """
+    Comprehensive image quality assessment.
+
+    Combines blur detection, exposure check, and resolution check
+    to determine if image is suitable for processing.
+
+    Args:
+        image: Input BGR image
+
+    Returns:
+        Dictionary containing:
+        - passed: True if image passes all quality checks
+        - blur_score: Laplacian variance score
+        - brightness: Mean brightness
+        - contrast: Standard deviation
+        - resolution: (width, height)
+        - issues: List of quality issues found
+        - fail_reason: Primary failure reason if failed, else None
+    """
+    issues = []
+    fail_reason = None
+
+    # Check blur
+    blur_score, is_sharp = detect_blur(image)
+    if not is_sharp:
+        issues.append(f"Image is blurry (score: {blur_score:.1f}, threshold: {BLUR_THRESHOLD})")
+        if fail_reason is None:
+            fail_reason = "image_too_blurry"
+
+    # Check exposure
+    exposure = check_exposure(image)
+    if exposure["is_underexposed"]:
+        issues.append(f"Image is underexposed (brightness: {exposure['brightness']:.1f})")
+        if fail_reason is None:
+            fail_reason = "image_underexposed"
+    if exposure["is_overexposed"]:
+        issues.append(f"Image is overexposed (brightness: {exposure['brightness']:.1f})")
+        if fail_reason is None:
+            fail_reason = "image_overexposed"
+    if not exposure["has_good_contrast"]:
+        issues.append(f"Image has low contrast (std: {exposure['contrast']:.1f})")
+        if fail_reason is None:
+            fail_reason = "image_low_contrast"
+
+    # Check resolution
+    resolution = check_resolution(image)
+    if not resolution["is_sufficient"]:
+        issues.append(
+            f"Resolution too low ({resolution['width']}x{resolution['height']})"
+        )
+        if fail_reason is None:
+            fail_reason = "image_resolution_too_low"
+
+    passed = len(issues) == 0
+
+    return {
+        "passed": passed,
+        "blur_score": round(blur_score, 2),
+        "brightness": round(exposure["brightness"], 2),
+        "contrast": round(exposure["contrast"], 2),
+        "resolution": (resolution["width"], resolution["height"]),
+        "issues": issues,
+        "fail_reason": fail_reason,
+    }

src/visualization.py

@@ -0,0 +1,366 @@
+"""
+Debug visualization utilities.
+
+This module handles:
+- Credit card overlay
+- Finger contour and axis visualization
+- Ring zone highlighting
+- Cross-section measurement display
+- Result annotation
+"""
+
+import cv2
+import numpy as np
+from typing import Dict, Any, Optional, List, Tuple
+
+# Import shared visualization constants
+from .viz_constants import (
+    FONT_FACE,
+    Color,
+    FontScale,
+    FontThickness,
+    Size,
+    Layout,
+    get_scaled_font_size,
+)
+
+# Font scaling parameters (specific to final visualization)
+FONT_BASE_SCALE = FontScale.BODY  # Base font scale at reference height
+FONT_REFERENCE_HEIGHT = 1200  # Reference image height for font scaling
+FONT_MIN_SCALE = FontScale.BODY  # Minimum font scale regardless of image size
+
+
+def get_scaled_font_params(image_height: int) -> Dict[str, float]:
+    """
+    Calculate font parameters scaled to image dimensions.
+
+    Args:
+        image_height: Height of the image in pixels
+
+    Returns:
+        Dictionary containing scaled font parameters
+    """
+    font_scale = max(FONT_MIN_SCALE, image_height / FONT_REFERENCE_HEIGHT)
+    scale_factor = font_scale / FONT_BASE_SCALE
+
+    return {
+        "font_scale": font_scale,
+        "text_thickness": int(FontThickness.BODY * scale_factor),
+        "line_thickness": int(Size.LINE_THICK * scale_factor),
+        "contour_thickness": int(Size.CONTOUR_THICK * scale_factor),
+        "corner_radius": int(Size.CORNER_RADIUS * scale_factor),
+        "endpoint_radius": int(Size.ENDPOINT_RADIUS * scale_factor),
+        "intersection_radius": int(Size.INTERSECTION_RADIUS * scale_factor),
+        "text_offset": int(Layout.TEXT_OFFSET_Y * scale_factor),
+        "label_offset": int(Layout.LABEL_OFFSET * scale_factor),
+        "line_height": int(Layout.RESULT_TEXT_LINE_HEIGHT * scale_factor),
+        "y_start": int(Layout.RESULT_TEXT_Y_START * scale_factor),
+        "x_offset": int(Layout.RESULT_TEXT_X_OFFSET * scale_factor),
+    }
+
+
+def create_debug_visualization(
+    image: np.ndarray,
+    card_result: Optional[Dict[str, Any]] = None,
+    contour: Optional[np.ndarray] = None,
+    axis_data: Optional[Dict[str, Any]] = None,
+    zone_data: Optional[Dict[str, Any]] = None,
+    width_data: Optional[Dict[str, Any]] = None,
+    measurement_cm: Optional[float] = None,
+    confidence: Optional[float] = None,
+    scale_px_per_cm: Optional[float] = None,
+) -> np.ndarray:
+    """
+    Create debug visualization overlay on original image.
+
+    Args:
+        image: Original BGR image
+        card_result: Credit card detection result
+        contour: Finger contour points
+        axis_data: Finger axis data
+        zone_data: Ring zone data
+        width_data: Width measurement data
+        measurement_cm: Final measurement in cm
+        confidence: Overall confidence score
+        scale_px_per_cm: Scale factor
+
+    Returns:
+        Annotated BGR image
+    """
+    # Create a copy for drawing
+    vis = image.copy()
+
+    # Draw credit card overlay
+    if card_result is not None:
+        vis = draw_card_overlay(vis, card_result, scale_px_per_cm)
+
+    # Draw finger contour and axis
+    if contour is not None:
+        vis = draw_finger_contour(vis, contour)
+
+    if axis_data is not None:
+        vis = draw_finger_axis(vis, axis_data)
+
+    # Draw ring zone
+    if zone_data is not None and axis_data is not None:
+        vis = draw_ring_zone(vis, zone_data, axis_data)
+
+    # Draw cross-section measurements
+    if width_data is not None and zone_data is not None:
+        vis = draw_cross_sections(vis, width_data)
+
+    # Add measurement annotation with JSON information
+    if measurement_cm is not None and confidence is not None:
+        vis = add_measurement_text(
+            vis,
+            measurement_cm,
+            confidence,
+            scale_px_per_cm=scale_px_per_cm,
+            card_detected=card_result is not None,
+            finger_detected=contour is not None,
+            view_angle_ok=True,  # This is passed from caller
+        )
+
+    return vis
+
+
+def draw_card_overlay(
+    image: np.ndarray,
+    card_result: Dict[str, Any],
+    scale_px_per_cm: Optional[float] = None,
+) -> np.ndarray:
+    """Draw credit card detection overlay."""
+    corners = card_result["corners"].astype(np.int32)
+    params = get_scaled_font_params(image.shape[0])
+
+    # Draw quadrilateral
+    cv2.polylines(image, [corners], isClosed=True, color=Color.CARD,
+                  thickness=params["contour_thickness"])
+
+    # Draw corner points with labels
+    corner_labels = ["TL", "TR", "BR", "BL"]
+    for corner, label in zip(corners, corner_labels):
+        cv2.circle(image, tuple(corner), params["corner_radius"], Color.CARD, -1)
+        cv2.putText(
+            image,
+            label,
+            tuple(corner + np.array([params["label_offset"], -params["label_offset"]])),
+            FONT_FACE,
+            params["font_scale"],
+            Color.CARD,
+            params["text_thickness"],
+        )
+
+    # Add scale annotation
+    if scale_px_per_cm is not None:
+        center = np.mean(corners, axis=0).astype(np.int32)
+        text = f"Card: {scale_px_per_cm:.1f} px/cm"
+        cv2.putText(
+            image,
+            text,
+            tuple(center),
+            FONT_FACE,
+            params["font_scale"] * 1.2,
+            Color.CARD,
+            params["text_thickness"],
+        )
+
+    return image
+
+
+def draw_finger_contour(
+    image: np.ndarray,
+    contour: np.ndarray,
+) -> np.ndarray:
+    """Draw finger contour."""
+    params = get_scaled_font_params(image.shape[0])
+    contour_int = contour.astype(np.int32).reshape((-1, 1, 2))
+    cv2.polylines(image, [contour_int], isClosed=True, color=Color.FINGER,
+                  thickness=params["contour_thickness"])
+    return image
+
+
+def draw_finger_axis(
+    image: np.ndarray,
+    axis_data: Dict[str, Any],
+) -> np.ndarray:
+    """Draw finger axis line."""
+    palm_end = axis_data["palm_end"].astype(np.int32)
+    tip_end = axis_data["tip_end"].astype(np.int32)
+    params = get_scaled_font_params(image.shape[0])
+
+    # Draw axis line
+    cv2.line(image, tuple(palm_end), tuple(tip_end), Color.AXIS_LINE,
+             params["line_thickness"])
+
+    # Mark endpoints
+    cv2.circle(image, tuple(palm_end), params["endpoint_radius"], Color.AXIS_PALM, -1)
+    cv2.circle(image, tuple(tip_end), params["endpoint_radius"], Color.AXIS_TIP, -1)
+
+    # Add labels
+    cv2.putText(
+        image,
+        "Palm",
+        tuple(palm_end + np.array([params["text_offset"], params["text_offset"]])),
+        FONT_FACE,
+        params["font_scale"],
+        Color.AXIS_PALM,
+        params["text_thickness"],
+    )
+    cv2.putText(
+        image,
+        "Tip",
+        tuple(tip_end + np.array([params["text_offset"], params["text_offset"]])),
+        FONT_FACE,
+        params["font_scale"],
+        Color.AXIS_TIP,
+        params["text_thickness"],
+    )
+
+    return image
+
+
+def draw_ring_zone(
+    image: np.ndarray,
+    zone_data: Dict[str, Any],
+    axis_data: Dict[str, Any],
+) -> np.ndarray:
+    """Draw ring-wearing zone band."""
+    direction = axis_data["direction"]
+    perp = np.array([-direction[1], direction[0]], dtype=np.float32)
+
+    start_point = zone_data["start_point"]
+    end_point = zone_data["end_point"]
+
+    # Create zone band (perpendicular lines at start and end)
+    # Make the band wide enough to be visible
+    band_width = 200  # pixels
+
+    start_left = start_point + perp * band_width
+    start_right = start_point - perp * band_width
+    end_left = end_point + perp * band_width
+    end_right = end_point - perp * band_width
+
+    # Draw zone band as a semi-transparent overlay
+    overlay = image.copy()
+    zone_poly = np.array([start_left, start_right, end_right, end_left], dtype=np.int32)
+    cv2.fillPoly(overlay, [zone_poly], Color.RING_ZONE)
+    cv2.addWeighted(overlay, 0.2, image, 0.8, 0, image)
+
+    # Draw zone boundaries
+    params = get_scaled_font_params(image.shape[0])
+    cv2.line(
+        image,
+        tuple(start_left.astype(np.int32)),
+        tuple(start_right.astype(np.int32)),
+        Color.RING_ZONE,
+        params["line_thickness"],
+    )
+    cv2.line(
+        image,
+        tuple(end_left.astype(np.int32)),
+        tuple(end_right.astype(np.int32)),
+        Color.RING_ZONE,
+        params["line_thickness"],
+    )
+
+    # Add zone label
+    label_offset = int(40 * params["font_scale"] / FONT_BASE_SCALE)
+    label_pos = zone_data["center_point"].astype(np.int32) + np.array([band_width + label_offset, 0], dtype=np.int32)
+    cv2.putText(
+        image,
+        "Ring Zone",
+        tuple(label_pos),
+        FONT_FACE,
+        params["font_scale"] * 1.2,
+        Color.RING_ZONE,
+        params["text_thickness"],
+    )
+
+    return image
+
+
+def draw_cross_sections(
+    image: np.ndarray,
+    width_data: Dict[str, Any],
+) -> np.ndarray:
+    """Draw cross-section sample lines and intersection points."""
+    params = get_scaled_font_params(image.shape[0])
+    sample_points = width_data.get("sample_points", [])
+
+    for left, right in sample_points:
+        left_int = tuple(np.array(left, dtype=np.int32))
+        right_int = tuple(np.array(right, dtype=np.int32))
+
+        # Draw cross-section line
+        cv2.line(image, left_int, right_int, Color.CROSS_SECTION,
+                 max(2, params["line_thickness"] // 2))
+
+        # Draw intersection points
+        cv2.circle(image, left_int, params["intersection_radius"], Color.POINT, -1)
+        cv2.circle(image, right_int, params["intersection_radius"], Color.POINT, -1)
+
+    return image
+
+
+def add_measurement_text(
+    image: np.ndarray,
+    measurement_cm: float,
+    confidence: float,
+    scale_px_per_cm: Optional[float] = None,
+    card_detected: bool = True,
+    finger_detected: bool = True,
+    view_angle_ok: bool = True,
+) -> np.ndarray:
+    """Add measurement result text overlay with JSON information."""
+    h, w = image.shape[:2]
+
+    # Create larger semi-transparent background for more text
+    overlay = image.copy()
+    cv2.rectangle(overlay, (10, 10), (1100, 550), (0, 0, 0), -1)
+    cv2.addWeighted(overlay, 0.7, image, 0.3, 0, image)
+
+    # Confidence level indicator
+    if confidence > 0.85:
+        level = "HIGH"
+        level_color = Color.TEXT_SUCCESS
+    elif confidence >= 0.6:
+        level = "MEDIUM"
+        level_color = (0, 255, 255)  # Yellow
+    else:
+        level = "LOW"
+        level_color = Color.TEXT_ERROR
+
+    # Build text lines with JSON information
+    text_lines = [
+        ("=== MEASUREMENT RESULT ===", Color.TEXT_PRIMARY, False),
+        (f"Finger Diameter: {measurement_cm:.2f} cm", Color.TEXT_PRIMARY, False),
+        (f"Confidence: {confidence:.3f} ({level})", level_color, True),
+        ("", Color.TEXT_PRIMARY, False),  # Empty line
+        ("=== QUALITY FLAGS ===", Color.TEXT_PRIMARY, False),
+        (f"Card Detected: {'YES' if card_detected else 'NO'}", Color.TEXT_SUCCESS if card_detected else Color.TEXT_ERROR, False),
+        (f"Finger Detected: {'YES' if finger_detected else 'NO'}", Color.TEXT_SUCCESS if finger_detected else Color.TEXT_ERROR, False),
+        (f"View Angle OK: {'YES' if view_angle_ok else 'NO'}", Color.TEXT_SUCCESS if view_angle_ok else Color.TEXT_ERROR, False),
+    ]
+
+    # Add scale information if available
+    if scale_px_per_cm is not None:
+        text_lines.insert(3, (f"Scale: {scale_px_per_cm:.2f} px/cm", Color.TEXT_PRIMARY, False))
+
+    # Get scaled font parameters
+    params = get_scaled_font_params(image.shape[0])
+
+    for i, (text, color, is_bold) in enumerate(text_lines):
+        if text:  # Skip empty lines for drawing
+            thickness = params["text_thickness"] + 1 if is_bold else params["text_thickness"]
+            cv2.putText(
+                image,
+                text,
+                (params["x_offset"], params["y_start"] + i * params["line_height"]),
+                FONT_FACE,
+                params["font_scale"],
+                color,
+                thickness,
+            )
+
+    return image

src/viz_constants.py

@@ -0,0 +1,306 @@
+"""
+Shared visualization constants for debug output across all algorithms.
+
+This module provides centralized configuration for fonts, colors, sizes, and
+layout used in debug visualizations throughout the Ring Sizer system.
+
+Used by:
+- card_detection.py - Multi-strategy card detection debug output
+- finger_segmentation.py - Hand/finger detection debug output
+- geometry.py - Axis, zone, measurement debug output
+- visualization.py - Final composite debug overlay
+- confidence.py - Confidence visualization
+
+Example usage:
+    from viz_constants import Color, FontScale, FontThickness, FONT_FACE
+
+    cv2.putText(img, "Title", (20, 100), FONT_FACE,
+                FontScale.TITLE, Color.WHITE,
+                FontThickness.TITLE_OUTLINE, cv2.LINE_AA)
+"""
+
+import cv2
+from typing import Tuple
+
+# ============================================================================
+# FONT SETTINGS
+# ============================================================================
+
+# Font face used across all visualizations
+FONT_FACE = cv2.FONT_HERSHEY_SIMPLEX
+
+
+class FontScale:
+    """
+    Font scale constants for text hierarchy levels.
+
+    Larger values = bigger text. These are base scales that may be
+    adjusted based on image size in some visualizations.
+    """
+    TITLE = 3.5          # Main titles (e.g., "Card Detection", "Final Result")
+    SUBTITLE = 2.5       # Section headers (e.g., "Score: 0.85")
+    LABEL = 1.8          # Inline labels (e.g., "#1 Score:0.83")
+    BODY = 1.5           # Body text (normal annotations)
+    SMALL = 1.0          # Small text (fine details)
+
+
+class FontThickness:
+    """
+    Font thickness (stroke width) for text rendering.
+
+    Larger values = thicker/bolder text.
+    Use OUTLINE variants for background layer to create outlined text effect.
+    """
+    # Main text thickness
+    TITLE = 7
+    SUBTITLE = 5
+    LABEL = 4
+    BODY = 2
+
+    # Outline/shadow thickness (draw first for outline effect)
+    TITLE_OUTLINE = 10
+    SUBTITLE_OUTLINE = 8
+    LABEL_OUTLINE = 6
+    BODY_OUTLINE = 4
+
+
+# ============================================================================
+# COLORS (BGR format for OpenCV)
+# ============================================================================
+
+class Color:
+    """
+    Standard colors used across all visualizations.
+
+    All colors in BGR format (Blue, Green, Red) as required by OpenCV.
+    Example: (255, 255, 255) = White in BGR
+
+    Usage:
+        cv2.circle(img, center, radius, Color.GREEN, -1)
+    """
+    # ========================================================================
+    # Basic Colors
+    # ========================================================================
+    WHITE = (255, 255, 255)
+    BLACK = (0, 0, 0)
+    RED = (0, 0, 255)      # BGR: (0, 0, 255)
+    GREEN = (0, 255, 0)     # BGR: (0, 255, 0)
+    BLUE = (255, 0, 0)      # BGR: (255, 0, 0)
+
+    # ========================================================================
+    # Extended Palette
+    # ========================================================================
+    CYAN = (255, 255, 0)    # BGR: (255, 255, 0)
+    YELLOW = (0, 255, 255)   # BGR: (0, 255, 255)
+    MAGENTA = (255, 0, 255)  # BGR: (255, 0, 255)
+    ORANGE = (0, 128, 255)   # BGR: (0, 128, 255)
+    PINK = (128, 128, 255)   # BGR: (128, 128, 255)
+
+    # ========================================================================
+    # Semantic Colors (what they represent in the system)
+    # ========================================================================
+
+    # Object colors
+    CARD = GREEN            # Credit card outline
+    FINGER = MAGENTA        # Finger contour
+
+    # Axis/geometry colors
+    AXIS_PALM = CYAN        # Palm-side axis endpoint
+    AXIS_TIP = ORANGE       # Fingertip axis endpoint
+    AXIS_LINE = YELLOW      # Finger principal axis line
+
+    # Measurement colors
+    RING_ZONE = CYAN        # Ring-wearing zone overlay
+    CROSS_SECTION = ORANGE  # Cross-section lines
+    POINT = BLUE            # Intersection/measurement points
+
+    # Text colors
+    TEXT_PRIMARY = WHITE    # Primary text (titles, main info)
+    TEXT_SUCCESS = GREEN    # Success messages
+    TEXT_ERROR = RED        # Error messages
+    TEXT_WARNING = YELLOW   # Warning messages
+
+
+class StrategyColor:
+    """
+    Colors for different card detection strategies.
+
+    Used to visually distinguish candidates from different detection methods
+    in debug visualizations.
+    """
+    CANNY = Color.CYAN           # Canny edge detection (cyan)
+    ADAPTIVE = Color.ORANGE      # Adaptive thresholding (orange)
+    OTSU = Color.MAGENTA         # Otsu's thresholding (magenta)
+    COLOR_BASED = Color.GREEN    # Color-based detection (green)
+    ALL_CANDIDATES = Color.PINK  # Combined candidates (pink/purple)
+
+
+# ============================================================================
+# DRAWING SIZES
+# ============================================================================
+
+class Size:
+    """
+    Size constants for drawing geometric elements (circles, lines, etc.).
+
+    All sizes in pixels.
+    """
+    # Circle radii
+    CORNER_RADIUS = 8           # Card corners, small points
+    ENDPOINT_RADIUS = 15        # Axis endpoints (palm/tip)
+    INTERSECTION_RADIUS = 8     # Cross-section intersection points
+    POINT_RADIUS = 5            # Generic points
+
+    # Line thicknesses
+    CONTOUR_THICK = 5           # Thick contours (finger, card)
+    CONTOUR_NORMAL = 3          # Normal contours (candidates)
+    LINE_THICK = 4              # Thick lines (axis)
+    LINE_NORMAL = 2             # Normal lines (cross-sections)
+    LINE_THIN = 1               # Thin lines (grid, reference)
+
+
+# ============================================================================
+# LAYOUT CONSTANTS
+# ============================================================================
+
+class Layout:
+    """
+    Layout positioning constants for text and elements.
+
+    All positions in pixels from top-left corner.
+    """
+    # Title positioning (top-left text block)
+    TITLE_Y = 100               # Y position for main title
+    SUBTITLE_Y = 200            # Y position for subtitle/secondary text
+    LINE_SPACING = 100          # Vertical spacing between text lines
+
+    # Text offsets
+    TEXT_OFFSET_X = 20          # Horizontal margin from left edge
+    TEXT_OFFSET_Y = 25          # Vertical offset for inline text
+    LABEL_OFFSET = 20           # Offset for labels near objects
+
+    # Result text area (final visualization)
+    RESULT_TEXT_Y_START = 60           # Starting Y for result text block
+    RESULT_TEXT_LINE_HEIGHT = 55       # Height between result text lines
+    RESULT_TEXT_X_OFFSET = 40          # X offset for result text
+
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+def get_scaled_font_size(base_scale: float, image_height: int,
+                         reference_height: int = 1200,
+                         min_scale: float = 1.5) -> float:
+    """
+    Scale font size based on image dimensions for consistent appearance.
+
+    Args:
+        base_scale: Base font scale (e.g., FontScale.TITLE)
+        image_height: Height of the image in pixels
+        reference_height: Reference height for scaling (default: 1200px)
+        min_scale: Minimum scale to prevent text from being too small
+
+    Returns:
+        Scaled font size adjusted for image dimensions
+
+    Example:
+        # For a 2400px tall image, double the font size
+        scale = get_scaled_font_size(FontScale.TITLE, 2400)
+        # scale = 3.5 * 2 = 7.0
+    """
+    scale_factor = image_height / reference_height
+    scaled = base_scale * scale_factor
+    return max(scaled, min_scale)
+
+
+def create_outlined_text(image, text, position, font_scale,
+                        color, outline_color=None,
+                        thickness=None, outline_thickness=None):
+    """
+    Draw text with outline for better visibility.
+
+    Args:
+        image: Image to draw on
+        text: Text string to draw
+        position: (x, y) position tuple
+        font_scale: Font scale (from FontScale)
+        color: Main text color (from Color)
+        outline_color: Outline color (default: Color.WHITE)
+        thickness: Main text thickness (auto-selected if None)
+        outline_thickness: Outline thickness (auto-selected if None)
+
+    Example:
+        create_outlined_text(img, "Title", (20, 100),
+                           FontScale.TITLE, Color.GREEN)
+    """
+    if outline_color is None:
+        outline_color = Color.WHITE
+
+    # Auto-select thickness based on font scale
+    if thickness is None:
+        if font_scale >= FontScale.TITLE:
+            thickness = FontThickness.TITLE
+        elif font_scale >= FontScale.SUBTITLE:
+            thickness = FontThickness.SUBTITLE
+        elif font_scale >= FontScale.LABEL:
+            thickness = FontThickness.LABEL
+        else:
+            thickness = FontThickness.BODY
+
+    if outline_thickness is None:
+        outline_thickness = thickness + 3
+
+    # Draw outline first (background layer)
+    cv2.putText(image, text, position, FONT_FACE,
+                font_scale, outline_color, outline_thickness, cv2.LINE_AA)
+
+    # Draw main text on top
+    cv2.putText(image, text, position, FONT_FACE,
+                font_scale, color, thickness, cv2.LINE_AA)
+
+
+# ============================================================================
+# VALIDATION (Optional: for type checking and debugging)
+# ============================================================================
+
+def validate_color(color: Tuple[int, int, int]) -> bool:
+    """
+    Validate that a color tuple is in correct BGR format.
+
+    Args:
+        color: Tuple of (B, G, R) values
+
+    Returns:
+        True if valid, False otherwise
+    """
+    if not isinstance(color, tuple) or len(color) != 3:
+        return False
+    return all(0 <= val <= 255 for val in color)
+
+
+# ============================================================================
+# EXPORTS
+# ============================================================================
+
+__all__ = [
+    # Font settings
+    'FONT_FACE',
+    'FontScale',
+    'FontThickness',
+
+    # Colors
+    'Color',
+    'StrategyColor',
+
+    # Sizes
+    'Size',
+
+    # Layout
+    'Layout',
+
+    # Helper functions
+    'get_scaled_font_size',
+    'create_outlined_text',
+    'validate_color',
+]

web_demo/README.md

@@ -0,0 +1,28 @@
+# Web Demo
+
+Local Flask demo for ring-size-cv. Upload an image, run measurement, and return JSON + debug overlay.
+
+## Setup
+
+```bash
+cd /Users/fengxie/Build/ring-size-cv
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Run
+
+```bash
+python web_demo/app.py
+```
+
+Open `http://localhost:8000`.
+
+## Notes
+- Uploads stored in `web_demo/uploads/`
+- Results stored in `web_demo/results/`
+- Debug overlay auto-generated per request
+- Default guided sample image is at `web_demo/static/examples/default_sample.jpg`
+- `Start Measurement` uses the default sample image when no upload is selected
+- Web demo enforces Sobel edge refinement only (`edge_method=sobel`)

web_demo/app.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Simple web demo for ring-size-cv.
+
+Upload an image, run measurement, and return JSON + debug overlay.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import uuid
+from pathlib import Path
+from typing import Dict, Any
+
+import cv2
+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
+
+APP_ROOT = Path(__file__).resolve().parent
+UPLOAD_DIR = APP_ROOT / "uploads"
+RESULTS_DIR = APP_ROOT / "results"
+DEFAULT_SAMPLE_PATH = APP_ROOT / "static" / "examples" / "default_sample.jpg"
+DEFAULT_SAMPLE_URL = "/static/examples/default_sample.jpg"
+ALLOWED_EXTENSIONS = {".jpg", ".jpeg", ".png"}
+DEMO_EDGE_METHOD = "sobel"
+
+app = Flask(__name__)
+
+
+def _allowed_file(filename: str) -> bool:
+    return Path(filename).suffix.lower() in ALLOWED_EXTENSIONS
+
+
+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)
+
+
+@app.route("/")
+def index():
+    return render_template("index.html", default_sample_url=DEFAULT_SAMPLE_URL)
+
+
+@app.route("/results/<path:filename>")
+def serve_result(filename: str):
+    return send_from_directory(RESULTS_DIR, filename)
+
+
+@app.route("/uploads/<path:filename>")
+def serve_upload(filename: str):
+    return send_from_directory(UPLOAD_DIR, filename)
+
+
+@app.route("/api/measure", methods=["POST"])
+def api_measure():
+    if "image" not in request.files:
+        return jsonify({"success": False, "error": "Missing image file"}), 400
+
+    file = request.files["image"]
+    if file.filename == "":
+        return jsonify({"success": False, "error": "Empty filename"}), 400
+
+    if not _allowed_file(file.filename):
+        return jsonify({"success": False, "error": "Unsupported file type"}), 400
+
+    finger_index = request.form.get("finger_index", "index")
+    run_id = uuid.uuid4().hex[:12]
+    safe_name = secure_filename(file.filename)
+    upload_name = f"{run_id}__{safe_name}"
+    upload_path = UPLOAD_DIR / upload_name
+    upload_path.parent.mkdir(parents=True, exist_ok=True)
+    file.save(upload_path)
+
+    image = cv2.imread(str(upload_path))
+    if image is None:
+        return jsonify({"success": False, "error": "Failed to load image"}), 400
+
+    return _run_measurement(
+        image=image,
+        finger_index=finger_index,
+        input_image_url=f"/uploads/{upload_name}",
+    )
+
+
+@app.route("/api/measure-default", methods=["POST"])
+def api_measure_default():
+    finger_index = request.form.get("finger_index", "index")
+    if not DEFAULT_SAMPLE_PATH.exists():
+        return jsonify({"success": False, "error": "Default sample image not found"}), 500
+
+    image = cv2.imread(str(DEFAULT_SAMPLE_PATH))
+    if image is None:
+        return jsonify({"success": False, "error": "Failed to load default sample image"}), 500
+
+    return _run_measurement(
+        image=image,
+        finger_index=finger_index,
+        input_image_url=DEFAULT_SAMPLE_URL,
+    )
+
+
+def _run_measurement(
+    image,
+    finger_index: str,
+    input_image_url: str,
+):
+    run_id = uuid.uuid4().hex[:12]
+
+    result_png_name = f"{run_id}__result.png"
+    result_png_path = RESULTS_DIR / result_png_name
+
+    result = measure_finger(
+        image=image,
+        finger_index=finger_index,
+        edge_method=DEMO_EDGE_METHOD,
+        result_png_path=str(result_png_path),
+        save_debug=False,
+    )
+
+    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)
+
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=8000, debug=True)

web_demo/static/app.js

@@ -0,0 +1,145 @@
+const form = document.getElementById("measureForm");
+const imageInput = document.getElementById("imageInput");
+const statusText = document.getElementById("statusText");
+const inputPreview = document.getElementById("inputPreview");
+const debugPreview = document.getElementById("debugPreview");
+const inputFrame = document.getElementById("inputFrame");
+const debugFrame = document.getElementById("debugFrame");
+const jsonOutput = document.getElementById("jsonOutput");
+const jsonLink = document.getElementById("jsonLink");
+const defaultSampleUrl = window.DEFAULT_SAMPLE_URL || "";
+const failReasonMessageMap = {
+  card_not_detected:
+    "Credit card not detected. Place a full card flat beside your hand.",
+  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_mask_too_small:
+    "Finger region is too small. Move closer and use a higher-resolution photo.",
+  contour_extraction_failed:
+    "Finger contour extraction failed. Improve lighting and reduce background clutter.",
+  axis_estimation_failed:
+    "Finger axis estimation failed. Keep the finger straight and fully visible.",
+  zone_localization_failed:
+    "Ring zone localization failed. Keep more of the finger base visible.",
+  width_measurement_failed:
+    "Width measurement failed. Retake with phone parallel to the table and steady focus.",
+  sobel_edge_refinement_failed:
+    "Edge refinement failed. Turn on flash or use stronger, even lighting.",
+  width_unreasonable:
+    "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.",
+};
+
+const formatFailReasonStatus = (failReason) => {
+  if (!failReason) {
+    return "Measurement failed.";
+  }
+
+  if (failReason.startsWith("quality_score_low_")) {
+    return `Low edge quality detected. Turn on flash and retake. (${failReason})`;
+  }
+
+  if (failReason.startsWith("consistency_low_")) {
+    return `Edge detection was inconsistent. Keep phone parallel to table and retry. (${failReason})`;
+  }
+
+  const friendlyMessage = failReasonMessageMap[failReason];
+  if (friendlyMessage) {
+    return `${friendlyMessage} (${failReason})`;
+  }
+
+  return `Measurement failed: ${failReason}`;
+};
+
+const setStatus = (text) => {
+  statusText.textContent = text;
+};
+
+const showImage = (imgEl, frameEl, url) => {
+  if (!url) return;
+  imgEl.src = url;
+  frameEl.classList.add("show");
+  frameEl.querySelector(".placeholder").style.display = "none";
+};
+
+const buildMeasureSettings = () => {
+  const fingerSelect = form.querySelector('select[name="finger_index"]');
+  return {
+    finger_index: fingerSelect ? fingerSelect.value : "index",
+    edge_method: "sobel",
+  };
+};
+
+const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
+  setStatus("Measuring… Please wait.");
+  jsonOutput.textContent = "{\n  \"status\": \"processing\"\n}";
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      setStatus(error.error || "Measurement failed");
+      return;
+    }
+
+    const data = await response.json();
+    jsonOutput.textContent = JSON.stringify(data.result, null, 2);
+    jsonLink.href = data.result_json_url || "#";
+
+    showImage(inputPreview, inputFrame, data.input_image_url || inputUrlFallback);
+    showImage(debugPreview, debugFrame, data.result_image_url);
+
+    if (data.success) {
+      setStatus("Measurement complete. Results updated.");
+    } else {
+      const failReason = data?.result?.fail_reason;
+      setStatus(formatFailReasonStatus(failReason));
+    }
+  } catch (error) {
+    setStatus("Network error. Please retry.");
+  }
+};
+
+imageInput.addEventListener("change", () => {
+  const file = imageInput.files[0];
+  if (!file) {
+    setStatus("Sample image loaded. Upload your own photo or click Start Measurement.");
+    if (defaultSampleUrl) {
+      showImage(inputPreview, inputFrame, defaultSampleUrl);
+    }
+    return;
+  }
+  const url = URL.createObjectURL(file);
+  showImage(inputPreview, inputFrame, url);
+  setStatus("Image ready. Click to start measurement.");
+});
+
+form.addEventListener("submit", async (event) => {
+  event.preventDefault();
+
+  const settings = buildMeasureSettings();
+  const formData = new FormData();
+  formData.append("finger_index", settings.finger_index);
+  formData.append("edge_method", settings.edge_method);
+
+  const file = imageInput.files[0];
+  if (file) {
+    formData.append("image", file);
+    await runMeasurement("/api/measure", formData);
+    return;
+  }
+
+  await runMeasurement("/api/measure-default", formData, defaultSampleUrl);
+});
+
+if (defaultSampleUrl) {
+  showImage(inputPreview, inputFrame, defaultSampleUrl);
+  setStatus("Sample image loaded. Upload your own photo or click Start Measurement.");
+}

web_demo/static/styles.css

@@ -0,0 +1,288 @@
+:root {
+  --bg-1: #f5f1e7;
+  --bg-2: #eedad5;
+  --bg-3: #e7efe8;
+  --ink: #2b1f1f;
+  --ink-soft: #4b3d3d;
+  --accent: #bf3a2b;
+  --accent-dark: #8f2b22;
+  --sand: #f9f4ec;
+  --shadow: rgba(34, 26, 26, 0.12);
+  --border: rgba(45, 33, 33, 0.18);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  color: var(--ink);
+  background: radial-gradient(circle at 10% 20%, var(--bg-3), transparent 55%),
+              radial-gradient(circle at 80% 10%, var(--bg-2), transparent 50%),
+              linear-gradient(140deg, var(--bg-1), #fff8f2 60%, #f0e2d8 100%);
+  font-family: "Iowan Old Style", "Palatino", "Book Antiqua", "Times New Roman", serif;
+}
+
+.background-orbit {
+  position: fixed;
+  inset: -30% 10% auto auto;
+  width: 60vw;
+  height: 60vw;
+  background: conic-gradient(from 120deg, rgba(191, 58, 43, 0.2), transparent, rgba(91, 44, 120, 0.18));
+  border-radius: 50%;
+  filter: blur(10px);
+  opacity: 0.6;
+  z-index: 0;
+  animation: slow-spin 40s linear infinite;
+}
+
+.background-glow {
+  position: fixed;
+  inset: auto auto -15% -10%;
+  width: 55vw;
+  height: 55vw;
+  background: radial-gradient(circle, rgba(191, 58, 43, 0.18), transparent 70%);
+  border-radius: 50%;
+  filter: blur(20px);
+  z-index: 0;
+}
+
+@keyframes slow-spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+
+.hero {
+  position: relative;
+  z-index: 1;
+  display: grid;
+  grid-template-columns: minmax(280px, 1.2fr) minmax(280px, 0.9fr);
+  gap: 32px;
+  padding: 72px 8vw 48px;
+  align-items: center;
+}
+
+.hero-copy h1 {
+  font-family: "Futura", "Gill Sans", "Optima", "Trebuchet MS", sans-serif;
+  font-size: clamp(2.2rem, 4vw, 3.4rem);
+  margin: 0 0 12px;
+  letter-spacing: 0.02em;
+}
+
+.hero-kicker {
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--accent-dark);
+  margin: 0 0 12px;
+}
+
+.hero-sub {
+  font-size: 1.05rem;
+  line-height: 1.7;
+  color: var(--ink-soft);
+  max-width: 36ch;
+}
+
+.hero-card {
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid var(--border);
+  border-radius: 24px;
+  padding: 28px;
+  box-shadow: 0 24px 60px var(--shadow);
+  backdrop-filter: blur(8px);
+  animation: rise-in 0.8s ease;
+}
+
+@keyframes rise-in {
+  from { transform: translateY(16px); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+
+.file-drop {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 24px;
+  border: 1.5px dashed var(--accent);
+  border-radius: 18px;
+  background: var(--sand);
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.file-drop:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 10px 20px rgba(191, 58, 43, 0.15);
+}
+
+.file-drop input {
+  display: none;
+}
+
+.file-title {
+  font-size: 1.1rem;
+  font-weight: 600;
+}
+
+.file-hint {
+  font-size: 0.9rem;
+  color: var(--ink-soft);
+}
+
+.controls {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 16px;
+  margin: 20px 0;
+}
+
+.controls label {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 0.9rem;
+  color: var(--ink-soft);
+}
+
+select {
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 10px 12px;
+  font-size: 0.95rem;
+  background: white;
+  color: var(--ink);
+}
+
+.primary {
+  width: 100%;
+  border: none;
+  border-radius: 14px;
+  padding: 12px 16px;
+  font-size: 1rem;
+  font-weight: 600;
+  color: white;
+  background: linear-gradient(120deg, var(--accent), #e25f4f);
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.primary:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 12px 24px rgba(191, 58, 43, 0.25);
+}
+
+.status {
+  margin-top: 12px;
+  font-size: 0.9rem;
+  color: var(--ink-soft);
+}
+
+.content {
+  position: relative;
+  z-index: 1;
+  padding: 0 8vw 80px;
+  display: flex;
+  flex-direction: column;
+  gap: 28px;
+}
+
+.preview,
+.result {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 24px;
+}
+
+.panel {
+  background: rgba(255, 255, 255, 0.78);
+  border-radius: 20px;
+  border: 1px solid var(--border);
+  padding: 20px;
+  box-shadow: 0 18px 40px rgba(43, 31, 31, 0.08);
+  backdrop-filter: blur(6px);
+}
+
+.panel h2 {
+  margin: 0 0 12px;
+  font-family: "Futura", "Gill Sans", "Optima", "Trebuchet MS", sans-serif;
+}
+
+.panel-head {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 12px;
+}
+
+.ghost {
+  text-decoration: none;
+  font-size: 0.85rem;
+  color: var(--accent-dark);
+  border: 1px solid var(--border);
+  padding: 6px 10px;
+  border-radius: 999px;
+  background: white;
+}
+
+.image-frame {
+  position: relative;
+  border-radius: 16px;
+  overflow: hidden;
+  background: #f6efea;
+  min-height: 260px;
+  display: grid;
+  place-items: center;
+}
+
+.image-frame img {
+  width: 100%;
+  height: auto;
+  display: none;
+}
+
+.image-frame.show img {
+  display: block;
+}
+
+.placeholder {
+  color: var(--ink-soft);
+  font-size: 0.95rem;
+}
+
+pre {
+  background: #1f1717;
+  color: #f7ece8;
+  padding: 16px;
+  border-radius: 16px;
+  min-height: 240px;
+  overflow: auto;
+  font-size: 0.85rem;
+  line-height: 1.6;
+}
+
+.tips ul {
+  margin: 0;
+  padding-left: 0;
+  list-style: none;
+  color: var(--ink-soft);
+  line-height: 1.7;
+}
+
+.tips li + li {
+  margin-top: 4px;
+}
+
+@media (max-width: 960px) {
+  .hero {
+    grid-template-columns: 1fr;
+    padding: 56px 6vw 36px;
+  }
+
+  .hero-copy h1 {
+    font-size: 2.4rem;
+  }
+}

web_demo/templates/index.html

@@ -0,0 +1,96 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Ring Size CV Demo</title>
+  <link rel="stylesheet" href="/static/styles.css" />
+</head>
+<body>
+  <div class="background-orbit"></div>
+  <div class="background-glow"></div>
+
+  <header class="hero">
+    <div class="hero-copy">
+      <p class="hero-kicker">Ring Size CV · Web Demo</p>
+      <h1>Upload a photo to quickly measure ring size</h1>
+      <p class="hero-sub">
+        Runs locally with no cloud upload. Results include JSON output and a visual overlay.
+      </p>
+    </div>
+    <div class="hero-card">
+      <form id="measureForm">
+        <label class="file-drop" for="imageInput">
+          <input id="imageInput" name="image" type="file" accept="image/*" />
+          <span class="file-title">Click or drag to upload a photo</span>
+          <span class="file-hint">JPG / PNG supported · 1080p or higher recommended</span>
+        </label>
+
+        <div class="controls">
+          <label>
+            <span>Finger Selection</span>
+            <select name="finger_index">
+              <option value="index" selected>Index (Default)</option>
+              <option value="middle">Middle</option>
+              <option value="ring">Ring</option>
+              <option value="pinky">Pinky</option>
+              <option value="auto">Auto</option>
+            </select>
+          </label>
+          <label>
+            <span>Edge Method</span>
+            <select name="edge_method" disabled aria-disabled="true">
+              <option value="sobel" selected>Sobel (Locked)</option>
+            </select>
+          </label>
+        </div>
+
+        <button class="primary" type="submit">Start Measurement</button>
+        <p class="status" id="statusText">Waiting for image…</p>
+      </form>
+    </div>
+  </header>
+
+  <main class="content">
+    <section class="preview">
+      <div class="panel">
+        <h2>Input Photo</h2>
+        <div class="image-frame show" id="inputFrame">
+          <img id="inputPreview" src="{{ default_sample_url }}" alt="Default sample photo example" />
+          <p class="placeholder" style="display:none;">No image yet</p>
+        </div>
+      </div>
+
+      <div class="panel">
+        <h2>Result Overlay</h2>
+        <div class="image-frame" id="debugFrame">
+          <img id="debugPreview" alt="" />
+          <p class="placeholder">Waiting for result</p>
+        </div>
+      </div>
+    </section>
+
+    <section class="result">
+      <div class="panel">
+        <div class="panel-head">
+          <h2>JSON Output</h2>
+          <a id="jsonLink" class="ghost" href="#" target="_blank" rel="noreferrer">Open raw JSON</a>
+        </div>
+        <pre id="jsonOutput">{}</pre>
+      </div>
+
+      <div class="panel tips">
+        <h2>Photo Tips</h2>
+        <ul>
+          <li>✓ Turn on flash</li>
+          <li>✓ Keep phone parallel to table</li>
+          <li>✓ Include full palm in frame</li>
+        </ul>
+      </div>
+    </section>
+  </main>
+
+  <script>window.DEFAULT_SAMPLE_URL = "{{ default_sample_url }}";</script>
+  <script src="/static/app.js"></script>
+</body>
+</html>