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.NETStandard.Dicomバージョン指定なしのコマンドは最新の安定版リリースをインストールします。このドキュメントで説明しているリリースにプラグインを固定するには、バージョンを別途指定してください:
dotnet add package Doconut.NETStandard.Dicom --version 26.10.0Doconut.NETStandard と同じバージョンで DICOM パッケージを保ちます。パッケージ ID は Doconut.NETStandard.Dicom です;.<version> はダウンロードされた .nupkg ファイル名にのみ現れます。
プラグインのライセンスファイル Doconut.Viewer.Dicom.lic は Doconut.Viewer.lic と同じフォルダーに配置します;ビューアのライセンスと一緒に読み込まれます。
プラグインの登録
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 ファイルは 3 つの方法で提示できます (DicomDisplayMode):
| モード | 生成ページ | 用途 |
|---|---|---|
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; } // デフォルト: 設定されている場合は 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;
}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; } // "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 ファイルではありません | メタデータを取得する前にファイルタイプを確認してください |
DICOM ファイルの場合、メタデータは null であり、または &meta が 501 を返します | このパッケージの想定される制限です;レンダリングには影響しません | タグが必要な場合は .NET 8 パッケージを使用してください |
GetDicomMetadataAsync が Document session not found. Please re-open document. をスロー | トークンが期限切れか、開かれていません | ドキュメントを再度開いてください |
フレームワークの注意点
- DICOM メタデータなし。 DICOM ページのレンダリング、個々のフレーム、アニメーション、変換、ウォーターマーキングがサポートされています。.NET Standard パッケージでは、メタデータリーダーが .NET 8 ビルドのみで提供されているため、技術的なタグメタデータは利用できません。
Viewer.GetDicomMetadataAsync(token)はそのため DICOM セッションでnullを返し、1 回限りの警告を記録します。対応する?token=…&meta=1リクエストは、安定したエラーコードdicom_metadata_unsupportedを伴う HTTP501 Not Implementedを返します。技術的な DICOM メタデータが必要な場合は .NET 8 パッケージを使用してください。 - Windows のみ、.NET Standard パッケージの他の部分と同様です。
このページは役に立ちましたか?