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:

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:

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:

curl

To search for studies in a DICOM store, make a GET request and specify the following information:

  • The name of the parent dataset
  • The name of the DICOM store
  • 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)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

If the request is successful, the server returns the response in JSON format:

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

PowerShell

To search for studies in a DICOM store, make a GET request and specify the following information:

  • The name of the parent dataset
  • The name of the DICOM store
  • 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" }

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

If the request is successful, the server the response in JSON format:

[
  {
    "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:

curl

To view the instance metadata for an instance in the study, make a GET request and specify the following information:

  • The name of the parent dataset
  • The name of the DICOM store
  • The study instance unique identifier (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)" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances?StudyInstanceUID=STUDY_INSTANCE_UID"

If the request is successful, the server returns the response in JSON format:

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

PowerShell

To view the instance metadata for all instances in the study, make a GET request and specify the following information:

  • The name of the parent dataset
  • The name of the DICOM store
  • The study 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" }

Invoke-RestMethod `
  -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"

If the request is successful, the server returns the response in JSON format:

[
  {
    "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_UID/series/SERIES_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_UID/series/SERIES_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_UID/series/SERIES_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_UID/series/SERIES_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:

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.

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

  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 SimpleHTTPServer 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.