DICOM Plugin

The DICOM plugin adds medical-image viewing to Doconut: multi-frame DICOM files render as an animated overview, individual frames, or both. DICOM is a plugin-only format — without this plugin (and its license capability), .dcm files cannot be opened at all.

The plugin has no widget of its own: DICOM files open in the regular viewer. With the Converter plugin also registered, .dcm and .ima files can be converted to Pdf, Png, Jpeg, Bmp, Tiff or Gif; that conversion needs the Dicom capability as well.

Install the package

dotnet add package Doconut.NETStandard.Dicom

The unversioned command installs the latest stable release. To pin the plugin to the release this documentation describes, pass the version separately:

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

Keep the DICOM package at the same version as Doconut.NETStandard. The package ID is Doconut.NETStandard.Dicom; .<version> appears only in the downloaded .nupkg filename.

The plugin's license file, Doconut.Viewer.Dicom.lic, goes in the same folder as Doconut.Viewer.lic; it is read together with the viewer license.

Register the plugin

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

The plugin (Name: "Doconut DICOM Viewer") registers viewers for the .dcm and .ima extensions, gated by the Dicom capability. Without a license that grants it, AddDoconut() throws an InvalidOperationException at startup, before the app serves a request:

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.

It throws for no license, a legacy TRIAL file, a license without Dicom, and a paid license used outside its version window. Temporary Demo/NFR licenses are accepted. See License Setup for how licenses are loaded.

Because no built-in viewer handles these formats, the runtime gate also fails hard if the capability later becomes unavailable:

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

Licensing & watermark

The normal page watermark decision also applies to DICOM output. For animated output, each GIF frame is stamped so the mark remains visible throughout playback. A custom DocOptions.Watermark is used only when the license path permits custom watermarks; it cannot replace an evaluation watermark.

Use from C#

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

Viewer.GetDicomMetadataAsync(token) exists on this package, but it returns null for a DICOM session: see Framework notes.

Display modes, resolution and metadata

Display modes

Multi-frame DICOM files can be presented three ways (DicomDisplayMode):

Animation timing is controlled by AnimationFrameDelayMs (default 100 ms = 10 FPS; GIF granularity is 10 ms units) and LoopCount (0 = loop forever).

Resolution

DicomConfig renders at 100 DPI per axis by default. The resolution properties have a fallback chain worth knowing: if you don't set HorizontalResolution/VerticalResolution explicitly, they follow BaseConfig.ImageResolution when that is configured, and only then fall back to 100.

// Uniform bump via the base property…
new DicomConfig { ImageResolution = 150 };

// …or per-axis control
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Metadata

DicomMetadata carries technical and imaging tags only — frame count, dimensions, bit depth, photometric interpretation, transfer syntax, modality and the default window level. It contains no patient-identifiable data. The full list is in the API reference. On this package the metadata is not available; see Framework notes.

In the viewer

The viewer needs no DICOM-specific setup. When the open document is a DICOM file, it requests the metadata (?token=<token>&meta=1) and adds a DICOM button that opens a technical-properties panel. If that request fails, the panel stays hidden and the document still renders. On this package the request answers 501, so the panel never appears.

Build your own frontend

The metadata is available over HTTP under the path where UseDoconut() is mounted (normally /doconut), for any open document token:

Page images, including the animated first page, use the standard viewer image route.

In production

Multiframe studies can generate both an animation and one static page per frame. AnimationAndFrames provides the richest navigation but also has the highest rendering and cache cost. For large studies:

• use FramesOnly when frame inspection matters more than cinematic playback;
• avoid increasing both resolution axes without measuring memory;
• close the session explicitly when the study is no longer open;
• keep CachePages enabled only when repeat access benefits outweigh the retained images.

Put Doconut.Viewer.Dicom.lic next to Doconut.Viewer.lic on every server.

API reference

DicomConfig, DicomDisplayMode and DicomMetadata are in the Doconut namespace. DicomPlugin is in Doconut.Plugins.Dicom. The complete DicomConfig property table lives in Format Configs.

DicomConfig

public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // default: ImageResolution when set, else 100
    public int VerticalResolution { get; set; }     // default: ImageResolution when set, else 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = loop forever
    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);

Returns null when the document is not a DICOM file, and always returns null on this package. Throws InvalidOperationException when the token is unknown or expired.

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" or "Signed"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null when not exposed
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Troubleshooting

Framework notes

• No DICOM metadata. DICOM page rendering, individual frames, animation, transforms, and watermarking are supported. Technical tag metadata is not available in the .NET Standard package because the metadata reader ships only a .NET 8 build. Viewer.GetDicomMetadataAsync(token) therefore returns null for a DICOM session and logs a one-time warning. The corresponding ?token=…&meta=1 request returns HTTP 501 Not Implemented with the stable error code dicom_metadata_unsupported. Use the .NET 8 package when technical DICOM metadata is a requirement.
• Windows only, like the rest of the .NET Standard package.