Mettre à jour et corriger des études, séries et instances DICOM

Cette page explique comment mettre à jour et corriger sur place les études, séries et instances DICOM dans l'API Cloud Healthcare. Pour savoir comment remplir les magasins de l'API Cloud Healthcare avec des données DICOM, consultez Utiliser la norme DICOMweb.

Mettre à jour des instances DICOM

Vous pouvez remplacer des instances DICOM en important une nouvelle version du fichier .dcm. Comme pour storeInstances, un fichier multipart peut également être utilisé pour mettre à jour plusieurs instances à la fois (souvent pour mettre à jour une étude ou une série avec plusieurs instances). Une fois la mise à jour effectuée, l'instance d'origine sera entièrement remplacée.

Contrairement à storeInstances, la mise à jour d'une instance complète ne peut pas être effectuée avec des métadonnées JSON. Pour les mises à jour partielles avec JSON, consultez Appliquer un correctif aux métadonnées DICOM.

La mise à jour d'une instance sera traitée comme une opération "upsert". Si l'instance existe, elle est mise à jour. Si l'instance n'existe pas, elle est créée et insérée dans le magasin.

Lorsque vous insérez une instance, les valeurs SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID et SERIES_INSTANCE_UID sont collectées à partir des métadonnées fournies. Les UID doivent répondre aux exigences suivantes :

  • ne contenir que des valeurs numériques séparées par des points ;
  • ne contiennent pas de données de santé protégées (PHI) ;

L'exemple suivant montre comment mettre à jour une instance dans un magasin DICOM. Pour en savoir plus, consultez projects.locations.datasets.dicomStores.updateInstances.

curl

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin DICOM
  • DICOM_STORE_ID : ID du magasin DICOM
  • DICOM_INSTANCE_FILE : chemin d'accès à un fichier d'instance DICOM sur votre ordinateur local, se terminant par le suffixe .dcm

L'exemple suivant montre une requête PUT utilisant 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"

Le résultat est la réponse XML suivante :

Mettre à jour plusieurs instances à la fois

L'exemple suivant montre comment mettre à jour une étude ou une série DICOM, composée de plusieurs instances, à l'aide d'un message multipartite.

curl

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin DICOM
  • DICOM_STORE_ID : ID du magasin DICOM
  • MULTIPART_FILE : chemin d'accès à un fichier multipartie sur votre ordinateur local. Le fichier contient plusieurs instances DICOM, chacune étant séparée par une limite.
  • BOUNDARY : limite utilisée pour séparer les instances DICOM dans le fichier multipart

L'exemple suivant montre une requête PUT utilisant 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"

Le résultat est la réponse XML suivante :

Appliquer un correctif aux métadonnées DICOM

Vous pouvez ajouter, supprimer ou modifier un tag DICOM au niveau de l'étude, de la série ou de l'instance. Le comportement de chacun des niveaux est le suivant :

Pour les correctifs qui renvoient une opération de longue durée, tout échec d'application du correctif à une instance sera consigné dans Cloud Logging. Le nombre d'instances ayant échoué est renvoyé dans les métadonnées de l'opération, ainsi qu'un lien vers les journaux associés.

JSON Patch

La syntaxe de modification des tags suit la norme de correctif JSON. Seules les opérations add, replace et remove sont acceptées. Vous pouvez spécifier un tag à l'aide de son mot clé public (si le tag est public) ou par un identifiant hexadécimal à huit chiffres. Notez que tous les chemins de tag doivent être précédés du préfixe /. Lorsque vous add ou replace un tag, vous devez spécifier une VR et une valeur pour le tag, ainsi que l'identifiant du tag. Lorsque vous remove un tag, il vous suffit de spécifier l'identifiant du tag.

Vous pouvez modifier les tags d'une séquence et remplacer une séquence. Pour savoir ce qui n'est pas compatible avec la méthode PATCH, consultez les limites de la méthode PATCH. Pour spécifier un tag dans une séquence, séparez la séquence et le tag enfant avec l'index de l'élément et des barres obliques inverses. Voici un exemple qui add la balise InstanceCreationDate au deuxième élément de ReferencedInstanceSequence (notez que les éléments de séquence sont indexés à partir de 0) :

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

Pour ajouter une séquence complète (ou remplacer une séquence complète), le champ value de l'entrée JSON Patch doit être la représentation JSON DICOM d'une séquence. Voici un exemple d'ajout de la séquence OtherPatientIDs avec deux éléments à une instance :

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

Appliquer un correctif à une seule instance

curl

Pour modifier les tags DICOM d'une seule instance, envoyez une requête PATCH et spécifiez les informations suivantes :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin DICOM
  • DICOM_STORE_ID : ID du magasin DICOM
  • STUDY_UID : UID de l'étude de l'instance DICOM
  • SERIES_UID : UID de la série de l'instance DICOM
  • INSTANCE_UID : UID de l'instance DICOM

L'exemple suivant montre une requête PATCH utilisant 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"

Si la requête aboutit, le serveur renvoie la réponse au format JSON :

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

Corriger une étude ou une série

curl

Pour modifier les tags DICOM de toutes les instances d'une étude donnée, envoyez une requête PATCH et spécifiez les informations suivantes :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin DICOM
  • DICOM_STORE_ID : ID du magasin DICOM
  • STUDY_UID : UID de l'étude DICOM

L'exemple suivant montre une requête PATCH utilisant 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"

Si la requête aboutit, le serveur renvoie la réponse au format JSON :

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

La réponse contient un ID d'opération. Pour suivre l'état de l'opération et afficher plus de détails, utilisez la méthode 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"

Si la requête aboutit, le serveur renvoie une réponse avec l'état de l'opération au format 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": "..."
  }
}

Limites

Les restrictions et comportements supplémentaires suivants s'appliquent lors de la modification de tags DICOM :

  • Vous ne pouvez pas modifier les tags suivants :
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • Tout tag dont le numéro de groupe est inférieur à "0008"
    • Tout tag considéré comme bulkdata (voir la définition de bulkdata)
    • En plus de la définition précédente, toute balise dont la VR est OD, OF, OL, OV, SV ou UV ne peut pas être ajoutée à l'aide de patch (opérations add ou replace), quelle que soit sa longueur.
  • Une séquence contenant un tag considéré comme des données groupées ne peut pas être modifiée.
    • Cela signifie que les opérations replace ou remove sur un tag de séquence échoueront si l'un des tags contenus dans la séquence d'origine est considéré comme bulkdata.
    • De plus, toute opération replace ou add sur un tag de séquence échouera si l'un des tags contenus dans la nouvelle séquence est considéré comme bulkdata.
  • Si vous essayez d'replace ou de remove un tag qui n'existe pas, l'API Cloud Healthcare renvoie une erreur et la modification échoue.
  • Si vous essayez d'add un tag qui existe déjà, l'opération de modification se comporte de la même manière que si vous aviez appelé une opération de remplacement. L'opération de remplacement remplace la valeur existante du tag par la nouvelle valeur spécifiée dans l'opération.
  • Vous pouvez ajouter, remplacer ou supprimer des séquences (et modifier les tags des éléments d'une séquence), mais vous ne pouvez pas ajouter, remplacer ni supprimer des éléments individuels d'une séquence.
    • En pratique, cela signifie que toute modification dont le chemin de tag se termine par un index sera refusée (par exemple, /ReferencedSeriesSequence/0).
    • Si vous devez modifier un élément individuel d'une séquence, remplacez l'intégralité de la séquence parente par une copie à laquelle les modifications ont été appliquées.

Mettre à jour à l'aide de DICOM Studio

Vous pouvez utiliser DICOM Studio pour mettre à jour les métadonnées DICOM d'une étude, d'une série ou d'une instance.

Pour mettre à jour les métadonnées DICOM à l'aide de DICOM Studio :

  1. Recherchez l'étude, la série ou l'instance que vous souhaitez modifier.
  2. Dans les résultats de recherche, cliquez sur l'élément pour accéder à sa page d'informations.
  3. Cliquez sur l'onglet Métadonnées.
  4. Cochez la case correspondant à un ou plusieurs tags à modifier, puis cliquez sur Modifier.
  5. Dans le panneau "Modifier", développez la balise que vous souhaitez modifier.
  6. Modifiez le mot clé, la VR ou la valeur du tag.
  7. Cliquez sur Enregistrer.

Toutes les limitations s'appliquent toujours à l'interface utilisateur. De plus, l'interface utilisateur présente les limites suivantes :

  1. L'interface de modification des tags ne permet pas de modifier les tags dont la multiplicité de valeur (VM) est supérieure à 1.
  2. L'interface de modification des tags ne fournit aucune indication ni validation sur les types de VR ou de valeurs attendus.