Como usar a API Cloud Healthcare para patologia digital

Nesta página, explicamos como armazenar, analisar e gerenciar imagens de lâminas inteiras (WSIs, na sigla em inglês) usando a API Cloud Healthcare.

Informações gerais

A patologia digital permite armazenar, processar e gerenciar lâminas de vidro convencionais, digitalizando-as para produzir imagens de lâminas inteiras (WSIs).

As WSIs normalmente são arquivos grandes que podem ter muitos GB. Esses arquivos têm vários formatos, o que pode dificultar o gerenciamento. A API Cloud Healthcare simplifica o processo de armazenamento, análise e gerenciamento de WSIs.

Como armazenar imagens de lâminas inteiras usando o DICOM

A API Cloud Healthcare fornece um serviço gerenciado para armazenar imagens DICOM. Esse serviço também permite o armazenamento e a recuperação de WSIs. Para mais informações sobre o DICOM na API Cloud Healthcare, consulte DICOM.

O uso do DICOM tem os seguintes benefícios:

• Oferece suporte a vários fornecedores e softwares.
• DICOM é um formato de arquivo e também um protocolo de rede que define as APIs DICOMweb e DIMSE. Essas APIs, usadas para recuperar e armazenar instâncias DICOM, fornecem funcionalidade abrangente e simplifica a interação com imagens.

Como converter imagens de lâminas inteiras para o DICOM

A maioria dos scanners de WSI não produzem arquivos DICOM de forma nativa a partir de WSIs. Como resultado, você precisa converter WSIs em arquivos DICOM manualmente.

As seguintes ferramentas podem converter WSIs em DICOM:

• Ferramenta de linha de comando "Dicomizer" do Orthanc
• Kit de ferramentas Java DICOM PixelMedTM
• Ferramenta de linha de comandowsi2dcm

A seção a seguir mostra como usar a ferramenta de linha de comando wsi2dcm para gerar arquivos DICOM.

Gerar arquivos DICOM usando a ferramenta de linha de comando wsi2dcm

Antes de concluir as etapas a seguir, verifique se você tem um arquivo WSI válido. Os dados de amostra estão disponíveis no OpenSlide e em outros recursos listados no site da Digital Pathology Association.

Execute a ferramenta de linha de comando wsi2dcm:

wsi2dcm \
    --input=INPUT_WSI \
    --outFolder=PATH/TO/OUTPUT/FOLDER \
    --seriesDescription=WSI_DESCRIPTION

onde:

• INPUT_WSI é o caminho e o nome do arquivo WSI.
• PATH/TO/OUTPUT/FOLDER é o caminho em que a ferramenta gera o arquivo DICOM convertido.
• WSI_DESCRIPTION é uma descrição de sua escolha para o arquivo DICOM convertido.

A execução da ferramenta gera vários arquivos DICOM a partir da WSI. Os arquivos DICOM têm o sufixo .dcm.

Como fazer upload dos arquivos DICOM para a API Cloud Healthcare

Se você ainda não criou um armazenamento DICOM, faça isso agora.

É possível fazer upload dos arquivos DICOM gerados em um armazenamento DICOM usando um dos seguintes métodos:

• Como armazenar os arquivos diretamente usando a implementação da transação do armazenamento DICOMweb da API Cloud Healthcare
• Como armazenar os arquivos usando a ferramenta de CLI do DICOMweb

Como recuperar arquivos DICOM e seus metadados

Depois de fazer o upload dos arquivos DICOM para um armazenamento DICOM, liste e visualize metadados sobre as imagens DICOM.

Como listar as imagens de lâminas inteiras

Cada WSI é um estudo de DICOM. Para listar as WSIs, chame o método dicomStores.searchForStudies:

REST

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

• PROJECT_ID: o ID do seu projeto do 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 repositório DICOM

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies" | Select-Object -Expand Content

APIs Explorer

Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

Você receberá uma resposta JSON semelhante a esta:

Resposta

[
  {
    "0020000D": {
      "vr": "UI",
      "Value": [
        "STUDY_INSTANCE_UID"
      ]
    }
  },
  {
    "00080005": {
      "vr": "CS",
      "Value": [
        "SPECIFIC_CHARACTER_SET"
      ]
    },
    "00080020": {
      "vr": "DA",
      "Value": [
        "STUDY_DATE"
      ]
    },
    "00080030": {
      "vr": "TM"
    },
    "00080050": {
      "vr": "SH",
      "Value": [
        "ACCESSION_NUMBER"
      ]
    },
    "00080090": {
      "vr": "PN"
    },
    "00100010": {
      "vr": "PN"
    },
    "00100020": {
      "vr": "LO",
      "Value": [
        "PATIENT_ID"
      ]
    },
    "00100030": {
      "vr": "DA"
    },
    "00100040": {
      "vr": "CS"
    },
    "0020000D": {
      "vr": "UI",
      "Value": [
        "STUDY_INSTANCE_UID"
      ]
    },
    "00200010": {
      "vr": "SH"
    }
  }
]

Como visualizar os metadados da imagem da lâmina inteira

Cada estudo contém várias instâncias, e cada instância contém um subconjunto dos blocos de uma WSI. Para ver os metadados de uma instância no estudo, chame o método dicomStores.searchForInstances:

REST

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

• PROJECT_ID: o ID do seu projeto do 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 repositório DICOM
• STUDY_INSTANCE_UID: o identificador exclusivo da instância de estudo (UID, na sigla em inglês)

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances?StudyInstanceUID=STUDY_INSTANCE_UID"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances?StudyInstanceUID=STUDY_INSTANCE_UID" | Select-Object -Expand Content

APIs Explorer

Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Preencha todos os campos obrigatórios e clique em Executar.

Você receberá uma resposta JSON semelhante a esta:

Resposta

[
  {
    "00080005": {
      "vr": "CS",
      "Value": [
        "SPECIFIC_CHARACTER_SET"
      ]
    },
    "00080016": {
      "vr": "UI",
      "Value": [
        "SOP_CLASS_UID"
      ]
    },
    "00080018": {
      "vr": "UI",
      "Value": [
        "SOP_INSTANCE_UID"
      ]
    },
    "00080020": {
      "vr": "DA",
      "Value": [
        "STUDY_DATE"
      ]
    },
    "00080030": {
      "vr": "TM"
    },
    "00080050": {
      "vr": "SH",
      "Value": [
        "ACCESSION_NUMBER"
      ]
    },
    "00080060": {
      "vr": "CS",
      "Value": [
        "MODALITY"
      ]
    },
    "00080090": {
      "vr": "PN"
    },
    "00100010": {
      "vr": "PN"
    },
    "00100020": {
      "vr": "LO",
      "Value": [
        "PATIENT_ID"
      ]
    },
    "00100030": {
      "vr": "DA"
    },
    "00100040": {
      "vr": "CS"
    },
    "0020000D": {
      "vr": "UI",
      "Value": [
        "STUDY_INSTANCE_UID"
      ]
    },
    "0020000E": {
      "vr": "UI",
      "Value": [
        "SERIES_INSTANCE_UID"
      ]
    },
    "00200010": {
      "vr": "SH"
    },
    "00200013": {
      "vr": "IS",
      "Value": [
        INSTANCE_NUMBER
      ]
    },
    "00280010": {
      "vr": "US",
      "Value": [
        ROWS
      ]
    },
    "00280011": {
      "vr": "US",
      "Value": [
        COLUMNS
      ]
    },
    "00280100": {
      "vr": "US",
      "Value": [
        BITS_ALLOCATED
      ]
    },
    "00400244": {
      "vr": "DA",
      "Value": [
        "PERFORMED_PROCEDURE_STEP_START_DATE"
      ]
    }
  },
...
]

Como visualizar os blocos da imagem da lâmina inteira

Cada instância geralmente contém vários frames. Um frame representa um bloco da WSI em um nível de zoom específico na "pirâmide" da WSI. Para recuperar um único frame no formato JPEG, chame o método frames.retrieveRendered:

curl

Para recuperar um único frame no formato JPEG, faça uma solicitação GET e especifique as seguintes informações:

• O nome do conjunto de dados pai
• O nome do armazenamento DICOM
• O UID do estudo
• O UID da série
• O UID da instância
• Um token de acesso

O exemplo a seguir mostra uma solicitação GET usando curl.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Accept: image/jpeg" \
    --output FILENAME \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID/frames/0/rendered"

Se a solicitação for bem-sucedida, o arquivo JPEG será gravado na sua máquina.

PowerShell

Para recuperar um único frame no formato JPEG, faça uma solicitação GET e especifique as seguintes informações:

• O nome do conjunto de dados pai
• O nome do armazenamento DICOM
• O UID do estudo
• O UID da série
• O UID da instância
• Um token de acesso

O exemplo a seguir mostra uma solicitação GET usando o Windows PowerShell.

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred"; "Accept" = "image/jpeg" }

Invoke-RestMethod `
  -Method Get `
  -Headers $headers `
  -OutFile FILENAME `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID/frames/0/rendered"

Se a solicitação for bem-sucedida, o arquivo JPEG será gravado na sua máquina.

Como recuperar as imagens de lâminas inteiras

Para recuperar toda a instância, que contém as WSIs, use o método instances.retrieveInstance:

curl

Para recuperar uma instância inteira, faça uma solicitação GET e especifique as seguintes informações:

• O nome do conjunto de dados pai
• O nome do armazenamento DICOM
• O UID do estudo
• O UID da série
• O UID da instância
• Um token de acesso

O exemplo a seguir mostra uma solicitação GET usando curl.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Accept: application/dicom" \
    --output FILENAME \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID"

Se a solicitação for bem-sucedida, o arquivo DICOM será gravado na sua máquina.

PowerShell

Para recuperar uma instância inteira, faça uma solicitação GET e especifique as seguintes informações:

• O nome do conjunto de dados pai
• O nome do armazenamento DICOM
• O UID do estudo
• O UID da série
• O UID da instância
• Um token de acesso

O exemplo a seguir mostra uma solicitação GET usando o Windows PowerShell.

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred"; "Accept" = "application/dicom" }

Invoke-RestMethod `
  -Method Get `
  -Headers $headers `
  -OutFile FILENAME `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_INSTANCE_UID/series/SERIES_INSTANCE_UID/instances/INSTANCE_UID"

Se a solicitação for bem-sucedida, o arquivo DICOM será gravado na sua máquina.

Como visualizar uma lâmina usando um visualizador de imagem da lâmina inteira

Nas seções anteriores, você aprendeu como visualizar os metadados de uma WSI e recuperar blocos individuais. Para visualizar toda o WSI, você precisa usar um visualizador de WSI com tecnologia DICOMweb.

Os seguintes visualizadores são compatíveis com a API Cloud Healthcare:

• Leitor de WSI do diCOMweb
• OHIF (em inglês)
• QuPath
• Slim (MGH)

Ver arquivos DICOM da WSI convertidos usando o visualizador de WSI com DICOMweb

Conclua as seções a seguir para usar o visualizador de WSI com DICOMweb para ver os arquivos DICOM da WSI convertidos.

Como fazer o download do visualizador

Faça o download do visualizador de WSI com DICOMweb:

git clone https://github.com/GoogleCloudPlatform/dicomweb-wsi-viewer.git

Como receber a chave secreta do cliente

Uma chave secreta do cliente autentica um usuário quando ele acessa um aplicativo. Você incorpora a chave secreta do cliente no código-fonte do visualizador de WSI com DICOMweb. Para receber uma chave secreta do cliente, siga estas etapas:

1. Acesse a página Credenciais no console do Google Cloud.
   Acessar a página "Credenciais"

2. Clique em Criar credenciais e selecione ID do cliente do Oauth.

3. Em Tipo de aplicativo, selecione Aplicativo da Web.

4. Adicione um Nome de sua escolha.

5. Em Origens JavaScript autorizadas e URIs de redirecionamento autorizados, insira http://localhost:8000.

6. Clique em Criar e em OK na janela Cliente OAuth exibida. Copie o ID do cliente para uso na próxima seção.

Como configurar a chave secreta do cliente no visualizador

Conclua as etapas a seguir usando o ID do cliente obtido na seção anterior:

1. No diretório dicomweb-wsi-viewer, abra o arquivo viewer.js.

2. Substitua a linha a seguir para que ela contenha o ID do cliente.

   const CLIENT_ID = 'INSERT-YOUR-CLIENT-ID-HERE'
   

   A linha precisa ter esta aparência:

   const CLIENT_ID = 'PROJECT_ID-VALUE.apps.googleusercontent.com';
   

3. Salve o arquivo.

Configurar a tela de consentimento OAuth

Se você ainda não configurou a tela de consentimento do OAuth do projeto do Google Cloud, siga estas etapas:

Atenção: não insira informações confidenciais na tela de consentimento do OAuth. Qualquer informação que você salvar nessa tela poderá ficar visível publicamente para quem acessa seu URL. Os detalhes do produto e do e-mail são exibidos na tela de login e quando alguém tenta acessar um recurso sem ter permissão para isso.

1. Acesse a tela de consentimento OAuth.
   Acesse a tela de consentimento do OAuth

2. Em E-mail de suporte, selecione o endereço de e-mail que você quer exibir como um contato público. Ele precisa ser seu endereço de e-mail ou um Grupo do Google que você tenha.

3. Digite o Nome do aplicativo que você quer exibir.

4. Clique em Adicionar escopo. Na caixa de diálogo exibida, insira https://www.googleapis.com/auth/cloud-healthcare e clique em Adicionar.

5. Clique em Save.

Para alterar as informações na tela de consentimento do OAuth posteriormente, como o nome do produto ou o endereço de e-mail, repita as etapas anteriores.

Se você já configurou a tela de consentimento do OAuth do projeto do Google Cloud, será necessário adicionar https://www.googleapis.com/auth/cloud-healthcare na caixa de diálogo Adicionar escopo.

Como executar o visualizador de WSI com DICOMweb

1. No diretório dicomweb-wsi-viewer, execute o seguinte comando:

   python -m http.server 8000
   

2. Navegue até https://localhost:8000 na máquina em que você executou o comando anterior.

3. Na IU, clique em Fazer login/Autorizar para acessar a tela de consentimento do OAuth e conceder ao visualizador permissão para acessar seu projeto do Google Cloud e os recursos da API Cloud Healthcare.