Lavora con i dati raster utilizzando Earth Engine in BigQuery

La combinazione di dati raster e vettoriali con la funzione ST_REGIONSTATS consente di calcolare statistiche zonali, come la qualità media dell'aria o il rischio di incendio, in regioni geografiche specifiche. Puoi utilizzare Google Earth Engine direttamente in BigQuery per analizzare le immagini satellitari e le previsioni meteo insieme ai confini vettoriali esistenti.

Panoramica

Un raster è una griglia bidimensionale di pixel, a ciascuno dei quali vengono assegnati uno o più valori chiamati bande. Ad esempio, ogni pixel potrebbe corrispondere a un chilometro quadrato specifico 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 le previsioni del meteo e la copertura del suolo. Molti formati di immagine comuni, come i file PNG o JPEG, sono formattati come dati raster.

I dati raster vengono spesso contrapposti ai 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'aggregazione di tutti i valori raster all'interno di una determinata regione vettoriale. Ad esempio, potresti voler calcolare quanto segue:

• Qualità dell'aria media in un insieme di città.
• Potenziale solare per una raccolta di poligoni di edifici.
• Rischio di incendio riepilogato 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 sottoscrivere 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:

• Earth Engine Resource Viewer (roles/earthengine.viewer)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• Sottoscrivi i set di dati nella condivisione di BigQuery: 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 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.

Trova 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 sottoscrivere schede e exchange di dati.

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

1. Vai alla pagina Sharing (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 iscriverti.

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 memorizza i metadati per una raccolta di immagini raster seguendo 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 di ogni immagine viene memorizzato nella colonna assets.image.href. Fai riferimento alle immagini di riferimento nelle query utilizzando questo ID come valore parametro del 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 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 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 per l'utilizzo di BigQuery DataFrames. Per saperne di più, 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 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 di Earth Engine

La funzione ST_REGIONSTATS supporta il passaggio di un percorso dell'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, segui questi passaggi:

1. Cerca nel Data Catalog 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 è nel formato ee.Image('IMAGE_PATH'), l'ID raster è 'ee://IMAGE_PATH'.

   Se lo snippet di Earth Engine è nel 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 valore IMAGE_PATH per l'immagine nella console. 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 ponderazione 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 di solito rappresentano dati mancanti o inaffidabili, come aree oscurate da nuvole, anomalie dei sensori, errori di elaborazione o posizioni 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 della dimensione 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 pari a 0.

Se un pixel parzialmente intersecante ha un peso dall'argomento include a ST_REGIONSTATS, BigQuery utilizza il valore 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 reale potrebbe differire dal valore utilizzato nei calcoli fino a 1/256 (circa lo 0,4%).

Puoi fornire un'espressione utilizzando la sintassi delle espressioni delle immagini 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 in pixel e scala di analisi

Un'immagine raster geospaziale è una griglia di pixel che corrisponde a una determinata 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 risoluzione di 10 metri ha pixel di dimensioni 10 x 10 metri. Le dimensioni dei pixel originali riportate 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 dei pixel dei dati raster è un fattore cruciale. Ad esempio, l'aggregazione di dati raster ad alta risoluzione sulla regione di un paese può essere computazionalmente intensiva e inutilmente granulare. Al contrario, l'aggregazione di dati a bassa risoluzione sulla regione, come i lotti della città, potrebbe non fornire dettagli sufficienti.

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

La modifica delle dimensioni dei pixel cambia il 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 creando il prototipo di 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 sulla 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 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 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 baricentro 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 ti viene addebitato in ore di slot con lo SKU dei servizi BigQuery, 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 di etichetta goog-bq-feature-type, con valore EARTH_ENGINE. Se la funzione ST_REGIONSTATS non va a buon fine, non ti verrà 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 di BigQuery fatturati nello SKU dei servizi BigQuery.

Puoi anche eseguire una query sul campo total_services_sku_slot_ms nella vista INFORMATION_SCHEMA.JOBS per trovare i millisecondi slot totali consumati dai servizi esterni fatturati nello SKU dei servizi BigQuery.

Fattori di costo

I seguenti fattori influiscono sull'utilizzo del computing quando esegui la funzione ST_REGIONSTATS:

• Il numero di righe di input.
• L'immagine raster che utilizzi. Alcuni raster sono immagini composite create da raccolte di immagini di origine nel Data Catalog 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 di input sulla Terra rispetto alle immagini di origine, nonché la proiezione e la risoluzione dell'immagine.

  • Le proiezioni delle immagini possono deformare 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 l'area geografica di input può variare in base alla regione 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 immagini a seconda delle condizioni atmosferiche mutevoli.

• 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ù, consulta le quote delle funzioni raster di BigQuery nella documentazione di Google Earth Engine.

Nota: come le quote per le query personalizzate in BigQuery, questa quota è approssimativa. Fornisce una protezione contro le spese eccessive, ma non è progettato per limitare rigorosamente il tempo degli slot. BigQuery potrebbe occasionalmente eseguire una query che supera il limite della 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ù sull'utilizzo dei dati geospaziali.