תוסף DICOM

הצגת תמונות רפואיות עם DicomPlugin

תוסף DICOM מוסיף צפייה בתמונות רפואיות ל‑Doconut: קבצי DICOM מרובי‑פריימים מוצגים כתצוגה מונפשת, פריימים בודדים, או שניהם. DICOM הוא פורמט רק תוסף — ללא תוסף זה (וללא יכולת הרישיון שלו), קבצים מסוג .dcm אינם ניתנים לפתיחה כלל.

ממשקמתי להשתמש
Viewer עם DicomConfig (C#)אתה פותח קבצי DICOM בשרת ובוחר כיצד מציגים את הפריימים שלהם
הצופה (docViewer)אתה מציג את המחקר בעמוד שלך: אנימציה, פריימים, ולוח תכונות DICOM
נקודת קצה HTTP (?token=<token>&meta=1)אתה קורא את המטא‑נתונים הטכניים מה‑frontend שלך

לתוסף אין וידג׳ט משלו: קבצי DICOM נפתחים בצופה הרגיל. עם תוסף תוסף הממיר שנרשם גם הוא, קבצים מסוג .dcm ו‑.ima יכולים להיות מומרי ל‑Pdf, Png, Jpeg, Bmp, Tiff או Gif; המרה זו דורשת גם את היכולת Dicom.

התקנת החבילה

bash
dotnet add package Doconut.NET8.Dicom

הפקודה ללא גרסה מתקינה את הגרסה היציבה האחרונה. כדי לקבע את התוסף לגרסה שהדוקומנטציה הזו מתארת, העבר את הגרסה בנפרד:

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

שמור על חבילת DICOM באותה גרסה כמו Doconut.NET8. מזהה החבילה הוא Doconut.NET8.Dicom; .<version> מופיע רק בשם הקובץ שהורד .nupkg.

קובץ הרישיון של התוסף, Doconut.Viewer.Dicom.lic, נמצא באותו תיקייה כמו Doconut.Viewer.lic; הוא נקרא יחד עם רישיון הצופה.

פלטפורמות. התוסף פועל בכל מקום שבו Doconut.NET8 פועל: Windows, ולינוקס מבוסס glibc על x64 (לא Alpine או הפצות אחרות מבוססות musl). בלינוקס, התקן את ספריית תצורת הפונטים לפני שהמסמך הראשון נפתח:

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

ב‑RHEL, 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.

רישום התוסף

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

התוסף (Name: "Doconut DICOM Viewer") רושם צופים עבור ההרחבות .dcm ו‑.ima, כאשר הגישה תלויה ביכולת Dicom. ללא רישיון שמעניק זאת, AddDoconut() זורק InvalidOperationException בעת ההפעלה, לפני שהאפליקציה מגישה בקשה:

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.

הוא זורק זאת כאשר אין רישיון, קובץ TRIAL מיושן, רישיון ללא Dicom, או רישיון בתשלום המשמש מחוץ לחלון הגרסה שלו. רישיונות זמניים (Demo/NFR) מתקבלים. ראה הגדרת רישיון לקבלת מידע כיצד נטענים רישיונות.

מכיוון שאין צופה מובנה שמטפל בפורמטים אלה, שער זמן הריצה גם הוא נכשל בצורה קריטית אם היכולת הופכת לחסרה מאוחר יותר:

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

רישוי & סימן מים

מצב רישיוןהפעלהפלט DICOM
רישיון בתשלום המעניק Dicom, בתוך חלון הגרסה שלומתחילמוצג תחת כללי סימן המים הרגילים של העמוד
רישיון זמני פעיל (Demo/NFR)מתחילמוצג עם סימן המים של ההערכה
אין רישיון, קובץ TRIAL מיושן, רישיון ללא Dicom, או רישיון בתשלום מחוץ לחלון הגרסה שלוAddDoconut() זורק—

החלטת סימן המים של העמוד הרגיל חלה גם על פלט DICOM. עבור פלט מונפש, כל פריים של GIF מתוייג כך שהסימן נשאר גלוי לאורך כל ההפעלה. DocOptions.Watermark מותאם אישית משמש רק כאשר נתיב הרישיון מאפשר סימני מים מותאמים; הוא אינו יכול להחליף סימן מים של הערכה.

שימוש מ‑C#

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

לסשנים שנפתחים דרך תוסף זה, Viewer חושף את מטא התגים:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null כאשר ההפעלה אינה מסמך DICOM

מצבי תצוגה, רזולוציה ונתוני מטא

מצבי תצוגה

קבצי DICOM מרובי‑פריימים יכולים להיות מוצגים בשלוש דרכים (DicomDisplayMode):

מצבדפים שנוצריםשימוש עבור
AnimationOnlyדף 1 = GIF מונפש שמחזור את כל הפריימיםסקירה קולנועית מהירה
FramesOnlyדפים 1..N = PNG סטטי אחד לכל פרייםניווט דיאגני פריים‑בפריים
AnimationAndFrames (default)דף 1 = GIF מונפש, דפים 2..N+1 = PNG סטטי אחד לכל פריים (N = מספר הפריימים)סקירה + פרטים במסמך אחד

זמן האנימציה נשלט על ידי AnimationFrameDelayMs (ברירת מחדל 100 מ״ש = 10 FPS; גרנולציה של GIF היא יחידות של 10 מ״ש) ו‑LoopCount (0 = לולאה אינסופית).

רזולוציה

DicomConfig מציג ב‑100 DPI לכל ציר כברירת מחדל. למאפייני הרזולוציה יש שרשרת נפילה שכדאי לדעת: אם לא מגדירים באופן מפורש את HorizontalResolution/VerticalResolution, הם נובעים מ‑BaseConfig.ImageResolution כאשר הוא מוגדר, ורק אז חוזרים ל‑100.

csharp
// העלאה אחידה דרך המאפיין הבסיסי…
new DicomConfig { ImageResolution = 150 };

// …או שליטה לפי‑ציר
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

נתוני מטא

DicomMetadata נושא רק תגים טכניים ותמונתיים — מספר פריימים, ממדים, עומק ביט, פרשנות פוטומטרית, תחביר העברה, מודליות ורמת החלון ברירת המחדל. הוא אינו מכיל נתוני זיהוי של מטופל. הרשימה המלאה נמצאת ב‑התייחסות API.

בצופה

הצופה אינו דורש הגדרה ספציפית ל‑DICOM. כאשר המסמך הפתוח הוא קובץ DICOM, הוא מבקש את המטא (?token=<token>&meta=1) ומוסיף כפתור DICOM הפותח פאנל של מאפיינים טכניים. אם הבקשה נכשלה, הפאנל נשאר מוסתר והמסמך עדיין מוצג.

בנה ממשק קדמי משלך

הנתונים זמינים דרך HTTP בנתיב שבו UseDoconut() מותקן (בדרך כלל /doconut), לכל אסימון של מסמך פתוח:

נתיבמטרהתגובה מוצלחת
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

csharp
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

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);

מחזיר null כאשר המסמך אינו קובץ DICOM. זורק InvalidOperationException כאשר האסימון אינו ידוע או שפג תוקפו.

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" או "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 אינו רשום, או שהחבילה שלו אינה משווקתהוסף AddPlugin<DicomPlugin>() בתוך AddDoconut() והפץ את החבילה
פתיחת קובץ .dcm זורקת LicenseException: This document type requires the 'Dicom' plugin license.הרישיון הטעון כבר לא מעניק Dicomהתקן רישיון שמעניק Dicom
מתקבלת רק דף אחדהמקור הוא מסגרת יחידה, או DisplayMode הוא AnimationOnlyהשתמש בFramesOnly או בAnimationAndFrames למקור מרובה מסגרות
האנימציה מהירה מדי או איטיתAnimationFrameDelayMs כבוי; תזמון GIF יעיל משתמש ביחידות של 10 מ״שהתאם את AnimationFrameDelayMs
הזיכרון גדל בקבצים מרובי מסגרות גדוליםמצב תצוגה, רזולוציה ומטמון דפים מוסיפים כולם תמונות שמורותראה בייצור; סגור מושבים במפורש
מטא‑נתונים הוא nullהמסמך אינו קובץ DICOMבדוק את סוג הקובץ לפני בקשת מטא‑נתונים
GetDicomMetadataAsync זורק Document session not found. Please re-open document.האסימון פג תוקף או שמעולם לא נפתחפתח את המסמך שוב

האם דף זה היה מועיל?