initial setup

Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+COPY . /app
+
+RUN pip install --no-cache-dir -r requirements.txt
+
+EXPOSE 7860
+CMD ["python", "app.py"]

README.md

@@ -1,10 +1,53 @@
 ---
-title: SOL9X FINGER QUALITY API
-emoji: 📉
-colorFrom: purple
-colorTo: pink
+title: Flask Finger Quality API
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Here is how to read each score and why some “good-looking” images still fail overall.  
+
+***
+
+## 1. What each score means
+
+These ranges are based on the thresholds used in the code you ran (blur_min=80, illum_min=60, illum_max=200, coverage_min=0.10, orientation_max_deviation=30, vertical_expected=True).  
+
+### Blur score (variance of Laplacian)
+
+- Metric: “How sharp is the finger texture?” Higher is better.  
+- Rough scale (with current threshold 80):
+  - 0–30 → Very blurry (fail).
+  - 30–60 → Soft / borderline sharpness (often fail, might be visually OK).
+  - 80–200 → Good sharpness for most mobile cases (pass).
+  - 200+ → Very sharp (pass).  
+
+### Illumination score (mean grayscale in ROI)
+
+- Metric: “Average brightness of the finger region.”  
+- Thresholds now: 60 ≤ illumination ≤ 200.  
+- Rough interpretation:
+  - < 50 → Too dark / underexposed (fail).
+  - 50–200 → Acceptable brightness (pass).
+  - > 200 → Too bright / overexposed (fail).  
+
+### Coverage ratio
+
+- Metric: “Fraction of the full frame covered by segmented finger pixels.”  
+- Threshold now: coverage ≥ 0.10 (10% of frame).  
+- Rough interpretation:
+  - < 0.10 → Finger too small, far away, or segmentation bad (fail).
+  - 0.10–0.20 → Minimum acceptable; finger is present but not very large.
+  - ≥ 0.20–0.40 → Good coverage for biometric capture (pass).  
+
+### Orientation angle
+
+- Metric: PCA angle of the main axis of the finger ROI, in degrees relative to x‑axis, normalized to about −90° to 90°.  
+- With `vertical_expected=True`, the code expects the finger to be **vertical** (angle near ±90°).  
+- Threshold now: within 30° of the expected orientation.  
+  - If vertical expected:
+    - Angles near +90° or −90° → good.
+    - Big deviation from vertical → fail. Deviation allowed - 45°
+  - If horizontal finger is desired, you would set `vertical_expected=False` to expect angles near 0°.  
+
+***
+

app.py

@@ -0,0 +1,93 @@
+from flask import Flask, request, jsonify
+import numpy as np
+import cv2
+
+# import your existing code
+from main import FingerQualityAssessor  # or wherever the class lives
+from quality_analyzer import QualityConfig
+
+app = Flask(__name__)
+
+# Create once (so model/config not recreated per request)
+CONFIG = QualityConfig(
+    target_width=640,
+    blur_min=60.0,
+    illum_min=50.0,
+    illum_max=200.0,
+    coverage_min=0.10,
+    orientation_max_deviation=45.0,
+    vertical_expected=True,
+    overall_quality_threshold=0.70,
+)
+ASSESSOR = FingerQualityAssessor(CONFIG)
+
+
+def _decode_uploaded_image(file_storage):
+    # file_storage is a Werkzeug FileStorage from request.files
+    data = file_storage.read()
+    if not data:
+        raise ValueError("Empty file")
+
+    nparr = np.frombuffer(data, np.uint8)
+    img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)  # BGR image
+    if img is None:
+        raise ValueError("Could not decode image (invalid/unsupported format)")
+    return img
+
+
+@app.post("/api/v1/finger-quality")
+def finger_quality():
+    """
+    Expects: multipart/form-data with file field name 'image'
+    Returns: JSON with result + feedback
+    """
+    if "image" not in request.files:
+        return jsonify({"error": "Missing file field 'image'"}), 400  # jsonify returns application/json response [web:7]
+
+    try:
+        bgr = _decode_uploaded_image(request.files["image"])
+        result, feedback, _debug = ASSESSOR.assess(bgr, draw_debug=False)
+
+        # Build JSON-safe dict (do not return numpy types/tuples blindly)
+        payload = {
+            "result": {
+                "blur_score": float(result.blur_score),
+                "illumination_score": float(result.illumination_score),
+                "coverage_ratio": float(result.coverage_ratio),
+                "orientation_angle_deg": float(result.orientation_angle_deg),
+
+                "blur_pass": bool(result.blur_pass),
+                "illumination_pass": bool(result.illumination_pass),
+                "coverage_pass": bool(result.coverage_pass),
+                "orientation_pass": bool(result.orientation_pass),
+
+                "quality_score": float(result.quality_score),
+                "overall_pass": bool(result.overall_pass),
+
+                "bbox": list(result.bbox) if result.bbox is not None else None,
+                "contour_area": float(result.contour_area),
+            },
+            "feedback": {
+                "is_acceptable": bool(feedback.is_acceptable),
+                "messages": [
+                    {
+                        "severity": m.severity,
+                        "category": m.category,
+                        "message": m.message,
+                    }
+                    for m in (feedback.messages or [])
+                ],
+            },
+        }
+
+        return jsonify(payload), 200  # jsonify formats JSON response conveniently [web:7]
+
+    except ValueError as e:
+        return jsonify({"error": str(e)}), 400  # jsonify is fine for structured errors [web:7]
+    except Exception as e:
+        # avoid leaking internals in production; log e server-side
+        return jsonify({"error": "Internal server error"}), 500  # jsonify response [web:7]
+
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=5000, debug=True)

finger_detector.py

@@ -0,0 +1,67 @@
+from typing import Optional, Tuple
+
+import cv2
+import numpy as np
+
+
+class FingerDetector:
+    """
+    Skin-based finger segmentation + largest contour extraction.
+    """
+
+    def __init__(self, min_contour_area_ratio: float = 0.02):
+        self.min_contour_area_ratio = min_contour_area_ratio
+
+    @staticmethod
+    def segment_skin_ycbcr(img_bgr: np.ndarray) -> np.ndarray:
+        """
+        Returns binary mask (uint8 0/255) using YCbCr thresholds.
+        Commonly used range: 77≤Cb≤127 and 133≤Cr≤173. [page:2]
+        """
+        ycrcb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2YCrCb)
+
+        # OpenCV order is Y, Cr, Cb in COLOR_BGR2YCrCb
+        lower = np.array([0, 133, 77], dtype=np.uint8)
+        upper = np.array([255, 173, 127], dtype=np.uint8)
+        mask = cv2.inRange(ycrcb, lower, upper)
+
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+        mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel, iterations=2)
+        mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel, iterations=2)
+        return mask
+
+    def find_largest_contour(
+        self,
+        mask: np.ndarray,
+        frame_area: float
+    ) -> Optional[np.ndarray]:
+        contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        if not contours:
+            return None
+
+        min_area = self.min_contour_area_ratio * frame_area
+        valid = [c for c in contours if cv2.contourArea(c) >= min_area]
+        if not valid:
+            return None
+
+        return max(valid, key=cv2.contourArea)
+
+    @staticmethod
+    def bounding_box(contour: np.ndarray) -> Tuple[int, int, int, int]:
+        x, y, w, h = cv2.boundingRect(contour)
+        return x, y, w, h
+
+    @staticmethod
+    def orientation_pca_deg(contour: np.ndarray) -> float:
+        pts = contour.reshape(-1, 2).astype(np.float64)
+        mean, eigenvectors, _ = cv2.PCACompute2(pts, mean=np.empty(0))
+        vx, vy = eigenvectors[0]
+        angle_rad = np.arctan2(vy, vx)
+        angle_deg = float(np.degrees(angle_rad))
+
+        # Normalize to [-90, 90]
+        if angle_deg < -90:
+            angle_deg += 180
+        elif angle_deg > 90:
+            angle_deg -= 180
+        return float(angle_deg)

finger_quality.py

@@ -0,0 +1,388 @@
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import cv2
+import numpy as np
+from dataclasses import asdict
+import json
+from typing import Any
+
+@dataclass
+class FingerQualityResult:
+    # Raw scores
+    blur_score: float
+    illumination_score: float
+    coverage_ratio: float
+    orientation_angle_deg: float  # angle of main axis w.r.t. x-axis
+
+    # Per-metric pass/fail
+    blur_pass: bool
+    illumination_pass: bool
+    coverage_pass: bool
+    orientation_pass: bool
+
+    # Overall
+    quality_score: float       # 0–1
+    overall_pass: bool
+
+    # Debug / geometry
+    bbox: Optional[Tuple[int, int, int, int]]  # x, y, w, h of finger bounding box
+    contour_area: float
+
+
+class FingerQualityAssessor:
+    """
+    End-to-end finger quality computation on single-finger mobile images.
+
+    Pipeline:
+    1. Preprocess (resize, blur, colorspace).
+    2. Skin-based finger segmentation (YCbCr + morphology).
+    3. Largest contour -> bounding box + PCA orientation.
+    4. Metrics on finger ROI (blur, illumination, coverage, orientation).
+    """
+
+    def __init__(
+        self,
+        target_width: int = 640,
+        min_contour_area_ratio: float = 0.02,
+        # Thresholds (tune for your data/device):
+        blur_min: float = 60.0,              # variance-of-Laplacian; > threshold = sharp
+        illum_min: float = 50.0,             # mean gray lower bound
+        illum_max: float = 200.0,            # mean gray upper bound
+        coverage_min: float = 0.10,          # fraction of frame area covered by finger
+        orientation_max_deviation: float = 45.0,  # degrees from vertical or horizontal (tunable)
+        vertical_expected: bool = True       # if True, expect finger roughly vertical
+    ):
+        self.target_width = target_width
+        self.min_contour_area_ratio = min_contour_area_ratio
+        self.blur_min = blur_min
+        self.illum_min = illum_min
+        self.illum_max = illum_max
+        self.coverage_min = coverage_min
+        self.orientation_max_deviation = orientation_max_deviation
+        self.vertical_expected = vertical_expected
+
+    # ---------- Public API ----------
+
+    def assess(
+        self,
+        bgr: np.ndarray,
+        draw_debug: bool = False
+    ) -> Tuple[FingerQualityResult, Optional[np.ndarray]]:
+        """
+        Main entrypoint.
+
+        :param bgr: HxWx3 uint8 BGR finger image from mobile camera.
+        :param draw_debug: If True, returns image with bbox and orientation visualized.
+        :return: (FingerQualityResult, debug_image or None)
+        """
+        if bgr is None or bgr.size == 0:
+            raise ValueError("Input image is empty")
+
+        # 1) Resize for consistent metrics
+        img = self._resize_keep_aspect(bgr, self.target_width)
+        h, w = img.shape[:2]
+        frame_area = float(h * w)
+
+        # 2) Segment finger (skin) and find largest contour
+        mask = self._segment_skin_ycbcr(img)
+        contour = self._find_largest_contour(mask, frame_area)
+        if contour is None:
+            # No valid finger found; everything fails.
+            result = FingerQualityResult(
+                blur_score=0.0,
+                illumination_score=0.0,
+                coverage_ratio=0.0,
+                orientation_angle_deg=0.0,
+                blur_pass=False,
+                illumination_pass=False,
+                coverage_pass=False,
+                orientation_pass=False,
+                quality_score=0.0,
+                overall_pass=False,
+                bbox=None,
+                contour_area=0.0
+            )
+            return result, img if draw_debug else None
+
+        contour_area = cv2.contourArea(contour)
+        x, y, w_box, h_box = cv2.boundingRect(contour)
+        bbox = (x, y, w_box, h_box)
+
+        # ROI around finger
+        roi = img[y:y + h_box, x:x + w_box]
+        roi_gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)
+
+        # Recompute mask for ROI to calculate coverage accurately
+        mask_roi = mask[y:y + h_box, x:x + w_box]
+
+        # 3) Metrics
+        blur_score = self._blur_score_laplacian(roi_gray)
+        illumination_score = float(roi_gray.mean())
+        coverage_ratio = float(np.count_nonzero(mask_roi)) / float(frame_area)
+
+        orientation_angle_deg = self._orientation_pca(contour)
+
+        # 4) Per-metric pass/fail
+        blur_pass = blur_score >= self.blur_min
+        illum_pass = self.illum_min <= illumination_score <= self.illum_max
+        coverage_pass = coverage_ratio >= self.coverage_min
+        orientation_pass = self._orientation_pass(orientation_angle_deg)
+
+        # 5) Quality score (simple weighted average; tune as needed)
+        # Scale each metric to [0,1], then weight.
+        blur_norm = np.clip(blur_score / (self.blur_min * 2.0), 0.0, 1.0)
+        illum_center = (self.illum_min + self.illum_max) / 2.0
+        illum_range = (self.illum_max - self.illum_min) / 2.0
+        illum_norm = 1.0 - np.clip(abs(illumination_score - illum_center) / (illum_range + 1e-6), 0.0, 1.0)
+        coverage_norm = np.clip(coverage_ratio / (self.coverage_min * 2.0), 0.0, 1.0)
+        orient_norm = 1.0 if orientation_pass else 0.0
+
+        # weights: prioritize blur and coverage for biometrics
+        w_blur, w_illum, w_cov, w_orient = 0.35, 0.25, 0.25, 0.15
+        quality_score = float(
+            w_blur * blur_norm +
+            w_illum * illum_norm +
+            w_cov * coverage_norm +
+            w_orient * orient_norm
+        )
+
+        # Comment strict condition - for tuning other metrics
+        # overall_pass = blur_pass and illum_pass and coverage_pass and orientation_pass
+        overall_pass = quality_score >= 0.7
+
+        result = FingerQualityResult(
+            blur_score=float(blur_score),
+            illumination_score=float(illumination_score),
+            coverage_ratio=float(coverage_ratio),
+            orientation_angle_deg=float(orientation_angle_deg),
+            blur_pass=blur_pass,
+            illumination_pass=illum_pass,
+            coverage_pass=coverage_pass,
+            orientation_pass=orientation_pass,
+            quality_score=quality_score,
+            overall_pass=overall_pass,
+            bbox=bbox,
+            contour_area=float(contour_area),
+        )
+
+        debug_img = None
+        if draw_debug:
+            debug_img = img.copy()
+            self._draw_debug(debug_img, contour, bbox, orientation_angle_deg, result)
+
+        return result, debug_img
+
+    # ---------- Preprocessing ----------
+
+    @staticmethod
+    def _resize_keep_aspect(img: np.ndarray, target_width: int) -> np.ndarray:
+        h, w = img.shape[:2]
+        if w == target_width:
+            return img
+        scale = target_width / float(w)
+        new_size = (target_width, int(round(h * scale)))
+        return cv2.resize(img, new_size, interpolation=cv2.INTER_AREA)
+
+    # ---------- Segmentation ----------
+
+    @staticmethod
+    def _segment_skin_ycbcr(img: np.ndarray) -> np.ndarray:
+        """
+        Segment skin using YCbCr range commonly used for hand/finger. [web:12][web:15]
+        Returns binary mask (uint8 0/255).
+        """
+        ycbcr = cv2.cvtColor(img, cv2.COLOR_BGR2YCrCb)
+        # These ranges are a reasonable starting point for many Asian/Indian skin tones;
+        # tweak per competition dataset. [web:12]
+        lower = np.array([0, 133, 77], dtype=np.uint8)
+        upper = np.array([255, 173, 127], dtype=np.uint8)
+        mask = cv2.inRange(ycbcr, lower, upper)
+
+        # Morphology to clean noise
+        kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
+        mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel, iterations=2)
+        mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel, iterations=2)
+
+        return mask
+
+    def _find_largest_contour(
+        self,
+        mask: np.ndarray,
+        frame_area: float
+    ) -> Optional[np.ndarray]:
+        contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        if not contours:
+            return None
+        # Filter by area
+        min_area = self.min_contour_area_ratio * frame_area
+        valid = [c for c in contours if cv2.contourArea(c) >= min_area]
+        if not valid:
+            return None
+        # Largest contour
+        largest = max(valid, key=cv2.contourArea)
+        return largest
+
+    # ---------- Metrics ----------
+
+    @staticmethod
+    def _blur_score_laplacian(gray: np.ndarray) -> float:
+        # Standard variance-of-Laplacian focus measure. [web:7][web:10][web:16]
+        lap = cv2.Laplacian(gray, cv2.CV_64F)
+        return float(lap.var())
+
+    @staticmethod
+    def _orientation_pca(contour: np.ndarray) -> float:
+        """
+        Compute orientation using PCA on contour points. [web:8][web:11][web:14]
+
+        :return: angle in degrees in range [-90, 90] w.r.t. x-axis.
+        """
+        pts = contour.reshape(-1, 2).astype(np.float64)
+        mean, eigenvectors, eigenvalues = cv2.PCACompute2(pts, mean=np.empty(0))
+        # First principal component
+        vx, vy = eigenvectors[0]
+        angle_rad = np.arctan2(vy, vx)
+        angle_deg = np.degrees(angle_rad)
+        # Normalize angle for convenience
+        if angle_deg < -90:
+            angle_deg += 180
+        elif angle_deg > 90:
+            angle_deg -= 180
+        return float(angle_deg)
+
+    def _orientation_pass(self, angle_deg: float) -> bool:
+        """
+        Check if orientation is close to expected vertical/horizontal.
+
+        vertical_expected=True  -> near 90 or -90 degrees
+        vertical_expected=False -> near 0 degrees
+        """
+        if self.vertical_expected:
+            # distance from ±90
+            dev = min(abs(abs(angle_deg) - 90.0), abs(angle_deg))
+        else:
+            # distance from 0
+            dev = abs(angle_deg)
+        return dev <= self.orientation_max_deviation
+
+    # ---------- Debug drawing ----------
+
+    @staticmethod
+    def _draw_axis(img, center, vec, length, color, thickness=2):
+        x0, y0 = center
+        x1 = int(x0 + length * vec[0])
+        y1 = int(y0 + length * vec[1])
+        cv2.arrowedLine(img, (x0, y0), (x1, y1), color, thickness, tipLength=0.2)
+
+    def _draw_debug(
+        self,
+        img: np.ndarray,
+        contour: np.ndarray,
+        bbox: Tuple[int, int, int, int],
+        angle_deg: float,
+        result: FingerQualityResult
+    ) -> None:
+        x, y, w_box, h_box = bbox
+        # Bounding box
+        cv2.rectangle(img, (x, y), (x + w_box, y + h_box), (0, 255, 0), 2)
+
+        # Draw contour
+        cv2.drawContours(img, [contour], -1, (255, 0, 0), 2)
+
+        # PCA axis
+        pts = contour.reshape(-1, 2).astype(np.float64)
+        mean, eigenvectors, eigenvalues = cv2.PCACompute2(pts, mean=np.empty(0))
+        center = (int(mean[0, 0]), int(mean[0, 1]))
+        main_vec = eigenvectors[0]
+        self._draw_axis(img, center, main_vec, length=80, color=(0, 0, 255), thickness=2)
+
+        # Overlay text
+        text_lines = [
+            f"Blur: {result.blur_score:.1f} ({'OK' if result.blur_pass else 'BAD'})",
+            f"Illum: {result.illumination_score:.1f} ({'OK' if result.illumination_pass else 'BAD'})",
+            f"Coverage: {result.coverage_ratio*100:.1f}% ({'OK' if result.coverage_pass else 'BAD'})",
+            f"Angle: {angle_deg:.1f} deg ({'OK' if result.orientation_pass else 'BAD'})",
+            f"Quality: {result.quality_score:.2f} ({'PASS' if result.overall_pass else 'FAIL'})",
+        ]
+        y0 = 25
+        for line in text_lines:
+            cv2.putText(
+                img,
+                line,
+                (10, y0),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.6,
+                (0, 255, 0) if "OK" in line or "PASS" in line else (0, 0, 255),
+                2,
+                cv2.LINE_AA
+            )
+            y0 += 22
+
+
+# 1) Load your finger image (replace with your path)
+img = cv2.imread(r"finger_inputs\clear_thumb.jpeg")
+if img is None:
+    raise RuntimeError("Image not found or path is wrong")
+
+# 2) Create assessor (tune thresholds later if needed)
+assessor = FingerQualityAssessor(
+    target_width=640,
+    blur_min=60.0,
+    illum_min=50.0,
+    illum_max=200.0,
+    coverage_min=0.10,
+    orientation_max_deviation=45.0,
+    vertical_expected=True
+)
+
+# 3) Run assessment.
+result, debug_image = assessor.assess(img, draw_debug=True)
+
+def _round_value(value: Any) -> Any:
+    """
+    Recursively round floats to 2 decimal places for JSON output.
+    """
+    if isinstance(value, float):
+        return round(value, 2)
+    if isinstance(value, dict):
+        return {k: _round_value(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_round_value(v) for v in value]
+    return value
+
+def finger_quality_result_to_json(result: FingerQualityResult) -> str:
+    """
+    Convert FingerQualityResult to a JSON string suitable for frontend usage.
+    """
+    data = asdict(result)
+
+    # Ensure bbox is frontend-friendly
+    if data["bbox"] is not None:
+        data["bbox"] = {
+            "x": data["bbox"][0],
+            "y": data["bbox"][1],
+            "width": data["bbox"][2],
+            "height": data["bbox"][3],
+        }
+    data = _round_value(data)
+    return json.dumps(data, indent=2)
+
+quality_json = finger_quality_result_to_json(result)
+print(quality_json)
+
+with open("output_dir/finger_quality_result.json", "w") as f:
+    f.write(quality_json)
+
+# 4) Print all scores and flags.
+print("Blur score:", result.blur_score, "pass:", result.blur_pass)
+print("Illumination:", result.illumination_score, "pass:", result.illumination_pass)
+print("Coverage ratio:", result.coverage_ratio, "pass:", result.coverage_pass)
+print("Orientation angle:", result.orientation_angle_deg, "pass:", result.orientation_pass)
+print("Quality score:", result.quality_score, "OVERALL PASS:", result.overall_pass)
+
+# 5) Show debug image with bounding box and text.
+if debug_image is not None:
+    cv2.imshow("Finger Quality Debug", debug_image)
+    cv2.waitKey(0)          # wait until key press to close window [web:18][web:24]
+    cv2.destroyAllWindows()

main.py

@@ -0,0 +1,143 @@
+import os
+import cv2
+import numpy as np
+
+from finger_detector import FingerDetector
+from models import FingerQualityResult
+from quality_analyzer import QualityAnalyzer, QualityConfig
+from utils import finger_quality_result_to_json
+from visualizer import Visualizer
+
+
+class FingerQualityAssessor:
+    """
+    End-to-end finger quality computation on single-finger mobile images.
+    """
+
+    def __init__(self, config: QualityConfig):
+        self.config = config
+        self.detector = FingerDetector(min_contour_area_ratio=0.02)
+        self.analyzer = QualityAnalyzer(config)
+
+    def assess(self, bgr: np.ndarray, draw_debug: bool = False):
+        if bgr is None or bgr.size == 0:
+            raise ValueError("Input image is empty")
+
+        img = self.analyzer.resize_keep_aspect(bgr, self.config.target_width)
+        h, w = img.shape[:2]
+        frame_area = float(h * w)
+
+        mask = self.detector.segment_skin_ycbcr(img)
+        contour = self.detector.find_largest_contour(mask, frame_area)
+        if contour is None:
+            result = FingerQualityResult(
+                blur_score=0.0,
+                illumination_score=0.0,
+                coverage_ratio=0.0,
+                orientation_angle_deg=0.0,
+                blur_pass=False,
+                illumination_pass=False,
+                coverage_pass=False,
+                orientation_pass=False,
+                quality_score=0.0,
+                overall_pass=False,
+                bbox=None,
+                contour_area=0.0,
+            )
+            feedback = self.analyzer.generate_feedback(result)
+            return result, feedback, (img if draw_debug else None)
+
+        contour_area = float(cv2.contourArea(contour))
+        bbox = self.detector.bounding_box(contour)
+        x, y, w_box, h_box = bbox
+
+        roi = img[y:y + h_box, x:x + w_box]
+        roi_gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY)
+        mask_roi = mask[y:y + h_box, x:x + w_box]
+
+        blur_score = self.analyzer.blur_score_laplacian(roi_gray)
+        illumination_score = float(roi_gray.mean())
+        coverage_ratio = float(np.count_nonzero(mask_roi)) / float(frame_area)
+
+        orientation_angle_deg = self.detector.orientation_pca_deg(contour)
+
+        blur_pass = blur_score >= self.config.blur_min
+        illum_pass = self.config.illum_min <= illumination_score <= self.config.illum_max
+        coverage_pass = coverage_ratio >= self.config.coverage_min
+        orientation_pass = self.analyzer.orientation_pass(orientation_angle_deg)
+
+        quality_score = self.analyzer.compute_quality_score(
+            blur_score=blur_score,
+            illumination_score=illumination_score,
+            coverage_ratio=coverage_ratio,
+            orientation_ok=orientation_pass,
+        )
+        overall_pass = quality_score >= self.config.overall_quality_threshold
+
+        result = FingerQualityResult(
+            blur_score=float(blur_score),
+            illumination_score=float(illumination_score),
+            coverage_ratio=float(coverage_ratio),
+            orientation_angle_deg=float(orientation_angle_deg),
+            blur_pass=bool(blur_pass),
+            illumination_pass=bool(illum_pass),
+            coverage_pass=bool(coverage_pass),
+            orientation_pass=bool(orientation_pass),
+            quality_score=float(quality_score),
+            overall_pass=bool(overall_pass),
+            bbox=bbox,
+            contour_area=contour_area,
+            feedback=None
+        )
+
+        feedback = self.analyzer.generate_feedback(result)
+
+        # NEW: embed feedback into result
+        result.feedback = feedback
+
+        debug_img = None
+        if draw_debug and contour is not None and result.bbox is not None:
+            debug_img = Visualizer.draw_debug(img, contour, bbox, orientation_angle_deg, result)
+
+        return result, feedback, debug_img
+
+
+def main():
+    image_path = r"C:\SagarKV\sol9x\ContactlessFinger\TRACK_A\finger_inputs\OM_TH.jpg"
+    img = cv2.imread(image_path)
+    if img is None:
+        raise RuntimeError("Image not found or path is wrong")
+
+    config = QualityConfig(
+        target_width=640,
+        blur_min=60.0,
+        illum_min=50.0,
+        illum_max=200.0,
+        coverage_min=0.10,
+        orientation_max_deviation=45.0,
+        vertical_expected=True,
+        overall_quality_threshold=0.70,
+    )
+
+    assessor = FingerQualityAssessor(config)
+    result, feedback, debug_image = assessor.assess(img, draw_debug=True)
+
+    os.makedirs("results", exist_ok=True)
+    quality_json = finger_quality_result_to_json(result)
+    with open("results/finger_quality_result.json", "w", encoding="utf-8") as f:
+        f.write(quality_json)
+
+    # Print JSON + feedback
+    print(quality_json)
+    for m in feedback.messages:
+        print(f"[{m.severity.upper()}] {m.category}: {m.message}")
+    print("Acceptable:", feedback.is_acceptable)
+
+    if debug_image is not None:
+        cv2.imshow("Finger Quality Debug", debug_image)
+        cv2.waitKey(0)
+        cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass, field
+from typing import Optional, Tuple, List
+
+
+
+
+@dataclass
+class FeedbackMessage:
+    category: str
+    message: str
+    severity: str  # "warning", "error", "success"
+
+
+@dataclass
+class QualityFeedback:
+    messages: List[FeedbackMessage] = field(default_factory=list)
+    is_acceptable: bool = True
+
+    def add(self, category: str, message: str, severity: str = "warning"):
+        self.messages.append(FeedbackMessage(category, message, severity))
+        if severity == "error":
+            self.is_acceptable = False
+
+@dataclass
+class FingerQualityResult:
+    # Raw scores
+    blur_score: float
+    illumination_score: float
+    coverage_ratio: float
+    orientation_angle_deg: float  # angle of main axis w.r.t. x-axis
+
+    # Per-metric pass/fail
+    blur_pass: bool
+    illumination_pass: bool
+    coverage_pass: bool
+    orientation_pass: bool
+
+    # Overall
+    quality_score: float       # 0–1
+    overall_pass: bool
+
+    # Debug / geometry
+    bbox: Optional[Tuple[int, int, int, int]]  # x, y, w, h
+    contour_area: float
+
+    # NEW: Feedback bundled into the same result JSON
+    feedback: Optional[QualityFeedback] = None

quality_analyzer.py

@@ -0,0 +1,123 @@
+from dataclasses import dataclass
+import cv2
+import numpy as np
+
+from models import FingerQualityResult, QualityFeedback
+
+
+@dataclass
+class QualityConfig:
+    target_width: int = 640
+    blur_min: float = 60.0
+    illum_min: float = 50.0
+    illum_max: float = 200.0
+    coverage_min: float = 0.10
+    orientation_max_deviation: float = 45.0
+    vertical_expected: bool = True
+    overall_quality_threshold: float = 0.70
+
+
+class QualityAnalyzer:
+    def __init__(self, config: QualityConfig):
+        self.config = config
+
+    @staticmethod
+    def resize_keep_aspect(img: np.ndarray, target_width: int) -> np.ndarray:
+        h, w = img.shape[:2]
+        if w == target_width:
+            return img
+        scale = target_width / float(w)
+        new_size = (target_width, int(round(h * scale)))
+        return cv2.resize(img, new_size, interpolation=cv2.INTER_AREA)
+
+    @staticmethod
+    def blur_score_laplacian(gray: np.ndarray) -> float:
+        # Variance-of-Laplacian focus measure. [page:1]
+        return float(cv2.Laplacian(gray, cv2.CV_64F).var())
+
+    def orientation_pass(self, angle_deg: float) -> bool:
+        if self.config.vertical_expected:
+            dev = min(abs(abs(angle_deg) - 90.0), abs(angle_deg))
+        else:
+            dev = abs(angle_deg)
+        return dev <= self.config.orientation_max_deviation
+
+    def compute_quality_score(
+        self,
+        blur_score: float,
+        illumination_score: float,
+        coverage_ratio: float,
+        orientation_ok: bool
+    ) -> float:
+        blur_norm = np.clip(blur_score / (self.config.blur_min * 2.0), 0.0, 1.0)
+
+        illum_center = (self.config.illum_min + self.config.illum_max) / 2.0
+        illum_range = (self.config.illum_max - self.config.illum_min) / 2.0
+        illum_norm = 1.0 - np.clip(abs(illumination_score - illum_center) / (illum_range + 1e-6), 0.0, 1.0)
+
+        coverage_norm = np.clip(coverage_ratio / (self.config.coverage_min * 2.0), 0.0, 1.0)
+        orient_norm = 1.0 if orientation_ok else 0.0
+
+        w_blur, w_illum, w_cov, w_orient = 0.35, 0.25, 0.25, 0.15
+        return float(w_blur * blur_norm + w_illum * illum_norm + w_cov * coverage_norm + w_orient * orient_norm)
+
+    def generate_feedback(self, result: FingerQualityResult) -> QualityFeedback:
+        """
+        User-friendly feedback with ranges consistent with your thresholds:
+        - blur_min (default 60): below ~0.6x is "very blurry", below threshold is "slightly blurry".
+        - illum_min/illum_max: too dark, too bright, or OK.
+        - coverage_min: very small (<0.5x), small (<threshold), too close (>0.70), OK.
+        - orientation_max_deviation: error if >1.5x deviation, warning if >threshold.
+        """
+        fb = QualityFeedback()
+
+        # Blur
+        if result.blur_score < 0.6 * self.config.blur_min:
+            fb.add("blur", "Image is very blurry. Hold phone steady and tap to focus.", "error")
+        elif result.blur_score < self.config.blur_min:
+            fb.add("blur", "Image is slightly blurry. Try holding your phone steadier.", "warning")
+        else:
+            fb.add("blur", "Image sharpness is good.", "success")
+
+        # Illumination
+        if result.illumination_score < 0.8 * self.config.illum_min:
+            fb.add("light", "Image is too dark. Move to a well-lit area.", "error")
+        elif result.illumination_score < self.config.illum_min:
+            fb.add("light", "Lighting is dim. Move closer to a light source.", "warning")
+        elif result.illumination_score > self.config.illum_max:
+            fb.add("light", "Image is overexposed. Avoid direct bright light.", "warning")
+        else:
+            fb.add("light", "Lighting conditions are good.", "success")
+
+        # Coverage
+        if result.coverage_ratio < 0.5 * self.config.coverage_min:
+            fb.add("position", "Finger too small. Move phone closer to your finger.", "error")
+        elif result.coverage_ratio < self.config.coverage_min:
+            fb.add("position", "Finger appears small. Move the camera closer.", "warning")
+        elif result.coverage_ratio > 0.70:
+            fb.add("position", "Finger too close. Move phone slightly away.", "warning")
+        else:
+            fb.add("position", "Finger positioning is good.", "success")
+
+        # Orientation
+        # compute deviation using same logic as pass/fail
+        angle_deg = result.orientation_angle_deg
+        if self.config.vertical_expected:
+            dev = min(abs(abs(angle_deg) - 90.0), abs(angle_deg))
+        else:
+            dev = abs(angle_deg)
+
+        if dev > 1.5 * self.config.orientation_max_deviation:
+            fb.add("orientation", "Finger is tilted too much. Align finger straight.", "error")
+        elif dev > self.config.orientation_max_deviation:
+            fb.add("orientation", "Finger is slightly tilted. Try to keep it straighter.", "warning")
+        else:
+            fb.add("orientation", "Finger orientation is correct.", "success")
+
+        # Overall
+        if result.overall_pass:
+            fb.add("overall", "Capture is acceptable.", "success")
+        else:
+            fb.add("overall", "Capture is not acceptable. Fix the issues above and retake.", "error")
+
+        return fb

requirements.txt

@@ -0,0 +1,3 @@
+flask
+opencv-python-headless
+numpy

results/finger_quality_result.json

@@ -0,0 +1,49 @@
+{
+  "blur_score": 79.14,
+  "illumination_score": 134.96,
+  "coverage_ratio": 0.73,
+  "orientation_angle_deg": -70.94,
+  "blur_pass": true,
+  "illumination_pass": true,
+  "coverage_pass": true,
+  "orientation_pass": true,
+  "quality_score": 0.85,
+  "overall_pass": true,
+  "bbox": {
+    "x": 0,
+    "y": 26,
+    "width": 640,
+    "height": 905
+  },
+  "contour_area": 432000.5,
+  "feedback": {
+    "messages": [
+      {
+        "category": "blur",
+        "message": "Image sharpness is good.",
+        "severity": "success"
+      },
+      {
+        "category": "light",
+        "message": "Lighting conditions are good.",
+        "severity": "success"
+      },
+      {
+        "category": "position",
+        "message": "Finger too close. Move phone slightly away.",
+        "severity": "warning"
+      },
+      {
+        "category": "orientation",
+        "message": "Finger orientation is correct.",
+        "severity": "success"
+      },
+      {
+        "category": "overall",
+        "message": "Capture is acceptable.",
+        "severity": "success"
+      }
+    ],
+    "is_acceptable": true
+  }
+}

utils.py

@@ -0,0 +1,31 @@
+import json
+from dataclasses import asdict
+from typing import Any
+
+from models import FingerQualityResult
+
+
+def _round_value(value: Any) -> Any:
+    if isinstance(value, float):
+        return round(value, 2)
+    if isinstance(value, dict):
+        return {k: _round_value(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_round_value(v) for v in value]
+    return value
+
+
+def finger_quality_result_to_json(result: FingerQualityResult) -> str:
+    data = asdict(result)
+
+    # Make bbox frontend-friendly
+    if data["bbox"] is not None:
+        data["bbox"] = {
+            "x": data["bbox"][0],
+            "y": data["bbox"][1],
+            "width": data["bbox"][2],
+            "height": data["bbox"][3],
+        }
+
+    data = _round_value(data)
+    return json.dumps(data, indent=2)

visualizer.py

@@ -0,0 +1,50 @@
+from typing import Tuple
+import cv2
+import numpy as np
+
+from models import FingerQualityResult
+
+
+class Visualizer:
+    @staticmethod
+    def draw_axis(img, center, vec, length, color, thickness=2):
+        x0, y0 = center
+        x1 = int(x0 + length * vec[0])
+        y1 = int(y0 + length * vec[1])
+        cv2.arrowedLine(img, (x0, y0), (x1, y1), color, thickness, tipLength=0.2)
+
+    @staticmethod
+    def draw_debug(
+        img: np.ndarray,
+        contour: np.ndarray,
+        bbox: Tuple[int, int, int, int],
+        angle_deg: float,
+        result: FingerQualityResult
+    ) -> np.ndarray:
+        out = img.copy()
+        x, y, w_box, h_box = bbox
+
+        cv2.rectangle(out, (x, y), (x + w_box, y + h_box), (0, 255, 0), 2)
+        cv2.drawContours(out, [contour], -1, (255, 0, 0), 2)
+
+        pts = contour.reshape(-1, 2).astype(np.float64)
+        mean, eigenvectors, _ = cv2.PCACompute2(pts, mean=np.empty(0))
+        center = (int(mean[0, 0]), int(mean[0, 1]))
+        main_vec = eigenvectors[0]
+        Visualizer.draw_axis(out, center, main_vec, length=80, color=(0, 0, 255), thickness=2)
+
+        text_lines = [
+            f"Blur: {result.blur_score:.1f} ({'OK' if result.blur_pass else 'BAD'})",
+            f"Illum: {result.illumination_score:.1f} ({'OK' if result.illumination_pass else 'BAD'})",
+            f"Coverage: {result.coverage_ratio*100:.1f}% ({'OK' if result.coverage_pass else 'BAD'})",
+            f"Angle: {angle_deg:.1f} deg ({'OK' if result.orientation_pass else 'BAD'})",
+            f"Quality: {result.quality_score:.2f} ({'PASS' if result.overall_pass else 'FAIL'})",
+        ]
+
+        y0 = 25
+        for line in text_lines:
+            color = (0, 255, 0) if ("OK" in line or "PASS" in line) else (0, 0, 255)
+            cv2.putText(out, line, (10, y0), cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2, cv2.LINE_AA)
+            y0 += 22
+
+        return out