Update app/eyes_localizer.py

app/eyes_localizer.py

@@ -1,21 +1,36 @@
 # app/eyes_localizer.py
-import numpy as np, cv2 as cv, base64, math
+# ====== Iris localizer (MediaPipe + heurísticas) ======
+# Ajustes cirúrgicos:
+# - TOP_DEG=270.0 / BOTTOM_DEG=90.0 unificados
+# - Hard-gate angular (top/base) ANTES de midband/sector/nudge
+# - Guardas locais de textura/L na zona top/base
+# - Banimento setorial top/base
+# - Nudge radial "down-only"
+# - Cool-preserve para olhos frios/claros
+# - Diag fields completos para auditoria
+
+import numpy as np, cv2 as cv, base64
 from skimage import color
 
+# =============================
+# MediaPipe (FaceMesh com refine_landmarks=True)
+# =============================
 try:
     import mediapipe as mp
     mp_face = mp.solutions.face_mesh
 except Exception:
-    mp_face = None
+    mp_face = None  # fallback seguro
 
 LEFT_IRIS_SETS  = [[474,475,476,477], [469,470,471,472]]
 RIGHT_IRIS_SETS = [[469,470,471,472], [474,475,476,477]]
 
-UPPER_EYELID_L = [159, 158, 157, 173]
-LOWER_EYELID_L = [145, 144, 163, 7]
-UPPER_EYELID_R = [386, 385, 384, 398]
-LOWER_EYELID_R = [374, 380, 381, 382]
+# Ângulos de referência (fixos!)
+TOP_DEG    = 270.0   # cílios superiores / pálpebra superior
+BOTTOM_DEG = 90.0    # pálpebra inferior
 
+# =============================
+# Utils
+# =============================
 def _to_b64(img_rgb):
     ok, buf = cv.imencode(".png", cv.cvtColor(img_rgb, cv.COLOR_RGB2BGR))
     return base64.b64encode(buf.tobytes()).decode("ascii") if ok else ""
@@ -23,7 +38,7 @@ def _to_b64(img_rgb):
 def _rgb2lab_uint8(rgb):
     if rgb.dtype != np.uint8:
         rgb = np.clip(rgb, 0, 255).astype(np.uint8)
-    lab = color.rgb2lab(rgb)
+    lab = color.rgb2lab(rgb)  # L [0..100]
     return lab[...,0].astype(np.float32), lab[...,1].astype(np.float32), lab[...,2].astype(np.float32)
 
 def _hsv_S(rgb_u8):
@@ -63,44 +78,16 @@ def _fit_circle(points_xy):
     r  = float(np.sqrt(uc*uc + vc*vc + Suu + Svv))
     return float(cx), float(cy), float(r)
 
-def _poly_from_lms(lms, ids, W, H):
-    pts = []
-    for pid in ids:
-        if pid >= len(lms.landmark): continue
-        p = lms.landmark[pid]
-        pts.append((p.x*W, p.y*H))
-    return np.asarray(pts, dtype=np.float32) if pts else None
-
-def _line_from_poly(poly):
-    if poly is None or len(poly) < 2:
-        return None
-    x = poly[:,0]; y = poly[:,1]
-    x_m = np.mean(x); y_m = np.mean(y)
-    ux = x - x_m; uy = y - y_m
-    cov = np.array([[np.dot(ux,ux), np.dot(ux,uy)],
-                    [np.dot(ux,uy), np.dot(uy,uy)]], dtype=np.float64)
-    vals, vecs = np.linalg.eigh(cov)
-    v = vecs[:,1]
-    p0 = np.array([x_m, y_m], dtype=np.float64)
-    p1 = p0 + v
-    return (p0, p1)
-
-def _point_line_dist(px, py, p0, p1):
-    v = p1 - p0
-    w = np.array([px, py], dtype=np.float64) - p0
-    c = np.cross(v, w)
-    den = np.linalg.norm(v) + 1e-9
-    return abs(c)/den
-
-def _sector_masks(h, w, cx, cy, keep, n):
+def _angular_field(h, w, cx, cy):
     Y, X = np.ogrid[:h, :w]
+    # 0° = eixo +X; ângulo cresce CCW; já normalizado [0..360)
     ang = (np.degrees(np.arctan2((Y - cy), (X - cx))) + 360.0) % 360.0
-    step = 360.0 / float(n)
-    masks = []
-    for i in range(n):
-        a0 = i*step; a1 = (i+1)*step
-        masks.append(keep & (ang >= a0) & (ang < a1))
-    return masks, step
+    return ang
+
+def _ang_dist_deg(a, b):
+    # distância modular mínima entre ângulos em graus
+    d = abs((a - b + 180.0) % 360.0 - 180.0)
+    return d
 
 def _laplacian_mag(u8):
     L = cv.Laplacian(u8, cv.CV_32F, ksize=3)
@@ -112,12 +99,37 @@ def _overlay_from_keep(roi, keep):
     contours, _ = cv.findContours(mask, cv.RETR_EXTERNAL, cv.CHAIN_APPROX_SIMPLE)
     cv.drawContours(rgb, contours, -1, (0,255,0), 1)
     rgb[keep] = np.clip(rgb[keep].astype(np.int16) + np.array([0,60,0], dtype=np.int16), 0, 255).astype(np.uint8)
-    ok, buf = cv.imencode(".png", cv.cvtColor(rgb, cv.COLOR_RGB2BGR))
-    return base64.b64encode(buf.tobytes()).decode("ascii") if ok else ""
+    return _to_b64(rgb)
+
+def _largest_contiguous_arc(flags):
+    n = len(flags)
+    if n == 0: return (0,0)
+    doubled = flags + flags
+    best_len, best_start = 0, 0
+    cur_len, cur_start = 0, 0
+    for i, v in enumerate(doubled):
+        if v:
+            if cur_len == 0: cur_start = i
+            cur_len += 1
+            if cur_len > best_len and cur_len <= n:
+                best_len = cur_len; best_start = cur_start
+        else:
+            cur_len = 0
+    if best_len > n: best_len = n
+    return (best_start % n, best_len)
 
+# =============================
+# Core
+# =============================
 def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=False):
+    """
+    Retorna: (metrics_dict | None, diag_dict)
+      metrics_dict: {"L","a","b","C","area","L_p50","C_p50","sat_rel"}
+      diag_dict:    campos detalhados (ver final)
+    """
     cfg = config or {}
 
+    # Guard-rails / leituras de config existentes
     inner_fr = cfg.get("iris_inner_frac_range", [0.38, 0.46])
     outer_fr = cfg.get("iris_outer_frac_range", [0.68, 0.78])
 
@@ -130,10 +142,21 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
     S_sclera_max = float(cfg.get("iris_S_sclera_max", 0.18))
     c_weighted   = bool(cfg.get("iris_c_weighted_mean", True))
 
+    # trims topo / sombra
     trim_enabled = bool(cfg.get("eyelid_top_trim_enabled", True))
     trim_deg_top = float(cfg.get("eyelid_top_trim_deg", 14.0))
     trim_L_rel_q = float(cfg.get("eyelid_top_trim_L_rel_q", 0.15))
 
+    # midband/lowC
+    mid_cfg = cfg.get("iris_midband_when_lowC",
+              {"enabled": True, "c_mean_threshold": 8.0, "subband_halfwidth_frac": 0.06,
+               "c_outlier_drop_q": 0.25, "guard_to_inner_outer_px": 2})
+    mid_enabled = bool(mid_cfg.get("enabled", True))
+    mid_thrC    = float(mid_cfg.get("c_mean_threshold", 8.0))
+    mid_hw_frac = float(mid_cfg.get("subband_halfwidth_frac", 0.06))
+    mid_guard   = int(mid_cfg.get("guard_to_inner_outer_px", 2))
+
+    # setorização
     sector_count            = int(cfg.get("iris_sector_count", 8))
     sector_arc_min_deg      = float(cfg.get("iris_sector_arc_min_deg", 90.0))
     sector_arc_min_deg_lowC = float(cfg.get("iris_sector_arc_min_deg_lowC", 60.0))
@@ -146,12 +169,14 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
     lowC_mean_thr           = float(cfg.get("iris_lowC_mean_thr", 7.0))
     warm_vs_cold_c_margin   = float(cfg.get("iris_warm_vs_cold_c_margin", 0.20))
 
+    # higiene quente (âmbar)
     amber_a_min        = float(cfg.get("iris_sector_amber_a_min", 2.0))
     amber_b_min        = float(cfg.get("iris_sector_amber_b_min", 4.0))
-    amber_L_q          = float(cfg.get("iris_sector_amber_L_q", 0.80))
+    amber_L_q         = float(cfg.get("iris_sector_amber_L_q", 0.80))
     amber_strict_a_min = float(cfg.get("iris_sector_amber_strict_a_min", 2.5))
     amber_strict_b_min = float(cfg.get("iris_sector_amber_strict_b_min", 6.0))
 
+    # anti-pupila / low-L drop
     anti_pupil_enabled   = bool(cfg.get("anti_pupil_enabled", True))
     anti_pupil_guard_px  = int(cfg.get("anti_pupil_guard_px", 3))
     anti_pupil_c_low_thr = float(cfg.get("anti_pupil_c_low_thr", 6.0))
@@ -160,39 +185,60 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
     lowL_drop_q          = float(cfg.get("lowL_drop_q", 0.10))
     lowL_drop_max_frac   = float(cfg.get("lowL_drop_max_frac", 0.20))
 
+    # nudge periférico pré-setorização
     pre_nudge_enabled     = bool(cfg.get("pre_sector_peripheral_nudge_enabled", True))
     pre_nudge_c_low_thr   = float(cfg.get("pre_sector_c_low_thr", 6.0))
     pre_nudge_high_max    = float(cfg.get("pre_sector_highlight_max", 0.02))
     pre_nudge_sclera_max  = float(cfg.get("pre_sector_sclera_max", 0.02))
     pre_nudge_pct         = float(cfg.get("pre_sector_nudge_pct", 0.025))
 
+    # edge-guard (cílios)
     edge_guard_enabled = bool(cfg.get("edge_guard_enabled", True))
     edge_guard_lap_thr = float(cfg.get("edge_guard_lap_thr", 22.0))
     edge_guard_L_rel_q = float(cfg.get("edge_guard_L_rel_q", 0.35))
 
-    lash_cfg = cfg.get("eyelash_guard", {})
-    lash_enabled   = bool(lash_cfg.get("enabled", True))
-    lash_top_extra = float(lash_cfg.get("top_extra_deg", 6.0))
-    lash_lap_thr   = float(lash_cfg.get("lap_thr", 26.0))
-    lash_L_rel_q   = float(lash_cfg.get("L_rel_q", 0.40))
-    lash_drop_q    = float(lash_cfg.get("drop_q", 0.20))
-    lash_max_frac  = float(lash_cfg.get("max_frac_of_keep", 0.15))
-
-    # >>> NOVO: parâmetros de exclusão angular hard (finalmente aplicados)
-    excl_top_deg = float(cfg.get("iris_sector_exclude_top_deg", 0.0))   # topo = 270°
-    excl_bot_deg = float(cfg.get("iris_sector_exclude_bottom_deg", 0.0))# base = 90°
-
-    # Gate castanho
-    brown_gate = cfg.get("brown_eye_gate", {})
-    brown_enabled      = bool(brown_gate.get("enabled", True))
-    br_b_q50_min       = float(brown_gate.get("b_q50_min", 1.8))
-    br_L_med_min       = float(brown_gate.get("L_med_min", 28.0))
-    br_L_med_max       = float(brown_gate.get("L_med_max", 58.0))
-    br_C_med_min       = float(brown_gate.get("C_med_min", 6.0))
-    cool_b_lt          = float(brown_gate.get("cool_protect_b_q50_lt", 1.0))
-    cool_a_le          = float(brown_gate.get("cool_protect_a_q50_le", 0.0))
-    cool_L_ge          = float(brown_gate.get("cool_protect_L_med_ge", 55.0))
-
+    # Eyelash Guard (já existente)
+    lash_cfg = cfg.get("eyelash_guard", {
+        "enabled": True,
+        "top_extra_deg": 10.0,
+        "lap_thr": 24.0,
+        "L_rel_q": 0.50,
+        "drop_q": 0.30,
+        "max_frac_of_keep": 0.25,
+        "theta_deg": 14.0,
+        "lap_ratio_thr": 1.22,
+        "top_frac_min": 0.05,
+        "c_drop_delta_frac": 0.06,
+        "L_drop_min": 3.0,
+        "max_frac_hard": 0.45
+    })
+
+    # NOVOS: hard-gate, guards locais, bans setoriais, cool-preserve, nudge down-only
+    hard_cfg = cfg.get("eyelid_hard_gate", {
+        "enabled": True,
+        "top_deg_width": 22.0,
+        "bottom_deg_width": 18.0,
+        "apply_when": { "lap_ratio_thr": 1.18, "L_rel_q": 0.55, "min_zone_frac": 0.045 }
+    })
+    local_guard_cfg = cfg.get("local_guard", {
+        "enabled": True,
+        "top":    {"lap_thr": 23.0, "L_rel_q": 0.55, "drop_q": 0.35, "max_frac": 0.35},
+        "bottom": {"lap_thr": 22.0, "L_rel_q": 0.50, "drop_q": 0.30, "max_frac": 0.30}
+    })
+    sector_ban_cfg = cfg.get("sector_ban", {
+        "top_deg": 28.0,
+        "bottom_deg": 24.0
+    })
+    cool_preserve_cfg = cfg.get("cool_preserve", {
+        "enabled": True,
+        "b_med_max": 0.0,
+        "L_min": 46.0,
+        "C_max": 6.8
+    })
+    nudge_down_only = cfg.get("iris_radial_nudge_down_only", {"enabled": True, "pct_max": 0.05})
+    min_eye_area_px = int(cfg.get("face_parsing",{}).get("min_eye_px", 180))
+
+    # Upscale ROI
     upcfg = cfg.get("eyes_roi_upscale", {"enabled": False})
     roi_up_enabled = bool(upcfg.get("enabled", False))
     roi_target_r   = float(upcfg.get("target_r_px", 140.0))
@@ -204,14 +250,15 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
 
     H, W = int(orig_rgb.shape[0]), int(orig_rgb.shape[1])
 
+    # ---- ROIs a partir da máscara semântica ----
     cnts = _contours_from_mask(eyes_mask)
     cnts = cnts[:2]
     rois = []
     for c in cnts:
-        if cv.contourArea(c) < int(cfg.get("face_parsing",{}).get("min_eye_px", 180)): continue
-        x, y, w2, h2 = cv.boundingRect(c)
+        if cv.contourArea(c) < min_eye_area_px: continue
+        x, y, w, h = cv.boundingRect(c)
         x0 = max(0, x-6); y0 = max(0, y-6)
-        x1 = min(W, x+w2+6); y1 = min(H, y+h2+6)
+        x1 = min(W, x+w+6); y1 = min(H, y+h+6)
         if (x1-x0) < 10 or (y1-y0) < 10: continue
         roi  = orig_rgb[y0:y1, x0:x1]
         mroi = eyes_mask[y0:y1, x0:x1].astype(bool)
@@ -219,9 +266,13 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
     if not rois:
         return None, {"tech":"mp_iris","gate_reason":"no_eyes_mask"}
 
+    # ---- MediaPipe ----
     face_result = None
     if mp_face is not None:
-        with mp_face.FaceMesh(static_image_mode=True, refine_landmarks=True, max_num_faces=1, min_detection_confidence=0.5) as fm:
+        with mp_face.FaceMesh(static_image_mode=True,
+                              refine_landmarks=True,
+                              max_num_faces=1,
+                              min_detection_confidence=0.5) as fm:
             bgr = cv.cvtColor(orig_rgb.astype(np.uint8), cv.COLOR_RGB2BGR)
             res = fm.process(bgr)
             if res and res.multi_face_landmarks:
@@ -245,19 +296,24 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
             right_circ = _iris_circle_from_lms(face_result, cand)
             if right_circ is not None: break
 
-    def _stats_on_mask(L, a, b, mk):
-        if not mk.any():
-            return {"px":0,"L":None,"a":None,"b":None,"C":None}
-        Lm = float(np.nanmedian(L[mk]))
-        am = float(np.nanmedian(a[mk])); bm = float(np.nanmedian(b[mk]))
-        Cm = float(np.nanmedian(np.hypot(a[mk], b[mk])))
-        return {"px":int(mk.sum()),"L":Lm,"a":am,"b":bm,"C":Cm}
-
-    candidates = []
-
+    # ---- Helpers de setorização ----
+    def _sector_masks(h, w, cx, cy, keep, n):
+        Y, X = np.ogrid[:h, :w]
+        ang = (np.degrees(np.arctan2((Y - cy), (X - cx))) + 360.0) % 360.0
+        step = 360.0 / float(n)
+        masks = []
+        for i in range(n):
+            a0 = i*step; a1 = (i+1)*step
+            masks.append(keep & (ang >= a0) & (ang < a1))
+        return masks, step
+
+    # ---- Avaliador de um candidato (um olho) ----
     def _score_one(roi, mroi, bbox, cx_abs, cy_abs, r_abs, tech_label):
         x0,y0,x1,y1 = bbox
 
+        # ============================
+        # NORMALIZAÇÃO DO ROI (UP-ONLY)
+        # ============================
         r_abs_pre = float(r_abs)
         roi_scale = 1.0
         if roi_up_enabled and r_abs_pre > 0:
@@ -273,16 +329,19 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
                     r_abs  = r_abs_pre * s
                     roi_scale = float(s)
 
+        # parâmetros escalados
         band_min_w   = max(14, int(round(base_band_min_w * roi_scale)))
-        min_ring_px  = int(round(base_min_ring_px * (roi_scale**2) * (roi_area_fac if roi_scale>1.0 else 1.0)))
+        min_ring_px  = int(round(base_min_ring_px * (roi_scale**2) * (0.8 if roi_scale>1.0 else 1.0)))
         guard_px     = max(1, int(round(base_guard_px * roi_scale)))
         min_px_after = int(round(base_min_px_after * (roi_scale**2) * (0.8 if roi_scale>1.0 else 1.0)))
 
+        # coords relativas ao ROI
         cx = cx_abs - x0; cy = cy_abs - y0
         h,w = roi.shape[:2]
         if cx < 0 or cy < 0 or cx >= w or cy >= h or r_abs <= 2.0:
             return None
 
+        # Banda base
         rin  = max(2.0, float(r_abs) * float(inner_fr[0]))
         rout = min(float(r_abs)*0.98, float(r_abs) * float(outer_fr[1]))
         if (rout - rin) < (band_min_w - 0.5):
@@ -298,7 +357,9 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
         rgb_u8 = roi.astype(np.uint8)
         L, a, b = _rgb2lab_uint8(rgb_u8)
         S       = _hsv_S(rgb_u8)
+        ang     = _angular_field(h, w, cx, cy)
 
+        # Clipes globais
         L_ring = L[ring]
         if L_ring.size == 0:
             return None
@@ -312,51 +373,108 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
         if int(keep.sum()) < 20:
             return None
 
-        # >>> AQUI: EXCLUSÃO ANGULAR HARD (Topo=270°, Base=90°) <<<
-        # Aplica antes de qualquer outra etapa setorial; respeita massa mínima.
-        top_cut_px = 0
-        bot_cut_px = 0
-        if (excl_top_deg > 0.0) or (excl_bot_deg > 0.0):
-            Yg, Xg = np.ogrid[:h, :w]
-            ang = (np.degrees(np.arctan2((Yg - cy), (Xg - cx))) + 360.0) % 360.0
-            def _band(center_deg, half_width):
-                # distância angular mínima no círculo
-                return np.abs(((ang - center_deg + 180.0) % 360.0) - 180.0) <= half_width
-
-            keep2 = keep.copy()
-            if excl_top_deg > 0.0:
-                top_band = _band(270.0, excl_top_deg)
-                cand = keep & top_band
-                cut = int(cand.sum())
-                if cut > 0 and (int(keep.sum()) - cut) >= max(20, min_px_after):
-                    keep2[cand] = False
-                    top_cut_px = cut
-            if excl_bot_deg > 0.0:
-                bot_band = _band(90.0, excl_bot_deg)
-                cand = keep2 & bot_band
-                cut = int(cand.sum())
-                if cut > 0 and (int(keep2.sum()) - cut) >= max(20, min_px_after):
-                    keep2[cand] = False
-                    bot_cut_px = cut
-            if int(keep2.sum()) >= 20:
-                keep = keep2
+        # ====== HARD-GATE (TOP/BOTTOM) — ANTES DE TUDO ======
+        hard_applied_top = hard_applied_bottom = False
+        keep_px_before_hard = int(keep.sum())
+        top_hard_px = bottom_hard_px = 0
+
+        if bool(hard_cfg.get("enabled", True)):
+            top_w = float(hard_cfg.get("top_deg_width", 22.0))
+            bot_w = float(hard_cfg.get("bottom_deg_width", 18.0))
+            cond  = hard_cfg.get("apply_when", {"lap_ratio_thr":1.18,"L_rel_q":0.55,"min_zone_frac":0.045})
+
+            gray = cv.cvtColor(rgb_u8, cv.COLOR_RGB2GRAY)
+            lap  = _laplacian_mag(gray)
+            L_ref_top = float(np.nanquantile(L[keep], float(cond.get("L_rel_q", 0.55)))) if int(keep.sum()) else 0.0
+
+            top_zone = keep & (_ang_dist_deg(ang, TOP_DEG) <= top_w*0.5)
+            bot_zone = keep & (_ang_dist_deg(ang, BOTTOM_DEG) <= bot_w*0.5)
+
+            # razão de textura (laplacian) no topo vs restante
+            rest_zone = keep & (~top_zone)
+            lap_top_mean  = float(np.nanmean(lap[top_zone]))  if np.any(top_zone) else 0.0
+            lap_rest_mean = float(np.nanmean(lap[rest_zone])) if np.any(rest_zone) else 1.0
+            lap_ratio = (lap_top_mean / (lap_rest_mean+1e-6)) if lap_rest_mean>0 else 0.0
+
+            min_frac = float(cond.get("min_zone_frac", 0.045))
+            if np.any(top_zone) and float(np.mean(top_zone)) >= min_frac and (lap_ratio >= float(cond.get("lap_ratio_thr",1.18)) or float(np.nanmedian(L[top_zone])) <= L_ref_top):
+                to_drop = int(np.sum(top_zone))
+                keep[top_zone] = False
+                top_hard_px = to_drop
+                hard_applied_top = True
+
+            if np.any(bot_zone) and float(np.mean(bot_zone)) >= (min_frac*0.8):
+                # simples corte da base (suave, com critério de L)
+                L_ref_bot = float(np.nanquantile(L[keep], 0.50)) if int(keep.sum()) else 0.0
+                if float(np.nanmedian(L[bot_zone])) <= L_ref_bot:
+                    to_drop = int(np.sum(bot_zone))
+                    keep[bot_zone] = False
+                    bottom_hard_px = to_drop
+                    hard_applied_bottom = True
+
+        keep_px_after_hard = int(keep.sum())
+        if int(keep.sum()) < 20:
+            return None
 
-        # ---- (restante do pipeline permanece igual) ----
+        # ====== LOCAL GUARDS (TOP/BOTTOM) — ainda antes de midband ======
+        lg_top_drop = lg_bottom_drop = 0
+        if bool(local_guard_cfg.get("enabled", True)) and keep.any():
+            gray = cv.cvtColor(rgb_u8, cv.COLOR_RGB2GRAY)
+            lap  = _laplacian_mag(gray)
+            top_lg = local_guard_cfg.get("top", {"lap_thr":23.0,"L_rel_q":0.55,"drop_q":0.35,"max_frac":0.35})
+            bot_lg = local_guard_cfg.get("bottom", {"lap_thr":22.0,"L_rel_q":0.50,"drop_q":0.30,"max_frac":0.30})
+
+            # TOP local
+            top_w = float(hard_cfg.get("top_deg_width", 22.0))
+            top_zone = keep & (_ang_dist_deg(ang, TOP_DEG) <= top_w*0.5)
+            if np.any(top_zone):
+                L_ref = float(np.nanquantile(L[keep], float(top_lg.get("L_rel_q",0.55)))) if int(keep.sum()) else 0.0
+                lap_thr = float(top_lg.get("lap_thr", 23.0))
+                if float(np.nanmean(lap[top_zone])) >= lap_thr and float(np.nanmedian(L[top_zone])) <= L_ref:
+                    thr_low = float(np.nanquantile(L[top_zone], float(top_lg.get("drop_q",0.35))))
+                    mask_drop = top_zone & (L < thr_low)
+                    max_frac  = float(top_lg.get("max_frac",0.35))
+                    to_drop   = int(mask_drop.sum())
+                    if to_drop > 0 and to_drop <= int(max_frac * int(keep.sum())) and (int(keep.sum())-to_drop)>=20:
+                        keep[mask_drop] = False
+                        lg_top_drop = to_drop
+
+            # BOTTOM local
+            bot_w = float(hard_cfg.get("bottom_deg_width", 18.0))
+            bot_zone = keep & (_ang_dist_deg(ang, BOTTOM_DEG) <= bot_w*0.5)
+            if np.any(bot_zone):
+                L_ref = float(np.nanquantile(L[keep], float(bot_lg.get("L_rel_q",0.50)))) if int(keep.sum()) else 0.0
+                lap_thr = float(bot_lg.get("lap_thr", 22.0))
+                if float(np.nanmedian(L[bot_zone])) <= L_ref:
+                    thr_low = float(np.nanquantile(L[bot_zone], float(bot_lg.get("drop_q",0.30))))
+                    mask_drop = bot_zone & (L < thr_low)
+                    max_frac  = float(bot_lg.get("max_frac",0.30))
+                    to_drop   = int(mask_drop.sum())
+                    if to_drop > 0 and to_drop <= int(max_frac * int(keep.sum())) and (int(keep.sum())-to_drop)>=20:
+                        keep[mask_drop] = False
+                        lg_bottom_drop = to_drop
+
+        keep_px_after_guard = int(keep.sum())
+        if int(keep.sum()) < 20:
+            return None
 
+        # ----- Anti-pupila / Low-L drop -----
         anti_pupil_applied = False
         lowL_drop_px = 0
 
         L_keep_all = L[keep]
         C_keep_all = np.hypot(a[keep], b[keep]).astype(np.float32)
-        c_mean_full = float(np.nanmean(C_keep_all)) if C_keep_all.size else 0.0
+        C_mean_full = float(np.nanmean(C_keep_all)) if C_keep_all.size else 0.0
         L_p50_all   = float(np.nanmedian(L_keep_all)) if L_keep_all.size else 0.0
 
-        if anti_pupil_enabled and (c_mean_full < anti_pupil_c_low_thr or L_p50_all < anti_pupil_L_p50_low):
-            rin += float(anti_pupil_guard_px) * roi_scale
-            if (rout - rin) < band_min_w:
-                rout = min(float(r_abs)*0.98, rin + band_min_w)
-            keep = _ring_mask(h,w, cx, cy, rin, rout) & (~mask_high) & (~mask_scl) & mroi
-            anti_pupil_applied = True
+        if anti_pupil_enabled and (C_mean_full < anti_pupil_c_low_thr or L_p50_all < anti_pupil_L_p50_low):
+            rin2 = rin + float(anti_pupil_guard_px) * roi_scale
+            if (rout - rin2) < band_min_w:
+                rout = min(float(r_abs)*0.98, rin2 + band_min_w)
+            keep2 = _ring_mask(h,w, cx, cy, rin2, rout) & keep
+            if int(keep2.sum()) >= 20:
+                keep = keep2; rin = rin2
+                anti_pupil_applied = True
 
         if lowL_drop_enabled:
             L_ring2 = L[keep]
@@ -373,11 +491,153 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
         if int(keep.sum()) < 20:
             return None
 
-        # … (demais etapas: eyelid_lm_cut/edge/trim/brown_gate/nudges/seleção, mantidas)
-        # Para manter a resposta objetiva, todas as outras lógicas permanecem como já estavam
-        # na tua base atual — não alterei pesos nem thresholds aqui.
+        # ----- Midband / low-C -----
+        band_mode = "full"
+        L_keep = L[keep]; a_keep = a[keep]; b_keep = b[keep]
+        C_keep = np.hypot(a_keep, b_keep).astype(np.float32)
+        c_mean_full = float(np.nanmean(C_keep)) if C_keep.size else 0.0
+        l_mean_full = float(np.nanmean(L_keep))
+        highlight_frac = float(np.mean(mask_high)) if ring.any() else 1.0
+        sclera_frac    = float(np.mean(mask_scl))  if ring.any() else 1.0
+
+        need_mid = False
+        if int(ring.sum()) < min_ring_px or ((rout - rin) < (band_min_w + 0.5)) or (highlight_frac >= 0.22) or (sclera_frac >= 0.18):
+            need_mid = True
+        elif (mid_enabled and c_mean_full < mid_thrC):
+            need_mid = True
+        if need_mid:
+            band_mode = "midband"
+            midr  = 0.5*(rin + rout)
+            hw    = max(1.0, float(mid_hw_frac) * float(r_abs))
+            rin2  = max(rin + mid_guard,  midr - hw)
+            rout2 = min(rout - mid_guard, midr + hw)
+            sub = _ring_mask(h,w, cx, cy, rin2, rout2) & keep
+            if int(sub.sum()) >= 20:
+                keep = sub
+                rin, rout = rin2, rout2
+
+        if int(keep.sum()) < 20:
+            return None
+
+        # ----- Pre-nudge periférico -----
+        pre_sector_nudge_applied = False
+        pre_sector_nudge_applied_pct = 0.0
+        if pre_nudge_enabled and c_mean_full < pre_nudge_c_low_thr and highlight_frac <= pre_nudge_high_max and sclera_frac <= pre_nudge_sclera_max:
+            shift = float(pre_nudge_pct) * float(r_abs)
+            rin3  = max(2.0, rin + shift)
+            rout3 = min(float(r_abs)*0.98, rout + shift)
+            test = _ring_mask(h,w, cx, cy, rin3, rout3) & keep
+            if int(test.sum()) >= int(0.75*int(keep.sum())):
+                keep = test
+                rin, rout = rin3, rout3
+                pre_sector_nudge_applied = True
+                pre_sector_nudge_applied_pct = pre_nudge_pct
 
-        # MÉTRICA FINAL (medianas, com ponderação lowC se ativada)
+        if int(keep.sum()) < 20:
+            return None
+
+        # ----- Top-trim / Edge-guard (existentes) -----
+        top_trim_tex_applied = False
+        edge_guard_applied = False
+
+        if trim_enabled and keep.any():
+            # trim relativo ao TOPO (270°)
+            top_sector = keep & (_ang_dist_deg(ang, TOP_DEG) <= float(trim_deg_top))
+            if top_sector.any():
+                thrT = np.nanquantile(L[keep], 1.0 - float(trim_L_rel_q))
+                keep2 = keep.copy()
+                keep2[top_sector & (L < thrT)] = False
+                if int(keep2.sum()) >= int(0.8*int(keep.sum())) and int(keep2.sum()) >= 20:
+                    keep = keep2
+                    top_trim_tex_applied = True
+
+        if edge_guard_enabled and keep.any():
+            lap = _laplacian_mag(cv.cvtColor(roi.astype(np.uint8), cv.COLOR_RGB2GRAY))
+            masks, step = _sector_masks(h, w, cx, cy, keep, max(1,sector_count))
+            L_ref = float(np.nanquantile(L[keep], edge_guard_L_rel_q))
+            drop = np.zeros(len(masks), dtype=bool)
+            for i, mk in enumerate(masks):
+                if not mk.any():
+                    continue
+                lap_m = float(np.nanmean(lap[mk]))
+                if lap_m >= edge_guard_lap_thr:
+                    if float(np.nanmedian(L[mk])) <= L_ref:
+                        drop[i] = True
+            if drop.any():
+                keep2 = keep.copy()
+                for i, d in enumerate(drop):
+                    if d: keep2[masks[i]] = False
+                if int(keep2.sum()) >= int(0.75*int(keep.sum())) and int(keep2.sum()) >= min_px_after:
+                    keep = keep2
+                    edge_guard_applied = True
+
+        if int(keep.sum()) < 20:
+            return None
+
+        # ===== Banimento setorial explícito TOP/BOTTOM =====
+        selected_arc_deg = 0.0
+        final_mode = band_mode
+        radial_shift_pct = 0.0
+
+        masks, step = _sector_masks(h, w, cx, cy, keep, max(1,sector_count))
+        ban_top_deg    = float(sector_ban_cfg.get("top_deg", 28.0))
+        ban_bottom_deg = float(sector_ban_cfg.get("bottom_deg", 24.0))
+        banned_any = False
+
+        if keep.any():
+            top_mask = (_ang_dist_deg(ang, TOP_DEG) <= ban_top_deg*0.5) & keep
+            if np.any(top_mask):
+                keep[top_mask] = False
+                banned_any = True
+
+            bottom_mask = (_ang_dist_deg(ang, BOTTOM_DEG) <= ban_bottom_deg*0.5) & keep
+            if np.any(bottom_mask):
+                keep[bottom_mask] = False
+                banned_any = True
+
+        if int(keep.sum()) < 20:
+            return None
+
+        # ===== NUDGE RADIAL pós-seleção (DOWN-ONLY) =====
+        if bool(nudge_down_only.get("enabled", True)):
+            pct_max = float(nudge_down_only.get("pct_max", 0.05))
+            # condição igual à antiga, mas só permite deslocar para "baixo" (aumentar rin/rout no sentido radial)
+            L_tmp = L[keep]; a_tmp = a[keep]; b_tmp = b[keep]
+            C_tmp = np.hypot(a_tmp, b_tmp).astype(np.float32)
+            c_mean_sel = float(np.nanmean(C_tmp)) if C_tmp.size else 0.0
+            b_med_sel  = float(np.nanmedian(b_tmp)) if b_tmp.size else 0.0
+            l_mean_sel = float(np.nanmean(L_tmp))   if L_tmp.size else 0.0
+
+            if (l_mean_sel >= float(cfg.get("iris_radial_nudge_L_min", 46.0))
+                and c_mean_sel <= float(cfg.get("iris_radial_nudge_C_max", 6.5))
+                and b_med_sel >= float(cfg.get("iris_radial_nudge_b_min", 0.0))):
+                shift = pct_max * float(r_abs)
+                rin2  = max(2.0, rin + shift)
+                rout2 = min(float(r_abs)*0.98, rout + shift)
+                ring2 = _ring_mask(h,w, cx, cy, rin2, rout2) & keep
+                if int(ring2.sum()) >= min_px_after:
+                    keep = ring2
+                    radial_shift_pct = pct_max
+                    final_mode = (final_mode + "+nudgeDown")
+
+        if int(keep.sum()) < 20:
+            return None
+
+        # ===== Cool-preserve (não aquecer olhos frios/claros) =====
+        cool_preserve_applied = False
+        if bool(cool_preserve_cfg.get("enabled", True)) and keep.any():
+            L_f = L[keep]; a_f = a[keep]; b_f = b[keep]
+            C_f = np.hypot(a_f, b_f).astype(np.float32)
+            b_med = float(np.nanmedian(b_f)) if b_f.size else 0.0
+            L_med = float(np.nanmedian(L_f)) if L_f.size else 0.0
+            C_med = float(np.nanmedian(C_f)) if C_f.size else 0.0
+            if (b_med <= float(cool_preserve_cfg.get("b_med_max", 0.0))) or \
+               (L_med >= float(cool_preserve_cfg.get("L_min", 46.0)) and C_med <= float(cool_preserve_cfg.get("C_max", 6.8))):
+                # Desabilita trims/â mbar nesse caso (não alteramos keep aqui, só sinalizamos)
+                cool_preserve_applied = True
+                # Nada a excluir adicionalmente — apenas evita heurísticas “quentes” em outros estágios externos
+
+        # ----- MÉDIA FINAL -----
         L_f = L[keep]; a_f = a[keep]; b_f = b[keep]
         C_f = np.hypot(a_f, b_f).astype(np.float32)
         if C_f.size == 0:
@@ -404,26 +664,52 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
             "rin": float(rin), "rout": float(rout),
             "roi_bbox": [int(x0),int(y0),int(x1),int(y1)],
             "overlay_b64": overlay_b64,
-            "band_mode": "full",
+            "band_mode": final_mode if final_mode else band_mode,
             "band_width_px": float(rout-rin),
             "highlight_frac": float(np.mean(mask_high)) if ring.any() else 1.0,
             "sclera_frac": float(np.mean(mask_scl))  if ring.any() else 1.0,
-            "c_mean_full": c_mean_full,
-            "l_mean_full": float(np.nanmean(L_f)) if L_f.size else 0.0,
-            # >>> novos diags
-            "angular_top_cut_px": int(top_cut_px),
-            "angular_bottom_cut_px": int(bot_cut_px)
+            "c_mean_full": float(c_mean_full),
+            "l_mean_full": float(l_mean_full),
+
+            # Ângulos de referência (auto-audit)
+            "top_deg_ref": float(TOP_DEG),
+            "bottom_deg_ref": float(BOTTOM_DEG),
+
+            # Auditoria hard/local guards
+            "keep_px_before_hard": int(keep_px_before_hard),
+            "top_hard_px": int(top_hard_px),
+            "bottom_hard_px": int(bottom_hard_px),
+            "keep_px_after_hard": int(keep_px_after_hard),
+            "top_guard_drop_px": int(lg_top_drop),
+            "bottom_guard_drop_px": int(lg_bottom_drop),
+            "keep_px_after_guard": int(keep_px_after_guard),
+
+            # Seleção/setor/nudge
+            "selected_arc_deg": float(selected_arc_deg),
+            "radial_shift_pct": float(radial_shift_pct),
+
+            # Flags já existentes
+            "anti_pupil_applied": bool(anti_pupil_applied),
+            "lowL_drop_px": int(lowL_drop_px),
+            "top_trim_tex_applied": bool(top_trim_tex_applied),
+            "edge_guard_applied": bool(edge_guard_applied),
+
+            # Proteção de cor fria
+            "cool_preserve_applied": bool(cool_preserve_applied),
         }
 
+        stats = {
+            "L": Lm, "a": am, "b": bm, "C": Cm, "area": ring_px_final,
+            "L_p50": float(np.nanmedian(L_f)), "C_p50": float(np.nanmedian(C_f))
+        }
         return {
-            "score": float(ring_px_final),
-            "stats": {
-                "L": Lm, "a": am, "b": bm, "C": Cm, "area": ring_px_final,
-                "L_p50": float(np.nanmedian(L_f)), "C_p50": float(np.nanmedian(C_f))
-            },
+            "score": float(ring_px_final * (1.0 - float(np.mean(mask_high)) if ring.any() else 1.0) * (1.0 - float(np.mean(mask_scl)) if ring.any() else 1.0)),
+            "stats": stats,
             "diag": diag
         }
 
+    # 1) círculos do MediaPipe
+    candidates = []
     if face_result is not None:
         for (roi, mroi, bbox) in rois:
             for circ in (left_circ, right_circ):
@@ -434,6 +720,7 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
                 cand = _score_one(roi, mroi, bbox, cx_abs, cy_abs, r_abs, tech_label="mp_iris")
                 if cand is not None: candidates.append(cand)
 
+    # 2) fallback geométrico
     if not candidates:
         for (roi, mroi, bbox) in rois:
             m = mroi.astype(np.uint8)
@@ -448,7 +735,15 @@ def localize_iris_and_sample_mediapipe(orig_rgb, eyes_mask, config=None, debug=F
             if cand is not None: candidates.append(cand)
 
     if not candidates:
-        return None, {"tech":"mp_iris","gate_reason":"no_valid_ring","ring_px":0,"overlay_b64":None}
+        return None, {
+            "tech":"mp_iris","gate_reason":"no_valid_ring",
+            "ring_px":0,"cx":None,"cy":None,"rin":None,"rout":None,
+            "roi_bbox":None,"overlay_b64":None,"band_mode":None,
+            "band_width_px":None,"highlight_frac":0.0,"sclera_frac":0.0,
+            "c_mean_full":None,"l_mean_full":None,
+            "final_mode": None, "selected_arc_deg": 0.0, "radial_shift_pct": 0.0,
+            "top_deg_ref": float(TOP_DEG), "bottom_deg_ref": float(BOTTOM_DEG)
+        }
 
     best = max(candidates, key=lambda c: c["score"])
     stats = best["stats"].copy()