Costruire un tool Python per esplorare dataset di imaging medico
Gli sviluppatori che lavorano con imaging medico interagiscono quotidianamente con file DICOM.
Nonostante sia lo standard globale per la gestione delle immagini medicali, i metadata DICOM sono spesso difficili da interpretare rapidamente, soprattutto quando si analizzano dataset, si debuggano pipeline o si preparano dati per sistemi di AI in ambito medicale.
Anche domande apparentemente semplici possono richiedere l’analisi di decine di tag DICOM:
Qual è la modalità dell’esame?
Quale distretto anatomico è stato acquisito?
È stato usato mezzo di contrasto?
Quante slice contiene la serie?
Qual è lo spessore delle slice?
Per semplificare questo processo abbiamo sviluppato una piccola libreria Python open-source chiamata dicom-insight.
L’obiettivo è semplice:
trasformare metadata DICOM complessi in report leggibili e strutturati per sviluppatori e data scientist.
Il problema dei metadata DICOM
Un header DICOM tipico contiene centinaia di campi.
Esempio:
(0018,0050) Slice Thickness: 1.0
(0028,0010) Rows: 512
(0028,0011) Columns: 512
(0018,0015) Body Part Examined: HEAD
(0020,0037) Image Orientation Patient
Per un umano, interpretare questi valori richiede:
esperienza nel dominio
conoscenza dello standard DICOM
tempo per analizzare i dati
Per sviluppatori che lavorano con:
integrazione PACS
piattaforme medical imaging
pipeline AI
sistemi di data ingestion
può essere molto utile avere un livello di interpretazione più leggibile e immediato sopra i metadata grezzi.
Un approccio leggero
L’idea alla base di dicom-insight è semplice:
leggere i file DICOM con
pydicomestrarre i metadata rilevanti
applicare alcune euristiche
generare un report strutturato
Il report include ad esempio:
modalità dell’esame
distretto anatomico
dimensione della matrice
spessore delle slice
numero di immagini
possibile utilizzo di contrasto
In questo modo si ottiene una descrizione immediatamente leggibile dello studio.
Installazione
Il progetto utilizza uv, un moderno gestore di ambienti e dipendenze Python sviluppato da Astral.
Clonare il repository e Installare l’ambiente e le dipendenze:
git clone https://github.com/dvisionlab/dicom-insight
cd dicom-insight
uv sync
Questo comando:
crea automaticamente un virtual environment
installa tutte le dipendenze
genera il lockfile per l’ambiente.
Utilizzo da Python
Esempio di analisi di un file DICOM:
from dicom_insight import analyze_file
report = analyze_file("ct_head.dcm")
print(report.summary)
print(report.explanation)
Output esempio:
Matrix 512×512
Slice thickness: 1.0 mm
Likely non-contrast acquisition
Il report può anche essere esportato in formato JSON:
print(report.to_json())
Output:
{
"modality": "CT",
"body_part": "HEAD",
"rows": 512,
"columns": 512,
"slice_thickness": 1.0,
"contrast_suspected": false
}
Questo rende la libreria facilmente integrabile in:
pipeline di data processing
strumenti di dataset exploration
workflow di machine learning
Analizzare un intero studio DICOM
La libreria include anche una CLI per analizzare intere cartelle contenenti file DICOM.
Esempio:
uv run dicom-insight ./dicom-study
Output:
Study summary
-------------
Modality: CT
Body part: CHEST
Slices: 324
Matrix: 512x512
Slice thickness: 1.25 mm
Contrast suspected: true
Questo tipo di analisi è particolarmente utile quando si lavora con:
dataset di imaging per AI
migrazioni di archivi PACS
controllo qualità delle acquisizioni
esplorazione di dataset clinici
Perché può essere utile
Strumenti semplici come questo possono semplificare diversi workflow.
Esplorazione dataset
Comprendere rapidamente la composizione di grandi collezioni di immagini medicali.
Pipeline AI
Estrarre automaticamente caratteristiche degli studi per il training dei modelli.
Ingestion PACS
Verificare rapidamente i metadata degli studi in ingresso.
Controllo qualità
Identificare incongruenze tra acquisizioni.
Possibili evoluzioni
Questo progetto è volutamente semplice, ma apre a diverse possibili estensioni:
analisi statistica di dataset DICOM
classificazione automatica degli studi
integrazione con DICOMweb
generazione automatica di preview delle serie
interpretazione dei metadata tramite LLM
L’idea è rendere l’ecosistema DICOM più accessibile agli sviluppatori, riducendo la distanza tra standard medicali complessi e strumenti software moderni.
Repository open-source
La libreria è disponibile su GitHub:
Un piccolo toolkit Python per esplorare e interpretare metadata DICOM in modo semplice e leggibile.
About D/Vision Lab
In D/Vision Lab sviluppiamo soluzioni software avanzate per:
piattaforme di medical imaging
workflow clinici supportati da AI
integrazioni PACS e cloud
visualizzazione interattiva di dati medicali
Progetti come dicom-insight nascono dall’esperienza diretta nello sviluppo di sistemi di imaging medico e dall’obiettivo di rendere strumenti complessi più accessibili per sviluppatori, ricercatori e data scientist.
