Plugin DICOM

Visualizar imagens médicas com DicomPlugin

O plugin DICOM adiciona visualização de imagens médicas ao Doconut: arquivos DICOM de múltiplas frames são renderizados como uma visão geral animada, frames individuais ou ambos. DICOM é um formato somente de plugin — sem este plugin (e sua capacidade de licença), arquivos .dcm não podem ser abertos de forma alguma.

SuperfícieQuando usar
Viewer com DicomConfig (C#)Você abre arquivos DICOM no servidor e escolhe como seus frames são apresentados
O visualizador (docViewer)Você exibe o estudo em sua página: animação, frames e um painel de propriedades DICOM
Endpoint HTTP (?token=<token>&meta=1)Você lê os metadados técnicos do seu próprio frontend

O plugin não tem widget próprio: arquivos DICOM são abertos no visualizador padrão. Com o plugin Conversor também registrado, arquivos .dcm e .ima podem ser convertidos para Pdf, Png, Jpeg, Bmp, Tiff ou Gif; essa conversão também requer a capacidade Dicom.

Instalar o pacote

bash
dotnet add package Doconut.NET8.Dicom

O comando sem versão instala a versão estável mais recente. Para fixar o plugin na versão que esta documentação descreve, passe a versão separadamente:

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

Mantenha o pacote DICOM na mesma versão que Doconut.NET8. O ID do pacote é Doconut.NET8.Dicom; .<version> aparece apenas no nome de arquivo .nupkg baixado.

O arquivo de licença do plugin, Doconut.Viewer.Dicom.lic, vai na mesma pasta que Doconut.Viewer.lic; ele é lido junto com a licença do visualizador.

Plataformas. O plugin funciona onde Doconut.NET8 funciona: Windows e Linux baseado em glibc em x64 (não Alpine ou outras distribuições baseadas em musl). No Linux, instale a biblioteca de configuração de fontes antes que o primeiro documento seja aberto:

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

No RHEL, Fedora e distribuições semelhantes o pacote é fontconfig. Sem ele, abrir um documento falha com The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Registrar o plugin

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

O plugin (Name: "Doconut DICOM Viewer") registra visualizadores para as extensões .dcm e .ima, controladas pela capacidade Dicom. Sem uma licença que a conceda, AddDoconut() lança um InvalidOperationException na inicialização, antes que o aplicativo atenda a uma solicitação:

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.

Ele lança o erro por falta de licença, um arquivo legado TRIAL, uma licença sem Dicom, e uma licença paga usada fora da sua janela de versão. Licenças temporárias Demo/NFR são aceitas. Veja Configuração de Licença para como as licenças são carregadas.

Como nenhum visualizador embutido lida com esses formatos, o gate de tempo de execução também falha severamente se a capacidade ficar indisponível posteriormente:

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

Licenciamento & marca d'água

Estado da licençaInicializaçãoSaída DICOM
Licença paga concedendo Dicom, dentro da sua janela de versãoIniciaRenderizado sob as regras normais de marca d'água da página
Licença Temporária Ativa (Demo/NFR)IniciaRenderizado com a marca d'água de avaliação
Sem licença, um arquivo legado TRIAL, uma licença sem Dicom, ou uma licença paga fora da sua janela de versãoLança AddDoconut()—

A decisão normal de marca d'água da página também se aplica à saída DICOM. Para saída animada, cada frame GIF é marcado para que a marca permaneça visível durante a reprodução. Um DocOptions.Watermark personalizado é usado somente quando o caminho de licença permite marcas d'água personalizadas; ele não pode substituir uma marca d'água de avaliação.

Uso a partir de C#

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

Para sessões abertas através deste plugin, Viewer expõe os metadados de tags:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null quando a sessão não é um documento DICOM

Modos de exibição, resolução e metadados

Modos de exibição

Arquivos DICOM multiquadro podem ser apresentados de três maneiras (DicomDisplayMode):

ModoPáginas produzidasUso para
AnimationOnlyPágina 1 = GIF animado em loop de todos os quadrosRevisão cinematográfica rápida
FramesOnlyPáginas 1..N = um PNG estático por quadroNavegação diagnóstica quadro a quadro
AnimationAndFrames (default)Página 1 = GIF animado, páginas 2..N+1 = um PNG estático por quadro (N = contagem de quadros)Visão geral + detalhe em um único documento

O tempo de animação é controlado por AnimationFrameDelayMs (padrão 100 ms = 10 FPS; granularidade do GIF é de unidades de 10 ms) e LoopCount (0 = loop infinito).

Resolução

DicomConfig renderiza a 100 DPI por eixo por padrão. As propriedades de resolução têm uma cadeia de fallback que vale a pena conhecer: se você não definir HorizontalResolution/VerticalResolution explicitamente, elas seguem BaseConfig.ImageResolution quando isso está configurado, e só então retornam a 100.

csharp
// Aumento uniforme via a base property…
new DicomConfig { ImageResolution = 150 };

// …ou controle por eixo
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Metadados

DicomMetadata contém apenas tags técnicas e de imagem — contagem de quadros, dimensões, profundidade de bits, interpretação fotométrica, sintaxe de transferência, modalidade e o nível de janela padrão. Não contém dados identificáveis do paciente. A lista completa está na referência da API.

No visualizador

O visualizador não precisa de configuração específica para DICOM. Quando o documento aberto é um arquivo DICOM, ele solicita os metadados (?token=<token>&meta=1) e adiciona um botão DICOM que abre um painel de propriedades técnicas. Se essa solicitação falhar, o painel permanece oculto e o documento ainda é renderizado.

Crie seu próprio frontend

Os metadados estão disponíveis via HTTP no caminho onde UseDoconut() está montado (normalmente /doconut), para qualquer token de documento aberto:

RotaPropósitoResposta de sucesso
GET ?token=<token>&meta=1Ler os metadados técnicos de um documento DICOM aberto200 — DicomMetadata como JSON, com os nomes das propriedades da referência da API (Width, Height, NumberOfFrames, …)
StatusQuandoCorpo
404O documento não é um arquivo DICOMapenas status
500Falha ao ler os metadados{ "error": "metadata failed" }

Imagens de página, incluindo a primeira página animada, usam a rota padrão de imagem do visualizador.

Em produção

Estudos multiquadro podem gerar tanto uma animação quanto uma página estática por quadro. AnimationAndFrames fornece a navegação mais rica, mas também tem o maior custo de renderização e cache. Para estudos grandes:

  • use FramesOnly quando a inspeção de quadros é mais importante que a reprodução cinematográfica;
  • evite aumentar ambos os eixos de resolução sem medir a memória;
  • feche a sessão explicitamente quando o estudo não estiver mais aberto;
  • mantenha CachePages habilitado somente quando os benefícios de acesso repetido superam as imagens retidas.

Coloque Doconut.Viewer.Dicom.lic ao lado de Doconut.Viewer.lic em cada servidor.

Referência da API

DicomConfig, DicomDisplayMode e DicomMetadata estão no namespace Doconut. DicomPlugin está em Doconut.Plugins.Dicom. A tabela completa de propriedades DicomConfig está em Configurações de Formato.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // padrão: ImageResolution quando definido, caso contrário 100
    public int VerticalResolution { get; set; }     // padrão: ImageResolution quando definido, caso contrário 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = loop infinito
    public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}

Modo de Exibição DICOM

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Visualizador.ObterMetadadosDicomAsync

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

Retorna null quando o documento não é um arquivo DICOM. Lança InvalidOperationException quando o token é desconhecido ou expirado.

Metadados DICOM

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" ou "Signed"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null quando não exposto
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Resolução de Problemas

SintomaCausaCorreção
AddDoconut() lança The Dicom plugin is registered via AddPlugin but no active license grants Dicom.Sem licença, um arquivo TRIAL, uma licença sem Dicom, ou uma licença paga fora da sua janela de versãoInstale uma licença que conceda Dicom, ou remova AddPlugin<DicomPlugin>()
Abrir um arquivo .dcm lança Document format '.dcm' is not supported.DicomPlugin não está registrado, ou seu pacote não está implantadoAdicione AddPlugin<DicomPlugin>() dentro de AddDoconut() e implante o pacote
Abrir um arquivo .dcm lança LicenseException: This document type requires the 'Dicom' plugin license.A licença carregada não concede mais DicomInstale uma licença que conceda Dicom
Apenas uma página apareceA fonte é de quadro único, ou DisplayMode está AnimationOnlyUse FramesOnly ou AnimationAndFrames para uma fonte multi‑quadro
A animação está muito rápida ou lentaAnimationFrameDelayMs está desativado; o tempo efetivo do GIF usa unidades de 10 msAjuste AnimationFrameDelayMs
A memória aumenta em arquivos multiquadro grandesModo de exibição, resolução e cache de página adicionam todas imagens retidasVeja Em produção; feche sessões explicitamente
Metadados são nullO documento não é um arquivo DICOMVerifique o tipo de arquivo antes de solicitar metadados
GetDicomMetadataAsync lança Document session not found. Please re-open document.O token expirou ou nunca foi abertoAbra o documento novamente

Esta página foi útil?