Plugin DICOM
Afficher les images médicales avec DicomPlugin
Le plugin DICOM ajoute la visualisation d'images médicales à Doconut : les fichiers DICOM multi‑trames sont rendus sous forme d'aperçu animé, de trames individuelles, 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.
| Surface | Utilisez‑le quand |
|---|---|
Viewer with DicomConfig (C#) | Vous ouvrez des fichiers DICOM sur le serveur et choisissez comment leurs trames sont présentées |
Le visualiseur (docViewer) | Vous affichez l'étude sur votre page : animation et trames |
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
dotnet add package Doconut.NETStandard.DicomLa commande sans version installe la dernière version stable. Pour fixer le plugin à la version décrite dans cette documentation, transmettez la version séparément :
dotnet add package Doconut.NETStandard.Dicom --version 26.10.0Conservez le paquet DICOM à la même version que Doconut.NETStandard. L'ID du paquet est Doconut.NETStandard.Dicom ; .<version> n'apparaît que dans le nom de fichier téléchargé .nupkg.
Le fichier de licence du plugin, Doconut.Viewer.Dicom.lic, se place dans le même dossier que Doconut.Viewer.lic ; il est lu conjointement avec la licence du visualiseur.
Enregistrer le plugin
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, contrôlées par la capacité Dicom. Sans une licence qui la concède, AddDoconut() lance une InvalidOperationException au démarrage, avant que l'application ne traite une requête :
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, avec un fichier hérité TRIAL, une licence sans Dicom, ou 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.
Comme aucun visualiseur intégré ne gère ces formats, la porte d'exécution échoue également de manière critique si la capacité devient indisponible ultérieurement :
LicenseException: This document type requires the 'Dicom' plugin license.Licence et filigrane
| État de la licence | Démarrage | Sortie DICOM |
|---|---|---|
Licence payante accordant Dicom, dans sa fenêtre de version | Démarre | Rendu selon les règles normales de filigrane de la page |
| Licence temporaire active (Démo/NFR) | Démarre | Rendu avec le filigrane d'évaluation |
Pas de licence, un fichier hérité TRIAL, une licence sans Dicom, ou une licence payante hors de sa fenêtre de version | AddDoconut() lance | — |
La décision de filigrane de la page normale s'applique également à la sortie DICOM. Pour une sortie animée, chaque trame GIF est estampillée afin que le filigrane reste visible pendant toute la lecture. Un DocOptions.Watermark personnalisé n'est utilisé que lorsque le chemin de licence autorise des filigranes personnalisés ; il ne peut pas remplacer un filigrane d'évaluation.
Utilisation depuis C#
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 multiframe peuvent être présentés de trois manières (DicomDisplayMode) :
| Mode | Pages produites | Utilisation |
|---|---|---|
AnimationOnly | Page 1 = GIF animé en boucle de toutes les images | Revue cinématographique rapide |
FramesOnly | Pages 1..N = un PNG statique par image | Navigation diagnostique image par image |
AnimationAndFrames (par défaut) | 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 (par défaut 100 ms = 10 FPS ; 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 lorsque celui‑ci est configuré, et ce n’est qu’alors qu’elles reviennent à 100.
// Déformation 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 contient 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 les notes du cadre.
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.
Construisez 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 :
| Route | Objectif | Réponse réussie |
|---|---|---|
GET ?token=<token>&meta=1 | Lire les métadonnées techniques d'un document DICOM ouvert | 200 — DicomMetadata en JSON, avec les noms de propriétés de la référence API (Width, Height, NumberOfFrames, …) |
| Statut | Quand | Corps |
|---|---|---|
404 | Le document n'est pas un fichier DICOM | statut uniquement |
501 | Le 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." } |
500 | La lecture des métadonnées a échoué | { "error": "metadata failed" } |
Les images de page, y compris la première page animée, utilisent la route 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
FramesOnlylorsque l'inspection des images prime sur 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
CachePagesactivé 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 se trouvent dans l'espace de noms Doconut. DicomPlugin est dans Doconut.Plugins.Dicom. Le tableau complet des propriétés DicomConfig se trouve dans Configurations de format.
DicomConfig
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;
}Mode d'affichage DICOM
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
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
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 lorsqu'il n'est pas exposé
public double? WindowCenter { get; init; }
public double? WindowWidth { get; init; }
public bool IsColor { get; init; }
}Dépannage
| Symptôme | Cause | Correction |
|---|---|---|
AddDoconut() throws The Dicom plugin is registered via AddPlugin but no active license grants Dicom. | Aucune licence, un fichier TRIAL, une licence sans Dicom, ou une licence payante hors de sa fenêtre de version | Installez 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 Dicom | Installez une licence qui accorde Dicom |
| Une seule page apparaît | La source est à image unique, ou DisplayMode est AnimationOnly | Utilisez FramesOnly ou AnimationAndFrames pour une source multi‑images |
| L'animation est trop rapide ou trop lente | AnimationFrameDelayMs est désactivé ; le timing GIF effectif utilise des unités de 10 ms | Ajustez AnimationFrameDelayMs |
| La mémoire augmente avec de gros fichiers multi‑images | Le mode d'affichage, la résolution et le cache de pages ajoutent tous des images retenues | Voir En production ; fermez les sessions explicitement |
Les métadonnées sont null | Le document n'est pas un fichier DICOM | Vé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 501 | Limitation attendue de ce package ; 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é ouvert | Ouvrez à 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 techniques des balises ne sont pas disponibles dans le package .NET Standard car le lecteur de métadonnées ne fournit qu'une version .NET 8.
Viewer.GetDicomMetadataAsync(token)renvoie doncnullpour une session DICOM et consigne un avertissement unique. La requête?token=…&meta=1correspondante renvoie HTTP501 Not Implementedavec le code d'erreur stabledicom_metadata_unsupported. Utilisez le package .NET 8 lorsque les métadonnées techniques DICOM sont requises. - Windows uniquement, comme le reste du package .NET Standard.
Cette page était-elle utile ?