pyatia 0.1.0

Librería para análisis automatizado de calidad en mamografía (basado en IAEA ATIA)

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:

git clone https://github.com/tu-usuario/pyatia.git
cd pyatia

2. Instalar dependencias:

pip install -r requirements.txt

Nota: si encuentras errores con numpy, prueba:

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.

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

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).