Plugin DICOM
Ver imágenes médicas con DicomPlugin
El plugin DICOM añade la visualización de imágenes médicas a Doconut: los archivos DICOM de varios fotogramas se renderizan como una vista previa animada, fotogramas individuales, o ambos. DICOM es un formato solo de plugin — sin este plugin (y su capacidad de licencia), los archivos .dcm no pueden abrirse en absoluto.
| Superficie | Cuándo usarlo |
|---|---|
Viewer con DicomConfig (C#) | Abres archivos DICOM en el servidor y eliges cómo se presentan sus fotogramas |
El visor (docViewer) | Muestras el estudio en tu página: animación y fotogramas |
El plugin no tiene su propio widget: los archivos DICOM se abren en el visor regular. Con el plugin de conversión también registrado, los archivos .dcm y .ima pueden convertirse a Pdf, Png, Jpeg, Bmp, Tiff o Gif; esa conversión también necesita la capacidad Dicom.
Instalar el paquete
dotnet add package Doconut.NET6.DicomEl comando sin versión instala la última versión estable. Para fijar el plugin a la versión que describe esta documentación, pasa la versión por separado:
dotnet add package Doconut.NET6.Dicom --version 26.10.0Mantén el paquete DICOM en la misma versión que Doconut.NET6. El ID del paquete es Doconut.NET6.Dicom; .<version> aparece solo en el nombre de archivo descargado .nupkg.
El archivo de licencia del plugin, Doconut.Viewer.Dicom.lic, se coloca en la misma carpeta que Doconut.Viewer.lic; se lee junto con la licencia del visor.
Plataformas. El plugin se ejecuta dondequiera que Doconut.NET6 se ejecute: Windows y Linux basado en glibc en x64 (no Alpine ni otras distribuciones basadas en musl). En Linux, instala la biblioteca de configuración de fuentes antes de que se abra el primer documento:
apt-get update && apt-get install -y libfontconfig1En RHEL, Fedora y distribuciones similares el paquete es fontconfig. Sin él, abrir un documento falla con 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 el plugin
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});El plugin (Name: "Doconut DICOM Viewer") registra visores para las extensiones .dcm y .ima, controladas por la capacidad Dicom. Sin una licencia que lo otorgue, AddDoconut() lanza un InvalidOperationException al iniciar, antes de que la aplicación sirva una solicitud:
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.Se lanza por falta de licencia, un archivo TRIAL heredado, una licencia sin Dicom, y una licencia de pago usada fuera de su ventana de versión. Se aceptan licencias temporales Demo/NFR. Consulta Configuración de licencia para saber cómo se cargan las licencias.
Debido a que ningún visor incorporado maneja estos formatos, la puerta de tiempo de ejecución también falla bruscamente si la capacidad se vuelve indisponible más adelante:
LicenseException: This document type requires the 'Dicom' plugin license.Licenciamiento y marca de agua
| Estado de licencia | Al iniciar | Salida DICOM |
|---|---|---|
Licencia de pago que otorga Dicom, dentro de su ventana de versión | Al iniciar | Renderizado bajo las reglas normales de marca de agua de la página |
| Licencia temporal activa (Demo/NFR) | Al iniciar | Renderizado con la marca de agua de evaluación |
Sin licencia, un archivo TRIAL heredado, una licencia sin Dicom, o una licencia de pago fuera de su ventana de versión | AddDoconut() lanza | — |
La decisión normal de marca de agua de la página también se aplica a la salida DICOM. Para la salida animada, cada fotograma GIF se marca para que la marca permanezca visible durante toda la reproducción. Un DocOptions.Watermark personalizado se usa solo cuando la ruta de licencia permite marcas de agua personalizadas; no puede reemplazar una marca de agua de evaluación.
Uso desde C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Viewer.GetDicomMetadataAsync(token) existe en este paquete, pero devuelve null para una sesión DICOM: vea Notas del framework.
Modos de visualización, resolución y metadatos
Modos de visualización
Los archivos DICOM multicuadro pueden presentarse de tres maneras (DicomDisplayMode):
| Modo | Páginas producidas | Uso para |
|---|---|---|
AnimationOnly | Página 1 = GIF animado que reproduce todos los cuadros en bucle | Revisión cinematográfica rápida |
FramesOnly | Páginas 1..N = un PNG estático por cuadro | Navegación diagnóstica cuadro a cuadro |
AnimationAndFrames (default) | Página 1 = GIF animado, páginas 2..N+1 = un PNG estático por cuadro (N = número de cuadros) | Visión general + detalle en un documento |
El tiempo de animación está controlado por AnimationFrameDelayMs (predeterminado 100 ms = 10 FPS; la granularidad del GIF es de unidades de 10 ms) y LoopCount (0 = repetir indefinidamente).
Resolución
DicomConfig renderiza a 100 DPI por eje por defecto. Las propiedades de resolución tienen una cadena de reserva que vale la pena conocer: si no estableces HorizontalResolution/VerticalResolution explícitamente, siguen a BaseConfig.ImageResolution cuando está configurado, y solo entonces vuelven a 100.
// Bump uniforme mediante la propiedad base…
new DicomConfig { ImageResolution = 150 };
// …o control por eje
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Metadatos
DicomMetadata lleva solo etiquetas técnicas y de imagen — recuento de cuadros, dimensiones, profundidad de bits, interpretación fotométrica, sintaxis de transferencia, modalidad y el nivel de ventana predeterminado. No contiene datos identificables del paciente. La lista completa está en la referencia de API. En este paquete los metadatos no están disponibles; vea Notas del framework.
En el visor
El visor no necesita configuración específica de DICOM. Cuando el documento abierto es un archivo DICOM, solicita los metadatos (?token=<token>&meta=1) y agrega un botón DICOM que abre un panel de propiedades técnicas. Si esa solicitud falla, el panel permanece oculto y el documento sigue renderizándose. En este paquete la solicitud responde 501, por lo que el panel nunca aparece.
Construye tu propio frontend
Los metadatos están disponibles vía HTTP bajo la ruta donde UseDoconut() está montado (normalmente /doconut), para cualquier token de documento abierto:
| Ruta | Propósito | Respuesta exitosa |
|---|---|---|
GET ?token=<token>&meta=1 | Leer los metadatos técnicos de un documento DICOM abierto | 200 — DicomMetadata como JSON, con los nombres de propiedad de la referencia de API (Width, Height, NumberOfFrames, …) |
| Estado | Cuándo | Cuerpo |
|---|---|---|
404 | El documento no es un archivo DICOM | solo estado |
501 | El documento es un archivo DICOM, pero este paquete no puede leer sus etiquetas | { "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 | Falló la lectura de los metadatos | { "error": "metadata failed" } |
Las imágenes de página, incluida la primera página animada, usan la ruta estándar de imágenes del visor.
En producción
Los estudios multicuadro pueden generar tanto una animación como una página estática por cuadro. AnimationAndFrames proporciona la navegación más completa pero también tiene el mayor costo de renderizado y caché. Para estudios grandes:
- use
FramesOnlycuando la inspección de cuadros es más importante que la reproducción cinematográfica; - evite aumentar ambos ejes de resolución sin medir la memoria;
- cierre la sesión explícitamente cuando el estudio ya no esté abierto;
- mantenga
CachePageshabilitado solo cuando los beneficios de acceso repetido superen a las imágenes retenidas.
Coloque Doconut.Viewer.Dicom.lic junto a Doconut.Viewer.lic en cada servidor.
Referencia de API
DicomConfig, DicomDisplayMode y DicomMetadata están en el espacio de nombres Doconut. DicomPlugin está en Doconut.Plugins.Dicom. La tabla completa de propiedades DicomConfig se encuentra en Configuraciones de formato.
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // predeterminado: ImageResolution cuando está configurado, de lo contrario 100
public int VerticalResolution { get; set; } // predeterminado: ImageResolution cuando está configurado, de lo contrario 100
public int AnimationFrameDelayMs { get; set; } = 100;
public ushort LoopCount { get; set; } = 0; // 0 = bucle 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);Devuelve null cuando el documento no es un archivo DICOM, y siempre devuelve null en este paquete. Lanza InvalidOperationException cuando el token es desconocido o ha 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" o "Signed"
public string? PlanarConfiguration { get; init; }
public string? TransferSyntax { get; init; }
public string? Modality { get; init; } // null cuando no está expuesto
public double? WindowCenter { get; init; }
public double? WindowWidth { get; init; }
public bool IsColor { get; init; }
}Solución de problemas
| Síntoma | Causa | Solución |
|---|---|---|
AddDoconut() lanza The Dicom plugin is registered via AddPlugin but no active license grants Dicom. | Sin licencia, un archivo TRIAL, una licencia sin Dicom, o una licencia paga fuera de su ventana de versión | Instale una licencia que conceda Dicom, o elimine AddPlugin<DicomPlugin>() |
Abrir un archivo .dcm lanza Document format '.dcm' is not supported. | DicomPlugin no está registrado, o su paquete no está desplegado | Agregue AddPlugin<DicomPlugin>() dentro de AddDoconut() y despliegue el paquete |
Abrir un archivo .dcm lanza LicenseException: This document type requires the 'Dicom' plugin license. | La licencia cargada ya no concede Dicom | Instale una licencia que conceda Dicom |
| Solo aparece una página | La fuente es de un solo cuadro, o DisplayMode está AnimationOnly | Utilice FramesOnly o AnimationAndFrames para una fuente multi‑cuadro |
| La animación es demasiado rápida o lenta | AnimationFrameDelayMs está desactivado; el tiempo efectivo del GIF usa unidades de 10 ms | Ajuste AnimationFrameDelayMs |
| La memoria crece en archivos multicuadro grandes | El modo de visualización, la resolución y la caché de páginas añaden todas imágenes retenidas | Vea En producción; cierre las sesiones explícitamente |
Los metadatos son null | El documento no es un archivo DICOM | Verifique el tipo de archivo antes de solicitar los metadatos |
Los metadatos son null para un archivo DICOM, o &meta devuelve 501 | Limitación esperada de .NET 6; la renderización no se ve afectada | Utilice el paquete .NET 8 cuando necesite las etiquetas |
GetDicomMetadataAsync lanza Document session not found. Please re-open document. | El token expiró o nunca se abrió | Abra el documento nuevamente |
Notas del framework
- Sin metadatos DICOM. Se admite la renderización de páginas DICOM, cuadros individuales, animación, transformaciones y marcas de agua. Los metadatos técnicos de etiquetas no están disponibles en el paquete .NET 6 porque el lector de metadatos no tiene una compilación para .NET 6.
Viewer.GetDicomMetadataAsync(token)por lo tanto devuelvenullpara una sesión DICOM y registra una advertencia única. La solicitud correspondiente?token=…&meta=1devuelve HTTP501 Not Implementedcon el código de error establedicom_metadata_unsupported. Utilice el paquete .NET 8 cuando los metadatos técnicos DICOM sean un requisito.
¿Fue útil esta página?