תוסף DICOM

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

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

משטחמתי להשתמש
Viewer with DicomConfig (C#)אתה פותח קבצי DICOM בשרת ובוחר כיצד מוצגות המסגרות שלהם
הצופה (docViewer)אתה מציג את המחקר בעמוד שלך: אנימציה ומסגרות

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

התקנת החבילה

bash
dotnet add package Doconut.NET6.Dicom

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

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

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

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

פלטפורמות. התוסף פועל בכל מקום שבו Doconut.NET6 פועל: 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.GetDicomMetadataAsync(token) קיים בחבילה זו, אך הוא מחזיר null עבור מושב DICOM: ראה הערות מסגרת.

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

מצבי תצוגה

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

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

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

רזולוציה

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

csharp
// הקפצה אחידה דרך המאפיין base…
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 נמצאת ב-תצורות פורמט.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // default: ImageResolution כאשר מוגדר, אחרת 100
    public int VerticalResolution { get; set; }     // default: 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, ותמיד מחזיר null בחבילה זו. זורק 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; }   // "ללא סימן" או "חתום"
    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בדוק את סוג הקובץ לפני בקשת מטא-נתונים
מטא-נתונים הוא null עבור קובץ DICOM, או שה&meta מחזיר 501הגבלה צפויה של .NET 6; הרינדור אינו מושפעהשתמש בחבילה .NET 8 כאשר אתה צריך את התגים
GetDicomMetadataAsync זורק Document session not found. Please re-open document.האסימון פג תוקף או שמעולם לא נפתחפתח את המסמך שוב

הערות מסגרת

  • אין מטא-נתוני DICOM. רינדור דפי DICOM, מסגרות בודדות, אנימציה, טרנספורמציות והוספת סימני מים נתמכים. מטא-נתוני תגים טכניים אינם זמינים בחבילה .NET 6 מכיוון שקורא המטא-נתונים אינו כולל בנייה עבור .NET 6. Viewer.GetDicomMetadataAsync(token) ולכן מחזיר null עבור מושב DICOM ורושם אזהרה חד-פעמית. הבקשה המתאימה ?token=…&meta=1 מחזירה HTTP 501 Not Implemented עם קוד השגיאה היציב dicom_metadata_unsupported. השתמש בחבילה .NET 8 כאשר מטא-נתוני DICOM טכניים הם דרישה.

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