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.
| Superficie | Quando 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
dotnet add package Doconut.NET6.DicomIl comando senza versione installa l'ultima versione stabile. Per fissare il plugin alla release descritta in questa documentazione, passa la versione separatamente:
dotnet add package Doconut.NET6.Dicom --version 26.10.0Mantieni 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:
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 risponda a 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 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:
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 senza Dicom, o una licenza a pagamento fuori dalla sua finestra di versione | genera 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#
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 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 (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.
// 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:
| Percorso | Scopo | Risposta di successo |
|---|---|---|
GET ?token=<token>&meta=1 | Leggi 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 |
501 | Il 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." } |
500 | La 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
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 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
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
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 e restituisce sempre null in questo pacchetto. Lancia 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" 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
| Sintomo | Causa | Risoluzione |
|---|---|---|
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 GIF efficace 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 le sessioni esplicitamente |
I metadati sono null | Il documento non è un file DICOM | Verifica il tipo di file prima di richiedere i metadati |
I metadati sono null per un file DICOM, o &meta restituisce 501 | Limitazione prevista di .NET 6; il rendering non è influenzato | 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
- 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 restituiscenullper una sessione DICOM e registra un avviso una tantum. La corrispondente richiesta?token=…&meta=1restituisce HTTP501 Not Implementedcon il codice di errore stabiledicom_metadata_unsupported. Usa il pacchetto .NET 8 quando i metadati tecnici DICOM sono un requisito.
Questa pagina è stata utile?