Plugin DICOM
Visualizza immagini mediche con DicomPlugin
Il plugin DICOM aggiunge la visualizzazione di immagini mediche a Doconut: i file DICOM multi‑frame vengono renderizzati come una panoramica animata, fotogrammi individuali o entrambi. DICOM è un formato solo plugin — senza questo plugin (e la sua capacità di licenza), i file .dcm non possono essere aperti affatto.
Su .NET Framework 4.7.2, i file DICOM vengono renderizzati completamente — pagine, fotogrammi e animazione — ma i metadati tecnici (i tag DICOM) non sono disponibili.
Viewer.GetDicomMetadataAsyncrestituisce semprenull, e la richiesta di metadati del visualizzatore (?token=…&meta=1suDocImage.axd) risponde404, quindi il visualizzatore non mostra alcun pannello delle proprietà DICOM. UsaDoconut.NET8se la tua applicazione ha bisogno dei tag.
| Superficie | Quando usarlo |
|---|---|
Viewer with DicomConfig (C#) | Apri i file DICOM sul server e scegli come presentare i loro fotogrammi |
Il visualizzatore (docViewer) su DocImage.axd | Mostri lo studio nella tua pagina: animazione e fotogrammi |
Il plugin non ha alcun widget proprio: i file DICOM si aprono nel visualizzatore standard. Con il plugin Convertitore anch'esso registrato, i file .dcm e .ima possono essere convertiti in Pdf, Png, Jpeg, Bmp, Tiff o Gif; quella conversione richiede anche la capacità Dicom.
Installa il pacchetto
Install-Package Doconut.NETFramework.DicomPer fissare il plugin alla versione descritta in questa documentazione:
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0Mantieni il pacchetto DICOM alla stessa versione di Doconut.NETFramework.
Il file di licenza del plugin, Doconut.Viewer.Dicom.lic, va nella stessa cartella di Doconut.Viewer.lic; viene letto insieme alla licenza del visualizzatore.
Registra il plugin
Doconut.DoconutHost.Initialize(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});Il plugin (Name: "Doconut DICOM Viewer") registra visualizzatori per le estensioni .dcm e .ima, controllate dalla capacità Dicom. Se la licenza non la concede, DoconutHost.Initialize genera un'eccezione da Application_Start:
The Dicom plugin is registered via AddPlugin but no active license grants Dicom. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Dicom.In System.Web ciò significa che ogni richiesta restituisce un 500 vuoto, e il motivo è registrato solo nel registro eventi di Windows (origine ASP.NET). Genera un'eccezione per nessuna licenza, un file legacy TRIAL, una licenza priva di Dicom, e una licenza a pagamento usata al di fuori della sua finestra di versione. Le licenze temporanee Demo/NFR sono accettate. Vedi Configurazione Licenza.
Poiché nessun visualizzatore integrato gestisce questi formati, l'apertura di uno fallisce immediatamente se la capacità diventa successivamente non disponibile:
LicenseException: This document type requires the 'Dicom' plugin license.Licenze e filigrana
| Stato della licenza | Avvio | Output DICOM |
|---|---|---|
Licenza a pagamento che concede Dicom, entro la sua finestra di versione | Avvia | Renderizzato secondo le normali regole di filigrana della pagina |
| Licenza Temporanea Attiva (Demo/NFR) | Avvia | Renderizzato con la filigrana di valutazione |
Nessuna licenza, un file legacy TRIAL, una licenza priva di Dicom, o una licenza a pagamento al di fuori della sua finestra di versione | Application_Start genera un'eccezione; ogni richiesta restituisce un 500 vuoto | — |
La decisione normale sulla filigrana della pagina si applica anche all'output DICOM. Per l'output animato, ogni fotogramma GIF è marcato, quindi il segno rimane visibile durante la riproduzione. Un DocOptions.Watermark personalizzato è usato solo quando la licenza consente filigrane personalizzate; non può sostituire una filigrana di valutazione.
Utilizzo da C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});var metadata = await viewer.GetDicomMetadataAsync(token);
// Su .NET Framework questo è sempre null: il lettore dei metadati DICOM non è disponibile per questo
// target. Pagine, fotogrammi e animazione vengono renderizzati normalmente.Il metodo esiste in questo pacchetto in modo che il codice condiviso con il pacchetto .NET 8 venga compilato, ma la lettura dei tag DICOM richiede un componente che non ha una build per .NET Framework. Progetta la tua interfaccia utente senza di essi — ad esempio, nascondi un pannello dei metadati quando il risultato è null.
Modalità di visualizzazione e risoluzione
Modalità di visualizzazione
I file DICOM multi-frame possono essere presentati in tre modi (DicomDisplayMode):
| Modalità | Pagine generate | Uso per |
|---|---|---|
AnimationOnly | Pagina 1 = GIF animato che ripete tutti i fotogrammi | Revisione cinematografica rapida |
FramesOnly | Pagine 1..N = un PNG statico per fotogramma | Navigazione diagnostica fotogramma per fotogramma |
AnimationAndFrames (predefinito) | Pagina 1 = GIF animato, pagine 2..N+1 = un PNG statico per fotogramma (N = conteggio dei fotogrammi) | Panoramica e dettaglio in un unico documento |
Il timing dell'animazione è controllato da AnimationFrameDelayMs (predefinito 100 ms = 10 FPS; il timing GIF usa unità di 10 ms) e LoopCount (0 = loop infinito).
Il visualizzatore scopre che la pagina 1 è animata inviando una richiesta HEAD per essa. Il gestore DocImage.axd deve quindi accettare HEAD in Web.config (verb="GET,HEAD,POST", vedi Installazione); senza di esso, IIS risponde 404 prima che Doconut venga eseguito e la rilevazione dell'animazione non funziona mai.
Risoluzione
DicomConfig renderizza a 100 DPI per asse per impostazione predefinita. Se non imposti esplicitamente HorizontalResolution/VerticalResolution, seguono BaseConfig.ImageResolution quando questo è impostato, e solo allora tornano a 100.
// Incremento uniforme tramite la proprietà base…
new DicomConfig { ImageResolution = 150 };
// …o controllo per asse
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Crea il tuo frontend
Le immagini delle pagine, inclusa la prima pagina animata, utilizzano il percorso immagine standard DocImage.axd. La richiesta di metadati, GET /DocImage.axd?token=<token>&meta=1, restituisce 404 in questo pacchetto per ogni documento, inclusi i file DICOM, perché il lettore di metadati non è disponibile.
In produzione
Gli studi multi-frame possono produrre sia un'animazione sia una pagina statica per fotogramma. AnimationAndFrames offre la navigazione più ricca ma anche il più alto costo di rendering e memoria — e su un singolo server quella memoria appartiene al processo worker di IIS. Per studi di grandi dimensioni:
- usa
FramesOnlyquando l'ispezione dei fotogrammi è più importante della riproduzione; - evita di aumentare entrambi gli assi di risoluzione senza misurare la memoria;
- chiudi esplicitamente la sessione quando lo studio non è più aperto;
- mantieni
CachePagesattivo solo quando l'accesso ripetuto vale le immagini conservate.
Posiziona Doconut.Viewer.Dicom.lic accanto a Doconut.Viewer.lic su ogni server, e mantieni HEAD nella lista verb del gestore.
Riferimento API
DicomConfig, DicomDisplayMode e DicomMetadata sono nel namespace Doconut. DicomPlugin è in Doconut.Plugins.Dicom. La tabella completa delle proprietà DicomConfig è in Configurazioni Formato.
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // predefinito: ImageResolution quando impostato, altrimenti 100
public int VerticalResolution { get; set; } // predefinito: ImageResolution quando impostato, altrimenti 100
public int AnimationFrameDelayMs { get; set; } = 100;
public ushort LoopCount { get; set; } = 0; // 0 = ciclo infinito
public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}DicomDisplayMode
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);Restituisce sempre null in questo pacchetto. Lancia InvalidOperationException quando il token è sconosciuto o scaduto. DicomMetadata è definito in modo che il codice condiviso con il pacchetto .NET 8 venga compilato.
Risoluzione dei problemi
| Sintomo | Causa | Correzione |
|---|---|---|
Ogni richiesta restituisce un 500 vuoto dopo aver aggiunto il plugin; il registro eventi di Windows (origine ASP.NET) mostra The Dicom plugin is registered via AddPlugin but no active license grants Dicom. | Nessuna licenza, un file TRIAL, una licenza senza Dicom, o una licenza a pagamento al di fuori della sua finestra di versione | Installa una licenza che conceda Dicom, o rimuovi AddPlugin<DicomPlugin>() |
L'apertura di un file .dcm genera Document format '.dcm' is not supported. | DicomPlugin non è registrato, o il suo pacchetto non è distribuito | Aggiungi AddPlugin<DicomPlugin>() in DoconutHost.Initialize e distribuisci il pacchetto |
L'apertura di un file .dcm genera LicenseException: This document type requires the 'Dicom' plugin license. | La licenza caricata non concede più Dicom | Installa una licenza che conceda Dicom |
| Viene visualizzata solo una pagina | La sorgente è a singolo fotogramma, o DisplayMode è AnimationOnly | Usa FramesOnly o AnimationAndFrames per una sorgente multi‑fotogramma |
| La pagina 1 non si anima | Il gestore in Web.config non accetta HEAD | Usa verb="GET,HEAD,POST" |
| L'animazione è troppo veloce o lenta | AnimationFrameDelayMs è disattivato; il timing dei GIF usa unità di 10 ms | Regola AnimationFrameDelayMs |
| La memoria aumenta con file multi‑fotogramma di grandi dimensioni | La modalità di visualizzazione, la risoluzione e la cache delle pagine aggiungono tutte immagini trattenute | Vedi In produzione; chiudi le sessioni esplicitamente |
I metadati sono sempre null | Previsto in questo pacchetto | Usa il pacchetto .NET 8 quando ti servono i tag |
GetDicomMetadataAsync genera Document session not found. Please re-open document. | Il token è scaduto o non è mai stato aperto | Apri nuovamente il documento |
Note sul framework
Rispetto ai pacchetti ASP.NET Core, questo pacchetto differisce per l'hosting e per i metadati DICOM:
- Registrazione è in
Application_Start, tramiteDoconutHost.Initialize, invece dibuilder.Services.AddDoconut. - Errori di avvio si manifestano come un
500vuoto in ogni richiesta, con la motivazione nel registro eventi di Windows. - Rilevamento dell'animazione richiede
HEADnella listaverbdel gestoreDocImage.axd. - Nessun metadato DICOM.
Viewer.GetDicomMetadataAsyncrestituisce semprenulle registra un avviso una tantum per una sessione DICOM; la richiesta di metadatiDocImage.axdrisponde404, non il501dei pacchetti .NET 6 e .NET Standard. - Solo Windows, come il resto del pacchetto .NET Framework.
Questa pagina è stata utile?