Utilizzare i dati raster con Earth Engine in BigQuery

Questo documento spiega come combinare dati raster e vettoriali utilizzando la funzione ST_REGIONSTATS, che chiama Google Earth Engine per eseguire l'analisi geospaziale 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 pioggia media. 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 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 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 nel progetto:

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 richieste 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. Nelle sezioni seguenti viene spiegato 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 BigQuery sharing, 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. 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, a volte chiamata 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. L'ID raster per ogni immagine è memorizzato 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 tabella climate contiene più ID raster. La seguente query filtra la tabella delle immagini utilizzando la colonna properties.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  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;

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 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 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. 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 Earth Engine è del modulo 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 sulla 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 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, come i lotti di 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 scoprire di più su come Earth Engine gestisce il ridimensionamento, consulta Scale nella documentazione di Google Earth Engine.

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. L'utilizzo viene fatturato in ore di slot in base allo 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 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 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 ulteriori informazioni, leggi le informazioni sulle quote delle funzioni raster di BigQuery nella documentazione di Google Earth Engine.

Limitazioni

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

  • US
  • us-central1
  • us-central2

Passaggi successivi