feat: lighting quality assessment for Fitzpatrick estimation

src/fitzpatrick_estimator.py

@@ -2,6 +2,9 @@
 
 Calibrated on 61 DFU images with expert ground truth.
 Validation: 86.9% exact match, 98.4% adjacent, r=0.975.
+
+Includes lighting quality assessment to avoid misclassification
+under poor illumination conditions.
 """
 import numpy as np
 import cv2
@@ -23,6 +26,12 @@ FITZPATRICK_LABELS = {
     "IV": "Tan", "V": "Brown", "VI": "Dark",
 }
 
+# Lighting quality thresholds (L* scale 0-100)
+L_SCENE_MIN = 35.0        # Below this: scene too dark for reliable ITA
+L_SCENE_LOW = 50.0        # Below this: suboptimal lighting, reduce confidence
+L_SKIN_MIN = 25.0         # Healthy skin L* below this is almost certainly lighting artifact
+L_SKIN_SUSPICIOUS = 40.0  # L* this low is rare even for Fitzpatrick VI under good light
+
 
 @dataclass
 class FitzpatrickResult:
@@ -36,6 +45,10 @@ class FitzpatrickResult:
     healthy_pixels: int            # Number of healthy skin pixels used
     healthy_ratio: float           # Healthy pixels / total image pixels
     confidence: float              # 0-1 confidence score
+    # Lighting quality
+    l_scene_mean: float = 0.0      # Mean L* of entire image
+    lighting_quality: str = "good" # "good", "low", "insufficient"
+    lighting_warning: str = ""     # Human-readable warning if lighting is poor
 
 
 def compute_ita(l_values: np.ndarray, b_values: np.ndarray) -> tuple:
@@ -62,6 +75,43 @@ def classify_fitzpatrick(ita: float) -> tuple:
     return "III", 3  # Default fallback
 
 
+def assess_lighting(img_bgr: np.ndarray, l_skin_mean: float) -> tuple:
+    """Assess scene lighting quality for reliable Fitzpatrick estimation.
+
+    Returns:
+        (l_scene_mean, quality, warning, confidence_penalty)
+        quality: "good", "low", "insufficient"
+        confidence_penalty: 0.0 to 1.0 (multiplied with confidence)
+    """
+    # Global scene luminance
+    lab_full = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2Lab).astype(np.float32)
+    l_scene = float(np.mean(lab_full[:, :, 0]) * (100.0 / 255.0))
+
+    # Evaluate lighting
+    if l_scene < L_SCENE_MIN or l_skin_mean < L_SKIN_MIN:
+        quality = "insufficient"
+        warning = (
+            f"Iluminacion insuficiente (L* escena={l_scene:.0f}, L* piel={l_skin_mean:.0f}). "
+            "El tipo Fitzpatrick puede estar sobreestimado (piel aparenta mas oscura). "
+            "Recapture con mejor iluminacion para un resultado confiable."
+        )
+        penalty = 0.2  # Severely reduce confidence
+    elif l_scene < L_SCENE_LOW or l_skin_mean < L_SKIN_SUSPICIOUS:
+        quality = "low"
+        warning = (
+            f"Iluminacion suboptima (L* escena={l_scene:.0f}, L* piel={l_skin_mean:.0f}). "
+            "El tipo Fitzpatrick podria estar 1-2 niveles sobreestimado. "
+            "Se recomienda iluminacion uniforme para mayor precision."
+        )
+        penalty = 0.5  # Moderate confidence reduction
+    else:
+        quality = "good"
+        warning = ""
+        penalty = 1.0  # No penalty
+
+    return l_scene, quality, warning, penalty
+
+
 def estimate_fitzpatrick(
     img_bgr: np.ndarray,
     masks: dict,
@@ -72,6 +122,9 @@ def estimate_fitzpatrick(
     Strategy: Healthy skin = foot region - perilesion zone - ulcer.
     ITA is computed on the healthy skin pixels only.
 
+    Includes lighting quality assessment — if scene is too dark,
+    confidence is penalized and a warning is issued.
+
     Args:
         img_bgr: BGR image (H, W, 3)
         masks: dict with keys 'foot', 'perilesion', 'ulcer' (bool arrays H, W)
@@ -107,6 +160,9 @@ def estimate_fitzpatrick(
             healthy_pixels=healthy_pixels,
             healthy_ratio=healthy_pixels / (h * w),
             confidence=0.0,
+            l_scene_mean=0.0,
+            lighting_quality="insufficient",
+            lighting_warning="Insuficientes pixeles de piel sana para estimar Fitzpatrick.",
         )
 
     # Convert to L*a*b*
@@ -117,11 +173,20 @@ def estimate_fitzpatrick(
     ita_mean, ita_std = compute_ita(l_values, b_values)
     ftype, fint = classify_fitzpatrick(ita_mean)
 
-    # Confidence: pixel count + ITA consistency + coverage
+    l_skin_mean = float(np.mean(l_values))
+    b_skin_mean = float(np.mean(b_values))
+
+    # Lighting quality assessment
+    l_scene, lighting_quality, lighting_warning, lighting_penalty = assess_lighting(
+        img_bgr, l_skin_mean
+    )
+
+    # Confidence: pixel count + ITA consistency + coverage + lighting
     pixel_conf = min(healthy_pixels / 5000.0, 1.0)
     ita_conf = max(0.0, 1.0 - (ita_std / 30.0))
     coverage_conf = min((healthy_pixels / (h * w)) / 0.15, 1.0)
-    confidence = pixel_conf * 0.3 + ita_conf * 0.4 + coverage_conf * 0.3
+    base_confidence = pixel_conf * 0.3 + ita_conf * 0.4 + coverage_conf * 0.3
+    confidence = base_confidence * lighting_penalty
 
     return FitzpatrickResult(
         fitzpatrick_type=ftype,
@@ -129,9 +194,12 @@ def estimate_fitzpatrick(
         fitzpatrick_label=FITZPATRICK_LABELS[ftype],
         ita_angle=round(ita_mean, 2),
         ita_std=round(ita_std, 2),
-        l_skin_mean=round(float(np.mean(l_values)), 2),
-        b_skin_mean=round(float(np.mean(b_values)), 2),
+        l_skin_mean=round(l_skin_mean, 2),
+        b_skin_mean=round(b_skin_mean, 2),
         healthy_pixels=healthy_pixels,
         healthy_ratio=round(healthy_pixels / (h * w), 4),
         confidence=round(confidence, 3),
+        l_scene_mean=round(l_scene, 2),
+        lighting_quality=lighting_quality,
+        lighting_warning=lighting_warning,
     )