Using the Cloud Healthcare API for digital pathology

This page explains how to store, analyze, and manage whole slide images (WSIs) using the Cloud Healthcare API.

Overview

Digital pathology enables the storing, processing, and managing of conventional glass slides by digitizing them to produce whole slide images (WSIs).

WSIs are typically large files that can be up to several GB. They come in various file formats, which can make them difficult to manage. The Cloud Healthcare API simplifies the process of storing, analyzing, and managing WSIs.

Storing whole slide images using DICOM

The Cloud Healthcare API provides a managed service for storing DICOM images. This service also supports storing and retrieving WSIs. For more information on DICOM in the Cloud Healthcare API, see DICOM.

Using DICOM has the following benefits:

• Supports multiple vendors and software.
• DICOM is a file format and also a networking protocol that defines the DICOMweb and DIMSE APIs. These APIs, used for retrieving and storing DICOM instances, provide extensive functionality and simplify interacting with images.

Converting whole slide images to DICOM

Most WSI scanners do not natively produce DICOM files from WSIs. As a result, you must convert WSIs to DICOM files manually.

The following tools can convert WSIs to DICOM:

• Orthanc "Dicomizer" command-line tool
• PixelMed™ Java DICOM Toolkit
• wsi2dcm command-line tool

The following section shows how to use the wsi2dcm command-line tool to generate DICOM files.

Generate DICOM files using the wsi2dcm command-line tool

Before completing the following steps, ensure that you have a valid WSI file. Sample data is available from OpenSlide and other resources listed on the Digital Pathology Association website.

Run the wsi2dcm command-line tool:

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

where:

• INPUT_WSI is the path and name of the WSI file.
• PATH/TO/OUTPUT/FOLDER is the path where the tool outputs the converted DICOM file.
• WSI_DESCRIPTION is a description of your choosing for the converted DICOM file.

Running the tool generates several DICOM files from the WSI. The DICOM files have the suffix .dcm.

Uploading the DICOM files to the Cloud Healthcare API

If you have not already created a DICOM store, do so now.

You can upload the generated DICOM files in a DICOM store using either of the following methods:

• Storing the files directly using the Cloud Healthcare API DICOMweb Store transaction implementation
• Storing the files using the DICOMweb CLI tool

Retrieving DICOM files and their metadata

After uploading the DICOM files into a DICOM store, you can list and view metadata about the DICOM images.

Listing the whole slide images

Each WSI is a DICOM study. To list the WSIs, you can call the dicomStores.searchForStudies method:

REST

Before using any of the request data, make the following replacements:

• PROJECT_ID: the ID of your Google Cloud project
• LOCATION: the dataset location
• DATASET_ID: the DICOM store's parent dataset
• DICOM_STORE_ID: the DICOM store ID

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$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

Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

You should receive a JSON response similar to the following:

Response

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

Viewing the whole slide image metadata

Each study contains multiple instances, and each instance contains a subset of the tiles of a WSI. To view the instance metadata for an instance in the study, call the dicomStores.searchForInstances method:

REST

Before using any of the request data, make the following replacements:

• PROJECT_ID: the ID of your Google Cloud project
• LOCATION: the dataset location
• DATASET_ID: the DICOM store's parent dataset
• DICOM_STORE_ID: the DICOM store ID
• STUDY_INSTANCE_UID: the study instance unique identifier (UID)

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$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

Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

You should receive a JSON response similar to the following:

Response

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

Viewing the whole slide image tiles

Each instance typically contains multiple frames. A frame represents one tile of the WSI at a particular zoom level in the WSI "pyramid". To retrieve a single frame in JPEG format, call the frames.retrieveRendered method:

curl

To retrieve a single frame in JPEG format, make a GET request and specify the following information:

• The name of the parent dataset
• The name of the DICOM store
• The study UID
• The series UID
• The instance UID
• An access token

The following sample shows a GET request using 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"

If the request is successful, the JPEG file is written to your machine.

PowerShell

To retrieve a single frame in JPEG format, make a GET request and specify the following information:

• The name of the parent dataset
• The name of the DICOM store
• The study UID
• The series UID
• The instance UID
• An access token

The following sample shows a GET request using 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"

If the request is successful, the JPEG file is written to your machine.

Retrieving all whole slide images

To retrieve the entire instance, which contains the WSIs, use the instances.retrieveInstance method:

curl

To retrieve an entire instance, make a GET request and specify the following information:

• The name of the parent dataset
• The name of the DICOM store
• The study UID
• The series UID
• The instance UID
• An access token

The following sample shows a GET request using 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"

If the request is successful, the DICOM file is written to your machine.

PowerShell

To retrieve an entire instance, make a GET request and specify the following information:

• The name of the parent dataset
• The name of the DICOM store
• The study UID
• The series UID
• The instance UID
• An access token

The following sample shows a GET request using 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"

If the request is successful, the DICOM file is written to your machine.

Viewing a slide using a whole slide image viewer

The previous sections showed how to view the metadata of a WSI and retrieve individual tiles. To view the entire WSI, you need to use a WSI viewer powered by DICOMweb.

The following viewers are compatible with the Cloud Healthcare API:

• DICOMweb WSI Viewer
• OHIF
• QuPath
• Slim (MGH)

View converted WSI DICOM files using the DICOMweb WSI viewer

Complete the following sections to use the DICOMweb WSI Viewer to view the converted WSI DICOM files.

Downloading the viewer

Download the DICOMweb WSI Viewer:

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

Getting the client secret

A client secret authenticates a user when the user accesses an application. You embed the client secret in the source code of the DICOMweb WSI Viewer. To get a client secret, complete the following steps:

1. Go to the Credentials page in the Google Cloud console.
   Go to the Credentials page

2. Click Create credentials and select OAuth client ID.

3. Under Application type, select Web application.

4. Add a Name of your choosing.

5. Under Authorized JavaScript origins and Authorized redirect URIs, enter http://localhost:8000.

6. Click Create, then click OK on the OAuth client window that appears. Copy the client ID for use in the next section.

Configuring the client secret in the viewer

Complete the following steps using the client ID you obtained in the previous section:

1. In the dicomweb-wsi-viewer directory, open the viewer.js file.

2. Replace the following line so that it contains your client ID.

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

   The line should instead look like the following sample:

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

3. Save the file.

Configuring the OAuth consent screen

If you haven't already configured your Google Cloud project's OAuth consent screen, complete the following steps:

Caution: Don't enter any confidential information on the OAuth consent screen. Any information you save to the OAuth consent screen could be publicly visible for anyone who accesses your URL. Email and product details display on the login screen and when someone tries to access a resource for which they don't have permission.

1. Go to the OAuth consent screen.
   Go to the OAuth consent screen

2. Under Support email, select the email address you want to display as a public contact. This email address must be your email address or a Google Group you own.

3. Enter the Application name you want to display.

4. Click Add scope. In the dialog that appears, enter https://www.googleapis.com/auth/cloud-healthcare, and then click Add.

5. Click Save.

To change information on the OAuth consent screen later, such as the product name or email address, repeat the preceding steps to configure the consent screen.

If you've already configured your Google Cloud project's OAuth consent screen, then you need to add https://www.googleapis.com/auth/cloud-healthcare in the Add scope dialog.

Running the DICOMweb WSI viewer

1. In the dicomweb-wsi-viewer directory, run the following command:

   python -m http.server 8000
   

2. Navigate to https://localhost:8000 on the machine where you ran the previous command.

3. In the UI, click Sign in/Authorize to access the OAuth consent screen and grant the viewer permission to access your Google Cloud project and Cloud Healthcare API resources.