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ície | Quando 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
dotnet add package Doconut.NET8.DicomO 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:
dotnet add package Doconut.NET8.Dicom --version 26.10.0Mantenha 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:
apt-get update && apt-get install -y libfontconfig1No 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
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:
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:
LicenseException: This document type requires the 'Dicom' plugin license.Licenciamento & marca d'água
| Estado da licença | Inicialização | Saída DICOM |
|---|---|---|
Licença paga concedendo Dicom, dentro da sua janela de versão | Inicia | Renderizado sob as regras normais de marca d'água da página |
| Licença Temporária Ativa (Demo/NFR) | Inicia | Renderizado 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ão | Lanç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#
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:
var metadata = await viewer.GetDicomMetadataAsync(token);
// null quando a sessão não é um documento DICOMModos de exibição, resolução e metadados
Modos de exibição
Arquivos DICOM multiquadro podem ser apresentados de três maneiras (DicomDisplayMode):
| Modo | Páginas produzidas | Uso para |
|---|---|---|
AnimationOnly | Página 1 = GIF animado em loop de todos os quadros | Revisão cinematográfica rápida |
FramesOnly | Páginas 1..N = um PNG estático por quadro | Navegaçã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.
// 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:
| Rota | Propósito | Resposta de sucesso |
|---|---|---|
GET ?token=<token>&meta=1 | Ler os metadados técnicos de um documento DICOM aberto | 200 — DicomMetadata como JSON, com os nomes das propriedades da referência da API (Width, Height, NumberOfFrames, …) |
| Status | Quando | Corpo |
|---|---|---|
404 | O documento não é um arquivo DICOM | apenas status |
500 | Falha 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
FramesOnlyquando 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
CachePageshabilitado 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
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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Visualizador.ObterMetadadosDicomAsync
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
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
| Sintoma | Causa | Correçã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ão | Instale 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á implantado | Adicione 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 Dicom | Instale uma licença que conceda Dicom |
| Apenas uma página aparece | A fonte é de quadro único, ou DisplayMode está AnimationOnly | Use FramesOnly ou AnimationAndFrames para uma fonte multi‑quadro |
| A animação está muito rápida ou lenta | AnimationFrameDelayMs está desativado; o tempo efetivo do GIF usa unidades de 10 ms | Ajuste AnimationFrameDelayMs |
| A memória aumenta em arquivos multiquadro grandes | Modo de exibição, resolução e cache de página adicionam todas imagens retidas | Veja Em produção; feche sessões explicitamente |
Metadados são null | O documento não é um arquivo DICOM | Verifique 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 aberto | Abra o documento novamente |
Esta página foi útil?