DICOM プラグイン
DicomPlugin で医療画像を表示
DICOM プラグインは Doconut に医療画像の閲覧機能を追加します:マルチフレーム DICOM ファイルはアニメーションの概要、個々のフレーム、またはその両方として表示されます。DICOM は プラグイン専用フォーマット であり、このプラグイン(およびそのライセンス機能)がなければ、.dcm ファイルはまったく開くことができません。
| 対象 | 使用する場面 |
|---|---|
Viewer と DicomConfig (C#) | サーバー上で DICOM ファイルを開き、フレームの表示方法を選択します |
ビューア (docViewer) | ページにスタディを表示します:アニメーション、フレーム、そして DICOM プロパティパネル |
HTTP エンドポイント (?token=<token>&meta=1) | 独自のフロントエンドから技術メタデータを取得します |
プラグインには独自のウィジェットはありません:DICOM ファイルは通常のビューアで開きます。コンバータプラグイン も登録されている場合、.dcm と .ima ファイルは Pdf、Png、Jpeg、Bmp、Tiff、または Gif に変換できます。その変換には Dicom 機能も必要です。
パッケージのインストール
dotnet add package Doconut.NET8.Dicomバージョン指定なしのコマンドは最新の安定版リリースをインストールします。このドキュメントで説明しているリリースにプラグインを固定するには、バージョンを別途指定してください:
dotnet add package Doconut.NET8.Dicom --version 26.10.0Doconut.NET8 と同じバージョンの DICOM パッケージを保ちます。パッケージ ID は Doconut.NET8.Dicom です;.<version> はダウンロードされた .nupkg ファイル名にのみ表示されます。
プラグインのライセンスファイル Doconut.Viewer.Dicom.lic は Doconut.Viewer.lic と同じフォルダーに配置します;ビューアのライセンスと共に読み込まれます。
プラットフォーム。プラグインは Doconut.NET8 が動作するすべての環境で実行されます: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 が欠如したライセンス、バージョンウィンドウ外で使用された有料ライセンスの場合にエラーが発生します。Temporary Demo/NFR ライセンスは受け入れられます。ライセンスのロード方法については ライセンス設定 を参照してください。
これらの形式を処理する組み込みビューアがないため、ランタイムゲートは後で機能が利用できなくなるとハードに失敗します:
LicenseException: This document type requires the 'Dicom' plugin license.ライセンスと透かし
| ライセンス状態 | 起動時 | DICOM 出力 |
|---|---|---|
バージョンウィンドウ内で Dicom を付与する有料ライセンス | 開始 | 通常のページ透かしルールに従ってレンダリングされます |
| 有効な一時(Demo/NFR)ライセンス | 開始 | 評価用透かしでレンダリングされます |
ライセンスなし、レガシー TRIAL ファイル、Dicom が欠如したライセンス、またはバージョンウィンドウ外の有料ライセンス | AddDoconut() が投げられます | — |
通常のページ透かしの判定は DICOM 出力にも適用されます。アニメーション出力の場合、各 GIF フレームに透かしがスタンプされ、再生中ずっとマークが表示されます。カスタム DocOptions.Watermark は、ライセンスパスがカスタム透かしを許可する場合にのみ使用され、評価用透かしの代替にはなりません。
C#からの使用
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});このプラグインで開かれたセッションでは、Viewer がタグメタデータを公開します:
var metadata = await viewer.GetDicomMetadataAsync(token);
// セッションが DICOM ドキュメントでない場合は null表示モード、解像度、メタデータ
表示モード
マルチフレーム DICOM ファイルは、DicomDisplayMode によって3つの方法で提示できます:
| モード | 作成されるページ | 用途 |
|---|---|---|
AnimationOnly | ページ1 = すべてのフレームをループするアニメーションGIF | 迅速なシネマティックレビュー |
FramesOnly | ページ1..N = フレームごとに1枚の静的PNG | フレーム単位の診断ナビゲーション |
AnimationAndFrames (default) | ページ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 ボタンを追加して技術プロパティパネルを開きます。そのリクエストが失敗した場合、パネルは非表示のままでドキュメントは引き続きレンダリングされます。
独自フロントエンドの構築
メタデータは、UseDoconut() がマウントされているパス(通常は /doconut)で HTTP 経由で利用可能で、任意のオープンドキュメントトークンに対して提供されます:
| ルート | 目的 | 成功レスポンス |
|---|---|---|
GET ?token=<token>&meta=1 | オープンされた DICOM ドキュメントの技術メタデータを読み取る | 200 — DicomMetadata を JSON として返し、APIリファレンス のプロパティ名(Width、Height、NumberOfFrames、…)を使用します |
| ステータス | 発生条件 | 本文 |
|---|---|---|
404 | ドキュメントが DICOM ファイルではありません | ステータスのみ |
500 | メタデータの読み取りに失敗しました | { "error": "metadata failed" } |
アニメーション付きの最初のページを含むページ画像は、標準のビューア画像ルートを使用します。
本番環境で
マルチフレームのスタディは、アニメーションとフレームごとの静的ページの両方を生成できます。AnimationAndFrames は最も豊富なナビゲーションを提供しますが、レンダリングとキャッシュのコストが最も高くなります。大規模なスタディの場合は:
- シネマティック再生よりもフレーム検査が重要な場合は
FramesOnlyを使用してください; - メモリ測定なしに解像度軸を両方増やすことは避けてください;
- スタディがもう開かれていないときは、セッションを明示的に閉じてください;
- 再アクセスの利点が保持された画像のコストを上回る場合にのみ
CachePagesを有効にしてください。
すべてのサーバーで Doconut.Viewer.Dicom.lic を Doconut.Viewer.lic の横に配置してください。
APIリファレンス
DicomConfig、DicomDisplayMode、DicomMetadata は Doconut 名前空間にあります。DicomPlugin は Doconut.Plugins.Dicom にあります。完全な DicomConfig プロパティテーブルは フォーマット設定 にあります。
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // デフォルト: 設定されている場合は ImageResolution、そうでなければ 100
public int VerticalResolution { get; set; } // デフォルト: 設定されている場合は ImageResolution、そうでなければ 100
public int AnimationFrameDelayMs { get; set; } = 100;
public ushort LoopCount { get; set; } = 0; // 0 = 無限ループ
public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}Dicom表示モード
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync メソッド
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);ドキュメントが DICOM ファイルでない場合は 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; } // "Unsigned" または "Signed"
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 ファイルではありません | メタデータを取得する前にファイルタイプを確認してください |
GetDicomMetadataAsync が Document session not found. Please re-open document. をスローします | トークンが期限切れか、開かれていません | ドキュメントを再度開いてください |
このページは役に立ちましたか?