Atualizar e corrigir estudos, séries e instâncias de DICOM

Nesta página, explicamos como estudos, séries e instâncias DICOM na API Cloud Healthcare podem ser atualizados e corrigidos no local. Para informações sobre como preencher armazenamentos na API Cloud Healthcare com dados DICOM, consulte Usar o padrão DICOMweb.

Como atualizar instâncias DICOM

As instâncias DICOM podem ser substituídas fazendo upload de uma nova versão do arquivo .dcm. Semelhante a storeInstances, um arquivo de várias partes também pode ser usado para atualizar várias instâncias de uma só vez (geralmente para atualizar um estudo ou série com várias instâncias). Depois da atualização, a instância original será totalmente substituída.

Ao contrário de storeInstances, não é possível atualizar uma instância completa com metadados JSON. Para atualizações parciais com JSON, consulte Adicionar patch aos metadados DICOM.

A atualização de uma instância será tratada como um "upsert". Se a instância existir, ela será atualizada. Se ela não existir, será criada e inserida no armazenamento.

Ao inserir uma nova instância, os valores SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID e SERIES_INSTANCE_UID são coletados dos metadados fornecidos. Os UIDs precisam atender a estes requisitos:

  • Conter apenas valores numéricos separados por pontos.
  • Não conter informações protegidas de saúde (PHI).

O exemplo a seguir mostra como atualizar uma instância em um armazenamento DICOM. Para ver mais informações, consulte projects.locations.datasets.dicomStores.updateInstances.

curl

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto Google Cloud
  • LOCATION: o local do conjunto de dados;
  • DATASET_ID: o conjunto de dados pai do armazenamento DICOM
  • DICOM_STORE_ID: o ID do armazenamento DICOM
  • DICOM_INSTANCE_FILE: o caminho para um arquivo de instância DICOM na máquina local que termina com o sufixo .dcm

O exemplo a seguir mostra uma solicitação PUT usando 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"

A saída é a seguinte resposta XML:

Atualizar várias instâncias de uma só vez

O exemplo a seguir mostra como atualizar um estudo ou uma série DICOM, que consiste em várias instâncias, usando uma mensagem de várias partes.

curl

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto Google Cloud
  • LOCATION: o local do conjunto de dados;
  • DATASET_ID: o conjunto de dados pai do armazenamento DICOM
  • DICOM_STORE_ID: o ID do armazenamento DICOM
  • MULTIPART_FILE: o caminho para um arquivo de várias partes na sua máquina local. O arquivo contém várias instâncias DICOM, cada uma separada por um limite.
  • BOUNDARY: o limite usado para separar as instâncias DICOM no arquivo de várias partes.

O exemplo a seguir mostra uma solicitação PUT usando 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"

A saída é a seguinte resposta XML:

Como fazer patch em metadados DICOM

É possível adicionar, remover ou editar uma tag DICOM no nível de estudo, da série ou da instância. O comportamento de cada um dos níveis é o seguinte:

Para patches que retornam uma operação de longa duração, falhas ao aplicar o patch a uma instância serão registradas no Cloud Logging. O número de instâncias com falha é retornado nos metadados da operação, junto com um link para os registros associados.

JSON Patch

A sintaxe para edição de tags segue o padrão de patch JSON. Somente as operações add, replace e remove são compatíveis. É possível especificar uma tag usando a palavra-chave pública (se ela for pública) ou um identificador hexadecimal de oito dígitos. Todos os caminhos de tag precisam ter o prefixo /. Ao add ou replace uma tag, é necessário especificar uma RV e um valor para ela junto do identificador dela. Ao remove uma tag, basta especificar o identificador dela.

É possível editar tags em uma sequência e substituir sequências. Consulte as limitações de patch para saber o que não é compatível com o uso de patch. Para especificar uma tag em uma sequência, separe a sequência e a tag filha com o índice do item e barras invertidas. Este é um exemplo que add a tag InstanceCreationDate para o segundo item de ReferencedInstanceSequence. Observe que os itens de sequência são indexados em zero:

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

Para adicionar ou substituir uma sequência completa, o campo value da entrada de patch JSON precisa ser a representação JSON DICOM de uma sequência. Confira um exemplo de como adicionar a sequência OtherPatientIDs com dois elementos a uma instância:

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

Como corrigir uma única instância

curl

Para editar as tags DICOM de uma única instância, faça uma solicitação PATCH e especifique as seguintes informações:

  • PROJECT_ID: o ID do projeto Google Cloud
  • LOCATION: o local do conjunto de dados;
  • DATASET_ID: o conjunto de dados pai do armazenamento DICOM
  • DICOM_STORE_ID: o ID do armazenamento DICOM
  • STUDY_UID: o UID do estudo da instância DICOM
  • SERIES_UID: o UID da série da instância DICOM
  • INSTANCE_UID: o UID da instância DICOM

O exemplo a seguir mostra uma solicitação PATCH usando 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 a solicitação for bem-sucedida, o servidor retornará a resposta no 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
  }
}

Aplicar patch em um estudo ou série

curl

Para editar as tags DICOM de todas as instâncias de um determinado estudo, faça uma solicitação PATCH e especifique as seguintes informações:

  • PROJECT_ID: o ID do projeto Google Cloud
  • LOCATION: o local do conjunto de dados;
  • DATASET_ID: o conjunto de dados pai do armazenamento DICOM
  • DICOM_STORE_ID: o ID do armazenamento DICOM
  • STUDY_UID: o UID do estudo DICOM

O exemplo a seguir mostra uma solicitação PATCH usando 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 a solicitação for bem-sucedida, o servidor retornará a resposta no formato JSON:

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

A resposta contém um ID de operação. Para rastrear o status da operação e ver mais detalhes, use o método get de operação:

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 a solicitação for bem-sucedida, o servidor retornará uma resposta com o status da operação no 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": "..."
  }
}

Limitações

As seguintes limitações e comportamentos se aplicam ao editar tags DICOM:

  • Não é possível editar as seguintes tags:
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • Qualquer tag com um número de grupo menor que "0008"
    • Qualquer tag considerada bulkdata (consulte a definição de bulkdata)
    • Além da definição anterior, não é possível adicionar usando patch (operações add ou replace) tags com um VR de OD, OF, OL, OV, SV ou UV, independente do comprimento.
  • Não é possível editar uma sequência que contenha uma tag considerada bulkdata
    • Isso significa que as operações replace ou remove em uma tag de sequência vão falhar se alguma das tags contidas na sequência original for considerada bulkdata.
    • Além disso, qualquer operação replace ou add em uma tag de sequência vai falhar se alguma das tags contidas na nova sequência for considerada bulkdata.
  • Se você tentar replace ou remove uma tag que não existe, a API Cloud Healthcare vai retornar um erro e a edição vai falhar.
  • Se você tentar add uma tag que já existe, a operação de edição se comportará da mesma forma que se você tivesse chamado uma operação de substituição. A operação de substituição substitui o valor atual da tag pelo novo valor especificado na operação.
  • Embora seja possível adicionar/substituir/remover sequências (e editar tags em itens de uma sequência), não é possível adicionar/substituir/remover itens individuais em uma sequência.
    • Na prática, isso significa que qualquer edição com um caminho de tag que termine em um índice será rejeitada (por exemplo, /ReferencedSeriesSequence/0).
    • Se forem necessárias mudanças em um item individual de uma sequência, substitua toda a sequência principal por uma cópia com as mudanças aplicadas.