Utilizzo dell'API Cloud Healthcare per la patologia digitale

Questa pagina spiega come archiviare, analizzare e gestire le immagini di diapositive intere (WSI) utilizzando l'API Cloud Healthcare.

Panoramica

La patologia digitale consente di archiviare, elaborare e gestire i vetrini convenzionali digitalizzandoli per produrre immagini di vetrini interi (WSI).

In genere, gli WSI sono file di grandi dimensioni che possono arrivare a diversi GB. Sono disponibili in vari formati, il che può renderli difficili da gestire. L'API Cloud Healthcare semplifica il processo di archiviazione, analisi e gestione delle immagini WSI.

Archiviazione di immagini di diapositive intere utilizzando DICOM

L'API Cloud Healthcare fornisce un servizio gestito per l'archiviazione di immagini DICOM. Questo servizio supporta anche la memorizzazione e il recupero dei WSI. Per ulteriori informazioni su DICOM nell'API Cloud Healthcare, consulta DICOM.

L'utilizzo di DICOM presenta i seguenti vantaggi:

• Supporta più fornitori e software.
• DICOM è un formato file e anche un protocollo di rete che definisce le API DICOMweb e DIMSE. Queste API, utilizzate per recuperare e archiviare istanze DICOM, forniscono funzionalità ampie e semplificano l'interazione con le immagini.

Conversione di immagini di diapositive intere in DICOM

La maggior parte degli scanner WSI non produce in modo nativo file DICOM dalle immagini WSI. Di conseguenza, devi convertire manualmente i WSI in file DICOM.

I seguenti strumenti possono convertire i WSI in DICOM:

• Strumento a riga di comando "Dicomizer" di Orthanc
• PixelMed™ Java DICOM Toolkit
• Strumento a riga di comando wsi2dcm

La sezione seguente mostra come utilizzare lo strumento a riga di comando wsi2dcm per generare file DICOM.

Generare file DICOM utilizzando lo strumento a riga di comando wsi2dcm

Prima di completare i passaggi che seguono, assicurati di avere un file WSI valido. I dati di esempio sono disponibili su OpenSlide e su altre risorse elencate sul sito web della Digital Pathology Association.

Esegui lo strumento a riga di comando wsi2dcm:

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

dove:

• INPUT_WSI è il percorso e il nome del file WSI.
• PATH/TO/OUTPUT/FOLDER è il percorso in cui lo strumento genera il file DICOM convertito.
• WSI_DESCRIPTION è una descrizione scelta per il file DICOM convertito.

L'esecuzione dello strumento genera diversi file DICOM dalla WSI. I file DICOM hanno il suffisso .dcm.

Caricamento dei file DICOM nell'API Cloud Healthcare

Se non hai ancora creato un archivio DICOM, effettua questa operazione ora.

Puoi caricare i file DICOM generati in un archivio DICOM utilizzando uno dei seguenti metodi:

• Archiviazione dei file direttamente utilizzando l'implementazione delle transazioni dell'archivio DICOMweb dell'API Cloud Healthcare
• Archiviazione dei file utilizzando lo strumento DICOMweb CLI

Recupero dei file DICOM e dei relativi metadati

Dopo aver caricato i file DICOM in un archivio DICOM, puoi elencare e visualizzare i metadati relativi alle immagini DICOM.

Elenco di tutte le immagini della diapositiva

Ogni WSI è uno studio DICOM. Per elencare gli IWS, puoi chiamare il metodo dicomStores.searchForStudies:

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• PROJECT_ID: l'ID del tuo progetto Google Cloud
• LOCATION: la posizione del set di dati
• DATASET_ID: il set di dati principale dell'archivio DICOM
• DICOM_STORE_ID: l'ID dell'archivio DICOM

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Explorer API

Apri la pagina di riferimento del metodo. Il riquadro Esplora API si apre sul lato destro della pagina. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

Dovresti ricevere una risposta JSON simile alla seguente:

Risposta

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

Visualizzazione dei metadati dell'immagine dell'intera diapositiva

Ogni studio contiene più istanze e ogni istanza contiene un sottoinsieme di riquadri di una WSI. Per visualizzare i metadati di un'istanza nello studio, chiama il metodo dicomStores.searchForInstances:

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• PROJECT_ID: l'ID del tuo progetto Google Cloud
• LOCATION: la posizione del set di dati
• DATASET_ID: il set di dati principale dell'archivio DICOM
• DICOM_STORE_ID: l'ID dell'archivio DICOM
• STUDY_INSTANCE_UID: l'identificatore univoco (UID) dell'istanza dello studio

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Explorer API

Apri la pagina di riferimento del metodo. Il riquadro Esplora API si apre sul lato destro della pagina. Puoi interagire con questo strumento per inviare richieste. Compila i campi obbligatori e fai clic su Esegui.

Dovresti ricevere una risposta JSON simile alla seguente:

Risposta

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

Visualizzazione dei riquadri delle immagini dell'intera presentazione

In genere ogni istanza contiene più frame. Un frame rappresenta un riquadro della "piramide" della WSI a un determinato livello di zoom. Per recuperare un singolo frame in formato JPEG, chiama il metodo frames.retrieveRendered:

curl

Per recuperare un singolo frame in formato JPEG, effettua una richiesta GET e specifica le seguenti informazioni:

• Il nome del set di dati principale
• Il nome dell'archivio DICOM
• L'UID dello studio
• L'UID della serie
• L'UID dell'istanza
• Un token di accesso

L'esempio seguente mostra una richiesta GET che utilizza 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 la richiesta va a buon fine, il file JPEG viene scritto sul computer.

PowerShell

Per recuperare un singolo frame in formato JPEG, effettua una richiesta GET e specifica le seguenti informazioni:

• Il nome del set di dati principale
• Il nome dell'archivio DICOM
• L'UID dello studio
• L'UID della serie
• L'UID dell'istanza
• Un token di accesso

Il seguente esempio mostra una richiesta GET mediante 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 la richiesta va a buon fine, il file JPEG viene scritto sul computer.

Recupero di tutte le immagini delle diapositive intere

Per recuperare l'intera istanza, che contiene gli WSI, utilizza il metodo instances.retrieveInstance:

curl

Per recuperare un'intera istanza, effettua una richiesta GET e specifica le seguenti informazioni:

• Il nome del set di dati principale
• Il nome dell'archivio DICOM
• L'UID dello studio
• L'UID della serie
• L'UID dell'istanza
• Un token di accesso

L'esempio seguente mostra una richiesta GET che utilizza 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 la richiesta va a buon fine, il file DICOM viene scritto sul computer.

PowerShell

Per recuperare un'intera istanza, effettua una richiesta GET e specifica le seguenti informazioni:

• Il nome del set di dati principale
• Il nome dell'archivio DICOM
• L'UID dello studio
• L'UID della serie
• L'UID dell'istanza
• Un token di accesso

Il seguente esempio mostra una richiesta GET mediante 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 la richiesta va a buon fine, il file DICOM viene scritto sul computer.

Visualizzazione di una diapositiva utilizzando un visualizzatore di immagini di diapositive complete

Le sezioni precedenti hanno mostrato come visualizzare i metadati di un'immagine WSI e recuperare i singoli riquadri. Per visualizzare l'intera WSI, devi utilizzare un visualizzatore WSI basato su DICOMweb.

I seguenti visualizzatori sono compatibili con l'API Cloud Healthcare:

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

Visualizzare i file DICOM WSI convertiti utilizzando il visualizzatore DICOMweb WSI

Completa le seguenti sezioni per utilizzare DICOMweb WSI Viewer per visualizzare i file DICOM WSI convertiti.

Download del visualizzatore

Scarica il visualizzatore DICOMweb WSI:

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

Ottenere il client secret

Un client secret autentica un utente quando accede a un'applicazione. Incorpora il client secret nel codice sorgente del visualizzatore DICOMweb WSI. Per ottenere un client secret:

1. Vai alla pagina Credenziali nella console Google Cloud.
   Vai alla pagina Credenziali

2. Fai clic su Crea credenziali e seleziona ID client OAuth.

3. In Tipo di applicazione, seleziona Applicazione web.

4. Aggiungi un nome a tua scelta.

5. In Origini JavaScript autorizzate e URI di reindirizzamento autorizzati, inserisci http://localhost:8000.

6. Fai clic su Crea, quindi su OK nella finestra Client OAuth visualizzata. Copia l'ID client da utilizzare nella sezione successiva.

Configurazione del client secret nel visualizzatore

Completa i seguenti passaggi utilizzando l'ID client ottenuto nella sezione precedente:

1. Nella directory dicomweb-wsi-viewer, apri il file viewer.js.

2. Sostituisci la riga seguente in modo che contenga il tuo ID client.

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

   La riga dovrebbe invece avere il seguente aspetto:

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

3. Salva il file.

Configurazione della schermata per il consenso OAuth

Se non hai ancora configurato la schermata per il consenso OAuth del progetto Google Cloud, completa i seguenti passaggi:

Attenzione: non inserire informazioni riservate nella schermata di consenso OAuth. Qualsiasi informazione salvata nella schermata di consenso OAuth potrebbe essere visibile pubblicamente per chiunque acceda al tuo URL. L'email e i dettagli del prodotto vengono visualizzati nella schermata di accesso e quando un utente tenta di accedere a una risorsa per la quale non dispone dell'autorizzazione.

1. Vai alla schermata di consenso OAuth.
   Vai alla schermata per il consenso OAuth

2. In Email dell'assistenza, seleziona l'indirizzo email da visualizzare come contatto pubblico. Devi utilizzare il tuo indirizzo email o l'indirizzo email di un gruppo Google di tuo proprietà.

3. Inserisci il nome dell'applicazione da visualizzare.

4. Fai clic su Aggiungi ambito. Nella finestra di dialogo visualizzata, inserisci https://www.googleapis.com/auth/cloud-healthcare e poi fai clic su Aggiungi.

5. Fai clic su Salva.

Per modificare in un secondo momento le informazioni nella schermata di consenso OAuth, ad esempio il nome del prodotto o l'indirizzo email, ripeti i passaggi precedenti per configurare la schermata di consenso.

Se hai già configurato la schermata per il consenso OAuth del progetto Google Cloud, devi aggiungere https://www.googleapis.com/auth/cloud-healthcare nella finestra di dialogo Aggiungi ambito.

Eseguire il visualizzatore DICOMweb WSI

1. Nella directory dicomweb-wsi-viewer, esegui il seguente comando:

   python -m http.server 8000
   

2. Vai a https://localhost:8000 sulla macchina in cui hai eseguito il comando precedente.

3. Nell'interfaccia utente, fai clic su Accedi/Autorizza per accedere alla schermata del consenso OAuth e concedi al visualizzatore l'autorizzazione per accedere al tuo progetto Google Cloud e alle risorse dell'API Cloud Healthcare.