pydicom

¿Qué hace pydicom?

Usa pydicom para E/S de conjuntos de datos DICOM y procesamiento de píxeles. La versión 3.0.2 es la versión estable actual revisada aquí. Corrige CVE-2026-32711, un problema de path-traversal en DICOMDIR manipulado. pydicom 3.0.2 declara Python >=3.10; su diccionario DICOM incluido es 2024c, mientras que el Estándar DICOM en vivo puede ser más reciente.

Límite de seguridad obligatorio

• Trabaja únicamente con datos locales que el usuario esté autorizado a acceder.
• Los metadatos DICOM, nombres de archivo, elementos privados, overlays, contenido estructurado y píxeles pueden contener información de salud protegida (PHI).
• Nunca imprimas Dataset, exportes metadatos/JSON completos ni registres valores de elementos por defecto. Usa una lista blanca documentada y salida agregada.
• pydicom es un marco general de DICOM, no un visor de diagnóstico. La salida de píxeles, validación, conversión y disponibilidad de plugins no constituyen afirmaciones de diagnóstico.
• La desidentificación es específica del perfil, propósito, destinatario, jurisdicción y contexto de amenaza. Requiere verificación de un experto en privacidad/DICOM.
• Nunca afirmes que un script de eliminación de etiquetas cumple con DICOM PS3.15, HIPAA, GDPR u otros estándares. Conserva los originales y audita las salidas derivadas.
• Trata las claves de seudonimización deterministas y los mapas de UID como secretos de reidentificación: usa el principio de menor privilegio y almacenamiento cifrado/gestionado, nunca los comprometas, sincronices, registres ni compartas con derivados, y define procedimientos de copia de seguridad, rotación, revocación y destrucción. Una clave filtrada invalida la separación prevista; la rotación también cambia los mapeos deterministas.
• Establece límites explícitos de archivo de entrada, recuento de archivos, recuento de fotogramas, bytes decodificados y salida antes de analizar conjuntos de datos no confiables o inusualmente grandes.

Instalación

Crea o activa un entorno aislado, luego instala la versión exacta revisada:

uv pip install "pydicom==3.0.2"

Arreglos de píxeles sin comprimir y renderizado de imágenes:

uv pip install "pydicom==3.0.2" "numpy==2.5.1" "Pillow==12.3.0"

Instala únicamente los plugins de sintaxis de transferencia requeridos por el despliegue:

# JPEG/JPEG-LS, JPEG 2000/HTJ2K, y RLE más rápido a través de pylibjpeg
uv pip install "numpy==2.5.1" "pylibjpeg==2.1.0" \
  "pylibjpeg-libjpeg==2.4.0" "pylibjpeg-openjpeg==2.5.0" \
  "pylibjpeg-rle==2.2.0"

# Codificador/decodificador JPEG-LS
uv pip install "numpy==2.5.1" "pyjpegls==1.5.1"

# Decodificador alternativo con wheels específicos de plataforma
uv pip install "python-gdcm==3.2.6"

Las licencias y los wheels de los plugins varían según el paquete/plataforma; revísalos antes del despliegue. Pillow tiene limitaciones de decodificación documentadas y pydicom advierte que la salida del plugin debe verificarse de forma independiente.

Los wheels de códecs nativos amplían el límite de seguridad de la cadena de suministro y la memoria. Para un despliegue controlado, resuelve estos pines exactos en un host de compilación confiable, bloquea y verifica los hashes/procedencia de los wheels, refleja internamente los artefactos aprobados, escanéalos e instala con verificación de hash en lugar de resolver desde el índice público en tiempo de ejecución.

Elige el flujo de trabajo

1. ¿Necesitas una visión general agregada? Ejecuta scripts/extract_metadata.py.
2. ¿Necesitas verificaciones técnicas acotadas? Ejecuta scripts/dicom_inventory.py.
3. ¿Necesitas un pre-vuelo de despliegue de códecs? Ejecuta scripts/transfer_syntax_inspector.py.
4. ¿Necesitas planificación de fotogramas/memoria? Ejecuta scripts/pixel_frame_planner.py.
5. ¿Necesitas un fotograma renderizado no diagnóstico? Ejecuta scripts/dicom_to_image.py.
6. ¿Necesitas un derivado seudonimizado? Lee la sección de desidentificación, crea un perfil de acción revisado por el sitio, luego ejecuta scripts/anonymize_dicom.py y scripts/deidentification_audit.py.
7. ¿Necesitas verificar un mapa de UID sensible? Ejecuta scripts/uid_mapping_validator.py.

Leer conjuntos de datos de forma segura

dcmread() devuelve un FileDataset, una subclase de Dataset con estado de Formato de Archivo, como file_meta, preámbulo y codificación original.

from pathlib import Path
import pydicom

path = Path("authorized/input.dcm")
ds = pydicom.dcmread(
    path,
    stop_before_pixels=True,
    specific_tags=[
        "SOPClassUID",
        "Modality",
        "Rows",
        "Columns",
        "NumberOfFrames",
    ],
)

techical = {
    "sop_class": ds.get("SOPClassUID"),
    "modality": ds.get("Modality"),
    "rows": ds.get("Rows"),
    "columns": ds.get("Columns"),
}

Usa:

• stop_before_pixels=True para trabajo solo de metadatos.
• specific_tags=[...] para una lista blanca mínima.
• defer_size="1 MiB" cuando una escritura posterior deba preservar valores grandes.
• force=False (predeterminado). force=True solo omite la verificación del encabezado de Formato de Archivo; no demuestra que los bytes sean DICOM válidos.

No llames a print(ds), repr(ds) ni iteres valores en registros con datos clínicos.

Dataset, DataElement y secuencias

Accede a los elementos estándar por palabra clave y verifica su ausencia:

modality = ds.get("Modality", "NO ESPECIFICADO")
if "ReferencedImageSequence" in ds:
    for item in ds.ReferencedImageSequence:
        referenced_class = item.get("ReferencedSOPClassUID")

El acceso por etiqueta, como ds[0x0010, 0x0010], devuelve un DataElement; su .value está separado. Sequence se comporta como una lista de elementos Dataset anidados. Las acciones de privacidad deben recorrer cada elemento de la secuencia, no solo el nivel superior.

Al crear un archivo, usa FileMetaDataset para el grupo 0002, mantén los UIDs de SOP consistentes entre el conjunto de datos y los metadatos del archivo, establece un UID de Sintaxis de Transferencia y escribe en Formato de Archivo obligatorio:

from pydicom import dcmwrite
from pydicom.dataset import FileDataset, FileMetaDataset
from pydicom.uid import CTImageStorage, ExplicitVRLittleEndian, generate_uid

meta = FileMetaDataset()
meta.MediaStorageSOPClassUID = CTImageStorage
meta.MediaStorageSOPInstanceUID = generate_uid()
meta.TransferSyntaxUID = ExplicitVRLittleEndian

ds = FileDataset(None, {}, file_meta=meta, preamble=b"\0" * 128)
ds.SOPClassUID = meta.MediaStorageSOPClassUID
ds.SOPInstanceUID = meta.MediaStorageSOPInstanceUID
# Agrega todos los atributos requeridos por la IOD seleccionada antes de escribir.
dcmwrite("new.dcm", ds, enforce_file_format=True, overwrite=False)

write_like_original está obsoleto en pydicom 3.0; usa enforce_file_format. Una escritura exitosa no implica conformidad total con PS3.3 IOD.

UIDs y sintaxis de transferencia

El UID de Sintaxis de Transferencia de Información de Metadatos de Archivo controla la codificación del conjunto de datos y la compresión de píxeles:

ts = ds.file_meta.TransferSyntaxUID
summary = {
    "uid": str(ts),
    "name": ts.name,
    "compressed": ts.is_compressed,
    "implicit_vr": ts.is_implicit_VR,
    "little_endian": ts.is_little_endian,
}

pydicom 3.0 elige la codificación de escritura a partir del UID de Sintaxis de Transferencia antes que las banderas heredadas del conjunto de datos. No reemplaces los UIDs estructurales (Sintaxis de Transferencia, Clase SOP o UIDs de esquema de codificación) durante la seudonimización. El reemplazo de UID de instancia/referencia debe ser uno a uno y consistente en todo el alcance declarado.

Lee references/transfer_syntaxes.md antes de comprimir, descomprimir o encapsular.

Datos de píxeles y fotogramas

La API estable pydicom.pixels admite decodificación basada en ruta y específica de fotogramas:

from pydicom.pixels import pixel_array

# Lee solo el fotograma seleccionado cuando la fuente lo permite.
frame = pixel_array("authorized/image.dcm", index=0, raw=False)

Semántica de formas:

• escala de grises de un solo fotograma: (rows, columns)
• escala de grises de múltiples fotogramas: (frames, rows, columns)
• color de un solo fotograma: (rows, columns, samples)
• color de múltiples fotogramas: (frames, rows, columns, samples)

raw=False convierte datos de píxeles YCbCr a RGB cuando es posible; raw=True retiene el espacio de color decodificado después del procesamiento mínimo obligatorio. Usa iter_pixels(path, indices=[...]) para iteración acotada de múltiples fotogramas.

Para visualización en escala de grises, aplica las transformaciones en este orden:

from pydicom.pixels import apply_modality_lut, apply_voi_lut

modality_values = apply_modality_lut(frame, ds)
display_values = apply_voi_lut(modality_values, ds, index=0)

La LUT de modalidad/reescalado y la ventana VOI cambian la semántica de visualización/valores. MONOCHROME1 puede requerir inversión de presentación. El color de paleta requiere apply_color_lut(). Los estados de presentación y el comportamiento ICC pueden requerir un visor validado. Nunca uses normalización mín/máx por fotograma para análisis cuantitativos.

Compresión, descompresión y encapsulación

• Acceder a pixel_array decodifica según sea necesario pero no cambia el conjunto de datos.
• Dataset.decompress() cambia los Datos de Píxeles en el lugar, establece Explicit VR Little Endian, actualiza los metadatos de la imagen y genera un nuevo UID de Instancia SOP de forma predeterminada.
• Dataset.compress(uid) cambia los Datos de Píxeles y la Sintaxis de Transferencia en el lugar y genera un nuevo UID de Instancia SOP de forma predeterminada.
• Los codificadores integrados/encontrados de pydicom 3.0 cubren combinaciones de RLE sin pérdida, JPEG-LS y JPEG 2000 documentadas en la matriz de plugins estable.
• Cada fotograma comprimido se codifica por separado y luego se encapsula. Usa encapsulate() o encapsulate_extended() para fotogramas codificados externamente.
• Lee fotogramas con pydicom.encaps.generate_frames() o get_frame() actuales; los nombres de los generadores de encapsulación heredados están obsoletos para pydicom 4.

Inspecciona siempre las capacidades primero, limita los bytes/fotogramas decodificados y verifica la corrección de los píxeles de forma independiente. La aceptabilidad de la compresión con pérdida está fuera de pydicom y la especificación de codificación DICOM.

JSON DICOM y elementos privados

Dataset.to_json(), to_json_dict() y Dataset.from_json() implementan el Modelo JSON DICOM, pero pydicom documenta el soporte JSON como beta. El JSON completo puede incluir datos binarios en línea y exponer cada identificador y carga útil de píxeles. No lo emitas como un informe de metadatos. Un manejador BulkDataURI introduce obligaciones separadas de almacenamiento, autorización y recuperación.

Los elementos privados no están estandarizados y pueden contener PHI:

# Eliminación recursiva, pero no es suficiente desidentificación por sí sola.
ds.remove_private_tags()

Conserva los elementos privados solo bajo una política explícita de datos privados seguros revisada. Lee references/common_tags.md para acceso a etiquetas, clases de privacidad y punteros estándar.

Flujo de trabajo de desidentificación

El Anexo E de DICOM PS3.15 establece explícitamente que los perfiles de confidencialidad no garantizan la eliminación de toda la información de identificación y no reemplazan un proceso completo de desidentificación.

1. Define el propósito, destinatarios, necesidades de vinculación, regulaciones, modelo de amenaza y riesgo de reidentificación aceptable.
2. Selecciona el Perfil de Confidencialidad de Nivel de Aplicación Básico y las opciones necesarias (píxeles, características visuales reconocibles, gráficos, contenido estructurado, descriptores, información temporal, características del paciente, dispositivos, instituciones, UIDs y datos privados seguros).
3. Conserva los objetos fuente sin cambios en almacenamiento controlado.
4. Aplica cada acción de forma recursiva, incluyendo secuencias anidadas.
5. Reemplaza los UIDs de instancia/referencia de manera consistente en todo el alcance completo; preserva los UIDs estructurales.
6. Decide el manejo de fecha/hora explícitamente. Un desplazamiento fijo puede preservar intervalos, pero las fechas parciales, zonas horarias, horas independientes, días bisiestos, vinculación longitudinal y eventos externos requieren una política revisada.
7. Inspecciona píxeles, overlays, gráficos, contenido estructurado y características visuales reconocibles. No infieras píxeles limpios a partir de metadatos faltantes ni establezcas BurnedInAnnotation=NO sin verificación.
8. Reconstruye la Información de Metadatos de Archivo y el preámbulo para evitar fugas.
9. Realiza validación técnica y una auditoría de desidentificación, luego lleva a cabo verificación experta y revisión de riesgo documentada.

El script incluido establece intencionalmente PatientIdentityRemoved=NO porque no puede garantizar una desidentificación exitosa.

CLI auxiliares

Todas las rutas --help son independientes de dependencias. Las herramientas no realizan acceso a la red y no emiten valores DICOM más allá de listas blancas técnicas estrechas.

El contenido incluido consiste en las dos referencias vinculadas, los scripts auxiliares documentados y pruebas sintéticas. La dependencia de tiempo de ejecución de pydicom se instala desde la versión fija de PyPI.

# Metadatos agregados con redacción
python scripts/extract_metadata.py authorized/ --recursive

# Inventario técnico solo de metadatos
python scripts/dicom_inventory.py authorized/ --recursive

# Capacidades de códec/plugin instalados
python scripts/transfer_syntax_inspector.py --input authorized/image.dcm

# Plan de forma, bytes y transformación de fotogramas
python scripts/pixel_frame_planner.py authorized/image.dcm --frames 0,2-4

# Un fotograma no diagnóstico
python scripts/dicom_to_image.py authorized/image.dcm frame.png \
  --acknowledge-pixel-phi

# Crear una clave secreta, luego un derivado seudonimizado con ámbito más auditoría
python scripts/anonymize_dicom.py --generate-uid-key project.key
python scripts/anonymize_dicom.py authorized/in.dcm derived/out.dcm \
  --uid-key-file project.key --uid-scope export-v1 \
  --audit-report derived/out.audit.json

# Auditar metadatos candidatos; sin descompresión de píxeles
python scripts/deidentification_audit.py derived/out.dcm

# Validar un mapeo de UID sensible solicitado explícitamente
python scripts/uid_mapping_validator.py derived/uid-map.json \
  --uid-key-file project.key --uid-scope export-v1

El archivo de clave sin procesar generado es una conveniencia local controlada y se crea con permisos exclusivos del propietario. Para producción, materializa los bytes de clave desde un administrador de secretos aprobado en un archivo efímero bloqueado, restringe el acceso al servicio de desidentificación y elimínalo de forma segura después. Almacena cualquier mapa de UID opcional por separado de los derivados; vincula directamente los identificadores originales y de reemplazo.

Notas de migración a pydicom 3.0

• read_file() y write_file() fueron eliminados; usa dcmread() y dcmwrite().
• write_like_original está obsoleto; usa enforce_file_format.
• pydicom.pixel_data_handlers está obsoleto para su eliminación en v4; usa pydicom.pixels.
• Dataset.pixel_array usa el nuevo backend de píxeles por defecto y convierte YCbCr a RGB cuando es posible.
• JPEGLossless ahora significa UID 1.2.840.10008.1.2.4.57; JPEGLosslessSV1 es .70.
• Dataset.is_little_endian e is_implicit_VR están obsoletos para v4.

Fuentes (verificado el 2026-07-23)

• pydicom 3.0.2 en PyPI — publicado el 2026-0

... [truncado para traducción]