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 frames são renderizados como uma visão geral animada, frames individuais ou ambos. DICOM é um formato apenas 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 with 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 e frames

O plugin não possui um 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.NET6.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.NET6.Dicom --version 26.10.0

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

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.

Plataformas. O plugin funciona onde Doconut.NET6 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, a abertura de 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 saber como as licenças são carregadas.

Como nenhum visualizador interno 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ãoAddDoconut() lança—

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 toda 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 em C#

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

Viewer.GetDicomMetadataAsync(token) existe neste pacote, mas ele retorna null para uma sessão DICOM: veja Notas do framework.

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 repetindo 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 + detalhe em um único documento

O tempo da animação é controlado por AnimationFrameDelayMs (padrão 100 ms = 10 FPS; a 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 ao valor 100.

csharp
// Elevação uniforme via a propriedade base…
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. Neste pacote os metadados não estão disponíveis; veja Notas do framework.

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. Neste pacote a solicitação responde 501, portanto o painel nunca aparece.

Construa sua própria interface

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 de propriedades da referência da API (Width, Height, NumberOfFrames, …)
StatusQuandoCorpo
404O documento não é um arquivo DICOMapenas status
501O documento é um arquivo DICOM, mas este pacote não pode ler suas tags{ "error": "dicom_metadata_unsupported", "message": "DICOM technical metadata is not supported on this package: the underlying medical-imaging engine has no build for this target framework. On this package it always returns null; use the .NET 8 package if you need it. DICOM rendering is unaffected." }
500Falha ao ler os metadados{ "error": "metadata failed" }

Imagens de página, incluindo a primeira página animada, usam a rota padrão de imagens 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 for 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 superarem 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;
}

DicomDisplayMode

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

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

Retorna null quando o documento não é um arquivo DICOM, e sempre retorna null neste pacote. Lança InvalidOperationException quando o token é desconhecido ou expirado.

DicomMetadata

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

Soluçã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>()
Abrindo 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
Abrindo 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 multiquadro
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
Metadados são null para um arquivo DICOM, ou &meta retorna 501Limitação esperada do .NET 6; a renderização não é afetadaUse 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

  • Sem metadados DICOM. Renderização de páginas DICOM, quadros individuais, animação, transformações e marca d'água são suportados. Metadados de tags técnicas não estão disponíveis no pacote .NET 6 porque o leitor de metadados não tem compilação .NET 6. Viewer.GetDicomMetadataAsync(token) portanto retorna null para uma sessão DICOM e registra um aviso único. A solicitação ?token=…&meta=1 correspondente retorna HTTP 501 Not Implemented com o código de erro estável dicom_metadata_unsupported. Use o pacote .NET 8 quando metadados DICOM técnicos forem necessários.

Esta página foi útil?