תוסף DICOM
צפייה בתמונות רפואיות עם DicomPlugin
תוסף DICOM מוסיף צפייה בתמונות רפואיות ל‑Doconut: קבצי DICOM מרובי‑מסגרות מוצגים כתצוגה מונפשת, מסגרות בודדות, או שניהם. DICOM הוא פורמט רק‑תוסף — ללא תוסף זה (וללא יכולת הרישיון שלו), קבצים .dcm אינם ניתנים לפתיחה כלל.
| משטח | מתי להשתמש |
|---|---|
Viewer with DicomConfig (C#) | אתה פותח קבצי DICOM בשרת ובוחר כיצד מוצגות המסגרות שלהם |
הצופה (docViewer) | אתה מציג את המחקר בעמוד שלך: אנימציה ומסגרות |
התוסף אין לו וידג'ט משלו: קבצי DICOM נפתחים בצופה הרגיל. עם תוסף תוסף Converter הרשום גם הוא, קבצים .dcm ו‑.ima יכולים להיות מומרצים ל‑Pdf, Png, Jpeg, Bmp, Tiff או Gif; המרה זו דורשת גם את היכולת Dicom.
התקנת החבילה
dotnet add package Doconut.NET6.Dicomהפקודה ללא גרסה מתקינה את הגרסה היציבה האחרונה. כדי לעגן את התוסף לגרסה שהמסמך הזה מתאר, העבר את הגרסה בנפרד:
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). בלינוקס, התקן את ספריית תצורת הגופנים לפני שהמסמך הראשון נפתח:
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.
רישום התוסף
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});התוסף (Name: "Doconut DICOM Viewer") רושם צופים עבור ההרחבות .dcm ו‑.ima, כאשר הגישה נשלטת על ידי היכולת Dicom. ללא רישיון שמעניק זאת, AddDoconut() זורק InvalidOperationException בעת ההפעלה, לפני שהאפליקציה מגישה בקשה:
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) מתקבלים. ראה הגדרת רישיון כדי להבין איך רישיונות נטענים.
מאחר שאין צופה מובנה שמטפל בפורמטים אלו, שער זמן הריצה גם נכשל באופן חמור אם היכולת הופכת לחסרה מאוחר יותר:
LicenseException: This document type requires the 'Dicom' plugin license.רישוי & סימן מים
| מצב רישיון | הפעלה | פלט DICOM |
|---|---|---|
רישיון בתשלום המעניק Dicom, בתוך חלון הגרסה שלו | מתחיל | מוצג תחת כללי סימן המים הרגילים של העמוד |
| רישיון זמני פעיל (Demo/NFR) | מתחיל | מוצג עם סימן המים של ההערכה |
אין רישיון, קובץ TRIAL ישן, רישיון ללא Dicom, או רישיון בתשלום מחוץ לחלון הגרסה שלו | AddDoconut() זורק | — |
החלטת סימן המים הרגילה של העמוד חלה גם על פלט DICOM. עבור פלט מונפש, כל מסגרת GIF מתויגת כך שהסימן נשאר גלוי לאורך כל ההפעלה. DocOptions.Watermark מותאם אישית משמש רק כאשר נתיב הרישיון מאפשר סימני מים מותאמים; הוא אינו יכול להחליף סימן מים של הערכה.
שימוש ב‑C#
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.
// הקפצה אחידה דרך המאפיין 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
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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);מחזיר null כאשר המסמך אינו קובץ DICOM, ותמיד מחזיר null בחבילה זו. זורק InvalidOperationException כאשר האסימון אינו ידוע או שפג תוקפו.
DicomMetadata
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מחזירה HTTP501 Not Implementedעם קוד השגיאה היציבdicom_metadata_unsupported. השתמש בחבילה .NET 8 כאשר מטא-נתוני DICOM טכניים הם דרישה.
האם דף זה היה מועיל?