Utilizzare i dati raster con Earth Engine in BigQuery

Questo documento spiega come combinare dati raster e vettoriali utilizzando la funzione ST_REGIONSTATS, che utilizza Google Earth Engine per accedere ai dati raster e delle immagini in BigQuery.

Panoramica

Un raster è una griglia bidimensionale di pixel, a ciascuno dei quali viene assegnato uno o più valori chiamati bande. Ad esempio, ogni pixel potrebbe corrispondere a un particolare chilometro quadrato sulla superficie terrestre e avere bande per temperatura media e precipitazioni medie. I dati raster includono immagini satellitari e altri dati continui basati su griglie, come le previsioni meteo e la copertura del suolo. Molti formati immagine comuni, come i file PNG o JPEG, sono formattati come dati raster.

I dati raster sono spesso in contrasto con i dati vettoriali, in cui i dati sono descritti da linee o curve anziché da una griglia rettangolare fissa. Ad esempio, puoi utilizzare il tipo di dati GEOGRAPHY in BigQuery per descrivere i confini di paesi, città o altre regioni.

I dati raster e vettoriali geospaziali vengono spesso combinati utilizzando un'operazione di statistica zonale, che calcola un aggregato di tutti i valori raster all'interno di una determinata regione vettoriale. Ad esempio, potresti voler calcolare quanto segue:

• Qualità dell'aria media in una raccolta di città.
• Potenziale solare per una raccolta di poligoni di edifici.
• Rischio di incendio riassunto lungo i corridoi delle linee elettriche nelle aree boschive.

BigQuery eccelle nell'elaborazione dei dati vettoriali, mentre Google Earth Engine eccelle nell'elaborazione dei dati raster. Puoi utilizzare la funzione geografica ST_REGIONSTATS per combinare i dati raster utilizzando Earth Engine con i dati vettoriali archiviati in BigQuery.

Prima di iniziare

1. Per utilizzare la funzione ST_REGIONSTATS nelle query, abilita l'API Earth Engine.

   Abilitare l'API

2. (Facoltativo) Per abbonarti e utilizzare i dati pubblicati in BigQuery sharing (in precedenza Analytics Hub) utilizzando la funzione ST_REGIONSTATS, abilita l'API Analytics Hub.

   Abilitare l'API

Autorizzazioni obbligatorie

Per ottenere le autorizzazioni necessarie per chiamare la funzione ST_REGIONSTATS, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

• Visualizzatore risorse Earth Engine (roles/earthengine.viewer)
• Consumer di utilizzo del servizio (roles/serviceusage.serviceUsageConsumer)
• Iscriviti ai set di dati nella condivisione BigQuery: Editor dati BigQuery (roles/bigquery.dataEditor)

Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per chiamare la funzione ST_REGIONSTATS. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per chiamare la funzione ST_REGIONSTATS sono necessarie le seguenti autorizzazioni:

• earthengine.computations.create
• serviceusage.services.use
• bigquery.datasets.create

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Trovare dati raster

Il parametro raster_id nella funzione ST_REGIONSTATS è una stringa che specifica l'origine dei dati raster. Le sezioni seguenti spiegano come trovare e formattare l'ID raster.

Tabelle delle immagini BigQuery

Puoi utilizzare BigQuery sharing (in precedenza Analytics Hub) per scoprire e accedere ai set di dati raster in BigQuery. Per utilizzare la condivisione BigQuery, devi abilitare l'API Analytics Hub e assicurarti di disporre delle autorizzazioni necessarie per visualizzare le schede e abbonarti.

Google Earth Engine pubblica set di dati disponibili pubblicamente che contengono dati raster nelle multiregioni US e EU. Per abbonarti a un set di dati Earth Engine con dati raster, segui questi passaggi:

1. Vai alla pagina Condivisione (Analytics Hub).

   Vai a Condivisione (Analytics Hub)

2. Fai clic su Cerca schede.

3. Nel campo Cerca schede, inserisci "Google Earth Engine".

4. Fai clic su un set di dati a cui vuoi abbonarti.

5. Fai clic su Abbonati.

6. (Facoltativo) Aggiorna i campi Progetto o Nome del set di dati collegato.

7. Fai clic su Salva. Il set di dati collegato viene aggiunto al progetto.

Il set di dati contiene una tabella delle immagini che memorizza i metadati per una raccolta di immagini raster in base alla specifica degli elementi STAC. Una tabella di immagini è analoga a una raccolta di immagini di Earth Engine (ImageCollection).

Ogni riga della tabella corrisponde a una singola immagine raster, con colonne contenenti le proprietà e i metadati dell'immagine. L'ID raster per ogni immagine è memorizzato nella colonna assets.image.href. Fai riferimento alle immagini nelle query utilizzando questo ID come valore parametro raster_id.

Filtra la tabella utilizzando le colonne delle proprietà per selezionare immagini o sottoinsiemi di immagini specifici che soddisfano i tuoi criteri. Per ulteriori informazioni su bande disponibili, dimensioni dei pixel e definizioni delle proprietà, apri la tabella e fai clic sulla scheda Dettagli immagine.

Ogni tabella delle immagini include una tabella *_metadata corrispondente che fornisce informazioni di supporto per la tabella delle immagini.

Ad esempio, il set di dati ERA5-Land fornisce statistiche giornaliere sulle variabili climatiche ed è disponibile pubblicamente. La tabella climate contiene più ID raster. La seguente query filtra la tabella delle immagini utilizzando la colonna start_datetime per ottenere l'ID raster per l'immagine corrispondente al 1° gennaio 2025 e calcola la temperatura media per ogni paese utilizzando la banda temperature_2m:

WITH SimplifiedCountries AS (
  SELECT
    ST_SIMPLIFY(geometry, 10000) AS simplified_geometry,
    names.primary AS name
  FROM
    `bigquery-public-data.overture_maps.division_area`
  WHERE
    subtype = 'country'
)
SELECT
  sc.simplified_geometry AS geometry,
  sc.name,
  ST_REGIONSTATS(
    sc.simplified_geometry,
    (SELECT assets.image.href
     FROM `LINKED_DATASET_NAME.climate`
     WHERE start_datetime = '2025-01-01 00:00:00'),
    'temperature_2m'
  ).mean - 273.15 AS mean_temperature
FROM
  SimplifiedCountries AS sc
ORDER BY
  mean_temperature DESC;

Cloud Storage GeoTIFF

GeoTIFF è un formato file comune per l'archiviazione di dati raster geospaziali. La funzione ST_REGIONSTATS supporta i dati raster archiviati nel formato Cloud Optimized GeoTIFF (COG) nei bucket Cloud Storage che si trovano nelle seguenti regioni:

• US multiregionale
• us-central1
• EU multiregionale
• europe-west1

Fornisci l'URI Cloud Storage come ID raster, ad esempio gs://bucket/folder/raster.tif.

Asset immagine Earth Engine

La funzione ST_REGIONSTATS supporta il passaggio di un percorso dell'asset immagine di Earth Engine per l'argomento raster_id. I dati raster di Earth Engine sono disponibili come singole immagini o raccolte di immagini. Questi dati esistono nella regione US e sono compatibili solo con le query eseguite nella regione US. Per trovare l'ID raster di un'immagine:

1. Cerca nel catalogo di dati di Earth Engine il set di dati che ti interessa.

2. Per aprire la pagina della descrizione della voce, fai clic sul nome del set di dati. Lo snippet di Earth Engine descrive una singola immagine o una raccolta di immagini.

   Se lo snippet Earth Engine è del modulo ee.Image('IMAGE_PATH'), l'ID raster è 'ee://IMAGE_PATH'.

   Se lo snippet di Earth Engine è del tipo ee.ImageCollection('IMAGE_COLLECTION_PATH'), puoi utilizzare Earth Engine Code Editor per filtrare ImageCollection in una singola immagine. Utilizza il metodo ee.Image.get('system:id') per stampare il valore IMAGE_PATH per l'immagine nella console. L'ID raster è 'ee://IMAGE_PATH'.

Pesi dei pixel

Puoi specificare un peso, a volte chiamato valore maschera, per il parametro include nella funzione ST_REGIONSTATS che determina la ponderazione di ogni pixel nei calcoli. I valori del peso devono essere compresi tra 0 e 1. I pesi al di fuori di questo intervallo vengono impostati sul limite più vicino, ovvero 0 o 1.

Un pixel viene considerato valido se ha un peso maggiore di 0. Un peso pari a 0 indica un pixel non valido. I pixel non validi in genere rappresentano dati mancanti o inaffidabili, ad esempio aree oscurate dalle nuvole, anomalie dei sensori, errori di elaborazione o località al di fuori di un confine definito.

Se non specifichi un peso, ogni pixel viene ponderato automaticamente in base alla proporzione del pixel che rientra nella geometria, consentendo l'inclusione proporzionale nelle statistiche zonali. Se la geometria è inferiore a 1/256 delle dimensioni del pixel, il peso del pixel è 0. In questi casi, null viene restituito per tutte le statistiche tranne count e area, che sono 0.

Se un pixel parzialmente intersecante ha un peso compreso tra l'argomento include e ST_REGIONSTATS, BigQuery utilizza il valore minimo tra questo peso e la frazione del pixel che interseca la regione.

I valori del peso non hanno la stessa precisione dei valori FLOAT64. In pratica, il loro valore effettivo potrebbe differire dal valore utilizzato nei calcoli fino a 1/256 (circa lo 0,4%).

Puoi fornire un'espressione utilizzando la sintassi dell'espressione dell'immagine di Earth Engine nell'argomento include per ponderare dinamicamente i pixel in base a criteri specifici all'interno delle bande raster. Ad esempio, la seguente espressione limita i calcoli ai pixel in cui la banda probability supera il 70%:

include => 'probability > 0.7'

Se il set di dati include una banda del fattore di ponderazione, puoi utilizzarla con la seguente sintassi:

include => 'weight_factor_band_name'

Dimensioni dei pixel e scala dell'analisi

Un'immagine raster geospaziale è una griglia di pixel che corrisponde a una posizione sulla superficie della Terra. La dimensione in pixel di un raster, a volte chiamata scala, è la dimensione nominale di un bordo di un pixel nel sistema di riferimento delle coordinate della griglia. Ad esempio, un raster con una risoluzione di 10 metri ha pixel di dimensioni 10 metri x 10 metri. Le dimensioni originali dei pixel segnalate possono variare notevolmente tra i set di dati, da meno di 1 metro a più di 20 chilometri.

Quando utilizzi la funzione ST_REGIONSTATS per calcolare le statistiche zonali, la dimensione in pixel dei dati raster è un aspetto fondamentale da considerare. Ad esempio, l'aggregazione di dati raster ad alta risoluzione nella regione di un paese può essere computazionalmente intensiva e inutilmente granulare. Al contrario, l'aggregazione di dati a bassa risoluzione sulla regione, ad esempio i pacchi della città, potrebbe non fornire dettagli sufficienti.

Per ottenere risultati significativi ed efficienti dall'analisi, ti consigliamo di scegliere una dimensione del pixel appropriata per le dimensioni dei poligoni e l'obiettivo dell'analisi. Puoi trovare le dimensioni dei pixel per ogni set di dati raster nella sezione della descrizione delle tabelle delle immagini nella condivisione di BigQuery.

La modifica delle dimensioni dei pixel cambia il numero di pixel che intersecano una determinata geografia, il che influisce sui risultati e sulla loro interpretazione. Non consigliamo di modificare le dimensioni dei pixel per le analisi di produzione. Tuttavia, se stai prototipando una query, aumentare le dimensioni dei pixel può ridurre il tempo di esecuzione e il costo della query, soprattutto per i dati ad alta risoluzione.

Per modificare le dimensioni dei pixel, imposta scale nell'argomento options della funzione ST_REGIONSTATS. Ad esempio, per calcolare le statistiche su pixel di 1000 metri, utilizza options => JSON '{"scale":1000}', che indica a Earth Engine di ricampionare l'immagine alla scala richiesta. Per saperne di più su come Earth Engine gestisce il ridimensionamento, consulta Scale nella documentazione di Google Earth Engine.

Il calcolo delle statistiche per i poligoni significativamente più piccoli dei pixel del raster può produrre risultati imprecisi o nulli. In questo caso, un'alternativa è sostituire il poligono con il suo punto centroide utilizzando ST_CENTROID.

Fatturazione

Quando esegui una query, l'utilizzo della funzione ST_REGIONSTATS viene fatturato separatamente dal resto della query perché Earth Engine calcola i risultati della chiamata di funzione. Ti viene addebitato questo utilizzo in ore di slot nella SKU BigQuery Services, indipendentemente dal fatto che utilizzi la fatturazione on demand o le prenotazioni. Per visualizzare l'importo fatturato per le chiamate BigQuery a Earth Engine, visualizza il report sulla fatturazione e utilizza le etichette per filtrare in base alla chiave dell'etichetta goog-bq-feature-type, con valore EARTH_ENGINE. Se la funzione ST_REGIONSTATS non va a buon fine, non ti viene addebitato alcun costo per il calcolo di Earth Engine utilizzato.

Per ogni query, puoi utilizzare il metodo jobs.get nell'API BigQuery per visualizzare le seguenti informazioni:

• Il campo slotMs, che mostra il numero di millisecondi di slot consumati da Earth Engine quando il campo externalService è EARTH_ENGINE e il campo billingMethod è SERVICES_SKU.
• Il campo totalServicesSkuSlotMs, che mostra il numero totale di millisecondi di slot utilizzati da tutti i servizi esterni BigQuery fatturati in base allo SKU dei servizi BigQuery.

Fattori di costo

I seguenti fattori influiscono sull'utilizzo di Compute quando esegui la funzione ST_REGIONSTATS:

• Il numero di righe di input.
• L'immagine raster che utilizzi. Alcuni raster sono compositi creati da raccolte di immagini di origine nel catalogo dati di Earth Engine e le risorse di calcolo per produrre il risultato composito variano.
• La risoluzione dell'immagine.
• Le dimensioni e la complessità della geografia di input, il numero di pixel che intersecano la geografia e il numero di riquadri immagine e byte letti da Earth Engine.

• La posizione della geografia di input su Earth rispetto alle immagini di origine e la proiezione e la risoluzione dell'immagine.

  • Le proiezioni delle immagini possono distorcere i pixel, in particolare quelli ad alte latitudini o molto al di fuori dell'area di copertura prevista dell'immagine.
  • Per i raster compositi, il numero di immagini di origine che intersecano la geografia di input può variare a livello regionale e nel tempo. Ad esempio, alcuni satelliti producono più immagini a latitudini basse o alte, a seconda della loro orbita e dei parametri di raccolta dei dati, oppure potrebbero omettere immagini a seconda delle condizioni atmosferiche variabili.

• L'utilizzo di formule negli argomenti include o band_name e il numero di bande che coinvolgono.

• La memorizzazione nella cache dei risultati precedenti.

Costi sotto controllo

Per controllare i costi associati alla funzione ST_REGIONSTATS, puoi modificare la quota che controlla la quantità di tempo di slot che la funzione può consumare. Il valore predefinito è 350 ore di slot al giorno. Quando visualizzi le quote, filtra l'elenco Metrica in base a earthengine.googleapis.com/bigquery_slot_usage_time per visualizzare la quota di Earth Engine associata alle chiamate da BigQuery. Per saperne di più, leggi le informazioni sulle quote delle funzioni raster di BigQuery nella documentazione di Google Earth Engine.

Nota: come le quote di query personalizzate in BigQuery, questa quota è approssimativa. Fornisce una protezione contro una spesa eccessiva, ma non è progettata per limitare rigorosamente il tempo dello slot. A volte BigQuery potrebbe eseguire una query che supera il limite di quota e potresti esaurire la quota senza che ti venga addebitato l'intero importo consumato.

Aree geografiche supportate

Le query che chiamano la funzione ST_REGIONSTATS devono essere eseguite in una delle seguenti regioni:

• US multiregionale
• us-central1
• us-central2
• EU multiregionale
• europe-west1

Passaggi successivi

• Prova il tutorial che mostra come utilizzare i dati raster per analizzare la temperatura.
• Scopri di più sulle funzioni geografiche in BigQuery.
• Scopri di più su come utilizzare i dati geospaziali.