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.GetDicomMetadataAsync sempre retorna null, e a solicitação de metadados do visualizador (?token=…&meta=1 em DocImage.axd) responde 404, portanto o visualizador não mostra o painel de propriedades DICOM. Use Doconut.NET8 se sua aplicação precisar das tags.

SuperfícieQuando usar
Viewer com DicomConfig (C#)Você abre arquivos DICOM no servidor e escolhe como seus quadros são apresentados
O visualizador (docViewer) em DocImage.axdVocê 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

powershell
Install-Package Doconut.NETFramework.Dicom

Para fixar o plugin na versão que esta documentação descreve:

powershell
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0

Mantenha 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

csharp
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:

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.

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:

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ãoApplication_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#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
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):

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 (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.

csharp
// 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 FramesOnly quando 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 CachePages ativado 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

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;
}

DicomDisplayMode

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
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

SintomaCausaCorreçã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ã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 foi implantadoAdicione 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 DicomInstale uma licença que conceda Dicom
Aparece apenas uma páginaA fonte é de quadro único, ou DisplayMode está AnimationOnlyUse FramesOnly ou AnimationAndFrames para uma fonte multi‑quadro
A página 1 não animaO manipulador em Web.config não aceita HEADUse verb="GET,HEAD,POST"
A animação está muito rápida ou lentaAnimationFrameDelayMs está desativado; o tempo do GIF usa unidades de 10 msAjuste AnimationFrameDelayMs
A memória cresce em arquivos multi‑quadro grandesO modo de exibição, a resolução e o cache de páginas adicionam imagens retidasVeja Em produção; feche sessões explicitamente
Os metadados são sempre nullEsperado neste pacoteUse 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 abertoAbra 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 de DoconutHost.Initialize, ao invés de builder.Services.AddDoconut.
  • Falhas de inicialização aparecem como um 500 vazio em cada solicitação, com a razão no log de eventos do Windows.
  • Detecção de animação requer HEAD na lista verb do manipulador DocImage.axd.
  • Sem metadados DICOM. Viewer.GetDicomMetadataAsync sempre retorna null e registra um aviso único para uma sessão DICOM; a solicitação de metadados DocImage.axd responde 404, não o 501 dos pacotes .NET 6 e .NET Standard.
  • Somente Windows, como o resto do pacote .NET Framework.

Esta página foi útil?