Update app.py

app.py

@@ -14,7 +14,7 @@ import cv2
 import gradio as gr
 import numpy as np
 import torch
-from PIL import Image, ImageOps, ImageEnhance, ImageFilter
+from PIL import Image, ImageOps
 from huggingface_hub import snapshot_download
 from transformers import AutoImageProcessor, AutoTokenizer, VisionEncoderDecoderModel
 from ultralytics import YOLO
@@ -47,6 +47,12 @@ except AttributeError:
 # UTILIDADES GENERALES
 # ============================================================
 def clean_plate_text(text: str) -> str:
+    """
+    Normaliza texto de placa:
+    - mayúsculas
+    - sin espacios
+    - sin símbolos
+    """
     if not text:
         return ""
     text = text.upper().strip()
@@ -61,7 +67,7 @@ def save_pil_image(pil_img: Image.Image, suffix: str = ".png") -> str:
     return tmp.name
 
 
-def pad_box(x1, y1, x2, y2, w, h, pad_ratio=0.10):
+def pad_box(x1, y1, x2, y2, w, h, pad_ratio=0.08):
     bw = x2 - x1
     bh = y2 - y1
     pad_x = int(bw * pad_ratio)
@@ -94,6 +100,9 @@ def draw_box_and_label(pil_img: Image.Image, box, label: str) -> Image.Image:
 
 
 def levenshtein_distance(a: str, b: str) -> int:
+    """
+    Distancia de Levenshtein clásica para CER y exactitud parcial.
+    """
     a = a or ""
     b = b or ""
     if a == b:
@@ -116,6 +125,9 @@ def levenshtein_distance(a: str, b: str) -> int:
 
 
 def image_hash(pil_img: Image.Image) -> str:
+    """
+    Hash simple para detectar duplicados de imágenes.
+    """
     arr = np.array(pil_img.convert("RGB"))
     return str(hash(arr.tobytes()))
 
@@ -125,10 +137,6 @@ def safe_mean(values):
     return float(np.mean(values)) if values else 0.0
 
 
-def clamp01(x: float) -> float:
-    return float(max(0.0, min(1.0, x)))
-
-
 def try_save_histogram(values, title, out_path, bins=20):
     try:
         import matplotlib.pyplot as plt
@@ -166,150 +174,75 @@ def try_save_bar(counter_obj, title, out_path, max_items=20):
 
 
 # ============================================================
-# GEOMETRÍA / RECTIFICACIÓN DE ROI
+# PREPROCESADO PARA OCR
 # ============================================================
-def order_points(pts):
-    rect = np.zeros((4, 2), dtype="float32")
-    s = pts.sum(axis=1)
-    diff = np.diff(pts, axis=1)
-
-    rect[0] = pts[np.argmin(s)]       # top-left
-    rect[2] = pts[np.argmax(s)]       # bottom-right
-    rect[1] = pts[np.argmin(diff)]    # top-right
-    rect[3] = pts[np.argmax(diff)]    # bottom-left
-    return rect
-
-
-def four_point_transform(image, pts):
-    rect = order_points(pts)
-    (tl, tr, br, bl) = rect
-
-    width_a = np.linalg.norm(br - bl)
-    width_b = np.linalg.norm(tr - tl)
-    max_width = int(max(width_a, width_b))
-
-    height_a = np.linalg.norm(tr - br)
-    height_b = np.linalg.norm(tl - bl)
-    max_height = int(max(height_a, height_b))
-
-    if max_width < 2 or max_height < 2:
-        return image
-
-    dst = np.array([
-        [0, 0],
-        [max_width - 1, 0],
-        [max_width - 1, max_height - 1],
-        [0, max_height - 1]
-    ], dtype="float32")
-
-    M = cv2.getPerspectiveTransform(rect, dst)
-    warped = cv2.warpPerspective(image, M, (max_width, max_height))
-    return warped
-
-
-def rotate_if_needed(pil_img: Image.Image) -> Image.Image:
-    arr = np.array(pil_img.convert("RGB"))
-    h, w = arr.shape[:2]
-    if h > w * 1.2:
-        arr = cv2.rotate(arr, cv2.ROTATE_90_CLOCKWISE)
-    return Image.fromarray(arr)
-
-
-def rectify_plate_roi(pil_img: Image.Image) -> Image.Image:
+def resize_keep_aspect(pil_img: Image.Image, target_height: int = 448) -> Image.Image:
     """
-    Intenta corregir perspectiva e inclinación dentro de la ROI.
+    Agranda la ROI manteniendo relación de aspecto.
     """
-    img = np.array(pil_img.convert("RGB"))
-    if img.size == 0:
-        return pil_img
-
-    gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
-    gray = cv2.bilateralFilter(gray, 7, 50, 50)
-
-    # Resalta bordes y contornos de la placa
-    edges = cv2.Canny(gray, 40, 140)
-    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3))
-    edges = cv2.morphologyEx(edges, cv2.MORPH_CLOSE, kernel, iterations=2)
-
-    contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
-    if contours:
-        contours = sorted(contours, key=cv2.contourArea, reverse=True)
-        h, w = img.shape[:2]
-        min_area = max(500, 0.08 * (h * w))
+    img = pil_img.convert("RGB")
+    w, h = img.size
+    if w == 0 or h == 0:
+        return img
 
-        for c in contours[:8]:
-            area = cv2.contourArea(c)
-            if area < min_area:
-                continue
+    scale = target_height / float(h)
+    new_w = max(1, int(round(w * scale)))
+    new_h = target_height
+    return img.resize((new_w, new_h), RESAMPLE_LANCZOS)
 
-            peri = cv2.arcLength(c, True)
-            approx = cv2.approxPolyDP(c, 0.02 * peri, True)
 
-            if len(approx) == 4:
-                pts = approx.reshape(4, 2).astype("float32")
-                warped = four_point_transform(img, pts)
-                out = Image.fromarray(warped)
-                return rotate_if_needed(out)
+def deskew_roi(pil_img: Image.Image) -> Image.Image:
+    """
+    Corrige inclinación leve de la ROI usando minAreaRect.
+    """
+    img_rgb = np.array(pil_img.convert("RGB"))
+    gray = cv2.cvtColor(img_rgb, cv2.COLOR_RGB2GRAY)
 
-    # Fallback: corrección de inclinación con minAreaRect
-    gray2 = cv2.GaussianBlur(gray, (3, 3), 0)
+    gray_blur = cv2.GaussianBlur(gray, (3, 3), 0)
     thresh = cv2.adaptiveThreshold(
-        gray2,
+        gray_blur,
         255,
         cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
         cv2.THRESH_BINARY_INV,
         31,
         11
     )
+
     coords = cv2.findNonZero(thresh)
     if coords is None:
-        return rotate_if_needed(pil_img)
+        return pil_img
 
     angle = cv2.minAreaRect(coords)[-1]
     if angle < -45:
         angle = 90 + angle
 
     if abs(angle) < 1.0:
-        return rotate_if_needed(pil_img)
+        return pil_img
 
-    h, w = img.shape[:2]
+    h, w = img_rgb.shape[:2]
     center = (w // 2, h // 2)
     M = cv2.getRotationMatrix2D(center, angle, 1.0)
+
     rotated = cv2.warpAffine(
-        img,
+        img_rgb,
         M,
         (w, h),
         flags=cv2.INTER_CUBIC,
         borderMode=cv2.BORDER_REPLICATE
     )
-    return rotate_if_needed(Image.fromarray(rotated))
-
-
-# ============================================================
-# PREPROCESADO OCR
-# ============================================================
-def resize_keep_aspect(pil_img: Image.Image, target_height: int = 448) -> Image.Image:
-    img = pil_img.convert("RGB")
-    w, h = img.size
-    if w == 0 or h == 0:
-        return img
-
-    scale = target_height / float(h)
-    new_w = max(1, int(round(w * scale)))
-    new_h = target_height
-    return img.resize((new_w, new_h), RESAMPLE_LANCZOS)
+    return Image.fromarray(rotated)
 
 
 def preprocess_for_ocr(pil_img: Image.Image, target_height: int = 448) -> Image.Image:
     """
-    OCR más robusto:
-    - rectificación de perspectiva/inclinación
-    - redimensionamiento
-    - denoise
-    - contraste local
+    Preprocesado principal para OCR:
+    - corrección leve de inclinación
+    - redimensionamiento manteniendo aspecto
+    - reducción de ruido
+    - mejora de contraste
     - nitidez
     """
-    img = rectify_plate_roi(pil_img)
+    img = deskew_roi(pil_img)
     img = resize_keep_aspect(img, target_height=target_height)
 
     arr = np.array(img.convert("RGB"))
@@ -317,7 +250,7 @@ def preprocess_for_ocr(pil_img: Image.Image, target_height: int = 448) -> Image.
 
     gray = cv2.fastNlMeansDenoising(gray, None, 10, 7, 21)
 
-    clahe = cv2.createCLAHE(clipLimit=2.2, tileGridSize=(8, 8))
+    clahe = cv2.createCLAHE(clipLimit=2.5, tileGridSize=(8, 8))
     gray = clahe.apply(gray)
 
     gray = cv2.GaussianBlur(gray, (3, 3), 0)
@@ -334,12 +267,15 @@ def preprocess_for_ocr(pil_img: Image.Image, target_height: int = 448) -> Image.
 
 
 def enhance_for_ocr(pil_img: Image.Image) -> Image.Image:
+    """
+    Se mantiene el nombre original para no alterar el resto del código.
+    """
     return preprocess_for_ocr(pil_img)
 
 
 def build_ocr_variants(pil_img: Image.Image):
     """
-    Variantes orientadas a placas con fondo amarillo / blanco y texto oscuro.
+    Genera pocas variantes, pero más útiles y más rápidas.
     """
     base = preprocess_for_ocr(pil_img)
     arr = np.array(base.convert("RGB"))
@@ -347,19 +283,9 @@ def build_ocr_variants(pil_img: Image.Image):
 
     variants = [base]
 
-    # Autocontraste suave
     variants.append(ImageOps.autocontrast(base))
 
-    # Sharpen
-    sharp = ImageEnhance.Sharpness(base).enhance(1.8)
-    variants.append(sharp)
-
-    # Otsu
-    _, otsu = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
-    variants.append(Image.fromarray(otsu).convert("RGB"))
-
-    # Adaptive threshold
-    adaptive = cv2.adaptiveThreshold(
+    th = cv2.adaptiveThreshold(
         gray,
         255,
         cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
@@ -367,29 +293,28 @@ def build_ocr_variants(pil_img: Image.Image):
         31,
         11
     )
-    variants.append(Image.fromarray(adaptive).convert("RGB"))
-
-    # Invertida por si el contraste viene al revés
-    inv = cv2.bitwise_not(otsu)
-    variants.append(Image.fromarray(inv).convert("RGB"))
+    variants.append(Image.fromarray(th).convert("RGB"))
 
     return variants
 
 
 # ============================================================
-# FORMATO DE PLACA Y CONSENSO OCR
+# CONSENSO OCR Y REGLAS DE FORMATO
 # ============================================================
+PLATE_PATTERN_STRICT = re.compile(r"^[A-Z]{3}\d{3}$")
+PLATE_PATTERN_LOOSE = re.compile(r"^[A-Z0-9]{6}$")
+
 LETTER_CANDIDATES = {
     "0": ("O",),
     "1": ("I", "L"),
     "2": ("Z",),
-    "3": ("B", "E"),
+    "3": ("B",),
     "4": ("A",),
     "5": ("S",),
-    "6": ("G", "Q"),
+    "6": ("Q", "G"),
     "7": ("T",),
     "8": ("B",),
-    "9": ("P",),
+    "9": ("P", "G"),
     "A": ("A",),
     "B": ("B",),
     "C": ("C",),
@@ -447,62 +372,44 @@ DIGIT_CANDIDATES = {
     "9": ("9",),
 }
 
-# Formatos comunes para placas colombianas y motos
-PLATE_TEMPLATES = [
-    ("LLLDDL", 1.35),  # como MAN54G
-    ("LLLDDD", 1.20),  # placas de 3 letras + 3 dígitos
-    ("LLLDDL", 1.10),  # variantes cercanas
-]
 
-STRICT_PATTERNS = [
-    re.compile(r"^[A-Z]{3}\d{2}[A-Z]$"),  # MAN54G
-    re.compile(r"^[A-Z]{3}\d{3}$"),       # ABC123
-    re.compile(r"^[A-Z]{3}\d{2}[A-Z0-9]$"),
-]
+def clamp01(x: float) -> float:
+    return float(max(0.0, min(1.0, x)))
 
 
 def normalize_plate_candidate(text: str) -> str:
     return clean_plate_text(text)
 
 
-def candidate_matches_template(text: str, template: str) -> float:
-    if len(text) != len(template):
-        return 0.0
-
-    score = 0.0
-    for ch, t in zip(text, template):
-        if t == "L":
-            if ch.isalpha():
-                score += 1.0
-            elif ch in LETTER_CANDIDATES:
-                score += 0.45
-        elif t == "D":
-            if ch.isdigit():
-                score += 1.0
-            elif ch in DIGIT_CANDIDATES:
-                score += 0.45
-
-    return score / float(len(template))
-
-
 def plate_format_score(text: str) -> float:
+    """
+    Puntaje simple por formato de placa.
+    - 1.0 si cumple exactamente LLLDDD
+    - valor intermedio si tiene 6 caracteres alfanuméricos
+    - 0.0 en otros casos
+    """
     if not text:
         return 0.0
 
-    if len(text) != 6:
-        return 0.0
-
-    best = 0.0
-    for template, weight in PLATE_TEMPLATES:
-        best = max(best, weight * candidate_matches_template(text, template))
+    if PLATE_PATTERN_STRICT.fullmatch(text):
+        return 1.0
 
-    if any(p.fullmatch(text) for p in STRICT_PATTERNS):
-        best = max(best, 1.0)
+    if len(text) == 6 and PLATE_PATTERN_LOOSE.fullmatch(text):
+        score = 0.0
+        for i, ch in enumerate(text):
+            if i < 3 and ch.isalpha():
+                score += 1.0 / 6.0
+            elif i >= 3 and ch.isdigit():
+                score += 1.0 / 6.0
+        return score
 
-    return best
+    return 0.0
 
 
 def expand_plate_candidate(text: str):
+    """
+    Expande un OCR candidato a variantes plausibles.
+    """
     text = clean_plate_text(text)
     if not text:
         return []
@@ -512,93 +419,82 @@ def expand_plate_candidate(text: str):
 
     options = []
     for i, ch in enumerate(text):
-        # Para placas tipo MAN54G, el último caracter puede ser letra
         if i < 3:
             opts = LETTER_CANDIDATES.get(ch, (ch,))
-        elif i in (3, 4):
-            opts = DIGIT_CANDIDATES.get(ch, (ch,))
         else:
-            # último carácter: permitir letra o dígito según contexto
-            opts = tuple(sorted(set(LETTER_CANDIDATES.get(ch, (ch,)) + DIGIT_CANDIDATES.get(ch, (ch,)))))
+            opts = DIGIT_CANDIDATES.get(ch, (ch,))
         options.append(opts)
 
     variants = {"".join(chars) for chars in product(*options)}
-    return sorted(list(variants))[:128]
-
-
-def template_bonus_for_text(text: str) -> float:
-    best = 0.0
-    for template, weight in PLATE_TEMPLATES:
-        best = max(best, weight * candidate_matches_template(text, template))
-    return best
+    return sorted(list(variants))[:64]
 
 
 def choose_best_plate(candidates):
     """
-    Selecciona la mejor hipótesis por consenso entre variantes y beams.
-    Devuelve: texto, confianza OCR calibrada, diagnóstico.
+    Combina hipótesis OCR y devuelve:
+    - mejor placa
+    - confianza relativa normalizada
+    - diagnóstico
     """
     if not candidates:
         return "", 0.0, {"n_candidates": 0}
 
-    aggregated = defaultdict(lambda: {"score_sum": 0.0, "votes": 0})
+    filtered = []
+    for raw_text, raw_weight in candidates:
+        text = normalize_plate_candidate(raw_text)
+        if len(text) == 6 and PLATE_PATTERN_LOOSE.fullmatch(text):
+            filtered.append((text, float(raw_weight)))
 
-    for raw_text, raw_score in candidates:
-        cleaned = normalize_plate_candidate(raw_text)
-        if not cleaned:
-            continue
+    if not filtered:
+        fallback = normalize_plate_candidate(candidates[0][0])
+        return fallback, 0.0, {"n_candidates": 0}
 
-        expanded = expand_plate_candidate(cleaned)
-        if not expanded:
-            expanded = [cleaned]
+    total_weight = sum(w for _, w in filtered) + 1e-8
 
-        for cand in expanded:
-            # Penaliza ediciones frente al texto base y premia el formato plausible
-            edits = sum(a != b for a, b in zip(cleaned, cand))
-            fmt = plate_format_score(cand)
-            adjusted = float(raw_score) + (1.40 * fmt) - (0.18 * edits)
-            aggregated[cand]["score_sum"] += adjusted
-            aggregated[cand]["votes"] += 1
+    pos_votes = [defaultdict(float) for _ in range(6)]
+    text_votes = defaultdict(float)
 
-    if not aggregated:
-        fallback = normalize_plate_candidate(candidates[0][0])
-        return fallback, 0.0, {"n_candidates": 0}
+    for text, weight in filtered:
+        format_bonus = 1.0 if PLATE_PATTERN_STRICT.fullmatch(text) else 0.65
+        w = weight * format_bonus
+        text_votes[text] += w
+        for i, ch in enumerate(text):
+            pos_votes[i][ch] += w
 
     scored = []
-    for cand, data in aggregated.items():
-        votes = data["votes"]
-        mean_score = data["score_sum"] / max(votes, 1)
-        consensus = np.log1p(votes)
-        fmt = plate_format_score(cand)
-        final_score = mean_score + 0.45 * consensus + 0.80 * fmt
-        scored.append((cand, final_score, votes, fmt))
+    for text, weight_sum in text_votes.items():
+        pos_score = 0.0
+        for i in range(6):
+            dist = pos_votes[i]
+            if not dist:
+                continue
+            best_ch, best_w = max(dist.items(), key=lambda kv: kv[1])
+            pos_total = sum(dist.values()) + 1e-8
+            pos_score += best_w / pos_total
+
+        consensus = weight_sum / total_weight
+        format_score = plate_format_score(text)
+        score = (
+            0.50 * consensus +
+            0.25 * (pos_score / 6.0) +
+            0.25 * format_score
+        )
+        scored.append((text, score, consensus, format_score))
 
     scored.sort(key=lambda x: x[1], reverse=True)
 
-    scores = np.array([s for _, s, _, _ in scored], dtype=np.float32)
-    probs = np.exp(scores - scores.max())
-    probs = probs / max(1e-8, probs.sum())
-
-    best_text = scored[0][0]
-    best_soft = float(probs[0])
-    best_fmt = float(scored[0][3])
-
-    # Confianza OCR calibrada
-    ocr_conf = clamp01(
-        0.42 * best_soft +
-        0.28 * best_fmt +
-        0.30 * min(1.0, np.log1p(scored[0][2]) / 2.5)
-    )
+    best_text, best_score, best_consensus, best_format = scored[0]
+    best_conf = clamp01(best_score)
 
     diagnostics = {
-        "n_candidates": len(aggregated),
-        "top_score": round(float(scored[0][1]), 4),
-        "top_format_score": round(best_fmt, 4),
-        "top_soft_prob": round(best_soft, 4),
-        "top_votes": int(scored[0][2]),
+        "n_candidates": len(filtered),
+        "best_consensus": round(float(best_consensus), 4),
+        "best_format_score": round(float(best_format), 4),
+        "top_score": round(float(best_score), 4),
+        "top_text": best_text,
     }
 
-    return best_text, ocr_conf, diagnostics
+    return best_text, best_conf, diagnostics
 
 
 # ============================================================
@@ -628,26 +524,17 @@ def load_ocr():
     try:
         image_processor = AutoImageProcessor.from_pretrained(OCR_REPO_ID, token=HF_TOKEN)
     except Exception:
-        image_processor = AutoImageProcessor.from_pretrained(
-            "microsoft/trocr-base-printed",
-            token=HF_TOKEN
-        )
+        image_processor = AutoImageProcessor.from_pretrained("microsoft/trocr-base-printed", token=HF_TOKEN)
 
     try:
         tokenizer = AutoTokenizer.from_pretrained(OCR_REPO_ID, token=HF_TOKEN)
     except Exception:
-        tokenizer = AutoTokenizer.from_pretrained(
-            "microsoft/trocr-base-printed",
-            token=HF_TOKEN
-        )
+        tokenizer = AutoTokenizer.from_pretrained("microsoft/trocr-base-printed", token=HF_TOKEN)
 
     try:
         model = VisionEncoderDecoderModel.from_pretrained(OCR_REPO_ID, token=HF_TOKEN)
     except Exception:
-        model = VisionEncoderDecoderModel.from_pretrained(
-            "microsoft/trocr-base-printed",
-            token=HF_TOKEN
-        )
+        model = VisionEncoderDecoderModel.from_pretrained("microsoft/trocr-base-printed", token=HF_TOKEN)
 
     model.to(DEVICE)
     model.eval()
@@ -659,18 +546,21 @@ def load_ocr():
 # OCR ROBUSTO
 # ============================================================
 def ocr_variant_candidates(variant: Image.Image, image_processor, tokenizer, ocr_model):
+    """
+    Genera varias hipótesis OCR sobre una misma variante.
+    """
     pixel_values = image_processor(images=variant, return_tensors="pt").pixel_values.to(DEVICE)
 
     with torch.inference_mode():
         generated = ocr_model.generate(
             pixel_values,
-            max_new_tokens=8,
-            num_beams=8,
-            num_return_sequences=8,
+            max_new_tokens=10,
+            num_beams=3,
+            num_return_sequences=3,
             do_sample=False,
             early_stopping=True,
-            length_penalty=-0.2,
-            repetition_penalty=1.10,
+            length_penalty=0.0,
+            repetition_penalty=1.05,
             no_repeat_ngram_size=0,
             return_dict_in_generate=True,
             output_scores=True,
@@ -692,6 +582,9 @@ def ocr_variant_candidates(variant: Image.Image, image_processor, tokenizer, ocr
 
 
 def ocr_plate_from_roi(roi: Image.Image, image_processor, tokenizer, ocr_model):
+    """
+    OCR robusto sobre la ROI mejorada.
+    """
     variants = build_ocr_variants(roi)
     all_candidates = []
 
@@ -711,46 +604,25 @@ def ocr_plate_from_roi(roi: Image.Image, image_processor, tokenizer, ocr_model):
 
 
 def calibrate_total_confidence(det_conf: float, ocr_conf: float) -> float:
+    """
+    Combina detector + OCR de forma más estable que el producto directo.
+    """
     det_conf = clamp01(det_conf)
     ocr_conf = clamp01(ocr_conf)
 
-    # OCR pesa más porque es lo que valida el serial final
     total = 0.35 * det_conf + 0.65 * ocr_conf
     return round(clamp01(total), 4)
 
 
-# ============================================================
-# JUSTIFICACIÓN EXPERIMENTAL
-# ============================================================
-def build_experimental_justification():
-    return {
-        "detector": "YOLO porque es rápido, práctico y adecuado para localizar placas en imágenes completas.",
-        "ocr": "TrOCR porque trabaja bien sobre recortes de texto y permite consenso mediante beam search.",
-        "preprocessing": [
-            "Rectificación de perspectiva e inclinación para estabilizar caracteres.",
-            "Redimensionamiento manteniendo aspect ratio para estabilizar la entrada del OCR.",
-            "Reducción de ruido sin destruir bordes de caracteres.",
-            "CLAHE para mejorar contraste local.",
-            "Variantes con Otsu, binarización adaptativa, autocontraste e inversión para consenso OCR."
-        ],
-        "decision_rules": [
-            "Se usa un umbral de detección moderado para equilibrar precisión y recall.",
-            "Se aplica padding al bounding box para no recortar caracteres periféricos.",
-            "Se calcula una confianza aproximada combinando la confianza del detector y el consenso OCR.",
-            "Se priorizan formatos de 6 caracteres como LLLDDD y LLLDDL, útiles para placas vistas en la actividad."
-        ],
-        "limitations": [
-            "La confianza total es heurística y no sustituye una calibración formal.",
-            "La lectura final depende de la calidad de la detección y del recorte.",
-            "La evaluación real requiere ground truth para detección y OCR."
-        ]
-    }
-
-
 # ============================================================
 # ANÁLISIS DE DATOS
 # ============================================================
 def parse_yolo_label_file(label_path: Path, img_w: int, img_h: int):
+    """
+    Lee etiquetas YOLO y las convierte a coordenadas absolutas.
+    Formato esperado por línea:
+    class x_center y_center width height
+    """
     boxes = []
     if not label_path.exists():
         return boxes
@@ -784,6 +656,9 @@ def parse_yolo_label_file(label_path: Path, img_w: int, img_h: int):
 
 
 def analyze_detection_dataset(images_dir, labels_dir, output_dir="analysis_out"):
+    """
+    Analiza dataset de detección en formato YOLO.
+    """
     images_dir = Path(images_dir)
     labels_dir = Path(labels_dir)
     output_dir = Path(output_dir)
@@ -887,6 +762,12 @@ def analyze_detection_dataset(images_dir, labels_dir, output_dir="analysis_out")
 
 
 def analyze_ocr_dataset(csv_path, image_col="image_path", text_col="text", output_dir="analysis_out"):
+    """
+    Analiza dataset OCR en CSV.
+    Se espera mínimo:
+    - image_path
+    - text
+    """
     output_dir = Path(output_dir)
     output_dir.mkdir(parents=True, exist_ok=True)
 
@@ -964,6 +845,34 @@ def analyze_ocr_dataset(csv_path, image_col="image_path", text_col="text", outpu
     return report
 
 
+def build_experimental_justification():
+    """
+    Justificación experimental para el informe.
+    """
+    return {
+        "detector": "YOLO porque es rápido, práctico y adecuado para localizar placas en imágenes completas.",
+        "ocr": "TrOCR porque trabaja bien sobre recortes de texto y admite inferencia robusta con beam search.",
+        "preprocessing": [
+            "Redimensionamiento manteniendo aspect ratio para estabilizar la entrada del OCR.",
+            "Reducción de ruido para evitar perder bordes de caracteres.",
+            "CLAHE para mejorar contraste local.",
+            "Corrección leve de inclinación para ayudar al OCR.",
+            "Variantes adicionales con binarización adaptativa y autocontraste para consenso OCR."
+        ],
+        "decision_rules": [
+            "Se usa un umbral de detección moderado para equilibrar precisión y recall.",
+            "Se aplica padding al bounding box para no recortar caracteres periféricos.",
+            "Se calcula una confianza aproximada combinando la confianza del detector y la estabilidad OCR.",
+            "Se prioriza el patrón LLLDDD cuando el candidato tiene 6 caracteres."
+        ],
+        "limitations": [
+            "La confianza total es heurística y no sustituye una calibración formal.",
+            "El patrón LLLDDD puede no ser válido para todas las regiones.",
+            "La evaluación real requiere ground truth para detección y OCR."
+        ]
+    }
+
+
 # ============================================================
 # ENTRENAMIENTO DEL DETECTOR
 # ============================================================
@@ -979,6 +888,10 @@ def train_detector(
     project: str = "runs/train",
     name: str = "plates_detector"
 ):
+    """
+    Entrenamiento del detector YOLO sobre un dataset propio.
+    Requiere data.yaml en formato Ultralytics.
+    """
     model = YOLO(base_model)
     results = model.train(
         data=data_yaml,
@@ -1007,6 +920,9 @@ def xywh_to_xyxy(xc, yc, bw, bh, img_w, img_h):
 
 
 def compute_iou(box_a, box_b):
+    """
+    box = (x1, y1, x2, y2)
+    """
     ax1, ay1, ax2, ay2 = box_a
     bx1, by1, bx2, by2 = box_b
 
@@ -1036,6 +952,14 @@ def evaluate_detector_on_yolo_dataset(
     iou_threshold=0.5,
     max_images=None
 ):
+    """
+    Evalúa detección con métricas tipo:
+    - precision
+    - recall
+    - F1
+    - IoU promedio
+    - tiempo medio de inferencia
+    """
     images_dir = Path(images_dir)
     labels_dir = Path(labels_dir)
 
@@ -1139,6 +1063,9 @@ def evaluate_detector_on_yolo_dataset(
 
 
 def ultralytics_val_metrics(model, data_yaml):
+    """
+    Intenta extraer mAP50 y mAP50-95 usando la validación de Ultralytics.
+    """
     try:
         val_res = model.val(data=data_yaml, verbose=False)
         box = getattr(val_res, "box", None)
@@ -1165,6 +1092,12 @@ def evaluate_ocr_csv(
     ocr_model=None,
     max_rows=None
 ):
+    """
+    Evalúa OCR con métricas:
+    - exact match rate
+    - CER
+    - accuracy por caracteres
+    """
     if image_processor is None or tokenizer is None or ocr_model is None:
         image_processor, tokenizer, ocr_model = load_ocr()
 
@@ -1236,6 +1169,11 @@ def evaluate_end_to_end_csv(
     iou_threshold=0.5,
     max_rows=None
 ):
+    """
+    Evaluación integral:
+    - detección: IoU, precision, recall
+    - OCR: exact match, CER
+    """
     if detector is None:
         detector = load_detector()
     if image_processor is None or tokenizer is None or ocr_model is None:
@@ -1305,7 +1243,7 @@ def evaluate_end_to_end_csv(
                     det_fp += 1
                     det_fn += 1
 
-            x1, y1, x2, y2 = pad_box(*pred_box, w, h, pad_ratio=0.12)
+            x1, y1, x2, y2 = pad_box(*pred_box, w, h, pad_ratio=0.10)
             roi = img.crop((x1, y1, x2, y2))
             roi = enhance_for_ocr(roi)
 
@@ -1382,13 +1320,12 @@ def process_image(image: Image.Image):
             int(y2),
             w,
             h,
-            pad_ratio=0.12
+            pad_ratio=0.10
         )
 
         roi = image.crop((x1, y1, x2, y2))
         roi_display = enhance_for_ocr(roi)
 
-        # OCR sobre la ROI mejorada
         plate_text, ocr_conf, ocr_diag = ocr_plate_from_roi(
             roi_display,
             image_processor,