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, singoli fotogrammi o entrambi. DICOM è un formato solo plugin — senza questo plugin (e la sua capacità di licenza), i file .dcm non possono essere aperti affatto.

SurfaceUse it when
Viewer with DicomConfig (C#)Apri i file DICOM sul server e scegli come presentare i loro fotogrammi
The viewer (docViewer)Mostri lo studio nella tua pagina: animazione, fotogrammi e un pannello delle proprietà DICOM
HTTP endpoint (?token=<token>&meta=1)Leggi i metadati tecnici dal tuo frontend

Il plugin non ha un widget proprio: i file DICOM si aprono nel visualizzatore standard. Con il plugin di conversione 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

bash
dotnet add package Doconut.NET8.Dicom

Il comando senza versione installa l'ultima versione stabile. Per fissare il plugin alla versione descritta in questa documentazione, passa la versione separatamente:

bash
dotnet add package Doconut.NET8.Dicom --version 26.10.0

Mantieni il pacchetto DICOM alla stessa versione di Doconut.NET8. L'ID del pacchetto è Doconut.NET8.Dicom; .<version> appare solo nel nome file scaricato .nupkg.

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.

Piattaforme. Il plugin funziona ovunque Doconut.NET8 funzioni: Windows e Linux basato su glibc su x64 (non Alpine o altre distribuzioni basate su musl). Su Linux, installa la libreria di configurazione dei font prima che il primo documento si apra:

bash
apt-get update && apt-get install -y libfontconfig1

Su RHEL, Fedora e distribuzioni simili il pacchetto è fontconfig. Senza di esso, l'apertura di un documento fallisce con The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Registra il plugin

csharp
builder.Services.AddDoconut(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. Senza una licenza che la conceda, AddDoconut() genera un InvalidOperationException all'avvio, prima che l'app serva una richiesta:

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.

Viene generato per assenza di licenza, un file legacy TRIAL, una licenza senza 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 per come le licenze vengono caricate.

Poiché nessun visualizzatore integrato gestisce questi formati, il gate di runtime fallisce anche in modo critico se la capacità diventa successivamente non disponibile:

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

Licenze e filigrana

License stateStartupDICOM output
Paid license granting Dicom, within its version windowStartsRendered under the normal page watermark rules
Active Temporary (Demo/NFR) licenseStartsRendered with the evaluation watermark
No license, a legacy TRIAL file, a license without Dicom, or a paid license outside its version windowAddDoconut() throws—

La decisione della filigrana della pagina normale si applica anche all'output DICOM. Per l'output animato, ogni fotogramma GIF è contrassegnato in modo che il marchio rimanga visibile durante la riproduzione. Un DocOptions.Watermark personalizzato è usato solo quando il percorso di licenza consente filigrane personalizzate; non può sostituire una filigrana di valutazione.

Uso da C#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});

Per le sessioni aperte tramite questo plugin, Viewer espone i metadati dei tag:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null quando la sessione non è un documento DICOM

Modalità di visualizzazione, risoluzione e metadati

Modalità di visualizzazione

I file DICOM multiframe possono essere presentati in tre modi (DicomDisplayMode):

ModalitàPagine prodotteUso 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 = numero di fotogrammi)Panoramica + dettaglio in un unico documento

Il timing dell'animazione è controllato da AnimationFrameDelayMs (predefinito 100 ms = 10 FPS; la granularità del GIF è di unità da 10 ms) e da LoopCount (0 = ciclo infinito).

Risoluzione

DicomConfig rende a 100 DPI per asse per impostazione predefinita. Le proprietà di risoluzione hanno una catena di fallback da conoscere: se non imposti esplicitamente HorizontalResolution/VerticalResolution, esse seguono BaseConfig.ImageResolution quando è configurato, 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 };

Metadati

DicomMetadata contiene solo tag tecnici e di imaging — conteggio fotogrammi, dimensioni, profondità di bit, interpretazione fotometrica, sintassi di trasferimento, modalità e livello di finestra predefinito. Non contiene dati identificabili del paziente. L'elenco completo è nel riferimento API.

Nel visualizzatore

Il visualizzatore non richiede alcuna configurazione specifica per DICOM. Quando il documento aperto è un file DICOM, richiede i metadati (?token=<token>&meta=1) e aggiunge un pulsante DICOM che apre un pannello di proprietà tecniche. Se tale richiesta fallisce, il pannello rimane nascosto e il documento viene comunque renderizzato.

Costruisci il tuo frontend

I metadati sono disponibili via HTTP sotto il percorso dove UseDoconut() è montato (normalmente /doconut), per qualsiasi token di documento aperto:

PercorsoScopoRisposta di successo
GET ?token=<token>&meta=1Leggere i metadati tecnici di un documento DICOM aperto200 — DicomMetadata come JSON, con i nomi delle proprietà del riferimento API (Width, Height, NumberOfFrames, …)
StatoQuandoCorpo
404Il documento non è un file DICOMsolo stato
500Lettura dei metadati fallita{ "error": "metadata failed" }

Le immagini delle pagine, inclusa la prima pagina animata, usano il percorso standard delle immagini del visualizzatore.

In produzione

Gli studi multiframe possono generare sia un'animazione sia una pagina statica per fotogramma. AnimationAndFrames fornisce la navigazione più ricca ma ha anche il costo più alto di rendering e cache. Per studi di grandi dimensioni:

  • usa FramesOnly quando l'ispezione dei fotogrammi è più importante della riproduzione cinematografica;
  • evita di aumentare entrambi gli assi di risoluzione senza misurare la memoria;
  • chiudi esplicitamente la sessione quando lo studio non è più aperto;
  • mantieni CachePages abilitato solo quando i benefici di accessi ripetuti superano le immagini conservate.

Posiziona Doconut.Viewer.Dicom.lic accanto a Doconut.Viewer.lic su ogni server.

Riferimento API

DicomConfig, DicomDisplayMode e DicomMetadata sono nello spazio dei nomi Doconut. DicomPlugin è in Doconut.Plugins.Dicom. L'intera tabella delle proprietà DicomConfig si trova in Configurazioni Formato.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // predefinito: ImageResolution se impostato, altrimenti 100
    public int VerticalResolution { get; set; }     // predefinito: ImageResolution se 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 null quando il documento non è un file DICOM. Genera InvalidOperationException quando il token è sconosciuto o scaduto.

DicomMetadata

csharp
public sealed class DicomMetadata
{
    public int Width { get; init; }
    public int Height { get; init; }
    public int NumberOfFrames { get; init; }
    public int BitsAllocated { get; init; }
    public int BitsStored { get; init; }
    public int SamplesPerPixel { get; init; }
    public string? PhotometricInterpretation { get; init; }
    public string? PixelRepresentation { get; init; }   // "Unsigned" o "Signed"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null quando non esposto
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Risoluzione dei problemi

SintomoCausaCorrezione
AddDoconut() genera 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 concede Dicom, oppure 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>() all'interno di AddDoconut() 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 concede Dicom
Viene visualizzata una sola paginaLa sorgente è a singolo fotogramma, o DisplayMode è AnimationOnlyUsa FramesOnly o AnimationAndFrames per una sorgente multi-frame
L'animazione è troppo veloce o lentaAnimationFrameDelayMs è disattivato; il timing effettivo dei GIF utilizza unità di 10 msRegola AnimationFrameDelayMs
La memoria aumenta con file multiframe di grandi dimensioniLa modalità di visualizzazione, la risoluzione e la cache delle pagine aggiungono tutte immagini trattenuteVedi In produzione; chiudi esplicitamente le sessioni
I metadati sono nullIl documento non è un file DICOMVerifica il tipo di file prima di richiedere i metadati
GetDicomMetadataAsync genera Document session not found. Please re-open document.Il token è scaduto o non è mai stato apertoApri nuovamente il documento

Questa pagina è stata utile?