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.
| Surface | Use 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
dotnet add package Doconut.NET8.DicomIl comando senza versione installa l'ultima versione stabile. Per fissare il plugin alla versione descritta in questa documentazione, passa la versione separatamente:
dotnet add package Doconut.NET8.Dicom --version 26.10.0Mantieni 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:
apt-get update && apt-get install -y libfontconfig1Su 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
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:
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:
LicenseException: This document type requires the 'Dicom' plugin license.Licenze e filigrana
| License state | Startup | DICOM output |
|---|---|---|
Paid license granting Dicom, within its version window | Starts | Rendered under the normal page watermark rules |
| Active Temporary (Demo/NFR) license | Starts | Rendered with the evaluation watermark |
No license, a legacy TRIAL file, a license without Dicom, or a paid license outside its version window | AddDoconut() 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#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Per le sessioni aperte tramite questo plugin, Viewer espone i metadati dei tag:
var metadata = await viewer.GetDicomMetadataAsync(token);
// null quando la sessione non è un documento DICOMModalità di visualizzazione, risoluzione e metadati
Modalità di visualizzazione
I file DICOM multiframe possono essere presentati in tre modi (DicomDisplayMode):
| Modalità | Pagine prodotte | 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 = 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.
// 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:
| Percorso | Scopo | Risposta di successo |
|---|---|---|
GET ?token=<token>&meta=1 | Leggere i metadati tecnici di un documento DICOM aperto | 200 — DicomMetadata come JSON, con i nomi delle proprietà del riferimento API (Width, Height, NumberOfFrames, …) |
| Stato | Quando | Corpo |
|---|---|---|
404 | Il documento non è un file DICOM | solo stato |
500 | Lettura 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
FramesOnlyquando 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
CachePagesabilitato 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
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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
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
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
| Sintomo | Causa | Correzione |
|---|---|---|
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 versione | Installa 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 è distribuito | Aggiungi 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ù Dicom | Installa una licenza che concede Dicom |
| Viene visualizzata una sola pagina | La sorgente è a singolo fotogramma, o DisplayMode è AnimationOnly | Usa FramesOnly o AnimationAndFrames per una sorgente multi-frame |
| L'animazione è troppo veloce o lenta | AnimationFrameDelayMs è disattivato; il timing effettivo dei GIF utilizza unità di 10 ms | Regola AnimationFrameDelayMs |
| La memoria aumenta con file multiframe di grandi dimensioni | La modalità di visualizzazione, la risoluzione e la cache delle pagine aggiungono tutte immagini trattenute | Vedi In produzione; chiudi esplicitamente le sessioni |
I metadati sono null | Il documento non è un file DICOM | Verifica 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 aperto | Apri nuovamente il documento |
Questa pagina è stata utile?