This page explains how to integrate a third-party medical imaging viewer with the Cloud Healthcare API.
Authorizing using OAuth 2.0
At a high level, the authorization flow has the following steps:
- A user opens your medical viewer application. The viewer displays a consent window from Google that shows the name of your application and the Google API services that it is requesting permission to access with the user's authorization credentials. The user can then consent or refuse to grant access to your application.
- The user is sent to a Google sign-in page. If the user grants your application the requested access, then your application gains permission to access the user's data.
Do not store refresh tokens in the viewer. The access tokens granted to the viewer by the user should be short-lived and only exchanged when the tokens expire.
Additionally, refresh tokens are unnecessary because:
- The user will always be present when using the viewer
- Using refresh tokens requires additional work to store the token securely
For the viewer to function properly, the user must have the following roles:
roles/healthcare.dicomViewer(to view DICOM resources)
roles/healthcare.dicomEditor(to view, edit, and create DICOM resources)
It is expected that the user will already have configured these roles, and the
viewer should not need to do anything else. However, the viewer should return
PERMISSION_DENIED errors to users who do not have the
required permissions for accessing their DICOM stores.
Accessing DICOMweb endpoints
After the user signs in, the viewer can make requests to DICOMweb endpoints on the user’s behalf. Each DICOM store exposes a single DICOMweb endpoint.
When the user is in the viewer, they must specify which projects and DICOM stores they want to access. The simplest process is to ask the user to provide the IDs for the project, dataset, and DICOM store they want to access, but this might take the user a long time and make for a poor experience.
As an alternative, you can provide a combination of user input and auto-completion in the viewer. For example, you might have the user enter a project ID, and then the viewer would automatically populate a list of all of the datasets and DICOM stores within that project. Or, you could provide a single input field that automatically populates all of the projects, datasets, and DICOM stores that the user has access to. The following API methods might be helpful when setting up either of these alternatives:
projects.list: Lists projects that are visible to the user and that satisfy a specified filter.
projects.locations.list: Lists information about the supported locations for the Cloud Healthcare API.
projects.locations.datasets.list: Lists the Cloud Healthcare API datasets in a project.
projects.locations.datasets.dicomStores.list: Lists the DICOM stores in a dataset.
You might also consider pre-populating a list of a user's resources, but if a user has hundreds or thousands of DICOM stores or datasets, pre-populating and displaying such a list might be infeasible.
Using DICOMweb to access resources in the viewer
The Cloud Healthcare API supports the DICOMweb standard. To allow users to access their data, the viewer must implement the DICOMweb RESTful HTTP methods instead of the legacy DIMSE protocols.
There are two main components to any viewer: the worklist provider and the image viewer. You can use the DICOMweb standard with both components.
Viewing the worklist provider
Typically, the first thing a user sees when they open a viewer is a list of all available studies in each DICOM store. The viewer can retrieve these studies using the Search Transaction.
See the Cloud Healthcare API DICOM Conformance Statement for specifics on how the Search Transaction is implemented in the Cloud Healthcare API.
After the user is in the worklist provider, they will typically select a study for viewing. To render the study, the viewer must access the study's raw pixel bytes and additional DICOM metadata. The viewer can retrieve this information using the Search Transaction family of methods. These methods let you retrieve an entire raw DICOM file or just the file's raw pixel data. They also support transcoding between different transfer syntaxes.
See the Cloud Healthcare API DICOM Conformance Statement for specifics on how this method is implemented in the Cloud Healthcare API.
Maximizing network throughput
In some cases, such as when rendering a CT scan, a viewer might need to download many instances at once to render the image. For best results, fetch each instance in parallel using a high number of concurrent requests (such as 50 or more). The exact number will depend on your application and network bandwidth.