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ície | Quando 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
dotnet add package Doconut.NET6.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.NET6.Dicom --version 26.10.0Mantenha 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:
apt-get update && apt-get install -y libfontconfig1No 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
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 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:
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 | AddDoconut() 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#
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):
| Modo | Páginas produzidas | Uso para |
|---|---|---|
AnimationOnly | Página 1 = GIF animado repetindo 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 + 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.
// 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:
| 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 de propriedades da referência da API (Width, Height, NumberOfFrames, …) |
| Status | Quando | Corpo |
|---|---|---|
404 | O documento não é um arquivo DICOM | apenas status |
501 | O 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." } |
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 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
FramesOnlyquando 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
CachePageshabilitado 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
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);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
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
| 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>() |
Abrindo 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 |
Abrindo 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 multiquadro |
| 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 |
Metadados são null para um arquivo DICOM, ou &meta retorna 501 | Limitação esperada do .NET 6; a renderização não é afetada | 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
- 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 retornanullpara uma sessão DICOM e registra um aviso único. A solicitação?token=…&meta=1correspondente retorna HTTP501 Not Implementedcom o código de erro estáveldicom_metadata_unsupported. Use o pacote .NET 8 quando metadados DICOM técnicos forem necessários.
Esta página foi útil?