Aggiornamento e applicazione di patch a studi, serie e istanze DICOM

In questa pagina viene spiegato come aggiornare e applicare patch in loco a studi, serie e istanze DICOM nell'API Cloud Healthcare. Per informazioni su come popolare gli archivi nell'API Cloud Healthcare con dati DICOM, consulta Utilizzo dello standard DICOMweb.

Aggiornamento delle istanze DICOM

Le istanze DICOM possono essere sostituite caricando una nuova versione del file .dcm. Analogamente a storeInstances, un file multiparte può essere utilizzato anche per aggiornare più istanze contemporaneamente (spesso per aggiornare uno studio o una serie con più istanze). Dopo l'aggiornamento, l'istanza originale verrà sostituita completamente.

A differenza di storeInstances, l'aggiornamento di un'istanza completa non può essere eseguito con i metadati JSON. Per gli aggiornamenti parziali con JSON, consulta Applicazione di patch ai metadati DICOM.

L'aggiornamento di un'istanza verrà trattato come un'operazione "upsert". Se l'istanza esiste, verrà aggiornata. Se l'istanza non esiste, verrà creata e inserita nello store.

Quando inserisci una nuova istanza, i valori SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID e SERIES_INSTANCE_UID vengono raccolti dai metadati forniti. Gli UID devono soddisfare i seguenti requisiti:

  • Contengono solo valori numerici separati da punti.
  • Non contengano informazioni sanitarie protette (PHI).

Il seguente esempio mostra come aggiornare un'istanza in un archivio DICOM. Per ulteriori informazioni, vedi projects.locations.datasets.dicomStores.updateInstances.

curl

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio DICOM
  • DICOM_STORE_ID: l'ID dell'archivio DICOM
  • DICOM_INSTANCE_FILE: il percorso di un file di istanza DICOM sulla tua macchina locale che termina con il suffisso .dcm

L'esempio seguente mostra una richiesta PUT mediante 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"

L'output è la seguente risposta XML:

Aggiornamento di più istanze contemporaneamente

L'esempio riportato di seguito mostra come aggiornare uno studio o una serie DICOM, costituito da più istanze, utilizzando un messaggio in più parti.

curl

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio DICOM
  • DICOM_STORE_ID: l'ID dell'archivio DICOM
  • MULTIPART_FILE: il percorso di un file in più parti sulla macchina locale. Il file contiene più istanze DICOM, ciascuna separata da un limite.
  • BOUNDARY: il limite utilizzato per separare le istanze DICOM nel file in più parti

L'esempio seguente mostra una richiesta PUT mediante 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"

L'output è la seguente risposta XML:

Applicazione di patch ai metadati DICOM

Puoi aggiungere, rimuovere o modificare un tag DICOM a livello di studio, serie o istanza. Il comportamento per ciascun livello è il seguente:

Per le patch che restituiscono un'operazione a lunga esecuzione, eventuali errori di applicazione della patch a un'istanza verranno registrati in Cloud Logging. Il numero di istanze non riuscite viene restituito nei metadati dell'operazione, insieme a un link ai log associati.

JSON Patch

La sintassi per la modifica dei tag segue lo standard JSON Patch. Sono supportate solo le operazioni add, replace e remove. Puoi specificare un tag utilizzando la relativa parola chiave pubblica (se il tag è pubblico) o un identificatore esadecimale di 8 cifre. Tieni presente che tutti i percorsi dei tag devono avere il prefisso /. Quando add o replace un tag, devi specificare un VR e un valore per il tag insieme all'identificatore del tag. Quando remove un tag, devi specificare solo l'identificatore del tag.

La modifica dei tag all'interno di una sequenza è supportata, così come la sostituzione della sequenza. Consulta le limitazioni delle patch per scoprire cosa non è supportato utilizzando le patch. Per specificare un tag all'interno di una sequenza, separa la sequenza e il tag secondario con l'indice dell'elemento e le barre rovesciate. Ecco un esempio che addil tag InstanceCreationDate al secondo elemento di ReferencedInstanceSequence (tieni presente che gli elementi della sequenza sono indicizzati a 0):

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

Per aggiungere una sequenza completa (o sostituirla), il campo value della voce JSON Patch deve essere la rappresentazione JSON DICOM di una sequenza. Ecco un esempio di aggiunta della sequenza OtherPatientIDs con 2 elementi a un'istanza:

[
  {
    "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" ]
          }
        }
      ]
    }
  }
]

Applicazione di patch a una singola istanza

curl

Per modificare i tag DICOM per una singola istanza, effettua una richiesta PATCH e specifica le seguenti informazioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio DICOM
  • DICOM_STORE_ID: l'ID dell'archivio DICOM
  • STUDY_UID: l'UID studio dell'istanza DICOM
  • SERIES_UID: l'UID serie dell'istanza DICOM
  • INSTANCE_UID: l'UID istanza dell'istanza DICOM

L'esempio seguente mostra una richiesta PATCH mediante 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"

Se la richiesta riesce, il server restituisce la risposta in formato JSON:

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

Applicare una patch a uno studio o a una serie

curl

Per modificare i tag DICOM per tutte le istanze di un determinato studio, effettua una richiesta PATCH e specifica le seguenti informazioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio DICOM
  • DICOM_STORE_ID: l'ID dell'archivio DICOM
  • STUDY_UID: l'UID studio dello studio DICOM

L'esempio seguente mostra una richiesta PATCH mediante 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"

Se la richiesta riesce, il server restituisce la risposta in formato JSON:

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

La risposta contiene un ID operazione. Per monitorare lo stato dell'operazione e visualizzare ulteriori dettagli, utilizza il metodo get dell'operazione:

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"

Se la richiesta riesce, il server restituisce una risposta con lo stato dell'operazione in formato 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": "..."
  }
}

Limitazioni

Quando modifichi i tag DICOM, si applicano le seguenti limitazioni e il seguente comportamento aggiuntivo:

  • Non puoi modificare i seguenti tag:
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • Qualsiasi tag con un numero di gruppo inferiore a "0008"
    • Qualsiasi tag considerato bulkdata (vedi definizione di bulkdata)
    • Oltre alla definizione precedente, non è possibile aggiungere tag con un valore VR di OD, OF, OL, OV, SV o UV utilizzando patch (operazioni add o replace), indipendentemente dalla lunghezza.
  • Una sequenza che contiene un tag considerato bulkdata non può essere modificata
    • Ciò significa che le operazioni replace o remove su un tag di sequenza non andranno a buon fine se uno dei tag contenuti nella sequenza originale è considerato bulkdata
    • Inoltre, qualsiasi operazione replace o add su un tag di sequenza non andrà a buon fine se uno dei tag contenuti nella nuova sequenza è considerato bulkdata
  • Se provi a replace o remove un tag inesistente, l'API Cloud Healthcaree restituisce un errore e la modifica non va a buon fine
  • Se provi a add un tag già esistente, l'operazione di modifica si comporta allo stesso modo di un'operazione di sostituzione. L'operazione di sostituzione sostituisce il valore esistente del tag con il nuovo valore specificato nell'operazione
  • Anche se le sequenze possono essere aggiunte/sostituite/rimosse (e i tag all'interno degli elementi di una sequenza possono essere modificati), i singoli elementi di una sequenza non possono essere aggiunti/sostituiti/rimossi
    • In pratica, qualsiasi modifica con un percorso del tag che termina con un indice verrà rifiutata (ad esempio, /ReferencedSeriesSequence/0).
    • Se sono necessarie modifiche a un singolo elemento di una sequenza, sostituisci l'intera sequenza principale con una copia a cui sono state applicate le modifiche.

Aggiornamento tramite DICOM Studio

Puoi utilizzare DICOM Studio per aggiornare i metadati DICOM per uno studio, una serie o un'istanza.

Per aggiornare i metadati DICOM utilizzando DICOM Studio:

  1. Cerca lo studio, la serie o l'istanza che vuoi aggiornare.
  2. Nei risultati di ricerca, fai clic sull'elemento per passare alla pagina dei dettagli.
  3. Fai clic sulla scheda Metadati.
  4. Seleziona la casella di controllo per uno o più tag da modificare, quindi fai clic su Modifica.
  5. Nel pannello di modifica, espandi il tag che vuoi modificare.
  6. Modifica la parola chiave, il VR o il valore del tag.
  7. Fai clic su Salva.

Tutte le limitazioni continuano a essere applicate all'interfaccia utente. Inoltre, l'interfaccia utente presenta le seguenti limitazioni:

  1. L'interfaccia di modifica dei tag non supporta la modifica dei tag con una molteplicità di valori (VM) maggiore di 1.
  2. L'interfaccia di modifica dei tag non fornisce indicazioni o convalida sui tipi di VR o valori previsti.