Plugin DICOM

Lihat gambar medis dengan DicomPlugin

Plugin DICOM menambahkan tampilan gambar medis ke Doconut: file DICOM multi-frame dirender 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.

PermukaanGunakan ketika
Viewer with DicomConfig (C#)Anda membuka file DICOM di server dan memilih bagaimana frame mereka ditampilkan
The viewer (docViewer)Anda menampilkan studi di halaman Anda: animasi, frame, dan panel properti DICOM
HTTP endpoint (?token=<token>&meta=1)Anda membaca metadata teknis dari frontend Anda sendiri

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 itu juga memerlukan kemampuan Dicom.

Instal paket

bash
dotnet add package Doconut.NET8.Dicom

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

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

Pertahankan paket DICOM pada versi yang sama dengan Doconut.NET8. ID paketnya adalah Doconut.NET8.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.NET8 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, 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 melempar 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 lisensiSaat memulaiOutput DICOM
Lisensi berbayar yang memberikan Dicom, dalam jendela versinyaMulaiDitampilkan sesuai 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 cap sehingga tanda tetap terlihat selama pemutaran. DocOptions.Watermark khusus hanya digunakan ketika jalur lisensi mengizinkan watermark khusus; tidak dapat menggantikan watermark evaluasi.

Penggunaan dari C#

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

Untuk sesi yang dibuka melalui plugin ini, Viewer mengekspos metadata tag:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null ketika sesi bukan dokumen DICOM

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; granularity 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 untuk diketahui: jika Anda tidak mengatur HorizontalResolution/VerticalResolution secara eksplisit, mereka mengikuti BaseConfig.ImageResolution ketika itu dikonfigurasi, dan hanya kemudian kembali ke 100.

csharp
// Penambahan 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.

Di 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 ditampilkan.

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=1Membaca metadata teknis dari dokumen DICOM terbuka200 — DicomMetadata sebagai JSON, dengan nama properti dari referensi API (Width, Height, NumberOfFrames, …)
StatusKapanBadan
404Dokumen bukan file DICOMhanya status
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;
  • pertahankan CachePages 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 diatur, jika tidak 100
    public int VerticalResolution { get; set; }     // default: ImageResolution ketika diatur, jika tidak 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = loop 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. 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 terpapar
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Pemecahan Masalah

GejalaPenyebabPerbaikan
AddDoconut() melempar 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
GetDicomMetadataAsync melempar Document session not found. Please re-open document.Token kedaluwarsa atau tidak pernah dibukaBuka kembali dokumen

Apakah halaman ini membantu?