Guida utente

1 Installazione

PyCa è full portable: non è necessario installarlo, funziona direttamente dopo averlo scaricato, può essere utilizzato localmente o direttamente da una memoria USB e non richiede risorse esose. Per iniziare ad utilizzarlo:

1. Scarica PyCa.exe (Windows x64, ~180 MB).
2. Copialo in una cartella scrivibile (es. C:\PyCa\ o sulla chiavetta).
3. (Opzionale, modalità "portable totale") crea una sottocartella .pyca\ nella stessa directory dell'eseguibile: licenza, database paziente e settings verranno salvati lì invece che nella directory default ~/.pyca/.

2 Primo avvio

Splash

Una breve schermata di benvenuto mostra il logo PyCa, la licenza attiva e il disclaimer di uso di ricerca.

EULA

Al primo avvio compare l'End-User License Agreement. Devi leggere e accettare per usare il software. L'accettazione viene salvata e non sarà più richiesta agli avvii successivi (a meno che la versione dell'EULA cambi). Testo integrale sempre consultabile su radiolog.it/pyca/eula.

Attivazione licenza

Subito dopo l'EULA, se non è già attiva, compare il dialog di attivazione: inserisci nome completo e codice licenza ricevuto via email. Puoi richiedere il codice da questa pagina.

3 L'interfaccia

La finestra principale è organizzata in tre aree: pannello strumenti (sinistra), tre viewport (assiale + MIP + coronale) al centro e risultati a destra. In basso si trova un pannello di Volume Rendering espandibile con diverse opzioni.

Pannello strumenti (sinistra)

• Territory (Label): seleziona il territorio attivo per la segmentazione (LM, LAD, CX, RCA, AoV, Other).
• Segmentation tools: Click&Grow, Brush, Eraser, Clear Segmentation, visualizzazione anteprima calcio ≥130 HU (opzione disabilitabile dai settings).
• Patient Information: sesso, età, etnia (obbligatori per il percentile MESA e le soglie AVC).
• Calculate Score: calcola il calcium score Agatston per tutti i territori segmentati.

Viewport centrale

• Axial: piano assiale (supporto per tilting +/- 90° paraassiale).
• MIP: Maximum Intensity Projection con spessore slab configurabile (default 10 mm).
• Coronal: piano coronale; Ctrl+drag per inclinare l'assiale.
• Volume Rendering (espandibile): rendering 3D con preset CT-Cardiac e crop box.

Pannello risultati (destra)

• Tabella territori con score / volume / massa / numero di lesioni.
• Score Coronary & Aortic con categoria di rischio.
• Capture, Export PDF, Export CSV.
• Grafico percentile MESA (tab Coronary) e percentile aortico.

4 Requisiti del DICOM

Tipo di acquisizione consigliata

• TC cardiaca non-contrastografica per il calcium score (CACS / AVC).
• Modality: CT.
• Acquisizione ECG-gated (prospettica o retrospettiva): le sequenze tipiche sono ricostruite in mid-diastole (es. 70–80% R-R), ma il software gestisce anche fasi diverse in ricostruzione assoluta o relativa rispetto al ciclo R-R.
• kVp: 120 kV è lo standard Agatston (vincolante per la coerenza con MESA e con le soglie AVC). PyCa non applica correzioni per tensioni diverse e pertanto l'utilizzo di serie con kVp non standard potrebbe provocare una sottostima o sovrastima dei risultati.
• Kernel di ricostruzione standard (es. B35, FC11). Kernel sharp potrebbero portare una sovrastima dei risultati.
• FOV stretti. L'utilizzo di dataset Full FOV, seppur compatibili con il software, potrebbe rendere la segmentazione più complessa e/o sottostimare la quantità di lesioni.

Spessore di slice

Lo standard Agatston è 3 mm con incremento (gap) di 3 mm. PyCa accetta qualsiasi spessore presente nei DICOM (tipicamente 0.6, 1.0, 1.5, 2.0, 2.5 o 3.0 mm). Il punteggio finale viene normalizzato per consentire confronti con la letteratura:

Cosa non usare

• Serie con mezzo di contrasto (CTA arteriosa/venosa): l'enhancement vascolare falsa il punteggio del Calcium Score. Seppur esistano in letteratura modalità di calcolo con utilizzo di mezzo di contrasto, PyCa non normalizza ancora il calcolo. PyCa cerca automaticamente di scoraggiare la scelta di serie con mezzo di contrasto nel dialog di selezione serie, ma non può rilevarlo con certezza assoluta. Attraverso i metadati del DICOM possono essere altresì mostrati.
• Serie topogram / scout / localizer (rilevate automaticamente e mostrate in grigio).
• Serie con motion artifact severo o gating fallito non permettono una quantificazione del Calcium Score adeguata.

5 Caricare un DICOM

1. Clicca l'icona cartella nella toolbar in alto a sinistra (oppure File → Open Folder).
2. Seleziona la cartella che contiene la serie DICOM.
3. Se sono presenti più serie, si apre il Series Selection Dialog con i metadati (fase, spessore slice, kVp). Quello consigliato è già evidenziato.
4. Clicca Load Selected per caricare. Sulla destra appariranno i metadata e le viste si popoleranno.

6 MPR & tilting oblique

Navigazione

• Scroll del mouse sull'assiale → cambia slice (oppure trascina il cursore Wheel: Scroll sul controllo).
• Wheel: Zoom nel dropdown in alto → il wheel del mouse zoomma invece di cambiare slice.
• Click sinistro nel viewport (modalità Navigate) → posiziona il crosshair (e il pivot di rotazione).

Tilting oblique (workflow valvola aortica)

1. Sull'assiale o sul coronale, cliccare sulla valvola aortica (definisce il pivot).
2. Sul coronale, tenere premuto il tasto Ctrl e trascinare verticalmente. Il cursore varia in una freccia a doppia punta e la linea di riferimento può essere inclinata. La vista assiale viene ricampionata sul piano obliquo, ruotando attorno al punto cliccato.
3. Lo zoom impostato durante l'oblique si mantiene mentre si cambia slice.
4. Premere il tasto R per resettare il tilting (torna assiale standard).

7 Segmentazione

Strumenti

• ✨ AI Analysis (coronarie): segmentazione automatica di LM / LAD / CX / RCA con il modello SEGMENT-CACS (Föllmer 2024). Vedi paragrafo dedicato qui sotto.
• Click & Grow (C): seed point su una calcificazione, viene applicato un region growing automatico sulla soglia HU (standard 130 HU). Eventuali valori al di sotto del cutoff vengono scartati direttamente.
• Brush (B): pennello, dimensione regolabile sotto il bottone.
• Eraser (E): gomma, dimensione regolabile.
• Clear Segmentation: cancella tutto.
• Show Calcium Preview: overlay ciano di tutti i voxel ≥ 130 HU (utile per non perdere depositi) — opzione disabilitabile nei settings.
• N: torna in modalità Navigate.

AI Analysis (coronarie) — sperimentale

⚠ Funzionalità sperimentale. La segmentazione automatica può produrre risultati inattesi (falsi positivi su strutture extra-cardiache calcifiche — coste, colonna, valvole, anelli mitralici; falsi negativi su depositi a bassa densità o vasi tortuosi). Verificare sempre l'output a video e rifinire manualmente con brush/eraser prima di calcolare lo score. PyCa non è un dispositivo medico, l'IA non sostituisce in nessun caso il giudizio del radiologo.

Premendo ✨ AI Analysis PyCa esegue una segmentazione automatica delle tre arterie coronariche (LM, LAD, CX, RCA) sull'intero volume usando il modello multi-task SEGMENT-CACS di Föllmer et al. (Apache-2.0).

• Inferenza GPU via DirectML — funziona su qualsiasi GPU Windows (NVIDIA, AMD, Intel) senza CUDA installato. Fallback automatico CPU se la GPU non è disponibile o è disabilitata dai settings.
• ROI cardiaca: per dataset con FOV ampio (TC torace, > 250 mm) si apre un dialog per posizionare un cerchio sulla zona cardiaca. Drag con il mouse per spostarlo, mouse-wheel per ridimensionarlo. Le coste e la colonna fuori dal cerchio vengono ignorate. Bottone Skip ROI per saltare il filtro.
• Dopo l'inferenza il cerchio giallo della ROI rimane visibile sui viewport Axial e MIP, per ricordare cosa l'AI ha considerato.
• La valvola aortica (AoV) non è coperta dal modello e rimane manuale.
• Il modello è addestrato su non-contrast cardiac CT (CACS protocol): su TC torace ampie possono comparire falsi positivi anche dentro la ROI — rifinire con brush/eraser.

Dai Settings → AI: si può disabilitare il bottone (Enable AI Analysis) o forzare CPU (Use GPU).

Attribution del modello (licenza Apache 2.0)

Il modello SEGMENT-CACS è distribuito sotto licenza Apache 2.0; il file pesi originale (SegmentCACS_0001619_unet.pt) è stato convertito in ONNX per inferenza CPU/GPU portabile. PyCa riporta nell'About l'attribution richiesta dalla licenza:

• Modello: SEGMENT-CACS — Bernhard Föllmer et al. (github.com/Berni1557/SEGMENT-CACS)
• Articolo originale (lettura consigliata, non obbligatoria come citazione del proprio lavoro): Föllmer B, et al. Automated segment-level coronary artery calcium scoring on non-contrast CT: a multi-task deep-learning approach. Insights into Imaging. 2024;15:225. doi:10.1186/s13244-024-01827-0
• Licenza: Apache License 2.0

Per la citazione del proprio lavoro di ricerca che utilizza PyCa, si veda invece la sezione Citation della landing page (riferimento al software PyCa di Vittorio Censullo — AITeRTC).

Workflow tipico

1. Selezionare il territorio dal pannello a sinistra (es. LAD).
2. Attivare Show Calcium Preview per valutare visivamente il calcio al di sopra del cutoff.
3. Click & Grow sui depositi: ogni click assegna i voxel calcifici connessi al territorio attivo.
4. Brush per ritocchi, eraser per rimuovere. Ctrl+Z annulla, Ctrl+Y ripete.
5. Ripetere per tutti i territori (LM, LAD, CX, RCA, AoV).

Save / Load segmentazione

La segmentazione viene salvata insieme allo studio nel patient database:

• Ctrl+Shift+S — salva la maschera corrente (blob compresso npz).
• Database → Load Segmentation — ricarica manualmente.
• Quando si riapre lo stesso DICOM ed è presente una segmentazione salvata, PyCa propone automaticamente di ripristinare.

8 Calcium score

1. Compilare Patient Information (sesso, età, etnia) — usati per il percentile MESA e le soglie AVC.
2. Cliccare Calculate Score in fondo al pannello a sinistra.
3. Il calcolo applica il metodo Agatston con normalizzazione per spessore di slice (se non ≈3 mm).
4. I risultati appaiono nella tabella a destra (score, volume, massa, lesioni per territorio) e nei riquadri Coronary / Aortic.
5. Lo studio viene salvato automaticamente nel patient database.

Metodologia Agatston implementata

Il punteggio segue il metodo originale di Agatston et al. 1990:

1. Soglia HU: vengono considerati solo i voxel con HU ≥ 130 dentro la maschera segmentata.
2. Labeling 2D slice-by-slice: componenti connesse calcolate per ogni singola slice, non in 3D, come da definizione storica.
3. Area minima: ogni lesione (per slice) deve avere area ≥ 1 mm² per essere conteggiata.
4. Density factor (max HU della lesione nella slice):
   • 130–199 HU → ×1
   • 200–299 HU → ×2
   • 300–399 HU → ×3
   • ≥ 400 HU → ×4
5. Score per slice: area_mm² × density_factor; somma di tutte le slice = score grezzo della lesione.
6. Normalizzazione spessore: il punteggio totale viene moltiplicato per slice_thickness / 3 mm. Serie a 1.5 mm → ×0.5; a 3 mm → ×1.0. Questo restituisce un punteggio comparabile allo standard 3 mm.
7. Volume (mm³): conteggio voxel calcificati × area × spessore.
8. Massa (mg): volume × densità_media × calibration_factor / 1000. Il calibration factor di default è 0.81 (configurabile in Settings, sesso-specifico se necessario).

Stratificazione coronarica

Scala Agatston standard (RISK_CATEGORIES nel codice):

Stratificazione valvolare aortica (AVC)

Soglie sesso-specifiche per probabilità di stenosi aortica severa (AORTIC_VALVE_THRESHOLDS nel codice):

Percentile MESA

Il tab Coronary mostra il percentile basato su MESA, aggiustato per età, sesso ed etnia. Disponibile dai 45 anni in su (range MESA: 45–84). Etnie supportate: Caucasian, African-American, Hispanic, Chinese.

La tabella interna contiene i punti di ancoraggio MESA al 25°, 50°, 75°, 90° percentile per ogni combinazione (sesso × etnia × fascia di età 45–54 / 55–64 / 65–74 / 75–84). I valori intermedi sono ottenuti per interpolazione lineare.

9 Report PDF

1. Posizionati su una vista significativa per ogni viewport (assiale, MIP, eventualmente VRT).
2. Clicca Capture — cattura screenshot dell'assiale + MIP + Volume Rendering.
3. Clicca Export PDF, scegli il path. Se manca uno screenshot, PyCa te lo chiede.

Il PDF contiene:

• Header con logo PyCa e info paziente / studio.
• Sezione coronarica: score card + percentile MESA + striscia Agatston.
• Sezione valvolare: score card + soglie sesso-specifiche + heatmap a 3 cuspidi.
• Tabella per-territorio, screenshots, citazioni dei riferimenti (Pawade 2018, ESC/EACTS 2021, McClelland 2006).

10 Database e CSV

PyCa mantiene un database locale (SQLite) con tutti gli studi calcolati.

• Database → Browse Patients... (Ctrl+D): cerca, confronta follow-up.
• Database → Save Current Results (Ctrl+S): forza salvataggio manuale.
• Database → Export Database (CSV)...: esporta tutti gli studi in CSV. Ti chiede se anonimizzare (sostituisce nome, ID, birthdate con un surrogato deterministico SHA1).

11 Impostazioni

Settings → Settings... (oppure Ctrl+,) apre la finestra unica di configurazione.

• Calcium threshold: soglia HU per il riconoscimento del calcio (default 130).
• Coronary / Aortic mass factor: fattori di calibrazione della massa (0.81 standard).
• Default MIP slab: spessore MIP (mm).
• Calcium Preview: nasconde la voce dal pannello laterale se non la usi.
• Export folder: cartella di default per PDF / CSV.

I valori sono persistenti tra i riavvii (QSettings).

12 Scorciatoie da tastiera

13 Riferimenti scientifici

Metodo Agatston

• Agatston AS, Janowitz WR, Hildner FJ, Zusmer NR, Viamonte M, Detrano R. Quantification of coronary artery calcium using ultrafast computed tomography. J Am Coll Cardiol. 1990;15(4):827–832.

Percentile coronarico

• McClelland RL, Chung H, Detrano R, Post W, Kronmal RA. Distribution of coronary artery calcium by race, gender, and age: Results from the Multi-Ethnic Study of Atherosclerosis (MESA). Circulation. 2006;113(1):30–37.

Le tabelle MESA implementate in PyCa contengono i punti 25/50/75/90 per (sesso × etnia × fascia di età 45–84). I valori intermedi sono ottenuti per interpolazione lineare.

Stratificazione valvolare aortica (AVC)

• Pawade T, Clavel MA, Tribouilloy C, et al. Computed Tomography Aortic Valve Calcium Scoring in Patients With Aortic Stenosis. Circ Cardiovasc Imaging. 2018;11(3):e007146.
• Vahanian A, Beyersdorf F, Praz F, et al. (ESC/EACTS Scientific Document Group). 2021 ESC/EACTS Guidelines for the management of valvular heart disease. Eur Heart J. 2022;43(7):561–632.

Le soglie sesso-specifiche implementate (Donna 1200/1600, Uomo 2000/3000 AU) derivano direttamente da queste due fonti.

14 FAQ & contatti

PyCa è un dispositivo medico?

No. PyCa è destinato esclusivamente a uso di ricerca e non è validato per uso clinico. Non sostituisce il giudizio medico.

I dati vengono inviati a qualche server?

No. PyCa funziona completamente offline. Tutti i dati restano sul tuo computer (o sulla USB).

Posso usarlo su Mac / Linux?

Al momento il bundle pronto è solo per Windows. Il codice è Python multipiattaforma — sorgenti su richiesta.

Come ottengo una nuova versione?

Per ora il download manuale da radiolog.it/pyca. Un sistema di aggiornamento OTA è in roadmap.

Posso citare PyCa in pubblicazioni?

Sì, è caldamente apprezzato. Formato suggerito:

Censullo V. — AITeRTC ETS. PyCa — Python Calcium Score Analyzer. 2026.

Contatti

Per bug, richieste di feature o domande tecniche: v.censullo@gmail.com.