תוסף DICOM
הצגת תמונות רפואיות עם DicomPlugin
תוסף DICOM מוסיף צפייה בתמונות רפואיות ל‑Doconut: קבצי DICOM מרובי‑מסגרות מוצגים כתצוגה מונפשת, מסגרות בודדות, או שניהם. DICOM הוא פורמט של תוסף בלבד — ללא תוסף זה (והיכולת הרישיון שלו), קבצי .dcm אינם ניתנים לפתיחה כלל.
| ממשק | מתי להשתמש |
|---|---|
Viewer with DicomConfig (C#) | אתה פותח קבצי DICOM על השרת ובוחר כיצד מוצגות המסגרות שלהם |
הצופה (docViewer) | אתה מציג את המחקר בעמוד שלך: אנימציה ומסגרות |
התוסף אין וידג'ט משלו: קבצי DICOM נפתחים בצופה הרגיל. עם תוסף הממיר הרשום גם הוא, קבצי .dcm ו‑.ima יכולים להיות מומרי ל‑Pdf, Png, Jpeg, Bmp, Tiff או Gif; המרה זו דורשת גם את היכולת Dicom.
התקנת החבילה
dotnet add package Doconut.NETStandard.Dicomהפקודה ללא גרסה מתקינה את הגרסה היציבה האחרונה. כדי לקבע את התוסף לגרסה שהמסמך מתאר, העבר את הגרסה בנפרד:
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; הוא נקרא יחד עם רישיון הצופה.
רישום התוסף
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 (default) | דף 1 = GIF מונפש, דפים 2..N+1 = PNG סטטי אחד לכל פריים (N = מספר הפריימים) | סקירה + פירוט במסמך אחד |
זמן האנימציה נשלט על‑ידי AnimationFrameDelayMs (ברירת מחדל 100 מ״ש = 10 FPS; רזולוציית GIF היא יחידות של 10 מ״ש) ו‑LoopCount (0 = לולאה אינסופית).
רזולוציה
DicomConfig מציג ב‑100 DPI לכל ציר כברירת מחדל. למאפייני הרזולוציה יש שרשרת נפילה שכדאי לדעת: אם אינך מגדיר באופן מפורש את HorizontalResolution/VerticalResolution, הם נצמדים ל‑BaseConfig.ImageResolution כאשר הוא מוגדר, ורק אז נופלים חזרה ל‑100.
// הקפצה אחידה דרך מאפיין הבסיס…
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; } // ברירת מחדל: 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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync – קבלת מטא‑נתוני DICOM באופן אסינכרוני
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);מחזיר null כאשר המסמך אינו קובץ DICOM, ותמיד מחזיר null בחבילה זו. זורק InvalidOperationException כאשר האסימון אינו ידוע או שפג תוקפו.
מטא‑נתוני DICOM
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מחזירה HTTP501 Not Implementedעם קוד השגיאה היציבdicom_metadata_unsupported. השתמש בחבילה .NET 8 כאשר מטא‑נתוני DICOM טכניים הם דרישה. - Windows בלבד, כמו שאר חבילה .NET Standard.
האם דף זה היה מועיל?