DICOM‑plugin

Visa medicinska bilder med DicomPlugin

DICOM‑pluginet lägger till visning av medicinska bilder i Doconut: flerbilds‑DICOM‑filer renderas som en animerad översikt, enskilda ramar eller båda. DICOM är ett plugin‑endast format — utan detta plugin (och dess licensfunktion) kan .dcm‑filer inte öppnas alls.

YtaAnvänd när
Viewer med DicomConfig (C#)Du öppnar DICOM‑filer på servern och väljer hur deras ramar ska presenteras
Visaren (docViewer)Du visar studien på din sida: animation och ramar

Pluginet har ingen egen widget: DICOM‑filer öppnas i den vanliga visaren. Med den Konverterings‑plugin som också är registrerad kan .dcm‑ och .ima‑filer konverteras till Pdf, Png, Jpeg, Bmp, Tiff eller Gif; den konverteringen kräver även Dicom‑kapaciteten.

Installera paketet

bash
dotnet add package Doconut.NETStandard.Dicom

Det oversionshanterade kommandot installerar den senaste stabila versionen. För att låsa pluginet till den version som denna dokumentation beskriver, ange versionen separat:

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

Behåll DICOM‑paketet på samma version som Doconut.NETStandard. Paket‑ID:t är Doconut.NETStandard.Dicom; .<version> visas endast i det nedladdade .nupkg‑filnamnet.

Pluginets licensfil, Doconut.Viewer.Dicom.lic, placeras i samma mapp som Doconut.Viewer.lic; den läses tillsammans med visarlicensen.

Registrera pluginet

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Pluginet (Name: "Doconut DICOM Viewer") registrerar visare för .dcm‑ och .ima‑tillägg, styrda av Dicom‑kapaciteten. Utan en licens som beviljar den, kastar AddDoconut() ett InvalidOperationException vid uppstart, innan appen hanterar en begäran:

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.

Det kastas när ingen licens finns, en äldre TRIAL‑fil, en licens utan Dicom, och en betald licens som används utanför dess versionsfönster. Tillfälliga Demo/NFR‑licenser accepteras. Se Licensinställning för hur licenser laddas.

Eftersom ingen inbyggd visare hanterar dessa format, misslyckas även körningens grind hårt om kapaciteten senare blir otillgänglig:

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

Licensiering & vattenstämpel

LicensstatusUppstartDICOM‑utdata
Betald licens som beviljar Dicom, inom dess versionsfönsterStartarRenderas enligt de normala sidans vattenstämpelreglerna
Aktiv tillfällig (Demo/NFR) licensStartarRenderas med utvärderingsvattenstämpeln
Ingen licens, en äldre TRIAL‑fil, en licens utan Dicom, eller en betald licens utanför dess versionsfönsterAddDoconut() kastar—

Det normala sidans vattenstämpelbeslut gäller även för DICOM‑utdata. För animerad utdata stämplas varje GIF‑ram så att märket förblir synligt under hela uppspelningen. En anpassad DocOptions.Watermark används endast när licensvägen tillåter anpassade vattenstämplar; den kan inte ersätta en utvärderingsvattenstämpel.

Användning från C#

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

Viewer.GetDicomMetadataAsync(token) finns i detta paket, men det returnerar null för en DICOM‑session: se Framework‑anteckningar.

Visningslägen, upplösning och metadata

Visningslägen

Multiramiga DICOM-filer kan presenteras på tre sätt (DicomDisplayMode):

LägeSidor som producerasAnvändning
AnimationOnlySida 1 = animerad GIF som loopar alla ramarSnabb filmisk granskning
FramesOnlySidor 1..N = en statisk PNG per ramRam-för-ram diagnostisk navigering
AnimationAndFrames (default)Sida 1 = animerad GIF, sidor 2..N+1 = en statisk PNG per ram (N = antal ramar)Översikt + detalj i ett dokument

Animeringstiden styrs av AnimationFrameDelayMs (standard 100 ms = 10 FPS; GIF-granularitet är 10 ms-enheter) och LoopCount (0 = loopa för alltid).

Upplösning

DicomConfig renderar med 100 DPI per axel som standard. Upplösningsegenskaperna har en återfallskedja som är värd att känna till: om du inte sätter HorizontalResolution/VerticalResolution explicit, följer de BaseConfig.ImageResolution när det är konfigurerat, och först då återgår de till 100.

csharp
// Enhetlig bump via basegenskapen…
new DicomConfig { ImageResolution = 150 };

// …eller per-axelskontroll
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Metadata

DicomMetadata innehåller endast tekniska och bildrelaterade taggar — antal ramar, dimensioner, bitdjup, fotometrisk tolkning, överföringssyntax, modalitet och standardfönsternivå. Den innehåller ingen patientidentifierbar data. Den fullständiga listan finns i API-referensen. I detta paket är metadata inte tillgänglig; se Framework-noteringar.

I visaren

Visaren kräver ingen DICOM-specifik konfiguration. När det öppna dokumentet är en DICOM-fil begär den metadata (?token=<token>&meta=1) och lägger till en DICOM-knapp som öppnar en tekniska-egenskaper-panel. Om den begäran misslyckas förblir panelen dold och dokumentet renderas ändå. I detta paket svarar begäran med 501, så panelen visas aldrig.

Bygg ditt eget frontend

Metadata är tillgänglig via HTTP under den sökväg där UseDoconut() är monterad (vanligtvis /doconut), för vilken som helst öppet dokumenttoken:

RuttSyfteLyckad respons
GET ?token=<token>&meta=1Läs den tekniska metadata för ett öppet DICOM-dokument200 — DicomMetadata som JSON, med egenskapsnamnen från API-referensen (Width, Height, NumberOfFrames, …)
StatusNärKropp
404Dokumentet är inte en DICOM-filendast status
501Dokumentet är en DICOM-fil, men detta paket kan inte läsa dess taggar{ "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." }
500Läsning av metadata misslyckades{ "error": "metadata failed" }

Sidsbilder, inklusive den animerade första sidan, använder den standardiserade bildrutten för visaren.

I produktion

Multiramiga studier kan generera både en animation och en statisk sida per ram. AnimationAndFrames ger den rikaste navigeringen men har också den högsta renderings- och cachekostnaden. För stora studier:

  • använd FramesOnly när raminspektion är viktigare än filmisk uppspelning;
  • undvik att öka båda upplösningsaxlarna utan att mäta minnet;
  • stäng sessionen explicit när studien inte längre är öppen;
  • håll CachePages aktiverad endast när fördelarna med återkommande åtkomst överväger de behållna bilderna.

Placera Doconut.Viewer.Dicom.lic bredvid Doconut.Viewer.lic på varje server.

API-referens

DicomConfig, DicomDisplayMode och DicomMetadata finns i Doconut-namnutrymmet. DicomPlugin finns i Doconut.Plugins.Dicom. Den kompletta DicomConfig-egenskapstabellen finns i Format Configs.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // standard: ImageResolution när angivet, annars 100
    public int VerticalResolution { get; set; }     // standard: ImageResolution när angivet, annars 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = loopa för alltid
    public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}

DicomVisningsläge

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);

Returnerar null när dokumentet inte är en DICOM‑fil, och returnerar alltid null i detta paket. Kastar InvalidOperationException när token är okänd eller har gått ut.

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; }   // "Osignerad" eller "Signerad"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null när den inte är exponerad
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Felsökning

SymptomOrsakLösning
AddDoconut() kastar The Dicom plugin is registered via AddPlugin but no active license grants Dicom.Ingen licens, en TRIAL‑fil, en licens utan Dicom, eller en betald licens utanför dess versionsfönsterInstallera en licens som ger Dicom, eller ta bort AddPlugin<DicomPlugin>()
Öppning av en .dcm‑fil kastar Document format '.dcm' is not supported.DicomPlugin är inte registrerad, eller så är dess paket inte distribueratLägg till AddPlugin<DicomPlugin>() i AddDoconut() och distribuera paketet
Öppning av en .dcm‑fil kastar LicenseException: This document type requires the 'Dicom' plugin license.Den laddade licensen ger inte längre DicomInstallera en licens som ger Dicom
Endast en sida visasKällan är enkelram, eller DisplayMode är AnimationOnlyAnvänd FramesOnly eller AnimationAndFrames för en fleramrig källa
Animationen är för snabb eller för långsamAnimationFrameDelayMs är avstängd; effektiv GIF-timing använder 10 ms‑enheterJustera AnimationFrameDelayMs
Minnet växer på stora fleramrsfilerVisningsläge, upplösning och sidcache lägger alla till behållna bilderSe I produktion; stäng sessioner explicit
Metadata är nullDokumentet är inte en DICOM‑filKontrollera filtypen innan du begär metadata
Metadata är null för en DICOM‑fil, eller &meta returnerar 501Förväntad begränsning i detta paket; rendering påverkas inteAnvänd .NET 8‑paketet när du behöver taggarna
GetDicomMetadataAsync kastar Document session not found. Please re-open document.Token har gått ut eller öppnades aldrigÖppna dokumentet igen

Ramverkanteckningar

  • Ingen DICOM‑metadata. DICOM‑sidrendering, enskilda ramar, animation, transformationer och vattenstämpling stöds. Teknisk tagg‑metadata är inte tillgänglig i .NET Standard‑paketet eftersom metadata‑läsaren endast levereras som en .NET 8‑byggnad. Viewer.GetDicomMetadataAsync(token) returnerar därför null för en DICOM‑session och loggar en engångsvarning. Den motsvarande ?token=…&meta=1‑begäran returnerar HTTP 501 Not Implemented med den stabila felkoden dicom_metadata_unsupported. Använd .NET 8‑paketet när teknisk DICOM‑metadata är ett krav.
  • Endast Windows, likt resten av .NET Standard‑paketet.

Var den här sidan hjälpsam?