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.GetDicomMetadataAsync restituisce sempre null, e la richiesta di metadati del visualizzatore (?token=…&meta=1 su DocImage.axd) risponde 404, quindi il visualizzatore non mostra alcun pannello delle proprietà DICOM. Usa Doconut.NET8 se la tua applicazione ha bisogno dei tag.

SuperficieQuando usarlo
Viewer with DicomConfig (C#)Apri i file DICOM sul server e scegli come presentare i loro fotogrammi
Il visualizzatore (docViewer) su DocImage.axdMostri 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

powershell
Install-Package Doconut.NETFramework.Dicom

Per fissare il plugin alla versione descritta in questa documentazione:

powershell
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0

Mantieni 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

csharp
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:

text
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:

text
LicenseException: This document type requires the 'Dicom' plugin license.

Licenze e filigrana

Stato della licenzaAvvioOutput DICOM
Licenza a pagamento che concede Dicom, entro la sua finestra di versioneAvviaRenderizzato secondo le normali regole di filigrana della pagina
Licenza Temporanea Attiva (Demo/NFR)AvviaRenderizzato 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 versioneApplication_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#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
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 generateUso per
AnimationOnlyPagina 1 = GIF animato che ripete tutti i fotogrammiRevisione cinematografica rapida
FramesOnlyPagine 1..N = un PNG statico per fotogrammaNavigazione 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.

csharp
// 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 FramesOnly quando 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 CachePages attivo 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

csharp
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

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
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

SintomoCausaCorrezione
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 versioneInstalla 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 è distribuitoAggiungi 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ù DicomInstalla una licenza che conceda Dicom
Viene visualizzata solo una paginaLa sorgente è a singolo fotogramma, o DisplayMode è AnimationOnlyUsa FramesOnly o AnimationAndFrames per una sorgente multi‑fotogramma
La pagina 1 non si animaIl gestore in Web.config non accetta HEADUsa verb="GET,HEAD,POST"
L'animazione è troppo veloce o lentaAnimationFrameDelayMs è disattivato; il timing dei GIF usa unità di 10 msRegola AnimationFrameDelayMs
La memoria aumenta con file multi‑fotogramma di grandi dimensioniLa modalità di visualizzazione, la risoluzione e la cache delle pagine aggiungono tutte immagini trattenuteVedi In produzione; chiudi le sessioni esplicitamente
I metadati sono sempre nullPrevisto in questo pacchettoUsa 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 apertoApri 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, tramite DoconutHost.Initialize, invece di builder.Services.AddDoconut.
  • Errori di avvio si manifestano come un 500 vuoto in ogni richiesta, con la motivazione nel registro eventi di Windows.
  • Rilevamento dell'animazione richiede HEAD nella lista verb del gestore DocImage.axd.
  • Nessun metadato DICOM. Viewer.GetDicomMetadataAsync restituisce sempre null e registra un avviso una tantum per una sessione DICOM; la richiesta di metadati DocImage.axd risponde 404, non il 501 dei pacchetti .NET 6 e .NET Standard.
  • Solo Windows, come il resto del pacchetto .NET Framework.

Questa pagina è stata utile?