DICOM プラグイン
DicomPluginで医療画像を表示
DICOM プラグインは Doconut に医療画像の閲覧機能を追加します:マルチフレーム DICOM ファイルはアニメーションの概要、個別フレーム、またはその両方として表示されます。DICOM は プラグイン専用フォーマット であり、このプラグイン(およびそのライセンス機能)がなければ、.dcm ファイルは全く開くことができません。
| 対象 | 使用シーン |
|---|---|
Viewer with DicomConfig (C#) | サーバー上で DICOM ファイルを開き、フレームの表示方法を選択します |
ビューア (docViewer) | ページにスタディを表示します:アニメーションとフレーム |
プラグイン自体にはウィジェットがありません:DICOM ファイルは通常のビューアで開きます。コンバータプラグイン も登録されていれば、.dcm と .ima ファイルを Pdf、Png、Jpeg、Bmp、Tiff、または Gif に変換できます。その変換には Dicom 機能も必要です。
パッケージのインストール
dotnet add package Doconut.NET6.Dicomバージョン指定のないコマンドは最新の安定版リリースをインストールします。このドキュメントで説明しているリリースにプラグインを固定するには、バージョンを別途指定してください:
dotnet add package Doconut.NET6.Dicom --version 26.10.0Doconut.NET6 と同じバージョンの DICOM パッケージを保ちます。パッケージ ID は Doconut.NET6.Dicom です。.<version> はダウンロードされた .nupkg ファイル名にのみ現れます。
プラグインのライセンスファイル Doconut.Viewer.Dicom.lic は Doconut.Viewer.lic と同じフォルダーに配置します。ビューアのライセンスと共に読み込まれます。
プラットフォーム。 プラグインは Doconut.NET6 が動作するすべての環境で動作します:Windows と x64 の glibc ベース Linux(Alpine や他の musl ベースディストリビューションは除く)。Linux では、最初のドキュメントを開く前にフォント設定ライブラリをインストールしてください:
apt-get update && apt-get install -y libfontconfig1RHEL、Fedora などの類似ディストリビューションではパッケージは fontconfig です。これがないと、ドキュメントを開く際に The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. が発生して失敗します。
プラグインの登録
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});プラグイン(Name: "Doconut DICOM Viewer")は .dcm と .ima 拡張子用のビューアを登録し、Dicom 機能でゲートします。これを許可するライセンスがない場合、AddDoconut() は起動時に InvalidOperationException をスローし、アプリがリクエストを処理する前にエラーになります:
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.ライセンスがない場合、レガシー TRIAL ファイル、Dicom が欠如したライセンス、バージョンウィンドウ外で使用された有料ライセンスの場合にスローされます。一時的なデモ/NFR ライセンスも受け付けられます。ライセンスのロード方法については、ライセンス設定 を参照してください。
組み込みビューアがこれらの形式を処理できないため、ランタイムゲートは後で機能が利用できなくなるとハードに失敗します:
LicenseException: This document type requires the 'Dicom' plugin license.ライセンスと透かし
| ライセンス状態 | 起動時 | DICOM 出力 |
|---|---|---|
バージョンウィンドウ内で Dicom を付与する有料ライセンス | 開始 | 通常のページ透かしルールに従ってレンダリング |
| 有効な一時(デモ/NFR)ライセンス | 開始 | 評価用透かしでレンダリング |
ライセンスなし、レガシー TRIAL ファイル、Dicom が欠如したライセンス、またはバージョンウィンドウ外の有料ライセンス | AddDoconut() がスロー | — |
通常のページ透かしの判定は DICOM 出力にも適用されます。アニメーション出力の場合、各 GIF フレームに透かしが付与され、再生中ずっとマークが表示されます。カスタム DocOptions.Watermark は、ライセンスパスがカスタム透かしを許可している場合にのみ使用され、評価用透かしの代わりにはなりません。
C#からの使用
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Viewer.GetDicomMetadataAsync(token) はこのパッケージに存在しますが、DICOM セッションでは null を返します: フレームワークの注記 を参照してください。
表示モード、解像度、メタデータ
表示モード
マルチフレーム DICOM ファイルは、DicomDisplayMode によって 3 つの方法で表示できます:
| モード | 生成されるページ | 用途 |
|---|---|---|
AnimationOnly | ページ 1 = すべてのフレームをループするアニメーション GIF | クイックシネマティックレビュー |
FramesOnly | ページ 1..N = フレームごとに 1 つの静的 PNG | フレーム単位の診断ナビゲーション |
AnimationAndFrames (デフォルト) | ページ 1 = アニメーション GIF、ページ 2..N+1 = フレームごとに 1 つの静的 PNG (N = フレーム数) | 1 つのドキュメントで概要と詳細 |
アニメーションのタイミングは AnimationFrameDelayMs で制御されます(デフォルト 100 ms = 10 FPS; GIF の粒度は 10 ms 単位)および LoopCount(0 = 無限ループ)。
解像度
DicomConfig はデフォルトで軸ごとに 100 DPI でレンダリングします。解像度プロパティには知っておく価値のあるフォールバックチェーンがあります: HorizontalResolution/VerticalResolution を明示的に設定しない場合、設定されている場合は BaseConfig.ImageResolution に従い、そして最後に 100 にフォールバックします。
// ベースプロパティによる均一バンプ…
new DicomConfig { ImageResolution = 150 };
// …または軸ごとの制御
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };メタデータ
DicomMetadata は技術的および画像タグのみを保持します — フレーム数、寸法、ビット深度、フォトメトリック解釈、転送構文、モダリティ、デフォルトウィンドウレベル。患者を特定できるデータは含まれていません。完全なリストは APIリファレンス にあります。このパッケージではメタデータは利用できません; フレームワークの注記 を参照してください。
ビューアでの表示
ビューアは DICOM 固有の設定を必要としません。開いているドキュメントが DICOM ファイルの場合、メタデータ(?token=<token>&meta=1)を要求し、DICOM ボタンを追加して技術プロパティパネルを開きます。その要求が失敗した場合、パネルは非表示のままでドキュメントは引き続きレンダリングされます。このパッケージでは要求は 501 を返すため、パネルは決して表示されません。
独自のフロントエンドを構築する
メタデータは HTTP 経由で、UseDoconut() がマウントされているパス(通常は /doconut)で、任意の開いているドキュメントトークンに対して利用可能です:
| ルート | 目的 | 成功レスポンス |
|---|---|---|
GET ?token=<token>&meta=1 | 開いている DICOM ドキュメントの技術メタデータを読み取る | 200 — DicomMetadata を JSON 形式で、APIリファレンス のプロパティ名(Width、Height、NumberOfFrames、…)と共に |
| ステータス | 条件 | 本文 |
|---|---|---|
404 | ドキュメントが DICOM ファイルではない | ステータスのみ |
501 | ドキュメントが DICOM ファイルだが、このパッケージはタグを読み取れない | { "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 | メタデータの読み取りに失敗した | { "error": "metadata failed" } |
ページ画像(アニメーションされた最初のページを含む)は、標準のビューア画像ルートを使用します。
本番環境で
マルチフレームのスタディは、アニメーションとフレームごとの静的ページの両方を生成できます。AnimationAndFrames は最もリッチなナビゲーションを提供しますが、レンダリングとキャッシュのコストが最も高くなります。大規模なスタディの場合:
- フレーム検査がシネマティック再生より重要な場合は
FramesOnlyを使用してください; - メモリを測定せずに解像度軸の両方を増やすことは避けてください;
- スタディがもう開かれていないときは、セッションを明示的に閉じてください;
- 再アクセスの利点が保持された画像のコストを上回る場合にのみ、
CachePagesを有効にしてください。
すべてのサーバーで Doconut.Viewer.Dicom.lic を Doconut.Viewer.lic の隣に配置してください。
API リファレンス
DicomConfig、DicomDisplayMode、DicomMetadataはDoconut名前空間にあります。DicomPluginはDoconut.Plugins.Dicomにあります。完全なDicomConfigプロパティテーブルはFormat Configsにあります。
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // default: ImageResolution が設定されている場合、そうでなければ 100
public int VerticalResolution { get; set; } // default: ImageResolution が設定されている場合、そうでなければ 100
public int AnimationFrameDelayMs { get; set; } = 100;
public ushort LoopCount { get; set; } = 0; // 0 = 無限ループ
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);ドキュメントが DICOM ファイルでない場合は null を返し、このパッケージでは常に null を返します。トークンが不明または期限切れの場合は InvalidOperationException をスローします。
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; } // "符号なし" または "符号付き"
public string? PlanarConfiguration { get; init; }
public string? TransferSyntax { get; init; }
public string? Modality { get; init; } // null は公開されていない場合
public double? WindowCenter { get; init; }
public double? WindowWidth { get; init; }
public bool IsColor { get; init; }
}トラブルシューティング
| 症状 | 原因 | 対策 |
|---|---|---|
AddDoconut() が The Dicom plugin is registered via AddPlugin but no active license grants Dicom. をスローする | ライセンスがない、TRIAL ファイル、Dicom がないライセンス、またはバージョンウィンドウ外の有料ライセンス | Dicom を付与するライセンスをインストールするか、AddPlugin<DicomPlugin>() を削除してください |
.dcm ファイルを開くと Document format '.dcm' is not supported. がスローされる | DicomPlugin が登録されていない、またはパッケージがデプロイされていない | AddDoconut() 内に AddPlugin<DicomPlugin>() を追加し、パッケージをデプロイしてください |
.dcm ファイルを開くと LicenseException: This document type requires the 'Dicom' plugin license. がスローされる | ロードされたライセンスはもはや Dicom を付与しません | Dicom を付与するライセンスをインストールしてください |
| 1 ページしか表示されない | ソースが単一フレームであるか、DisplayMode が AnimationOnly です | マルチフレームソースの場合は FramesOnly または AnimationAndFrames を使用してください |
| アニメーションが速すぎるまたは遅すぎる | AnimationFrameDelayMs がオフになっています;実際の GIF タイミングは 10 ms 単位です | AnimationFrameDelayMs を調整してください |
| 大きなマルチフレームファイルでメモリが増加する | 表示モード、解像度、ページキャッシュがすべて保持画像を追加します | 本番環境での対処 を参照してください;セッションを明示的に閉じてください |
メタデータが null | ドキュメントが DICOM ファイルではありません | メタデータを取得する前にファイルタイプを確認してください |
DICOM ファイルのメタデータが null、または &meta が 501 を返す | .NET 6 の既知の制限です;レンダリングには影響しません | タグが必要な場合は .NET 8 パッケージを使用してください |
GetDicomMetadataAsync が Document session not found. Please re-open document. をスローする | トークンが期限切れか、開かれていません | ドキュメントを再度開いてください |
フレームワークの注意点
- DICOM メタデータなし。 DICOM ページのレンダリング、個別フレーム、アニメーション、変換、ウォーターマーキングがサポートされています。技術タグメタデータは、メタデータリーダーに .NET 6 ビルドがないため、.NET 6 パッケージでは利用できません。
Viewer.GetDicomMetadataAsync(token)はそのため DICOM セッションでnullを返し、1 回限りの警告を記録します。対応する?token=…&meta=1リクエストは、安定したエラーコードdicom_metadata_unsupportedを伴う HTTP501 Not Implementedを返します。技術的な DICOM メタデータが必要な場合は .NET 8 パッケージを使用してください。
このページは役に立ちましたか?