Plugin DICOM

Afficher les images médicales avec DicomPlugin

Le plugin DICOM ajoute la visualisation d'images médicales à Doconut : les fichiers DICOM multi‑cadres sont rendus sous forme d'aperçu animé, de cadres individuels, ou les deux. DICOM est un format uniquement plugin — sans ce plugin (et sa capacité de licence), les fichiers .dcm ne peuvent pas être ouverts du tout.

SurfaceQuand l'utiliser
Viewer avec DicomConfig (C#)Vous ouvrez les fichiers DICOM sur le serveur et choisissez comment leurs cadres sont présentés
Le visualiseur (docViewer)Vous affichez l'étude sur votre page : animation et cadres

Le plugin n’a aucun widget propre : les fichiers DICOM s’ouvrent dans le visualiseur standard. Avec le plugin de conversion également enregistré, les fichiers .dcm et .ima peuvent être convertis en Pdf, Png, Jpeg, Bmp, Tiff ou Gif ; cette conversion nécessite également la capacité Dicom.

Installer le paquet

bash
dotnet add package Doconut.NET6.Dicom

La commande non versionnée installe la dernière version stable. Pour fixer le plugin à la version décrite dans cette documentation, transmettez la version séparément :

bash
dotnet add package Doconut.NET6.Dicom --version 26.10.0

Conservez le paquet DICOM à la même version que Doconut.NET6. L’identifiant du paquet est Doconut.NET6.Dicom ; .<version> apparaît uniquement dans le nom de fichier .nupkg téléchargé.

Le fichier de licence du plugin, Doconut.Viewer.Dicom.lic, se trouve dans le même dossier que Doconut.Viewer.lic ; il est lu conjointement avec la licence du visualiseur.

Plateformes. Le plugin fonctionne partout où Doconut.NET6 fonctionne : Windows et Linux basé sur glibc en x64 (pas Alpine ou autres distributions basées sur musl). Sous Linux, installez la bibliothèque de configuration des polices avant l’ouverture du premier document :

bash
apt-get update && apt-get install -y libfontconfig1

Sur RHEL, Fedora et les distributions similaires, le paquet est fontconfig. Sans cela, l’ouverture d’un document échoue avec The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Enregistrer le plugin

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Le plugin (Name : "Doconut DICOM Viewer") enregistre des visualiseurs pour les extensions .dcm et .ima, conditionnées par la capacité Dicom. Sans une licence qui le permet, AddDoconut() génère une InvalidOperationException au démarrage, avant que l’application ne traite une requête :

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.

Il se déclenche en l’absence de licence, d’un fichier legacy TRIAL, d’une licence sans Dicom, et d’une licence payante utilisée en dehors de sa fenêtre de version. Les licences temporaires Démo/NFR sont acceptées. Voir Configuration de licence pour savoir comment les licences sont chargées.

Parce qu’aucun visualiseur intégré ne gère ces formats, le verrou d’exécution échoue également de manière critique si la capacité devient indisponible ultérieurement :

text
LicenseException: This document type requires the 'Dicom' plugin license.

Licence & filigrane

État de la licenceDémarrageSortie DICOM
Licence payante accordant Dicom, dans sa fenêtre de versionDémarreRendu selon les règles normales de filigrane de la page
Licence temporaire active (Démo/NFR)DémarreRendu avec le filigrane d'évaluation
Pas de licence, un fichier legacy TRIAL, une licence sans Dicom, ou une licence payante hors de sa fenêtre de versionAddDoconut() génère—

La décision de filigrane de la page normale s’applique également à la sortie DICOM. Pour la sortie animée, chaque cadre GIF est estampillé afin que le marquage reste visible pendant toute la lecture. Un DocOptions.Watermark personnalisé n’est utilisé que lorsque le chemin de licence autorise les filigranes personnalisés ; il ne peut pas remplacer un filigrane d’évaluation.

Utilisation depuis C#

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

Viewer.GetDicomMetadataAsync(token) existe dans ce paquet, mais il renvoie null pour une session DICOM : voir Notes du framework.

Modes d'affichage, résolution et métadonnées

Modes d'affichage

Les fichiers DICOM multi‑cadres peuvent être présentés de trois manières (DicomDisplayMode) :

ModePages généréesUtilisation
AnimationOnlyPage 1 = GIF animé en boucle de toutes les imagesRevue cinématographique rapide
FramesOnlyPages 1..N = un PNG statique par imageNavigation diagnostique image par image
AnimationAndFrames (default)Page 1 = GIF animé, pages 2..N+1 = un PNG statique par image (N = nombre d'images)Vue d'ensemble + détail dans un même document

Le timing de l'animation est contrôlé par AnimationFrameDelayMs (100 ms par défaut = 10 IPS ; la granularité du GIF est de 10 ms) et LoopCount (0 = boucle infinie).

Résolution

DicomConfig rend à 100 DPI par axe par défaut. Les propriétés de résolution ont une chaîne de secours utile à connaître : si vous ne définissez pas explicitement HorizontalResolution/VerticalResolution, elles suivent BaseConfig.ImageResolution lorsqu'il est configuré, et ce n'est qu'ensuite qu'elles reviennent à 100.

csharp
// Bump uniforme via la propriété de base…
new DicomConfig { ImageResolution = 150 };

// …ou contrôle par axe
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Métadonnées

DicomMetadata ne transporte que des balises techniques et d'imagerie — nombre d'images, dimensions, profondeur de bits, interprétation photométrique, syntaxe de transfert, modalité et niveau de fenêtre par défaut. Il ne contient aucune donnée permettant d'identifier le patient. La liste complète se trouve dans la Référence API. Dans ce paquet, les métadonnées ne sont pas disponibles ; voir Notes du framework.

Dans le visualiseur

Le visualiseur ne nécessite aucune configuration spécifique à DICOM. Lorsque le document ouvert est un fichier DICOM, il demande les métadonnées (?token=<token>&meta=1) et ajoute un bouton DICOM qui ouvre un panneau de propriétés techniques. Si cette requête échoue, le panneau reste caché et le document s'affiche tout de même. Dans ce paquet, la requête renvoie 501, de sorte que le panneau n'apparaît jamais.

Créez votre propre interface

Les métadonnées sont disponibles via HTTP sous le chemin où UseDoconut() est monté (normalement /doconut), pour tout jeton de document ouvert :

CheminObjectifRéponse réussie
GET ?token=<token>&meta=1Lire les métadonnées techniques d'un document DICOM ouvert200 — DicomMetadata en JSON, avec les noms de propriétés de la Référence API (Width, Height, NumberOfFrames, …)
StatutQuandCorps
404Le document n'est pas un fichier DICOMstatut uniquement
501Le document est un fichier DICOM, mais ce paquet ne peut pas lire ses balises{ "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." }
500La lecture des métadonnées a échoué{ "error": "metadata failed" }

Les images de page, y compris la première page animée, utilisent le chemin d'image standard du visualiseur.

En production

Les études multiframe peuvent générer à la fois une animation et une page statique par image. AnimationAndFrames offre la navigation la plus riche mais aussi le coût de rendu et de cache le plus élevé. Pour les grandes études :

  • utilisez FramesOnly lorsque l'inspection des images est plus importante que la lecture cinématographique ;
  • évitez d'augmenter les deux axes de résolution sans mesurer la mémoire ;
  • fermez explicitement la session lorsque l'étude n'est plus ouverte ;
  • conservez CachePages activé uniquement lorsque les avantages d'un accès répété l'emportent sur les images conservées.

Placez Doconut.Viewer.Dicom.lic à côté de Doconut.Viewer.lic sur chaque serveur.

Référence API

DicomConfig, DicomDisplayMode et DicomMetadata sont dans l'espace de noms Doconut. DicomPlugin se trouve dans Doconut.Plugins.Dicom. Le tableau complet des propriétés DicomConfig se trouve dans Configurations de format.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // par défaut: ImageResolution lorsqu'il est défini, sinon 100
    public int VerticalResolution { get; set; }     // par défaut: ImageResolution lorsqu'il est défini, sinon 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = boucle infinie
    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);

Renvoie null lorsque le document n'est pas un fichier DICOM, et renvoie toujours null avec ce package. Lève InvalidOperationException lorsque le jeton est inconnu ou expiré.

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; }   // \"Non signé\" ou \"Signé\"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null lorsqu'il n'est pas exposé
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Dépannage

SymptômeCauseSolution
AddDoconut() lève The Dicom plugin is registered via AddPlugin but no active license grants Dicom.Pas de licence, un fichier TRIAL, une licence sans Dicom, ou une licence payante hors de sa fenêtre de versionInstallez une licence qui accorde Dicom, ou supprimez AddPlugin<DicomPlugin>()
L'ouverture d'un fichier .dcm lève Document format '.dcm' is not supported.DicomPlugin n'est pas enregistré, ou son package n'est pas déployéAjoutez AddPlugin<DicomPlugin>() à l'intérieur de AddDoconut() et déployez le package
L'ouverture d'un fichier .dcm lève LicenseException: This document type requires the 'Dicom' plugin license.La licence chargée n'accorde plus DicomInstallez une licence qui accorde Dicom
Une seule page apparaîtLa source est à image unique, ou DisplayMode est AnimationOnlyUtilisez FramesOnly ou AnimationAndFrames pour une source multi-image
L'animation est trop rapide ou trop lenteAnimationFrameDelayMs est désactivé ; le timing GIF effectif utilise des unités de 10 msAjustez AnimationFrameDelayMs
La mémoire augmente avec de gros fichiers multi-imageLe mode d'affichage, la résolution et le cache de pages ajoutent tous des images retenuesVoir En production ; fermez les sessions explicitement
Les métadonnées sont nullLe document n'est pas un fichier DICOMVérifiez le type de fichier avant de demander les métadonnées
Les métadonnées sont null pour un fichier DICOM, ou &meta renvoie 501Limitation attendue de .NET 6 ; le rendu n'est pas affectéUtilisez le package .NET 8 lorsque vous avez besoin des balises
GetDicomMetadataAsync lève Document session not found. Please re-open document.Le jeton a expiré ou n'a jamais été ouvertOuvrez à nouveau le document

Notes du framework

  • Pas de métadonnées DICOM. Le rendu des pages DICOM, les images individuelles, l'animation, les transformations et le filigrane sont pris en charge. Les métadonnées des balises techniques ne sont pas disponibles dans le package .NET 6 car le lecteur de métadonnées n'a pas de build .NET 6. Viewer.GetDicomMetadataAsync(token) renvoie donc null pour une session DICOM et consigne un avertissement unique. La requête ?token=…&meta=1 correspondante renvoie HTTP 501 Not Implemented avec le code d'erreur stable dicom_metadata_unsupported. Utilisez le package .NET 8 lorsque les métadonnées techniques DICOM sont requises.

Cette page était-elle utile ?