Plugin DICOM

Lihat gambar medis dengan DicomPlugin

Plugin DICOM menambahkan kemampuan melihat gambar medis ke Doconut: file DICOM multi-frame ditampilkan sebagai ikhtisar animasi, frame individual, atau keduanya. DICOM adalah format hanya plugin — tanpa plugin ini (dan kemampuan lisensinya), file .dcm tidak dapat dibuka sama sekali.

SurfaceUse it when
Viewer with DicomConfig (C#)You open DICOM files on the server and choose how their frames are presented
The viewer (docViewer)You show the study in your page: animation and frames

Plugin ini tidak memiliki widget sendiri: file DICOM dibuka di penampil reguler. Dengan Plugin Konverter yang juga terdaftar, file .dcm dan .ima dapat dikonversi menjadi Pdf, Png, Jpeg, Bmp, Tiff, atau Gif; konversi tersebut juga memerlukan kemampuan Dicom.

Instal paket

bash
dotnet add package Doconut.NET6.Dicom

Perintah tanpa versi menginstal rilis stabil terbaru. Untuk mengunci plugin ke rilis yang dijelaskan dalam dokumentasi ini, berikan versi secara terpisah:

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

Pertahankan paket DICOM pada versi yang sama dengan Doconut.NET6. ID paketnya adalah Doconut.NET6.Dicom; .<version> hanya muncul dalam nama file .nupkg yang diunduh.

File lisensi plugin, Doconut.Viewer.Dicom.lic, diletakkan di folder yang sama dengan Doconut.Viewer.lic; file ini dibaca bersama dengan lisensi penampil.

Platform. Plugin berjalan di mana pun Doconut.NET6 berjalan: Windows, dan Linux berbasis glibc pada x64 (bukan Alpine atau distribusi berbasis musl lainnya). Di Linux, instal pustaka konfigurasi font sebelum dokumen pertama dibuka:

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

Pada RHEL, Fedora, dan distribusi serupa paketnya adalah fontconfig. Tanpa itu, membuka dokumen gagal dengan The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Daftarkan plugin

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

Plugin (Name: "Doconut DICOM Viewer") mendaftarkan penampil untuk ekstensi .dcm dan .ima, yang dibatasi oleh kemampuan Dicom. Tanpa lisensi yang memberikannya, AddDoconut() melempar InvalidOperationException saat startup, sebelum aplikasi melayani permintaan:

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.

Ini terjadi karena tidak ada lisensi, file legacy TRIAL, lisensi tanpa Dicom, dan lisensi berbayar yang digunakan di luar jendela versinya. Lisensi Demo/NFR sementara diterima. Lihat Pengaturan Lisensi untuk cara memuat lisensi.

Karena tidak ada penampil bawaan yang menangani format ini, gerbang runtime juga gagal keras jika kemampuan tersebut kemudian tidak tersedia:

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

Lisensi & watermark

Status lisensiStartupOutput DICOM
Lisensi berbayar yang memberikan Dicom, dalam jendela versinyaMulaiDitampilkan di bawah aturan watermark halaman normal
Lisensi Sementara Aktif (Demo/NFR)MulaiDitampilkan dengan watermark evaluasi
Tidak ada lisensi, file legacy TRIAL, lisensi tanpa Dicom, atau lisensi berbayar di luar jendela versinyaAddDoconut() melempar—

Keputusan watermark halaman normal juga berlaku untuk output DICOM. Untuk output animasi, setiap frame GIF diberi stempel sehingga tanda tetap terlihat selama pemutaran. DocOptions.Watermark khusus hanya digunakan ketika jalur lisensi mengizinkan watermark khusus; ia tidak dapat menggantikan watermark evaluasi.

Penggunaan dari C#

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

Viewer.GetDicomMetadataAsync(token) ada pada paket ini, tetapi mengembalikan null untuk sesi DICOM: lihat Catatan Kerangka.

Mode tampilan, resolusi, dan metadata

Mode tampilan

File DICOM multi-frame dapat ditampilkan dalam tiga cara (DicomDisplayMode):

ModeHalaman yang dihasilkanDigunakan untuk
AnimationOnlyHalaman 1 = GIF animasi yang mengulang semua frameTinjauan sinematik cepat
FramesOnlyHalaman 1..N = satu PNG statis per frameNavigasi diagnostik frame-per-frame
AnimationAndFrames (default)Halaman 1 = GIF animasi, halaman 2..N+1 = satu PNG statis per frame (N = jumlah frame)Ikhtisar + detail dalam satu dokumen

Waktu animasi dikendalikan oleh AnimationFrameDelayMs (default 100 ms = 10 FPS; granularitas GIF adalah satuan 10 ms) dan LoopCount (0 = loop selamanya).

Resolusi

DicomConfig merender pada 100 DPI per sumbu secara default. Properti resolusi memiliki rantai fallback yang penting diketahui: jika Anda tidak mengatur HorizontalResolution/VerticalResolution secara eksplisit, mereka mengikuti BaseConfig.ImageResolution ketika itu dikonfigurasi, dan hanya kemudian kembali ke 100.

csharp
// Bump seragam melalui properti dasar…
new DicomConfig { ImageResolution = 150 };

// …atau kontrol per-sumbu
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Metadata

DicomMetadata hanya membawa tag teknis dan pencitraan — jumlah frame, dimensi, kedalaman bit, interpretasi fotometrik, sintaks transfer, modalitas, dan level jendela default. Tidak mengandung data yang dapat mengidentifikasi pasien. Daftar lengkap ada di referensi API. Pada paket ini metadata tidak tersedia; lihat Catatan Kerangka.

Di dalam penampil

Penampil tidak memerlukan pengaturan khusus DICOM. Ketika dokumen terbuka adalah file DICOM, ia meminta metadata (?token=<token>&meta=1) dan menambahkan tombol DICOM yang membuka panel properti teknis. Jika permintaan itu gagal, panel tetap tersembunyi dan dokumen tetap dirender. Pada paket ini permintaan menjawab 501, sehingga panel tidak pernah muncul.

Bangun frontend Anda sendiri

Metadata tersedia melalui HTTP di jalur tempat UseDoconut() dipasang (biasanya /doconut), untuk token dokumen terbuka apa pun:

RuteTujuanRespons sukses
GET ?token=<token>&meta=1Baca metadata teknis dari dokumen DICOM terbuka200 — DicomMetadata sebagai JSON, dengan nama properti dari referensi API (Width, Height, NumberOfFrames, …)
StatusKapanIsi
404Dokumen bukan file DICOMhanya status
501Dokumen adalah file DICOM, tetapi paket ini tidak dapat membaca tag-nya{ "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." }
500Membaca metadata gagal{ "error": "metadata failed" }

Gambar halaman, termasuk halaman pertama yang animasi, menggunakan rute gambar penampil standar.

Dalam produksi

Studi multiframe dapat menghasilkan baik animasi maupun satu halaman statis per frame. AnimationAndFrames menyediakan navigasi paling kaya tetapi juga memiliki biaya rendering dan cache tertinggi. Untuk studi besar:

  • gunakan FramesOnly ketika inspeksi frame lebih penting daripada pemutaran sinematik;
  • hindari meningkatkan kedua sumbu resolusi tanpa mengukur memori;
  • tutup sesi secara eksplisit ketika studi tidak lagi terbuka;
  • biarkan CachePages tetap aktif hanya ketika manfaat akses berulang melebihi gambar yang disimpan.

Letakkan Doconut.Viewer.Dicom.lic di sebelah Doconut.Viewer.lic pada setiap server.

Referensi API

DicomConfig, DicomDisplayMode dan DicomMetadata berada di namespace Doconut. DicomPlugin berada di Doconut.Plugins.Dicom. Tabel properti DicomConfig lengkap berada di Konfigurasi Format.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // default: ImageResolution ketika disetel, jika tidak 100
    public int VerticalResolution { get; set; }     // default: ImageResolution ketika disetel, jika tidak 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = ulangi selamanya
    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);

Mengembalikan null ketika dokumen bukan file DICOM, dan selalu mengembalikan null pada paket ini. Melempar InvalidOperationException ketika token tidak dikenal atau kedaluwarsa.

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; }   // "Unsigned" atau "Signed"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null ketika tidak diekspos
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Pemecahan Masalah

GejalaPenyebabPerbaikan
AddDoconut() throws The Dicom plugin is registered via AddPlugin but no active license grants Dicom.Tidak ada lisensi, file TRIAL, lisensi tanpa Dicom, atau lisensi berbayar di luar jendela versinyaPasang lisensi yang memberikan Dicom, atau hapus AddPlugin<DicomPlugin>()
Membuka file .dcm melempar Document format '.dcm' is not supported.DicomPlugin tidak terdaftar, atau paketnya tidak dideployTambahkan AddPlugin<DicomPlugin>() di dalam AddDoconut() dan deploy paketnya
Membuka file .dcm melempar LicenseException: This document type requires the 'Dicom' plugin license.Lisensi yang dimuat tidak lagi memberikan DicomPasang lisensi yang memberikan Dicom
Hanya satu halaman yang munculSumbernya single-frame, atau DisplayMode adalah AnimationOnlyGunakan FramesOnly atau AnimationAndFrames untuk sumber multi-frame
Animasi terlalu cepat atau lambatAnimationFrameDelayMs dimatikan; timing GIF efektif menggunakan satuan 10 msSesuaikan AnimationFrameDelayMs
Memori bertambah pada file multiframe besarMode tampilan, resolusi, dan cache halaman semuanya menambah gambar yang dipertahankanLihat Dalam produksi; tutup sesi secara eksplisit
Metadata adalah nullDokumen bukan file DICOMPeriksa tipe file sebelum meminta metadata
Metadata adalah null untuk file DICOM, atau &meta mengembalikan 501Batasan .NET 6 yang diharapkan; rendering tidak terpengaruhGunakan paket .NET 8 ketika Anda membutuhkan tag
GetDicomMetadataAsync melempar Document session not found. Please re-open document.Token kedaluwarsa atau tidak pernah dibukaBuka kembali dokumen

Catatan Kerangka

  • Tidak ada metadata DICOM. Rendering halaman DICOM, frame individual, animasi, transformasi, dan watermark didukung. Metadata tag teknis tidak tersedia dalam paket .NET 6 karena pembaca metadata tidak memiliki build .NET 6. Viewer.GetDicomMetadataAsync(token) oleh karena itu mengembalikan null untuk sesi DICOM dan mencatat peringatan satu kali. Permintaan ?token=…&meta=1 yang bersangkutan mengembalikan HTTP 501 Not Implemented dengan kode error stabil dicom_metadata_unsupported. Gunakan paket .NET 8 ketika metadata DICOM teknis menjadi kebutuhan.

Apakah halaman ini membantu?