Utilizzare i dati raster con Earth Engine in BigQuery

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

Panoramica

Un raster è una griglia bidimensionale di pixel, a ognuno dei quali vengono assegnati uno o più valori chiamati bande. Ad esempio, ogni pixel potrebbe corrispondere a un particolare 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 griglia, come previsioni meteorologiche e copertura del suolo. Molti formati di 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 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à media dell'aria 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 è eccellente nell'elaborazione dei dati vettoriali, mentre Google Earth Engine è eccellente nell'elaborazione dei dati raster. Puoi utilizzare la ST_REGIONSTATS funzione geografica 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 nel progetto:

• Visualizzatore risorse Earth Engine (roles/earthengine.viewer)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• Abbonati ai set di dati in BigQuery sharing: Editor dati BigQuery (roles/bigquery.dataEditor)

Per saperne di più 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 visualizzare le autorizzazioni esatte 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 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 scoprire e accedere ai set di dati raster in BigQuery. Per utilizzare BigQuery sharing, devi abilitare l'API Analytics Hub e assicurarti di disporre delle autorizzazioni necessarie per visualizzare e abbonarti alle schede e agli scambi di dati.

Google Earth Engine pubblica set di dati disponibili pubblicamente che contengono dati raster nelle multi-regioni US e EU. Per abbonarti a un set di dati di Earth Engine con dati raster:

1. Vai alla pagina Sharing (Analytics Hub).

   Vai a Sharing (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 di immagini che archivia i metadati per una raccolta di immagini raster che seguono la 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 proprietà e 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 sulle bande disponibili, sulle dimensioni dei pixel e sulle definizioni delle proprietà, apri la tabella e fai clic sulla scheda Dettagli immagine.

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

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

SQL

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;

BigQuery DataFrames

Prima di provare questo esempio, segui le istruzioni di configurazione di BigQuery DataFrames nella guida rapida di BigQuery utilizzando BigQuery DataFrames. Per ulteriori informazioni, consulta la documentazione di riferimento di BigQuery DataFrames.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

import datetime
from typing import cast

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# TODO: Set the project_id to your Google Cloud project ID.
# project_id = "your-project-id"
bpd.options.bigquery.project = project_id

# TODO: Set the dataset_id to the ID of the dataset that contains the
# `climate` table. This is likely a linked dataset to Earth Engine.
# See: https://cloud.google.com/bigquery/docs/link-earth-engine
linked_dataset = "era5_land_daily_aggregated"

# For the best efficiency, use partial ordering mode.
bpd.options.bigquery.ordering_mode = "partial"

# Load the table of country boundaries.
countries = bpd.read_gbq("bigquery-public-data.overture_maps.division_area")

# Filter to just the countries.
countries = countries[countries["subtype"] == "country"].copy()
countries["name"] = countries["names"].struct.field("primary")
countries["simplified_geometry"] = bbq.st_simplify(
    countries["geometry"],
    tolerance_meters=10_000,
)

# Get the reference to the temperature data from a linked dataset.
# Note: This sample assumes you have a linked dataset to Earth Engine.
image_href = (
    bpd.read_gbq(f"{project_id}.{linked_dataset}.climate")
    .set_index("start_datetime")
    .loc[[datetime.datetime(2025, 1, 1, tzinfo=datetime.timezone.utc)], :]
)
raster_id = image_href["assets"].struct.field("image").struct.field("href")
raster_id = raster_id.item()
stats = bbq.st_regionstats(
    countries["simplified_geometry"],
    raster_id=cast(str, raster_id),
    band="temperature_2m",
)

# Extract the mean and convert from Kelvin to Celsius.
countries["mean_temperature"] = stats.struct.field("mean") - 273.15

# Sort by the mean temperature to find the warmest countries.
result = countries[["name", "mean_temperature"]].sort_values(
    "mean_temperature", ascending=False
)
print(result.head(10))

GeoTIFF di Cloud Storage

GeoTIFF è un formato di 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:

• Multi-regione US
• us-central1
• Multi-regione EU
• 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 di asset immagine 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 di 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 di Earth Engine ha il formato ee.Image('IMAGE_PATH'), l'ID raster è 'ee://IMAGE_PATH'.

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

Pesi dei pixel

Puoi specificare un peso, a volte chiamato valore della maschera, per il parametro include nella ST_REGIONSTATS funzione che determina la ponderazione 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 peso pari a 0 indica un pixel non valido. I pixel non validi in genere rappresentano dati mancanti o non affidabili, 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, viene restituito null per tutte le statistiche, ad eccezione di count e area, che sono 0.

Se un pixel che si interseca parzialmente ha un peso dall'argomento include a ST_REGIONSTATS, BigQuery utilizza il minimo di quel peso e la 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 0,4%).

Puoi fornire un'espressione utilizzando la sintassi dell'espressione immagine di Earth Engine nell'argomento include per ponderare dinamicamente i pixel in base a criteri specifici all'interno delle bande raster. Ad esempio, l'espressione seguente 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 di fattori di peso, 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 posizione sulla superficie terrestre. Le dimensioni dei pixel di un raster, a volte chiamate la scala, sono le dimensioni nominali 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 per 10 metri. Le dimensioni dei pixel riportate originali possono variare notevolmente tra i set di dati, da meno di 1 metro a più di 20 chilometri.

Quando si utilizza la funzione ST_REGIONSTATS per calcolare le statistiche zonali, le dimensioni dei pixel dei dati raster sono un aspetto fondamentale da considerare. Ad esempio, l'aggregazione di dati raster ad alta risoluzione sulla regione di un paese può essere intensiva dal punto di vista computazionale e inutilmente granulare. Al contrario, l'aggregazione di dati a bassa risoluzione sulla regione, ad esempio i lotti di città, potrebbe non fornire dettagli sufficienti.

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

La modifica delle dimensioni dei pixel cambia il numero di pixel che si intersecano con 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, l'aumento delle 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 sui pixel di 1000 metri, utilizza options => JSON '{"scale":1000}', che indica a Earth Engine di ricampionare l'immagine alla scala richiesta. Per scoprire di più su come Earth Engine gestisce il ridimensionamento, consulta Scala nella documentazione di Google Earth Engine.

Il calcolo delle statistiche per i poligoni che sono 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 di 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. Questo utilizzo viene fatturato in ore di slot nella 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 BigQuery a Earth Engine, visualizza il report sulla fatturazione e utilizza le etichette per filtrare in base alla chiave di etichetta goog-bq-feature-type, con il valore EARTH_ENGINE. Se la funzione ST_REGIONSTATS non riesce, non ti verrà addebitato alcun calcolo di Earth Engine utilizzato.

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

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

Puoi anche eseguire una query sul campo total_services_sku_slot_ms nella visualizzazione INFORMATION_SCHEMA.JOBS per trovare il numero totale di millisecondi di slot consumati dai servizi esterni fatturati nella SKU dei servizi BigQuery.

Elementi 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 di 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 si intersecano con la geografia e il numero di riquadri e byte di immagini letti da Earth Engine.

• La posizione della geografia di input sulla Terra rispetto alle immagini di origine e alla proiezione e alla risoluzione dell'immagine.

  • Le proiezioni delle immagini possono distorcere i pixel, soprattutto 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 si intersecano con 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 possono omettere le immagini a seconda delle condizioni atmosferiche variabili.

• 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 di slot che la funzione può 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 saperne di più, consulta le 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 rigidamente il tempo di slot. A volte è possibile che BigQuery esegua una query che superi il limite di quota e che tu possa 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:

• Multi-regione US
• us-central1
• us-central2
• Multi-regione EU
• 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ù sull'utilizzo dei dati geospaziali.