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.

SuperficieQuando usarlo
Viewer with DicomConfig (C#)Apri i file DICOM sul server e scegli come presentare i loro fotogrammi
Il visualizzatore (docViewer)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 Converter anch'esso registrato, i file .dcm e .ima possono essere convertiti in Pdf, Png, Jpeg, Bmp, Tiff o Gif; tale conversione richiede anche la capacità Dicom.

Installa il pacchetto

bash
dotnet add package Doconut.NET6.Dicom

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

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

Mantieni il pacchetto DICOM alla stessa versione di Doconut.NET6. L'ID del pacchetto è Doconut.NET6.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.NET6 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 risponda a 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 fuori dalla sua finestra di versione. Le licenze temporanee Demo/NFR sono accettate. Vedi Configurazione Licenza per come vengono caricate le licenze.

Poiché nessun visualizzatore integrato gestisce questi formati, il gate di runtime fallisce anche in modo definitivo 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 senza Dicom, o una licenza a pagamento fuori dalla sua finestra di versionegenera AddDoconut()—

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.

Utilizzo da C#

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

Viewer.GetDicomMetadataAsync(token) esiste in questo pacchetto, ma restituisce null per una sessione DICOM: vedi Note sul framework.

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 (default)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 10 ms) e LoopCount (0 = loop infinito).

Risoluzione

DicomConfig rende a 100 DPI per asse per impostazione predefinita. Le proprietà di risoluzione hanno una catena di fallback utile da conoscere: se non imposti esplicitamente HorizontalResolution/VerticalResolution, seguono BaseConfig.ImageResolution quando è configurato, e solo allora tornano a 100.

csharp
// Bump 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 dei 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 è nella riferimento API. In questo pacchetto i metadati non sono disponibili; vedi Note sul framework.

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 quella richiesta fallisce, il pannello rimane nascosto e il documento viene comunque renderizzato. In questo pacchetto la richiesta restituisce 501, quindi il pannello non appare mai.

Crea 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=1Leggi 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
501Il documento è un file DICOM, ma questo pacchetto non può leggere i suoi tag{ "error": "dicom_metadata_unsupported", "message": "DICOM technical metadata is not supported on this package: the underlying medical-imaging engine has no build for this target framework. On this package it always returns null; use the .NET 8 package if you need it. DICOM rendering is unaffected." }
500La lettura dei metadati è fallita{ "error": "metadata failed" }

Le immagini delle pagine, inclusa la prima pagina animata, usano il percorso immagine standard 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 accesso ripetuto superano le immagini conservate.

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

Riferimento API

DicomConfig, DicomDisplayMode e DicomMetadata sono nel namespace Doconut. DicomPlugin è in Doconut.Plugins.Dicom. La tabella completa delle proprietà DicomConfig si trova in Configurazioni di formato.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // default: ImageResolution quando impostato, altrimenti 100
    public int VerticalResolution { get; set; }     // default: 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 null quando il documento non è un file DICOM e restituisce sempre null in questo pacchetto. Lancia 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" oppure "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

SintomoCausaRisoluzione
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 GIF efficace 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 le sessioni esplicitamente
I metadati sono nullIl documento non è un file DICOMVerifica il tipo di file prima di richiedere i metadati
I metadati sono null per un file DICOM, o &meta restituisce 501Limitazione prevista di .NET 6; il rendering non è influenzatoUsa 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

  • Nessun metadato DICOM. Il rendering delle pagine DICOM, i fotogrammi individuali, l'animazione, le trasformazioni e il watermarking sono supportati. I metadati tecnici dei tag non sono disponibili nel pacchetto .NET 6 perché il lettore di metadati non ha una build .NET 6. Viewer.GetDicomMetadataAsync(token) quindi restituisce null per una sessione DICOM e registra un avviso una tantum. La corrispondente richiesta ?token=…&meta=1 restituisce HTTP 501 Not Implemented con il codice di errore stabile dicom_metadata_unsupported. Usa il pacchetto .NET 8 quando i metadati tecnici DICOM sono un requisito.

Questa pagina è stata utile?