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, ramar och en DICOM‑egenskapspanel
HTTP‑slutpunkt (?token=<token>&meta=1)Du läser den tekniska metadata från ditt eget frontend

Pluginet har ingen egen widget: DICOM‑filer öppnas i den vanliga visaren. Med den även registrerade Konverterings‑pluginet 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.NET8.Dicom

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

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

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

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

Plattformar. Pluginet körs där Doconut.NET8 körs: Windows och glibc‑baserad Linux på x64 (inte Alpine eller andra musl‑baserade distributioner). På Linux, installera libfontconfig1‑biblioteket innan det första dokumentet öppnas:

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

På RHEL, Fedora och liknande distributioner är paketet fontconfig. Utan det misslyckas öppning av ett dokument med The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

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, styrt av Dicom‑kapaciteten. Utan en licens som beviljar den, kastar AddDoconut() ett InvalidOperationException vid start, innan appen betjänar 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 för ingen licens, en äldre TRIAL‑fil, en licens utan Dicom, och en betald licens som används utanför sitt 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 sitt versionsfönsterStartarRenderas enligt de vanliga 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 sitt versionsfönsterAddDoconut() kastar—

Det vanliga 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 i C#

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

För sessioner som öppnas via detta plugin, Viewer exponerar taggmetadata:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null när sessionen inte är ett DICOM-dokument

Visningslägen, upplösning och metadata

Visningslägen

Multiramade 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 (standard)Sida 1 = animerad GIF, sidor 2..N+1 = en statisk PNG per ram (N = antal ramar)Översikt + detaljer 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å faller de tillbaka till 100.

csharp
// Enhetlig ökning 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 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 panel med tekniska egenskaper. Om den begäran misslyckas förblir panelen dold och dokumentet renderas ändå.

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:

RuttSyfteSvar vid framgång
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
500Läsning av metadata misslyckades{ "error": "metadata failed" }

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

I produktion

Multiramstudier 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;
  • behå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 namnrymden Doconut. DicomPlugin finns i Doconut.Plugins.Dicom. Den kompletta egenskapstabellen för DicomConfig finns i Format Configs.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // standard: ImageResolution när satt, annars 100
    public int VerticalResolution { get; set; }     // standard: ImageResolution när satt, 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. 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; }   // "Unsigned" eller "Signed"
    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

SymtomOrsakLö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 dess paket är 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
GetDicomMetadataAsync kastar Document session not found. Please re-open document.Token har gått ut eller öppnades aldrigÖppna dokumentet igen

Var den här sidan hjälpsam?