Atualize e aplique patches a estudos, séries e instâncias DICOM

Esta página explica como os estudos, as séries e as instâncias DICOM na Cloud Healthcare API podem ser atualizados e corrigidos no local. Para obter informações sobre como preencher lojas na Cloud Healthcare API com dados DICOM, consulte Usar a norma DICOMweb.

Atualizar instâncias DICOM

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

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

A atualização de uma instância é tratada como uma "inserção/atualização". Se a instância existir, é atualizada. Se a instância não existir, é criada e inserida na loja.

Quando insere uma nova instância, os valores SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID e SERIES_INSTANCE_UID são recolhidos dos metadados fornecidos. Os UIDs têm de cumprir os seguintes requisitos:

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

O exemplo seguinte mostra como atualizar uma instância num arquivo DICOM. Para mais informações, consulte projects.locations.datasets.dicomStores.updateInstances.

curl

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do arquivo DICOM
  • DICOM_STORE_ID: o ID da loja DICOM
  • DICOM_INSTANCE_FILE: o caminho para um ficheiro de instância DICOM no seu computador local que termina com o sufixo .dcm

O exemplo seguinte mostra um pedido PUT através de 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"

O resultado é a seguinte resposta XML:

Atualizar várias instâncias em simultâneo

O exemplo seguinte mostra como atualizar um estudo ou uma série DICOM, que consiste em várias instâncias, através de uma mensagem multipartes.

curl

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do arquivo DICOM
  • DICOM_STORE_ID: o ID da loja DICOM
  • MULTIPART_FILE: o caminho para um ficheiro multipart no seu computador local. O ficheiro contém várias instâncias DICOM, com cada uma separada por um limite.
  • BOUNDARY: o limite usado para separar as instâncias DICOM no ficheiro de várias partes

O exemplo seguinte mostra um pedido PUT através de 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"

O resultado é a seguinte resposta XML:

Aplicação de patches aos metadados DICOM

Pode adicionar, remover ou editar uma etiqueta DICOM ao nível do estudo, da série ou da instância. O comportamento de cada um dos níveis é o seguinte:

Para patches que devolvem uma operação de longa duração, quaisquer falhas na aplicação do patch a uma instância são registadas no Cloud Logging. O número de instâncias com falhas é devolvido nos metadados da operação, juntamente com um link para os registos associados.

JSON Patch

A sintaxe para a edição de etiquetas segue a norma JSON Patch. Apenas são suportadas as operações add, replace e remove. Pode especificar uma etiqueta através da respetiva palavra-chave pública (se a etiqueta for pública) ou de um identificador hexadecimal de 8 dígitos. Tenha em atenção que todos os caminhos das etiquetas têm de ter o prefixo /. Quando add ou replace uma etiqueta, tem de especificar um VR e um valor para a etiqueta, juntamente com o identificador da etiqueta. Quando remove uma etiqueta, só tem de especificar o identificador da etiqueta.

A edição de etiquetas numa sequência é suportada, bem como a substituição de sequências. Consulte as limitações de patch para saber o que não é suportado através do patch. Para especificar uma etiqueta numa sequência, separe a sequência e a etiqueta secundária com o índice do item e barras invertidas. Segue-se um exemplo que adds a etiquetaInstanceCreationDate ao 2.º artigo de ReferencedInstanceSequence (tenha em atenção que os artigos da sequência têm índice 0):

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

Para adicionar uma sequência completa (ou substituir uma sequência completa), o campo value da entrada JSON Patch tem de ser a representação JSON DICOM de uma sequência. Segue-se um exemplo de adição da sequência OtherPatientIDs com 2 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" ]
          }
        }
      ]
    }
  }
]

Aplicação de patches a uma única instância

curl

Para editar etiquetas DICOM para uma única instância, faça um pedido PATCH e especifique as seguintes informações:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do arquivo DICOM
  • DICOM_STORE_ID: o ID da loja 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 seguinte mostra um pedido PATCH através de 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 o pedido for bem-sucedido, o servidor devolve 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 patches a um estudo ou uma série

curl

Para editar etiquetas DICOM para todas as instâncias num determinado estudo, faça um pedido PATCH e especifique as seguintes informações:

  • PROJECT_ID: o ID do seu Google Cloud projeto
  • LOCATION: a localização do conjunto de dados
  • DATASET_ID: o conjunto de dados principal do arquivo DICOM
  • DICOM_STORE_ID: o ID da loja DICOM
  • STUDY_UID: o UID do estudo DICOM

O exemplo seguinte mostra um pedido PATCH através de 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 o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

A resposta contém um ID da operação. Para acompanhar o estado da operação e ver mais detalhes, use o método 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"

Se o pedido for bem-sucedido, o servidor devolve uma resposta com o estado 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

Aplicam-se as seguintes limitações e comportamento adicional quando edita etiquetas DICOM:

  • Não pode editar as seguintes etiquetas:
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • Qualquer etiqueta com um número de grupo inferior a "0008"
    • Qualquer etiqueta considerada bulkdata (consulte a definição de bulkdata)
    • Além da definição anterior, não é possível adicionar nenhuma etiqueta com um VR de OD, OF, OL, OV, SV ou UV através de patch (operações add ou replace), independentemente do comprimento
  • Não é possível editar uma sequência que contenha uma etiqueta considerada dados em massa
    • Isto significa que as operações replace ou remove numa etiqueta de sequência falham se alguma das etiquetas contidas na sequência original for considerada bulkdata
    • Além disso, quaisquer operações replace ou add numa etiqueta de sequência falham se alguma das etiquetas contidas na nova sequência for considerada bulkdata
  • Se tentar replace ou remove uma etiqueta que não existe, a API Cloud Healthcare devolve um erro e a edição falha
  • Se tentar add uma etiqueta que já existe, a operação de edição comporta-se da mesma forma que se tivesse chamado uma operação de substituição. A operação de substituição substitui o valor existente da etiqueta pelo novo valor especificado na operação
  • Embora seja possível adicionar/substituir/remover sequências (e também editar etiquetas em itens numa sequência), não é possível adicionar/substituir/remover itens individuais numa sequência.
    • Na prática, isto significa que qualquer edição com um caminho de etiqueta que termine num índice será rejeitada (por exemplo, /ReferencedSeriesSequence/0)
    • Se forem necessárias alterações a um item individual numa sequência, substitua a sequência principal completa por uma cópia com as alterações aplicadas

Atualização através do DICOM Studio

Pode usar o DICOM Studio para atualizar os metadados DICOM de um estudo, uma série ou uma instância.

Para atualizar os metadados DICOM com o DICOM Studio:

  1. Pesquise o estudo, a série ou a instância que quer atualizar.
  2. Nos resultados da pesquisa, clique no item para navegar para a respetiva página de detalhes.
  3. Clique no separador Metadados.
  4. Selecione a caixa de verificação de uma ou mais etiquetas que quer editar e, de seguida, clique em Editar.
  5. No painel de edição, expanda a etiqueta que quer modificar.
  6. Edite a palavra-chave, o VR ou o valor da etiqueta.
  7. Clique em Guardar.

Todas as limitações continuam a aplicar-se à interface do utilizador. Além disso, a interface do utilizador tem as seguintes limitações:

  1. A interface de edição de etiquetas não suporta a edição de etiquetas com uma multiplicidade de valores (VM) superior a 1.
  2. A interface de edição de etiquetas não fornece orientações nem validação sobre os tipos de VR ou valores esperados.