עדכון ותיקון של מחקרים, סדרות ומופעים של DICOM

בדף הזה מוסבר איך אפשר לעדכן ולתקן במקום מחקרים, סדרות ומופעים של DICOM ב-Cloud Healthcare API. מידע על אכלוס חנויות ב-Cloud Healthcare API בנתוני DICOM זמין במאמר שימוש בתקן DICOMweb.

עדכון מופעי DICOM

אפשר להחליף מופעי DICOM על ידי העלאת גרסה חדשה של קובץ .dcm. בדומה ל-storeInstances, אפשר להשתמש בקובץ מרובה חלקים גם כדי לעדכן כמה מקרים בבת אחת (לרוב כדי לעדכן מחקר או סדרה עם כמה מקרים). אחרי העדכון, המופע המקורי יוחלף לחלוטין.

בניגוד ל-storeInstances, אי אפשר לעדכן מופע מלא באמצעות מטא-נתונים בפורמט JSON. לעדכונים חלקיים באמצעות JSON, אפשר לעיין במאמר בנושא תיקון מטא-נתונים של DICOM.

עדכון של מופע ייחשב כ-upsert. אם המופע קיים, הוא יעודכן. אם המופע לא קיים, הוא ייווצר ויוכנס לחנות.

כשמוסיפים מופע חדש, הערכים של SOP_CLASS_UID,‏ SOP_INSTANCE_UID,‏ STUDY_INSTANCE_UID ו-SERIES_INSTANCE_UID נאספים מהמטא-נתונים שסופקו. מזהי UID צריכים לעמוד בדרישות הבאות:

  • הם יכולים להכיל רק ערכים מספריים שמופרדים בנקודות.
  • לא מכילים מידע רפואי מוגן (PHI).

בדוגמה הבאה אפשר לראות איך מעדכנים מופע בחנות DICOM. מידע נוסף זמין במאמר projects.locations.datasets.dicomStores.updateInstances.

curl

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
  • ‫LOCATION: המיקום של מערך הנתונים
  • ‫DATASET_ID: מערך הנתונים הראשי של מאגר DICOM
  • ‫DICOM_STORE_ID: מזהה מאגר DICOM
  • ‫DICOM_INSTANCE_FILE: הנתיב לקובץ מופע DICOM במחשב המקומי שמסתיים בסיומת .dcm

בדוגמה הבאה מוצגת בקשת PUT באמצעות curl.

curl -X PUT \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/dicom" \
    --data-binary @DICOM_INSTANCE_FILE \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

הפלט הוא תגובת ה-XML הבאה:

עדכון של כמה מופעים בבת אחת

בדוגמה הבאה מוצג איך לעדכן מחקר או סדרה בפורמט DICOM, שכוללים כמה מקרים, באמצעות הודעה מרובת חלקים.

curl

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
  • ‫LOCATION: המיקום של מערך הנתונים
  • ‫DATASET_ID: מערך הנתונים הראשי של מאגר DICOM
  • ‫DICOM_STORE_ID: מזהה מאגר DICOM
  • ‫MULTIPART_FILE: הנתיב לקובץ מרובה חלקים במחשב המקומי. הקובץ מכיל כמה מקרים של DICOM, וכל אחד מהם מופרד על ידי גבול.
  • ‫BOUNDARY: התוחם שמשמש להפרדה בין מופעי DICOM בקובץ מרובה חלקים

בדוגמה הבאה מוצגת בקשת PUT באמצעות curl.

curl -X PUT \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: multipart/related; type=application/dicom; boundary=BOUNDARY" \
    --data-binary @MULTIPART_FILE \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

הפלט הוא תגובת ה-XML הבאה:

תיקון מטא-נתונים של DICOM

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

אם תיקוני האבטחה מחזירים פעולה ארוכת טווח, כל ניסיון כושל להחיל את תיקון האבטחה על מופע יתועד ב-Cloud Logging. מספר המקרים שנכשלו מוחזר במטא-נתונים של הפעולה, יחד עם קישור ליומנים המשויכים.

JSON Patch

התחביר לעריכת תגים הוא תקן JSON Patch. רק הפעולות add,‏ replace ו-remove נתמכות. אפשר לציין תג באמצעות מילת המפתח הציבורית שלו (אם התג הוא ציבורי), או באמצעות מזהה הקסדצימלי בן 8 הספרות. שימו לב שכל נתיבי התגים צריכים להתחיל בקידומת /. כשמגדירים תג add או replace, צריך לציין VR וערך לתג, וגם את מזהה התג. כשremove תג, צריך לציין רק את מזהה התג.

אפשר לערוך תגים ברצף, וגם להחליף רצף. במאמר מגבלות של תיקון מפורט מה לא נתמך בשימוש בתיקון. כדי לציין תג ברצף, מפרידים בין הרצף לתג הצאצא באמצעות אינדקס הפריט ולוכסנים הפוכים. דוגמה שבה התג addInstanceCreationDate מוחל על הפריט השני במערך ReferencedInstanceSequence (שימו לב שפריטים במערך ממוספרים החל מ-0):

[
  {
    "op": "add",
    "path": "/ReferencedInstanceSequence/1/InstanceCreationDate",
    "value": {
      "vr": "DA",
      "Value": [ "20240501" ]
    }
  }
]

כדי להוסיף רצף מלא (או להחליף רצף מלא), השדה value של רשומת התיקון ב-JSON חייב להיות ייצוג JSON של רצף DICOM. דוגמה להוספת רצף OtherPatientIDs עם 2 רכיבים למופע:

[
  {
    "op": "add",
    "path": "/OtherPatientIDs",
    "value": {
      "vr": "SQ",
      "Value": [
        {
          "00100020": {
            "vr": "LO",
            "Value": [ "54321" ]
          },
          "00100021": {
            "vr": "LO",
            "Value": [ "Hospital B" ]
          }
        },
        {
          "00100020": {
            "vr": "LO",
            "Value": [ "24680" ]
          },
          "00100021": {
            "vr": "LO",
            "Value": [ "Hospital C" ]
          }
        }
      ]
    }
  }
]

תיקון של מופע יחיד

curl

כדי לערוך תגי DICOM עבור מופע יחיד, שולחים בקשת PATCH ומציינים את הפרטים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
  • ‫LOCATION: המיקום של מערך הנתונים
  • ‫DATASET_ID: מערך הנתונים הראשי של מאגר DICOM
  • ‫DICOM_STORE_ID: מזהה מאגר DICOM
  • ‫STUDY_UID: ה-UID של המחקר של מופע DICOM
  • ‫SERIES_UID: ה-UID של הסדרה של מופע DICOM
  • ‫INSTANCE_UID: ה-UID של המכונה של DICOM

בדוגמה הבאה מוצגת בקשת PATCH באמצעות curl.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '[
      {
        "op": "add",
        "path": "/ProductName",
        "value": {
          "vr": "LO",
          "Value": [
            "My Product"
          ]
        }
      },
      {
        "op": "replace",
        "path": "/PatientName",
        "value": {
          "vr": "PN",
          "Value": [
            "New Patient Name"
          ]
        }
      },
      {
        "op": "remove",
        "path": "/Manufacturer"
      }
    ]' \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID/metadata"

אם הבקשה מצליחה, השרת מחזיר את התגובה בפורמט JSON:

{
  "studyUID": "STUDY_UID",
  "seriesUID": "SERIES_UID",
  "instanceUID": "INSTANCE_UID",
  "createTimestamp": "CREATE_TIMESTAMP",
  "metadata": {
    // Full DICOM JSON metadata for the instance after edits applied
  }
}

הוספת תיקון למחקר או לסדרה

curl

כדי לערוך תגי DICOM לכל המקרים במחקר נתון, שולחים בקשת PATCH ומציינים את הפרטים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
  • ‫LOCATION: המיקום של מערך הנתונים
  • ‫DATASET_ID: מערך הנתונים הראשי של מאגר DICOM
  • ‫DICOM_STORE_ID: מזהה מאגר DICOM
  • ‫STUDY_UID: מזהה המחקר (UID) של מחקר DICOM

בדוגמה הבאה מוצגת בקשת PATCH באמצעות curl.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '[
      {
        "op": "add",
        "path": "/ProductName",
        "value": {
          "vr": "LO",
          "Value": [
            "My Product"
          ]
        }
      },
      {
        "op": "replace",
        "path": "/PatientName",
        "value": {
          "vr": "PN",
          "Value": [
            "New Patient Name"
          ]
        }
      },
      {
        "op": "remove",
        "path": "/Manufacturer"
      }
    ]' \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/metadata"

אם הבקשה מצליחה, השרת מחזיר את התגובה בפורמט JSON:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

התשובה מכילה מזהה פעולה. כדי לעקוב אחרי סטטוס הפעולה ולראות פרטים נוספים, משתמשים בשיטה Operation get:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.dicom.DicomWebService.UpdateStudyMetadata",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "CLOUD_LOGGING_URL",
    "counter": {
      "success": "1" // Number of instances updated in the study
    }
  },
  "done": true,
  "response": {
    "@type": "..."
  }
}

מגבלות

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

  • אי אפשר לערוך את התגים הבאים:
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • כל תג עם מספר קבוצה שקטן מ-0008
    • כל תג שנחשב ל-bulkdata (ראו הגדרה של bulkdata)
    • בנוסף להגדרה הקודמת, אי אפשר להוסיף תג עם VR של OD,‏ OF,‏ OL,‏ OV,‏ SV או UV באמצעות patch (פעולות add או replace), ללא קשר לאורך.
  • אי אפשר לערוך רצף שמכיל תג שנחשב bulkdata
    • המשמעות היא שפעולות replace או remove בתג רצף ייכשלו אם אחד מהתגים שכלולים ברצף המקורי נחשב ל-bulkdata
    • בנוסף, כל פעולות replace או add בתג רצף ייכשלו אם אחד מהתגים שנכללים ברצף החדש נחשב ל-bulkdata
  • אם תנסו replace או remove תג שלא קיים, Cloud Healthcare API יחזיר שגיאה והעריכה תיכשל.
  • אם מנסים add תג שכבר קיים, פעולת העריכה מתנהגת כמו פעולת החלפה. פעולת ההחלפה מחליפה את הערך הקיים של התג בערך החדש שצוין בפעולה.
  • אפשר להוסיף, להחליף או להסיר רצפים (ואפשר גם לערוך תגים בתוך פריטים ברצף), אבל אי אפשר להוסיף, להחליף או להסיר פריטים בודדים ברצף.
    • בפועל, המשמעות היא שכל עריכה עם נתיב תג שמסתיים באינדקס תידחה (לדוגמה, /ReferencedSeriesSequence/0)
    • אם צריך לבצע שינויים בפריט ספציפי ברצף, מחליפים את כל רצף האב בעותק שבו השינויים מיושמים

עדכון באמצעות DICOM Studio

אתם יכולים להשתמש ב-DICOM Studio כדי לעדכן מטא-נתונים של DICOM עבור מחקר, סדרה או מופע.

כדי לעדכן מטא-נתונים של DICOM באמצעות DICOM Studio:

  1. מחפשים את המחקר, הסדרה או המופע שרוצים לעדכן.
  2. בתוצאות החיפוש, לוחצים על הפריט כדי לעבור לדף הפרטים שלו.
  3. לוחצים על הכרטיסייה מטא-נתונים.
  4. מסמנים את התיבה לצד התגים שרוצים לערוך ולוחצים על עריכה.
  5. בחלונית העריכה, מרחיבים את התג שרוצים לשנות.
  6. עורכים את מילת המפתח, את ערך ההמרה או את הערך של התג.
  7. לוחצים על Save.

כל המגבלות עדיין חלות על ממשק המשתמש. בנוסף, יש מגבלות על ממשק המשתמש:

  1. ממשק עריכת התגים לא תומך בעריכת תגים עם ערך Value Multiplicity ‏(VM) גדול מ-1.
  2. ממשק העריכה של התגים לא מספק הנחיות או אימות לגבי סוגי הערכים או הערכים הצפויים.