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.

Using DICOM to store whole slide images

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:

  • Interoperability: DICOM is interoperable with other imaging modalities and also with different software vendors in digital pathology.
  • DICOMweb and DIMSE APIs: In addition to being a file format, DICOM is 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 the process of 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.

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.

  1. 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 any of the following methods:

To upload the DICOM files to Cloud Storage and then import them into a DICOM store, complete the following steps:

  1. If you don't already have a Cloud Storage bucket, create a bucket.

  2. If you haven't already, grant the Cloud Healthcare Service Agent service account permission to read data from a Cloud Storage bucket. For instructions, see Importing data from Cloud Storage.

  3. Copy the DICOM files to a directory called wsi in an existing Cloud Storage bucket using the gsutil cp command:

    gsutil -m cp PATH/TO/OUTPUT/FOLDER/*.dcm gs://BUCKET/wsi
    

    If the command is successful, it prints the status of the copy operation:

    Copying file://PATH/TO/OUTPUT/FOLDER/DICOM_FILE_1.dcm [Content-Type=application/dicom]...
    Copying file://PATH/TO/OUTPUT/FOLDER/DICOM_FILE_2.dcm [Content-Type=application/dicom]...
    Copying file://PATH/TO/OUTPUT/FOLDER/DICOM_FILE_3.dcm [Content-Type=application/dicom]...
    ...
    \ [NUMBER files][  SIZE MiB/  SIZE MiB]
    Operation completed over NUMBER objects/SIZE MiB.
    
  4. Import the DICOM files from Cloud Storage into the DICOM store using the gcloud beta healthcare dicom-stores import command:

    gcloud beta healthcare dicom-stores import gcs DICOM_STORE_ID \
       --dataset=DATASET_ID \
       --location=REGION \
       --gcs-uri=gs://BUCKET/wsi/*.dcm
    

    If the command is successful, the command line displays the operation name:

    name: projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/operations/OPERATION_ID
    

    To view the status of the operation, run the gcloud beta healthcare operations describe command, providing the OPERATION_ID from the response:

    gcloud beta healthcare operations describe OPERATION_ID \
       --dataset=DATASET_ID \
       --location=LOCATION 
    

    After the command completes, the response includes done: true.

    done: true
    metadata:
     '@type': type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata
     apiMethodName: google.cloud.healthcare.v1beta1.dicom.DicomService.ImportDicomData
     createTime: "CREATE_TIME"
     endTime: "END_TIME"
    name: projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/operations/OPERATION_ID
    response:
     '@type': "..."
    

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 command

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 print-access-token) \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

200 OK
[
  {
    "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 print-access-token
$headers = @{ Authorization = "Bearer $cred" }

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

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

200 OK
[
  {
    "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 command

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 print-access-token) \
     "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances?StudyInstanceUID=STUDY_INSTANCE_UID"

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

200 OK
[
  {
    "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 print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-RestMethod `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/instances?StudyInstanceUID=STUDY_INSTANCE_UID"

If the request is successful, the server returns a 200 OK HTTP status code and the response in JSON format:

200 OK
[
  {
    "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 command

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 print-access-token) \
    -H "Accept: image/jpeg" \
    --output FILE_NAME \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/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 server returns a 200 OK HTTP status code and the JPEG file is written to your machine.

200 OK

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 print-access-token
$headers = @{ Authorization = "Bearer $cred"; "Accept" = "image/jpeg" }

Invoke-RestMethod `
  -Method Get `
  -Headers $headers `
  -OutFile FILE_NAME `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/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 server returns a 200 OK HTTP status code and the JPEG file is written to your machine.

200 OK

Retrieving all whole slide images

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

curl command

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 print-access-token) \
    -H "Accept: application/dicom" \
    --output FILE_NAME \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID"

If the request is successful, the server returns a 200 OK HTTP status code and the DICOM file is written to your machine.

200 OK

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 print-access-token
$headers = @{ Authorization = "Bearer $cred"; "Accept" = "application/dicom" }

Invoke-RestMethod `
  -Method Get `
  -Headers $headers `
  -OutFile FILE_NAME `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID"

If the request is successful, the server returns a 200 OK HTTP status code and the DICOM file is written to your machine.

200 OK

Using a whole slide image viewer to view a slide

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.

Google Cloud provides the DICOMweb WSI Viewer, a simple web-based viewer that provides basic viewing capabilities. Google Cloud also provides a QuPath plugin that uses the QuPath open source tool to analyze WSIs and read DICOM data from the Cloud Healthcare API.

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 Platform 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

Using the client ID you obtained in the previous section, complete the following steps:

  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 so:

    const CLIENT_ID = 'PROJECT_ID-VALUE.apps.googleusercontent.com';
    
  3. Save the file.

If you haven't already configured your GCP 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 GCP 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 GCP project and Cloud Healthcare API resources.

Var denne siden nyttig? Si fra hva du synes:

Send tilbakemelding om ...

Cloud Healthcare API