תוסף DICOM

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

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

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

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

התקנת החבילה

bash
dotnet add package Doconut.NETStandard.Dicom

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

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

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

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

רישום התוסף

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 (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 הפותח פאנל של מאפיינים טכניים. אם הבקשה נכשלת, הפאנל נשאר מוסתר והמסמך עדיין מוצג. בחבילה זו התשובה לבקשה היא 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; }   // ברירת מחדל: 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;
}

מצב תצוגת DICOM

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync – קבלת מטא‑נתוני DICOM באופן אסינכרוני

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

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

מטא‑נתוני DICOM

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בדוק את סוג הקובץ לפני בקשת המטא‑נתונים
המטה‑נתונים הם null עבור קובץ DICOM, או ש&meta מחזיר 501מגבלה צפויה של חבילה זו; הרינדור אינו מושפעהשתמש בחבילה .NET 8 כאשר אתה צריך את התגים
GetDicomMetadataAsync זורק Document session not found. Please re-open document.האסימון פג תוקף או שמעולם לא נפתחפתח את המסמך שוב

הערות מסגרת

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

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