pyatia 0.1.0
Librería para análisis automatizado de calidad en mamografía (basado en IAEA ATIA)
Requires Python: >=3.8

# PyATIA: Automated Tool for Image Analysis (Python Library)

**PyATIA** es una librería de Python de código abierto diseñada para el análisis automatizado de calidad de imagen en **Mamografía Digital**.

Esta librería implementa y extiende en Python la metodología **ATIA (Automated Tool for Image Analysis)** desarrollada por el **OIEA (IAEA)**, permitiendo el cálculo de métricas físicas objetivas directamente desde archivos **DICOM** de maniquíes (phantoms) estándar.

## 🚀 Características principales

- **Segmentación automática:** detección inteligente de ROIs (Regiones de Interés) sobre imágenes de maniquíes estándar (tipo IAEA/ACR) sin intervención manual.
- **Métricas de calidad de imagen:**
  - **SNR (Signal-to-Noise Ratio):** relación señal-ruido.
  - **SDNR (Signal-Difference-to-Noise Ratio):** contraste relativo al ruido.
  - **MTF (Modulation Transfer Function):** cálculo de la función de transferencia de modulación (nitidez) mediante el método de borde inclinado (*slanted-edge*) tanto vertical como horizontal.
  - **NNPS (Normalized Noise Power Spectrum):** análisis espectral del ruido con corrección de tendencias (*detrending*) polinómico 2D.
- **Índice de detectabilidad (d’):** cálculo basado en el modelo de observador **NPW (Non-Prewhitening)**, ajustado al contraste real del objeto según protocolos IAEA (Human Health Series No. 39).
- **Salida estructurada:** retorna todas las métricas en un diccionario Python, fácil de integrar en dashboards, bases de datos (p. ej., MongoDB) o reportes.

## 📋 Requisitos

- **Python 3.8+**

Dependencias principales:
- `numpy` *(se recomienda `< 2.0` por compatibilidad con SciPy en muchos entornos)*
- `pydicom`
- `opencv-python`
- `scipy`
- `matplotlib`
- `pandas`

## 🛠️ Instalación

1) Clonar el repositorio:
```bash
git clone https://github.com/tu-usuario/pyatia.git
cd pyatia
```

2) Instalar dependencias:
```bash
pip install -r requirements.txt
```

> Nota: si encuentras errores con `numpy`, prueba:
```bash
pip install "numpy<2.0"
```

## 💻 Uso básico

PyATIA está diseñada para ser directa de usar. Solo necesitas instanciar la clase `AtiaMamo` y pasar la ruta de un archivo DICOM.

```python
from pyatia import AtiaMamo

# 1) Instanciar el analizador
analyzer = AtiaMamo()

# 2) Procesar una imagen DICOM
dicom_path = "ruta/a/tu/imagen_mamo.dcm"
resultado = analyzer.process(dicom_path)

# 3) Verificar resultados
if resultado["success"]:
    metrics = resultado["metrics"]

    print("✅ Análisis exitoso")
    print(f"📡 SNR: {metrics['snr']}")
    print(f"🔎 SDNR: {metrics['sdnr']}")
    print(f"📉 MTF 50% (H): {metrics['mtf50_h']} cycles/mm")
    print(f"🧠 Detectabilidad (d' 0.25mm): {metrics['dprime_0.25mm']}")

    # Imagen procesada con ROIs (numpy array)
    imagen_rois = resultado["image_processed"]
else:
    print(f"❌ Error: {resultado['error']}")
```

## 🔬 Metodología física

El cálculo de métricas sigue lineamientos estándar de física médica:

- **MTF:** se utiliza la técnica *slanted-edge* con sobremuestreo (*super-sampling*) para obtener la curva de respuesta en frecuencia.
- **NNPS:** se extrae una ROI central de fondo, se normaliza por la señal media y se aplica una ventana de Hann 2D para calcular el espectro de potencia de ruido.
- **Detectabilidad (d’):** se implementa el modelo del observador ideal sin pre-blanqueo (**NPW**):

\[
d'^2 = \frac{\left[ \iint |W(u,v)|^2 \cdot MTF^2(u,v)\; du\; dv \right]^2}{\iint |W(u,v)|^2 \cdot MTF^2(u,v)\cdot NNPS(u,v)\; du\; dv}
\]

donde \(W(u,v)\) es la función de tarea (disco) escalada por el contraste medido del inserto.

## 📂 Estructura del proyecto

```text
pyatia/
├── pyatia/                  # Código fuente de la librería
│   ├── __init__.py          # Punto de entrada
│   ├── mamo.py              # Clase principal (AtiaMamo)
│   ├── image_utils.py       # Segmentación y utilidades CV2
│   └── physics/             # Módulos de física médica
│       ├── metrics.py       # SNR, SDNR, MTF
│       ├── nnps.py          # Noise Power Spectrum
│       └── detectability.py # Modelo d'
├── test_pyatia.py           # Script de prueba y demostración
└── requirements.txt         # Dependencias
```

## ⚠️ Exención de responsabilidad

Este software es una herramienta de soporte para control de calidad y **no** está diseñado ni certificado para uso diagnóstico clínico directo en pacientes. El usuario es responsable de validar los resultados en su entorno específico.

## 📄 Licencia

Este proyecto está bajo la **Licencia MIT**. Siéntete libre de usarlo y modificarlo.

Basado en metodologías del **OIEA (IAEA)**.