Lavorare con i dati raster utilizzando Earth Engine in BigQuery

Questo documento spiega come combinare i dati raster e vettoriali utilizzando la funzione ST_REGIONSTATS, che chiama Google Earth Engine per eseguire analisi geospaziali in BigQuery.

Panoramica

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

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

I dati raster e vettoriali geospaziali vengono spesso combinati utilizzando un'operazione di statistiche zonali, 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 ogni contea del tuo stato.
Potenziale solare per una raccolta di poligoni di edifici.
Rischio di incendio riassunto lungo i corridoi delle linee elettriche nelle aree boschive.

BigQuery è eccellente nell'elaborazione di dati vettoriali, mentre Google Earth Engine è eccellente nell'elaborazione di 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

Per utilizzare la funzione ST_REGIONSTATS nelle query, abilita l'API Earth Engine.
Abilitare l'API
(Facoltativo) Per iscriverti 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 nel progetto:

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

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

Questi ruoli predefiniti contengono le autorizzazioni necessarie per chiamare la funzione ST_REGIONSTATS. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

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 i 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 di immagini BigQuery

Puoi utilizzare BigQuery sharing (in precedenza Analytics Hub) per trovare 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 e iscriverti alle schede.

Google Earth Engine pubblica set di dati disponibili pubblicamente che contengono dati raster. Per abbonarti a un set di dati Earth Engine con dati raster:

Vai alla pagina Condivisione (Analytics Hub).
Andare a Condivisione (Analytics Hub)
Fai clic su Cerca schede.
Nel campo Cerca schede, inserisci "Google Earth Engine".
Fai clic su un set di dati a cui vuoi iscriverti.
Fai clic su Abbonati.
(Facoltativo) Aggiorna i campi Progetto o Nome set di dati collegato.
Fai clic su Salva. Il set di dati collegato viene aggiunto al progetto.

Il set di dati contiene una tabella, a volte chiamata tabella di immagini, che immagazzina i metadati di 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. L'ID raster di ogni immagine è archiviato nella colonna assets.image.href. Per trovare un'immagine specifica, puoi filtrare in base alle proprietà dell'immagine nella colonna properties. Puoi trovare informazioni sulle bande nella descrizione della tabella.

Ad esempio, il set di dati ERA5-Land fornisce statistiche giornaliere sulle variabili climatiche ed è disponibile pubblicamente. La climate tabella contiene più ID raster. La seguente query filtra la tabella delle immagini utilizzando la colonna properties.start_datetime per ottenere l'ID raster dell'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  properties.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;

GeoTIFF di Cloud Storage

GeoTIFF è un formato file comune per l'archiviazione di dati raster geospaziali. La funzione ST_REGIONSTATS supporta i dati raster archiviati nel formato GeoTIFF nei bucket Cloud Storage che si trovano nelle regioni US o us-central1. 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 della risorsa immagine Earth Engine per l'argomento raster_id. I dati raster di Earth Engine sono disponibili come singole immagini o raccolte di immagini. Per trovare l'ID raster di un'immagine:

Cerca nel catalogo di dati di Earth Engine il set di dati che ti interessa.
Per aprire la pagina della descrizione della voce, fai clic sul nome del set di dati. Lo snippet Earth Engine descrive una singola immagine o una raccolta di immagini.
Se lo snippet di Earth Engine è del tipo 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 l'editor di codice di Earth Engine per filtrare la raccolta di immagini su una singola immagine. Utilizza il metodo ee.Image.get('system:id') per stampare sulla console il valore IMAGE_PATH per l'immagine. L'ID raster è 'ee://IMAGE_PATH'.

Pesi dei pixel

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

Un pixel è considerato valido se ha un peso maggiore di 0. Un valore di 0 indica un pixel non valido. I pixel non validi di solito rappresentano dati mancanti o inaffidabili, ad esempio aree nascoste dalle nuvole, anomalie del sensore, 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 un pixel parzialmente intersecato ha un peso dall'argomento include a ST_REGIONSTATS, BigQuery utilizza il minimo di quel peso e della frazione del pixel che interseca la regione.

I valori di 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 delle espressioni di immagini di Earth Engine nell'argomento include per assegnare dinamicamente un peso ai 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 di analisi

Un'immagine raster geospaziale è una griglia di pixel che corrisponde a una determinata località sulla superficie della Terra. Le dimensioni in pixel di un raster, a volte chiamate scala, sono le dimensioni nominali di un lato 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 x 10 metri. Le dimensioni dei pixel originali registrate possono variare notevolmente da un set di dati all'altro, da meno di 1 metro a più di 20 chilometri.

Quando utilizzi la funzione ST_REGIONSTATS per calcolare le statistiche zonali, la dimensione del pixel degli raster è un fattore cruciale. Ad esempio, l'aggregazione di dati raster ad alta risoluzione per la regione di un paese può richiedere un'elaborazione intensa e non essere necessaria. Al contrario, l'aggregazione di dati a bassa risoluzione nella regione, come i lotti cittadini, potrebbe non fornire dettagli sufficienti.

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

La modifica delle dimensioni dei pixel influisce sul numero di pixel che intersecano una determinata area geografica, il che influisce sui risultati e sulla loro interpretazione. Sconsigliamo 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, in particolare 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 superiori a 1000 metri, utilizza options => JSON '{"scale":1000}', che indica a Earth Engine di ricalcolare l'immagine alla scala richiesta. Per scoprire di più su come Earth Engine gestisce la riscalatura, consulta Scala nella documentazione di Google Earth Engine.

Fatturazione

Quando esegui una query, l'utilizzo della funzione ST_REGIONSTATS viene fatturato distintamente dal resto della query perché Earth Engine calcola i risultati della chiamata della funzione. Ti viene addebitato questo utilizzo in ore di slot in base allo SKU dei servizi BigQuery, indipendentemente dal fatto che tu utilizzi la fatturazione on demand o le prenotazioni. Per visualizzare l'importo fatturato per le chiamate di BigQuery a Earth Engine, visualizza il report di fatturazione e utilizza le etichette per filtrare in base alla chiave dell'etichetta goog-bq-feature-type, con valore EARTH_ENGINE.

Fattori di costo

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

Il numero di righe di input.
L'immagine raster utilizzata. 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 di immagini e byte letti da Earth Engine.
La posizione della geografia inserita sulla Terra rispetto alle immagini di origine e la proiezione e la risoluzione dell'immagine.
- Le proiezioni delle immagini possono deformare i pixel, in particolare quelli a latitudini elevate 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 in base alla regione e nel tempo. Ad esempio, alcuni satellite producono più immagini a latitudini basse o elevate, a seconda della loro orbita e dei parametri di raccolta dei dati, oppure possono omettere le immagini in base alle condizioni atmosferiche mutevoli.
L'utilizzo di formule negli argomenti include o band_name e il numero di bande coinvolte.
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 dello slot che la funzione è autorizzata a consumare. Il valore predefinito è 350 ore di slot al giorno. Quando visualizzi le quote, filtra l'elenco Metrica su earthengine.googleapis.com/bigquery_slot_usage_time per visualizzare la quota di Earth Engine associata alle chiamate da BigQuery. Per ulteriori informazioni, consulta la sezione sulle quote delle funzioni raster di BigQuery nella documentazione di Google Earth Engine.

Limitazioni

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

US
us-central1
us-central2

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ù sull'utilizzo dei dati geospaziali.