Plugin DICOM
Visualize imagens médicas com DicomPlugin
O plugin DICOM adiciona visualização de imagens médicas ao Doconut: arquivos DICOM de múltiplas quadros são renderizados como uma visão geral animada, quadros 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.
No .NET Framework 4.7.2, arquivos DICOM são renderizados completamente — páginas, quadros e animação — mas os metadados técnicos (as tags DICOM) não estão disponíveis.
Viewer.GetDicomMetadataAsyncsempre retornanull, e a solicitação de metadados do visualizador (?token=…&meta=1emDocImage.axd) responde404, portanto o visualizador não mostra o painel de propriedades DICOM. UseDoconut.NET8se sua aplicação precisar das tags.
| Superfície | Quando usar |
|---|---|
Viewer com DicomConfig (C#) | Você abre arquivos DICOM no servidor e escolhe como seus quadros são apresentados |
O visualizador (docViewer) em DocImage.axd | Você exibe o estudo em sua página: animação e quadros |
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
Install-Package Doconut.NETFramework.DicomPara fixar o plugin na versão que esta documentação descreve:
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0Mantenha o pacote DICOM na mesma versão que Doconut.NETFramework.
O arquivo de licença do plugin, Doconut.Viewer.Dicom.lic, deve ficar na mesma pasta que Doconut.Viewer.lic; ele é lido junto com a licença do visualizador.
Registrar o plugin
Doconut.DoconutHost.Initialize(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. Se a licença não conceder isso, DoconutHost.Initialize lança uma exceção de Application_Start:
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.No System.Web isso significa que cada requisição responde com um 500 vazio, e o motivo está apenas no log de eventos do Windows (fonte ASP.NET). Ele lança exceção 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.
Como nenhum visualizador interno lida com esses formatos, abrir um falha completamente 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 | Application_Start lança; cada requisição responde com um 500 vazio | — |
A decisão normal de marca d'água da página também se aplica à saída DICOM. Para saída animada, cada quadro GIF é marcado, de modo que a marca permanece visível durante toda a reprodução. Um DocOptions.Watermark personalizado é usado somente quando a licença permite marcas d'água personalizadas; ele não pode substituir uma marca d'água de avaliação.
Uso a partir do C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});var metadata = await viewer.GetDicomMetadataAsync(token);
// No .NET Framework isso é sempre null: o leitor de metadados DICOM não está disponível para isso
// target. Páginas, quadros e animação são renderizados normalmente.O método existe neste pacote para que o código compartilhado com o pacote .NET 8 compile, mas a leitura de tags DICOM requer um componente que não tem compilação para .NET Framework. Planeje sua interface de usuário sem eles — por exemplo, oculte um painel de metadados quando o resultado for null.
Modos de exibição e resolução
Modos de exibição
Arquivos DICOM multi‑frame 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 (padrão) | Página 1 = GIF animado, páginas 2..N+1 = um PNG estático por quadro (N = contagem de quadros) | Visão geral e detalhe em um único documento |
O tempo de animação é controlado por AnimationFrameDelayMs (padrão 100 ms = 10 FPS; o tempo do GIF usa unidades de 10 ms) e LoopCount (0 = loop infinito).
O visualizador descobre que a página 1 está animada enviando uma solicitação HEAD para ela. O manipulador DocImage.axd deve, portanto, aceitar HEAD em Web.config (verb="GET,HEAD,POST", veja Instalação); sem isso, o IIS responde 404 antes que o Doconut seja executado e a detecção de animação nunca funciona.
Resolução
DicomConfig renderiza a 100 DPI por eixo por padrão. Se você não definir HorizontalResolution/VerticalResolution explicitamente, eles seguem BaseConfig.ImageResolution quando isso está definido, e só então retornam a 100.
// Aumento uniforme via a propriedade base…
new DicomConfig { ImageResolution = 150 };
// …ou controle por eixo
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Construa seu próprio frontend
As imagens das páginas, incluindo a primeira página animada, usam a rota de imagem padrão DocImage.axd. A solicitação de metadados, GET /DocImage.axd?token=<token>&meta=1, responde 404 neste pacote para cada documento, arquivos DICOM incluídos, porque o leitor de metadados não está disponível.
Em produção
Estudos multi‑frame podem gerar tanto uma animação quanto uma página estática por quadro. AnimationAndFrames oferece a navegação mais rica, mas também o maior custo de renderização e memória — e em um único servidor essa memória pertence ao processo de trabalho do IIS. Para estudos grandes:
- use
FramesOnlyquando a inspeção de quadros é mais importante que a reprodução; - 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
CachePagesativado apenas quando o acesso repetido vale as imagens retidas.
Coloque Doconut.Viewer.Dicom.lic ao lado de Doconut.Viewer.lic em cada servidor, e mantenha HEAD na lista verb do manipulador.
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;
}DicomDisplayMode
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);Sempre retorna null neste pacote. Lança InvalidOperationException quando o token é desconhecido ou expirado. DicomMetadata está definido para que o código compartilhado com o pacote .NET 8 compile.
Solução de Problemas
| Sintoma | Causa | Correção |
|---|---|---|
Cada solicitação responde com um 500 vazio após adicionar o plugin; o log de eventos do Windows (fonte ASP.NET) mostra 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 foi implantado | Adicione AddPlugin<DicomPlugin>() em DoconutHost.Initialize 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 |
| Aparece apenas uma página | A fonte é de quadro único, ou DisplayMode está AnimationOnly | Use FramesOnly ou AnimationAndFrames para uma fonte multi‑quadro |
| A página 1 não anima | O manipulador em Web.config não aceita HEAD | Use verb="GET,HEAD,POST" |
| A animação está muito rápida ou lenta | AnimationFrameDelayMs está desativado; o tempo do GIF usa unidades de 10 ms | Ajuste AnimationFrameDelayMs |
| A memória cresce em arquivos multi‑quadro grandes | O modo de exibição, a resolução e o cache de páginas adicionam imagens retidas | Veja Em produção; feche sessões explicitamente |
Os metadados são sempre null | Esperado neste pacote | Use o pacote .NET 8 quando precisar das tags |
GetDicomMetadataAsync lança Document session not found. Please re-open document. | O token expirou ou nunca foi aberto | Abra o documento novamente |
Observações do Framework
Comparado com os pacotes ASP.NET Core, este pacote difere em hospedagem e em metadados DICOM:
- Registro está em
Application_Start, através deDoconutHost.Initialize, ao invés debuilder.Services.AddDoconut. - Falhas de inicialização aparecem como um
500vazio em cada solicitação, com a razão no log de eventos do Windows. - Detecção de animação requer
HEADna listaverbdo manipuladorDocImage.axd. - Sem metadados DICOM.
Viewer.GetDicomMetadataAsyncsempre retornanulle registra um aviso único para uma sessão DICOM; a solicitação de metadadosDocImage.axdresponde404, não o501dos pacotes .NET 6 e .NET Standard. - Somente Windows, como o resto do pacote .NET Framework.
Esta página foi útil?