char colors

2026-01-20 15:18:56 +01:00
parent 4088a1efd0
commit 4195c67b0c
20 changed files with 465 additions and 95 deletions
--- a/docs/04_desarrollo_especifico.md
+++ b/docs/04_desarrollo_especifico.md
@@ -18,7 +18,7 @@ Los documentos académicos típicos incluyen texto corrido entremezclado con tab

 Se seleccionaron tres soluciones OCR de código abierto representativas del estado del arte:

-**Tabla 11.** *Soluciones OCR evaluadas en el benchmark comparativo.*
+**Tabla 20.** *Soluciones OCR evaluadas en el benchmark comparativo.*

 | Solución | Desarrollador | Versión | Justificación de selección |
 |----------|---------------|---------|----------------------------|
@@ -49,7 +49,7 @@ Los criterios establecidos para evaluar las soluciones fueron:

 Se utilizó el documento "Instrucciones para la redacción y elaboración del TFE" del Máster Universitario en Inteligencia Artificial de UNIR, ubicado en la carpeta `instructions/`.

-**Tabla 12.** *Características del dataset de evaluación inicial.*
+**Tabla 21.** *Características del dataset de evaluación inicial.*

 | Característica | Valor |
 |----------------|-------|
@@ -90,7 +90,7 @@ Se utilizó la biblioteca `jiwer` para calcular CER y WER de manera estandarizad

 Durante el benchmark inicial se evaluó PaddleOCR con configuración por defecto en un subconjunto del dataset. Los resultados preliminares mostraron variabilidad significativa entre páginas, con CER entre 1.54% y 6.40% dependiendo de la complejidad del layout.

-**Tabla 13.** *Variabilidad del CER por tipo de contenido.*
+**Tabla 22.** *Variabilidad del CER por tipo de contenido.*

 | Tipo de contenido | CER aproximado | Observaciones |
 |-------------------|----------------|---------------|
@@ -115,7 +115,7 @@ Durante el benchmark inicial se evaluó PaddleOCR con configuración por defecto

 Los tres modelos evaluados representan diferentes paradigmas de OCR:

-**Tabla 14.** *Comparativa de arquitecturas OCR evaluadas.*
+**Tabla 23.** *Comparativa de arquitecturas OCR evaluadas.*

 | Modelo | Tipo | Componentes | Fortalezas Clave |
 |--------|------|-------------|------------------|
@@ -156,7 +156,7 @@ Un análisis cualitativo de los errores producidos reveló patrones específicos

 La selección de PaddleOCR para la fase de optimización se basó en los siguientes criterios:

-**Tabla 15.** *Evaluación de criterios de selección.*
+**Tabla 24.** *Evaluación de criterios de selección.*

 | Criterio | EasyOCR | PaddleOCR | DocTR |
 |----------|---------|-----------|-------|
@@ -227,7 +227,7 @@ Esta aproximación ofrece ventajas significativas frente al fine-tuning tradicio

 El experimento se ejecutó en el siguiente entorno:

-**Tabla 16.** *Entorno de ejecución del experimento.*
+**Tabla 25.** *Entorno de ejecución del experimento.*

 | Componente | Versión/Especificación |
 |------------|------------------------|
@@ -307,7 +307,7 @@ Respuesta del servicio OCR:

 La infraestructura del proyecto se basa en contenedores Docker para garantizar reproducibilidad y aislamiento de dependencias. Se generaron seis imágenes Docker, cada una optimizada para su propósito específico.

-**Tabla 17.** *Imágenes Docker generadas para el proyecto.*
+**Tabla 26.** *Imágenes Docker generadas para el proyecto.*

 | Imagen | Propósito | Base | Puerto |
 |--------|-----------|------|--------|
@@ -397,7 +397,7 @@ flowchart LR

 El proyecto incluye múltiples archivos Docker Compose para diferentes escenarios de uso:

-**Tabla 18.** *Archivos Docker Compose del proyecto.*
+**Tabla 27.** *Archivos Docker Compose del proyecto.*

 | Archivo | Propósito | Servicios |
 |---------|-----------|-----------|
@@ -414,7 +414,7 @@ El proyecto incluye múltiples archivos Docker Compose para diferentes escenario

 Se utilizan volúmenes Docker nombrados para persistir los modelos descargados entre ejecuciones:

-**Tabla 19.** *Volúmenes Docker para caché de modelos.*
+**Tabla 28.** *Volúmenes Docker para caché de modelos.*

 | Volumen | Servicio | Contenido |
 |---------|----------|-----------|
@@ -517,7 +517,7 @@ Los resultados de los experimentos están disponibles en:

 Para la fase de optimización se extendió el dataset:

-**Tabla 20.** *Características del dataset de optimización.*
+**Tabla 29.** *Características del dataset de optimización.*

 | Característica | Valor |
 |----------------|-------|
@@ -535,7 +535,7 @@ La clase `ImageTextDataset` gestiona la carga de pares imagen-texto desde la est

 El espacio de búsqueda se definió considerando los hiperparámetros más relevantes identificados en la documentación de PaddleOCR, utilizando `tune.choice()` para parámetros booleanos y `tune.uniform()` para umbrales continuos. La implementación está disponible en `src/raytune/raytune_ocr.py` (ver Anexo A).

-**Tabla 21.** *Descripción detallada del espacio de búsqueda.*
+**Tabla 30.** *Descripción detallada del espacio de búsqueda.*

 | Parámetro | Tipo | Rango | Descripción |
 |-----------|------|-------|-------------|
@@ -561,7 +561,7 @@ El espacio de búsqueda se definió considerando los hiperparámetros más relev

 Se configuró Ray Tune con OptunaSearch como algoritmo de búsqueda, optimizando CER en 64 trials con 2 ejecuciones concurrentes. La implementación está disponible en `src/raytune/raytune_ocr.py` (ver Anexo A).

-**Tabla 22.** *Parámetros de configuración de Ray Tune.*
+**Tabla 31.** *Parámetros de configuración de Ray Tune.*

 | Parámetro | Valor | Justificación |
 |-----------|-------|---------------|
@@ -587,7 +587,7 @@ El número de trials se eligió considerando:

 El experimento se ejecutó exitosamente con los siguientes resultados globales:

-**Tabla 23.** *Resumen de la ejecución del experimento.*
+**Tabla 32.** *Resumen de la ejecución del experimento.*

 | Métrica | Valor |
 |---------|-------|
@@ -603,7 +603,7 @@ El experimento se ejecutó exitosamente con los siguientes resultados globales:

 Del archivo CSV de resultados (`src/results/raytune_paddle_results_20260119_122609.csv`):

-**Tabla 24.** *Estadísticas descriptivas de los 64 trials.*
+**Tabla 33.** *Estadísticas descriptivas de los 64 trials.*

 | Estadística | CER | WER | Tiempo/Página (s) |
 |-------------|-----|-----|-------------------|
@@ -626,7 +626,7 @@ Del archivo CSV de resultados (`src/results/raytune_paddle_results_20260119_1226

 #### Distribución de Resultados

-**Tabla 25.** *Distribución de trials por rango de CER.*
+**Tabla 34.** *Distribución de trials por rango de CER.*

 | Rango CER | Número de trials | Porcentaje |
 |-----------|------------------|------------|
@@ -637,6 +637,24 @@ Del archivo CSV de resultados (`src/results/raytune_paddle_results_20260119_1226

 *Fuente: Elaboración propia a partir de `src/results/raytune_paddle_results_20260119_122609.csv`.*

+```mermaid
+---
+title: "Distribución de trials por rango de CER"
+config:
+  theme: base
+  themeVariables:
+    primaryColor: "#E6F4F9"
+    primaryTextColor: "#404040"
+    primaryBorderColor: "#0098CD"
+    lineColor: "#0098CD"
+---
+pie showData
+    title Distribución de 64 trials
+    "CER < 2%" : 43
+    "CER 2-5%" : 10
+    "CER 5-10%" : 11
+```
+
 La mayoría de trials (67.2%) alcanzaron CER < 2%, cumpliendo el objetivo establecido. Ningún trial presentó fallos catastróficos (CER > 10%), demostrando la estabilidad de la optimización con GPU.

 #### Mejor Configuración Encontrada
@@ -657,7 +675,7 @@ Configuración óptima:
  text_rec_score_thresh: 0.5658
 ```

-**Tabla 26.** *Configuración óptima identificada.*
+**Tabla 35.** *Configuración óptima identificada.*

 | Parámetro | Valor óptimo | Valor por defecto | Cambio |
 |-----------|--------------|-------------------|--------|
@@ -675,7 +693,7 @@ Configuración óptima:

 Se calculó la correlación de Pearson entre los parámetros continuos y las métricas de error:

-**Tabla 27.** *Correlación de parámetros con CER.*
+**Tabla 36.** *Correlación de parámetros con CER.*

 | Parámetro | Correlación con CER | Interpretación |
 |-----------|---------------------|----------------|
@@ -686,7 +704,7 @@ Se calculó la correlación de Pearson entre los parámetros continuos y las mé

 *Fuente: Análisis de [`src/results/`](https://seryus.ddns.net/unir/MastersThesis/-/tree/main/src/results) generados por [`src/run_tuning.py`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/run_tuning.py).*

-**Tabla 28.** *Correlación de parámetros con WER.*
+**Tabla 37.** *Correlación de parámetros con WER.*

 | Parámetro | Correlación con WER | Interpretación |
 |-----------|---------------------|----------------|
@@ -696,13 +714,34 @@ Se calculó la correlación de Pearson entre los parámetros continuos y las mé

 *Fuente: Análisis de [`src/results/`](https://seryus.ddns.net/unir/MastersThesis/-/tree/main/src/results) generados por [`src/run_tuning.py`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/run_tuning.py).*

+```mermaid
+---
+title: "Correlación de hiperparámetros con CER"
+config:
+  theme: base
+  themeVariables:
+    primaryColor: "#E6F4F9"
+    primaryTextColor: "#404040"
+    primaryBorderColor: "#0098CD"
+    lineColor: "#0098CD"
+  xyChart:
+    plotColorPalette: "#0098CD"
+---
+xychart-beta
+    x-axis ["text_det_thresh", "text_det_box_thresh", "text_rec_score_thresh"]
+    y-axis "Correlación con CER" -0.6 --> 0.3
+    bar [-0.523, 0.226, -0.161]
+```
+
+*Leyenda: Valores negativos indican que aumentar el parámetro reduce el CER. El parámetro `text_det_thresh` tiene la correlación más fuerte (-0.52).*
+
 **Hallazgo clave**: El parámetro `text_det_thresh` muestra la correlación más fuerte (-0.52 con ambas métricas), indicando que valores más altos de este umbral tienden a reducir el error. Este umbral controla qué píxeles se consideran "texto" en el mapa de probabilidad del detector.

 #### Impacto del Parámetro textline_orientation

 El parámetro booleano `textline_orientation` demostró tener el mayor impacto en el rendimiento:

-**Tabla 29.** *Impacto del parámetro textline_orientation.*
+**Tabla 38.** *Impacto del parámetro textline_orientation.*

 | textline_orientation | CER Medio | CER Std | WER Medio | N trials |
 |---------------------|-----------|---------|-----------|----------|
@@ -729,6 +768,8 @@ config:
    primaryTextColor: "#404040"
    primaryBorderColor: "#0098CD"
    lineColor: "#0098CD"
+  xyChart:
+    plotColorPalette: "#0098CD"
 ---
 xychart-beta
    x-axis ["textline_orientation=False", "textline_orientation=True"]
@@ -744,7 +785,7 @@ El parámetro `textline_orientation` activa un clasificador que determina la ori

 Los trials con CER muy alto (>20%) presentaron patrones específicos:

-**Tabla 30.** *Características de trials con fallos catastróficos.*
+**Tabla 39.** *Características de trials con fallos catastróficos.*

 | Trial | CER | text_det_thresh | textline_orientation | Diagnóstico |
 |-------|-----|-----------------|---------------------|-------------|
@@ -771,7 +812,7 @@ Los trials con CER muy alto (>20%) presentaron patrones específicos:

 La configuración óptima identificada se evaluó sobre el dataset completo de 45 páginas, comparando con la configuración baseline (valores por defecto de PaddleOCR). Los parámetros optimizados más relevantes fueron: `textline_orientation=True`, `use_doc_orientation_classify=True`, `text_det_thresh=0.0462`, `text_det_box_thresh=0.4862`, y `text_rec_score_thresh=0.5658`.

-**Tabla 31.** *Comparación baseline vs optimizado (45 páginas).*
+**Tabla 40.** *Comparación baseline vs optimizado (45 páginas).*

 | Modelo | CER | Precisión Caracteres | WER | Precisión Palabras |
 |--------|-----|---------------------|-----|-------------------|
@@ -784,7 +825,7 @@ La configuración óptima identificada se evaluó sobre el dataset completo de 4

 #### Métricas de Mejora

-**Tabla 32.** *Análisis cuantitativo de la mejora.*
+**Tabla 41.** *Análisis cuantitativo de la mejora.*

 | Forma de Medición | CER | WER |
 |-------------------|-----|-----|
@@ -807,6 +848,8 @@ config:
    primaryTextColor: "#404040"
    primaryBorderColor: "#0098CD"
    lineColor: "#0098CD"
+  xyChart:
+    plotColorPalette: "#0098CD"
 ---
 xychart-beta
    x-axis ["CER Baseline", "CER Optimizado", "WER Baseline", "WER Optimizado"]
@@ -835,7 +878,7 @@ xychart-beta

 ### Tiempo de Ejecución

-**Tabla 33.** *Métricas de tiempo del experimento (GPU).*
+**Tabla 42.** *Métricas de tiempo del experimento (GPU).*

 | Métrica | Valor |
 |---------|-------|
@@ -871,7 +914,7 @@ Los resultados obtenidos en las secciones anteriores requieren un análisis que

 #### Progresión del Rendimiento

-**Tabla 34.** *Evolución del rendimiento a través del estudio.*
+**Tabla 43.** *Evolución del rendimiento a través del estudio.*

 | Fase | Configuración | CER | Mejora vs anterior |
 |------|--------------|-----|-------------------|
@@ -881,11 +924,32 @@ Los resultados obtenidos en las secciones anteriores requieren un análisis que

 *Fuente: Elaboración propia.*

+```mermaid
+---
+title: "Evolución del CER a través del estudio"
+config:
+  theme: base
+  themeVariables:
+    primaryColor: "#E6F4F9"
+    primaryTextColor: "#404040"
+    primaryBorderColor: "#0098CD"
+    lineColor: "#0098CD"
+  xyChart:
+    plotColorPalette: "#0098CD"
+---
+xychart-beta
+    x-axis ["Baseline", "Mejor trial (5 pág)", "Validación (45 pág)"]
+    y-axis "CER (%)" 0 --> 10
+    bar [8.85, 0.79, 7.72]
+```
+
+*Leyenda: El mejor trial alcanza CER 0.79% (objetivo cumplido). La validación sobre dataset completo muestra CER 7.72%, evidenciando sobreajuste al subconjunto de optimización.*
+
 El incremento del CER de 0.79% (5 páginas) a 7.72% (45 páginas) evidencia sobreajuste al subconjunto de optimización. Este fenómeno es esperado cuando se optimiza sobre un subconjunto pequeño y se valida sobre el dataset completo con mayor diversidad de layouts.

 #### Comparación con Objetivo

-**Tabla 35.** *Verificación del objetivo general.*
+**Tabla 44.** *Verificación del objetivo general.*

 | Aspecto | Objetivo | Resultado (trial) | Resultado (full) | Cumplimiento |
 |---------|----------|-------------------|------------------|--------------|
@@ -904,7 +968,7 @@ El incremento del CER de 0.79% (5 páginas) a 7.72% (45 páginas) evidencia sobr

 Basándose en el análisis de los resultados de optimización:

-**Tabla 36.** *Ranking de importancia de hiperparámetros.*
+**Tabla 45.** *Ranking de importancia de hiperparámetros.*

 | Rank | Parámetro | Impacto | Evidencia |
 |------|-----------|---------|-----------|
@@ -917,6 +981,27 @@ Basándose en el análisis de los resultados de optimización:

 *Fuente: Elaboración propia basada en [`src/results/raytune_paddle_results_20260119_122609.csv`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/results/raytune_paddle_results_20260119_122609.csv).*

+```mermaid
+---
+title: "Ranking de importancia de hiperparámetros"
+config:
+  theme: base
+  themeVariables:
+    primaryColor: "#E6F4F9"
+    primaryTextColor: "#404040"
+    primaryBorderColor: "#0098CD"
+    lineColor: "#0098CD"
+  xyChart:
+    plotColorPalette: "#0098CD"
+---
+xychart-beta horizontal
+    x-axis ["use_doc_unwarping", "text_rec_score_thresh", "text_det_box_thresh", "text_det_thresh", "use_doc_orientation", "textline_orientation"]
+    y-axis "Impacto relativo" 0 --> 100
+    bar [0, 30, 40, 70, 80, 100]
+```
+
+*Leyenda: Impacto relativo estimado basado en análisis de correlación y presencia en configuraciones óptimas. `textline_orientation` es el parámetro más crítico.*
+
 #### Análisis del Parámetro textline_orientation

 **Por qué es tan importante:**
@@ -969,7 +1054,7 @@ Para documentos PDF digitales como los evaluados, este módulo es innecesario y

 #### Clasificación de Errores

-**Tabla 37.** *Tipología de errores observados.*
+**Tabla 46.** *Tipología de errores observados.*

 | Tipo de error | Frecuencia | Ejemplo | Causa probable |
 |---------------|------------|---------|----------------|
@@ -983,7 +1068,7 @@ Para documentos PDF digitales como los evaluados, este módulo es innecesario y

 #### Patrones de Fallo por Tipo de Contenido

-**Tabla 38.** *Tasa de error por tipo de contenido.*
+**Tabla 47.** *Tasa de error por tipo de contenido.*

 | Tipo de contenido | CER estimado | Factor de riesgo |
 |-------------------|--------------|------------------|
@@ -998,7 +1083,7 @@ Para documentos PDF digitales como los evaluados, este módulo es innecesario y

 ### Comparación con Objetivos Específicos

-**Tabla 39.** *Cumplimiento de objetivos específicos.*
+**Tabla 48.** *Cumplimiento de objetivos específicos.*

 | Objetivo | Descripción | Resultado | Estado |
 |----------|-------------|-----------|--------|
@@ -1044,7 +1129,7 @@ Para documentos PDF digitales como los evaluados, este módulo es innecesario y

 Para documentos académicos en español similares a los evaluados:

-**Tabla 40.** *Configuración recomendada para PaddleOCR con GPU.*
+**Tabla 49.** *Configuración recomendada para PaddleOCR con GPU.*

 | Parámetro | Valor | Prioridad | Justificación |
 |-----------|-------|-----------|---------------|
@@ -1108,7 +1193,7 @@ Esta sección presenta la comparación de rendimiento entre ejecución en CPU y

 #### Configuración del Entorno GPU

-**Tabla 41.** *Especificaciones del entorno GPU utilizado.*
+**Tabla 50.** *Especificaciones del entorno GPU utilizado.*

 | Componente | Especificación |
 |------------|----------------|
@@ -1126,7 +1211,7 @@ Este hardware representa configuración típica de desarrollo, permitiendo evalu

 Se comparó el tiempo de procesamiento entre CPU y GPU utilizando los datos de [`src/raytune_paddle_subproc_results_20251207_192320.csv`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/raytune_paddle_subproc_results_20251207_192320.csv) (CPU) y [`src/results/raytune_paddle_results_20260119_122609.csv`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/results/raytune_paddle_results_20260119_122609.csv) (GPU).

-**Tabla 42.** *Rendimiento comparativo CPU vs GPU.*
+**Tabla 51.** *Rendimiento comparativo CPU vs GPU.*

 | Métrica | CPU | GPU (RTX 3060) | Factor de Aceleración |
 |---------|-----|----------------|----------------------|
@@ -1136,6 +1221,27 @@ Se comparó el tiempo de procesamiento entre CPU y GPU utilizando los datos de [

 *Fuente: Elaboración propia a partir de [`src/raytune_paddle_subproc_results_20251207_192320.csv`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/raytune_paddle_subproc_results_20251207_192320.csv) y [`src/results/raytune_paddle_results_20260119_122609.csv`](https://seryus.ddns.net/unir/MastersThesis/-/blob/main/src/results/raytune_paddle_results_20260119_122609.csv).*

+```mermaid
+---
+title: "Tiempo de procesamiento: CPU vs GPU (segundos/página)"
+config:
+  theme: base
+  themeVariables:
+    primaryColor: "#E6F4F9"
+    primaryTextColor: "#404040"
+    primaryBorderColor: "#0098CD"
+    lineColor: "#0098CD"
+  xyChart:
+    plotColorPalette: "#0098CD"
+---
+xychart-beta
+    x-axis ["CPU", "GPU (RTX 3060)"]
+    y-axis "Segundos por página" 0 --> 75
+    bar [69.4, 0.84]
+```
+
+*Leyenda: Aceleración de **82×** con GPU. El procesamiento de una página pasa de 69.4s (CPU) a 0.84s (GPU).*
+
 La aceleración de 82× obtenida con GPU transforma la viabilidad del enfoque:
 - **Optimización en CPU (6.4 horas)**: Viable pero lento para iteraciones rápidas
 - **Optimización en GPU (1.5 horas)**: Permite explorar más configuraciones y realizar múltiples experimentos
@@ -1145,7 +1251,7 @@ La aceleración de 82× obtenida con GPU transforma la viabilidad del enfoque:

 PaddleOCR ofrece dos variantes de modelos: Mobile (optimizados para dispositivos con recursos limitados) y Server (mayor precisión a costa de mayor consumo de memoria). Se evaluó la viabilidad de ambas variantes en el hardware disponible.

-**Tabla 43.** *Comparación de modelos Mobile vs Server en RTX 3060.*
+**Tabla 52.** *Comparación de modelos Mobile vs Server en RTX 3060.*

 | Modelo | VRAM Requerida | Resultado | Recomendación |
 |--------|----------------|-----------|---------------|