mve-micro-docs/OCR_SETUP.md

# Guía de Instalación y Configuración de OCR

## <20> ¿Usas Docker? (Recomendado)

Si usas **Docker Compose**, **NO necesitas instalar nada localmente**. Todo está incluido en el contenedor.

### Instalación con Docker

1. **Asegúrate de tener tu archivo `.env` configurado:**
```env
OCR_ENABLED=true
OCR_LANGUAGE=spa
OCR_DPI=300
OCR_TIMEOUT=300
```

2. **Construir y levantar los contenedores:**
```bash
docker-compose build
docker-compose up -d
```

3. **Verificar que Tesseract está instalado en el contenedor:**
```bash
docker exec mve-incrementables-parser tesseract --version
docker exec mve-incrementables-parser tesseract --list-langs
```

¡Eso es todo! El Dockerfile ya incluye:
- ✅ Tesseract OCR
- ✅ Paquete de idioma español (spa)
- ✅ Poppler-utils (para conversión PDF a imagen)
- ✅ Todas las dependencias Python

**Salta al final de este documento para ver cómo probar**.

---

## 💻 Instalación Local (Sin Docker)

Solo sigue estas instrucciones si **NO usas Docker** y ejecutas el servicio directamente en tu máquina.

## <20>📋 Requisitos

El sistema ahora soporta **OCR (Reconocimiento Óptico de Caracteres)** usando Tesseract para leer PDFs escaneados o no editables.

## 🔧 Instalación de Tesseract

### Windows

1. **Descargar el instalador:**
   - Visita: https://github.com/UB-Mannheim/tesseract/wiki
   - Descarga `tesseract-ocr-w64-setup-5.3.x.exe` (versión más reciente)

2. **Instalar Tesseract:**
   - Ejecuta el instalador
   - **IMPORTANTE**: Asegúrate de instalar el paquete de idioma **Español (spa)** durante la instalación
   - Ruta recomendada: `C:\Program Files\Tesseract-OCR`

3. **Agregar Tesseract al PATH:**
   - Botón derecho en "Este equipo" → Propiedades → Configuración avanzada del sistema
   - Variables de entorno → Path → Editar → Nuevo
   - Agregar: `C:\Program Files\Tesseract-OCR`
   - Guardar y reiniciar la terminal

4. **Verificar instalación:**
   ```powershell
   tesseract --version
   ```
   Deberías ver algo como: `tesseract 5.3.x`

5. **Verificar idioma español:**
   ```powershell
   tesseract --list-langs
   ```
   Deberías ver `spa` en la lista

### Linux (Ubuntu/Debian)

```bash
sudo apt update
sudo apt install tesseract-ocr tesseract-ocr-spa
tesseract --version
```

### macOS

```bash
brew install tesseract tesseract-lang
```

## 📦 Instalación de Dependencias Python

```powershell
pip install -r requirements.txt
```

Esto instalará:
- `pytesseract` - Interface Python para Tesseract
- `Pillow` - Procesamiento de imágenes
- `pdf2image` - Conversión de PDF a imágenes

**Nota para Windows**: También necesitas instalar **poppler**:
1. Descarga poppler para Windows: https://github.com/oschwartz10612/poppler-windows/releases
2. Extrae el archivo ZIP
3. Agrega `poppler-xx\Library\bin` al PATH del sistema

## ⚙️ Configuración

Edita tu archivo `.env` para configurar el OCR:

```env
# OCR Settings
OCR_ENABLED=true           # true para habilitar OCR, false para deshabilitarlo
OCR_LANGUAGE=spa           # "spa" para español, "eng" para inglés
OCR_DPI=300                # Calidad de escaneo (300 recomendado, más alto = más lento)
OCR_TIMEOUT=300            # Tiempo máximo en segundos para procesar
```

## 🚀 Cómo Funciona

El sistema ahora funciona de manera **inteligente y automática**:

### 1. PDFs Editables (con texto seleccionable)
- Se extrae el texto normalmente usando PyMuPDF o pdfplumber
- **Rápido** y eficiente
- No usa OCR

### 2. PDFs Escaneados (imágenes, sin texto)
- El sistema **detecta automáticamente** que el PDF no tiene texto
- Activa el OCR automáticamente
- Extrae el texto de las imágenes usando Tesseract
- **Más lento** pero funcional

### 3. Proceso Automático
```
PDF recibido 
    ↓
Intentar extracción normal (PyMuPDF)
    ↓
¿Tiene texto? → SÍ → Retornar texto
    ↓
    NO
    ↓
¿OCR habilitado? → NO → Error
    ↓
    SÍ
    ↓
Convertir PDF a imágenes
    ↓
Aplicar OCR a cada página
    ↓
Retornar texto extraído
```

## 📝 Ejemplo de Uso

```python
from app.services.pdf_text import extract_text_from_pdf

# Leer PDF
with open("documento.pdf", "rb") as f:
    pdf_bytes = f.read()

# Extraer texto (OCR automático si es necesario)
text, pages, method = extract_text_from_pdf(
    pdf_bytes,
    enable_ocr=True,      # Habilitar OCR
    ocr_lang="spa"        # Idioma español
)

print(f"Método usado: {method}")  # "pymupdf", "pdfplumber", o "ocr"
print(f"Páginas: {pages}")
print(f"Texto extraído: {text[:500]}...")
```

## 🔍 Métodos de Extracción

El sistema retorna uno de estos métodos en `method`:

- **`pymupdf`**: Extracción exitosa con PyMuPDF (texto seleccionable)
- **`pdfplumber`**: Extracción con pdfplumber (fallback)
- **`ocr`**: Texto extraído usando OCR (PDF escaneado)

## ⚡ Rendimiento

### PDFs Editables
- ⚡ **Muy rápido**: < 1 segundo para documentos de 10 páginas
- 💾 Bajo uso de CPU y memoria

### PDFs Escaneados (OCR)
- 🐌 **Más lento**: 5-30 segundos por página (depende de DPI)
- 💻 Mayor uso de CPU y memoria
- 📊 Calidad depende de:
  - Resolución del escaneo original
  - Claridad del texto en la imagen
  - DPI configurado (más alto = mejor pero más lento)

### Optimización
Para mejorar velocidad del OCR:
- Reducir `OCR_DPI` a 200 (menos calidad, más rápido)
- Usar procesamiento asíncrono con Celery (ya implementado)

## 🧪 Pruebas

### Con Docker

```bash
# Verificar Tesseract en el contenedor
docker exec mve-incrementables-parser tesseract --version
docker exec mve-incrementables-parser tesseract --list-langs

# Probar el endpoint con un PDF
curl -X POST http://localhost:9876/api/v1/incrementables/parse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@documento_escaneado.pdf"
```

### Local (sin Docker)

Para probar con un PDF escaneado:

```powershell
# Usando el endpoint síncrono
curl -X POST http://localhost:8000/api/v1/incrementables/parse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@documento_escaneado.pdf"

# Usando el endpoint asíncrono (recomendado para OCR)
curl -X POST http://localhost:8000/api/v1/incrementables/parse-async \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@documento_escaneado.pdf"
```

## 🐛 Solución de Problemas

### Error: "tesseract is not installed"
- Verifica que Tesseract esté instalado: `tesseract --version`
- Verifica que esté en el PATH del sistema
- Reinicia la terminal/IDE después de agregar al PATH

### Error: "Failed to load language 'spa'"
- Instala el paquete de idioma español
- Windows: Reinstala Tesseract y marca la opción "Spanish language data"
- Linux: `sudo apt install tesseract-ocr-spa`

### Error: "Unable to load library 'libpoppler'"
- Windows: Instala poppler y agrégalo al PATH
- Linux: `sudo apt install poppler-utils`
- macOS: `brew install poppler`

### OCR muy lento
- Reduce `OCR_DPI` en el archivo `.env`
- Usa el endpoint asíncrono para procesar en background
- Considera procesar solo las páginas necesarias

### OCR no detecta texto correctamente
- Aumenta `OCR_DPI` a 400 o 600
- Verifica que el PDF escaneado tenga buena calidad
- Prueba con otro idioma si el documento está en inglés: `OCR_LANGUAGE=eng`

## 📚 Recursos Adicionales

- [Documentación Tesseract](https://github.com/tesseract-ocr/tesseract)
- [pytesseract GitHub](https://github.com/madmaze/pytesseract)
- [pdf2image Documentation](https://github.com/Belval/pdf2image)

## 🎯 Próximos Pasos

Para mejorar aún más:
1. **Pre-procesamiento de imágenes**: Aplicar filtros para mejorar calidad
2. **Detección de idioma automática**
3. **Caché de resultados OCR** para evitar reprocesar el mismo PDF
4. **Procesamiento paralelo** de páginas para mayor velocidad
5. **Migrar a servicios cloud** (AWS Textract) para mejor precisión