Trabalhar com dados rasterizados usando o Earth Engine no BigQuery

Este documento explica como combinar dados rasterizados e vetoriais usando a função ST_REGIONSTATS, que usa o Google Earth Engine para acessar dados de imagem e rasterizados no BigQuery.

Visão geral

Um raster é uma grade bidimensional de pixels, cada um deles atribuído a um ou mais valores chamados bandas. Por exemplo, cada pixel pode corresponder a um quilômetro quadrado específico na superfície da Terra e ter bandas para temperatura média e precipitação média. Os dados rasterizados incluem imagens de satélite e outros dados contínuos baseados em grade, como previsões do tempo e cobertura do solo. Muitos formatos de imagem comuns, como arquivos PNG ou JPEG, são formatados como dados rasterizados.

Os dados rasterizados costumam ser contrastados com dados vetoriais, em que os dados são descritos por linhas ou curvas em vez de uma grade retangular fixa. Por exemplo, é possível usar o tipo de dados GEOGRAPHY no BigQuery para descrever os limites de países, cidades ou outras regiões.

Os dados rasterizados e vetoriais geoespaciais costumam ser combinados usando uma operação de estatísticas zonais, que calcula um agregado de todos os valores rasterizados em uma determinada região vetorial. Por exemplo, talvez você queira calcular o seguinte:

• Qualidade média do ar em uma coleção de cidades.
• Potencial solar para uma coleção de polígonos de edifícios.
• Risco de incêndio resumido ao longo de corredores de linhas de energia em áreas florestadas.

O BigQuery se destaca no tratamento de dados vetoriais, e o Google Earth Engine se destaca no tratamento de dados rasterizados. É possível usar a ST_REGIONSTATS função geográfica para combinar dados rasterizados usando o Earth Engine com os dados vetoriais armazenados no BigQuery.

Antes de começar

1. Para usar a função ST_REGIONSTATS nas consultas, ative a API Earth Engine.

   Ativar a API

2. Opcional: para assinar e usar dados publicados no BigQuery Sharing (antigo Analytics Hub) usando a função ST_REGIONSTATS, ative a API Analytics Hub.

   Ativar a API

Permissões necessárias

Para conseguir as permissões necessárias para chamar a função ST_REGIONSTATS peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Leitor de recursos do Earth Engine (roles/earthengine.viewer)
• Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)
• Assinar conjuntos de dados no BigQuery Sharing: Editor de dados do BigQuery (roles/bigquery.dataEditor)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para chamar a função ST_REGIONSTATS. Para conferir as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para chamar a função ST_REGIONSTATS:

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

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Encontrar dados rasterizados

O parâmetro raster_id na função ST_REGIONSTATS é uma string que especifica a origem dos dados rasterizados. As seções a seguir explicam como encontrar e formatar o ID rasterizado.

Tabelas de imagens do BigQuery

É possível usar o BigQuery Sharing (antigo Analytics Hub) para descobrir e acessar conjuntos de dados rasterizados no BigQuery. Para usar o BigQuery Sharing, é necessário ativar a API Analytics Hub e ter as permissões necessárias para visualizar e assinar listagens e trocas de dados.

O Google Earth Engine publica conjuntos de dados disponíveis publicamente que contêm dados rasterizados nas multirregiões US e EU. Para assinar um conjunto de dados do Earth Engine com dados rasterizados, siga estas etapas:

1. Acesse a página Compartilhamento (Analytics Hub).

   Acessar o compartilhamento (Analytics Hub)

2. Clique em Pesquisar listagens.

3. No campo Pesquisar listagens, insira "Google Earth Engine".

4. Clique em um conjunto de dados que você quer assinar.

5. Clique em Assinar.

6. Opcional: atualize os campos Projeto ou Nome do conjunto de dados vinculado.

7. Clique em Salvar. O conjunto de dados vinculado é adicionado ao seu projeto.

O conjunto de dados contém uma tabela de imagens que armazena metadados para uma coleção de imagens rasterizadas seguindo a especificação de itens STAC. Uma tabela de imagens é análoga a uma coleção de imagens do Earth Engine (ImageCollection).

Cada linha na tabela corresponde a uma única imagem rasterizada, com colunas que contêm propriedades e metadados da imagem. O ID rasterizado de cada imagem é armazenado na coluna assets.image.href. Faça referência a imagens nas consultas usando esse ID como o valor de parâmetro raster_id.

Filtre a tabela usando colunas de propriedade para selecionar imagens ou subconjuntos de imagens específicos que atendam aos seus critérios. Para mais informações sobre as bandas disponíveis, o tamanho do pixel e as definições de propriedade, abra a tabela e clique na guia Detalhes da imagem.

Cada tabela de imagens inclui uma tabela *_metadata correspondente que fornece informações de suporte para a tabela de imagens.

Por exemplo, o conjunto de dados ERA5-Land fornece estatísticas de variáveis climáticas diárias e está disponível publicamente. A tabela climate contém vários IDs rasterizados. A consulta a seguir filtra a tabela de imagens usando a coluna start_datetime para receber o ID rasterizado da imagem correspondente a 1º de janeiro de 2025 e calcula a temperatura média de cada país usando a 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

Antes de testar esta amostra, siga as instruções de configuração dos BigQuery DataFrames no Guia de início rápido do BigQuery: como usar os BigQuery DataFrames. Para mais informações, consulte a documentação de referência do BigQuery DataFrames.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

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 do Cloud Storage

O GeoTIFF é um formato de arquivo comum para armazenar dados rasterizados geoespaciais. A função ST_REGIONSTATS oferece suporte a dados rasterizados armazenados no formato GeoTIFF otimizado para nuvem (COG, na sigla em inglês) em buckets do Cloud Storage localizados nas seguintes regiões:

• Multirregião US
• us-central1
• Multirregião EU
• europe-west1

Forneça o URI do Cloud Storage como o ID rasterizado, como gs://bucket/folder/raster.tif.

Recursos de imagem do Earth Engine

A função ST_REGIONSTATS oferece suporte à transmissão de um caminho de recurso de imagem do Earth Engine para o argumento raster_id. Os dados rasterizados do Earth Engine estão disponíveis como imagens individuais ou coleções de imagens. Esses dados existem na região US e são compatíveis apenas com consultas executadas na região US. Para encontrar o ID rasterizado de uma imagem, siga estas etapas:

1. Pesquise o catálogo de dados do Earth Engine para o conjunto de dados de seu interesse.

2. Para abrir a página de descrição dessa entrada, clique no nome do conjunto de dados. O snippet do Earth Engine descreve uma única imagem ou uma coleção de imagens.

   Se o snippet do Earth Engine estiver no formato ee.Image('IMAGE_PATH'), o ID rasterizado será 'ee://IMAGE_PATH'.

   Se o snippet do Earth Engine estiver no formato ee.ImageCollection('IMAGE_COLLECTION_PATH'), você pode usar o editor de código do Earth Engine para filtrar o ImageCollection para uma única imagem. Use o método ee.Image.get('system:id') para imprimir o IMAGE_PATH valor dessa imagem no console. O ID rasterizado é 'ee://IMAGE_PATH'.

Pesos de pixel

É possível especificar um peso, às vezes chamado de valor de máscara, para o parâmetro include na ST_REGIONSTATS função que determina quanto ponderar cada pixel nos cálculos. Os valores de peso precisam variar de 0 a 1. Os pesos fora desse intervalo são definidos como o limite mais próximo, 0 ou 1.

Um pixel é considerado válido se tiver um peso maior que 0. Um peso de 0 indica um pixel inválido. Pixels inválidos geralmente representam dados ausentes ou não confiáveis, como áreas obscurecidas por nuvens, anomalias de sensor, erros de tratamento ou locais fora de um limite definido.

Se você não especificar um peso, cada pixel será ponderado automaticamente pela proporção do pixel que está dentro da geometria, permitindo a inclusão proporcional em estatísticas zonais. Se a geometria for menor que 1/256 do tamanho do pixel, o peso do pixel será 0. Nesses casos, null é retornado para todas as estatísticas, exceto count e area, que são 0.

Se um pixel parcialmente sobreposto tiver um peso do argumento include para ST_REGIONSTATS, o BigQuery usará o mínimo desse peso e a fração do pixel que cruza a região.

Os valores de peso não têm a mesma precisão que os valores FLOAT64. Na prática, o valor verdadeiro pode ser diferente do valor usado nos cálculos em até 1/256 (cerca de 0,4%).

É possível fornecer uma expressão usando a sintaxe de expressão de imagem do Earth Engine no argumento include para ponderar dinamicamente os pixels com base em critérios específicos nas bandas rasterizadas. Por exemplo, a expressão a seguir restringe os cálculos a pixels em que a banda probability excede 70%:

include => 'probability > 0.7'

Se o conjunto de dados incluir uma banda de fator de peso, use-a com a seguinte sintaxe:

include => 'weight_factor_band_name'

Tamanho do pixel e escala de análise

Uma imagem rasterizada geoespacial é uma grade de pixels que corresponde a algum local na superfície da Terra. O tamanho do pixel de um raster, às vezes chamado de escala, é o tamanho nominal de uma borda de um pixel no sistema de referência de coordenadas da grade. Por exemplo, um raster com resolução de 10 metros tem pixels de tamanho 10 metros por 10 metros. O tamanho original do pixel informado pode variar muito entre conjuntos de dados, de menos de 1 metro a mais de 20 quilômetros.

Ao usar a função ST_REGIONSTATS para calcular estatísticas zonais, o tamanho do pixel dos dados rasterizados é uma consideração crucial. Por exemplo, agregar dados rasterizados de alta resolução na região de um país pode ser computacionalmente intensivo e desnecessariamente granular. Por outro lado, agregar dados de baixa resolução na região, como parcelas de cidades, pode não fornecer detalhes suficientes.

Para receber resultados significativos e eficientes da análise, recomendamos escolher um tamanho de pixel adequado para o tamanho dos polígonos e o objetivo da análise. É possível encontrar o tamanho do pixel de cada conjunto de dados rasterizados na seção de descrição das tabelas de imagens no BigQuery Sharing.

A mudança do tamanho do pixel altera o número de pixels que cruzam uma determinada geografia, o que afeta os resultados e a interpretação deles. Não recomendamos mudar o tamanho do pixel para análises de produção. No entanto, se você estiver criando um protótipo de consulta, aumentar o tamanho do pixel poderá reduzir o tempo de execução e o custo da consulta, especialmente para dados de alta resolução.

Para mudar o tamanho do pixel, defina a scale no argumento options da função ST_REGIONSTATS. Por exemplo, para calcular estatísticas em pixels de 1.000 metros, use options => JSON '{"scale":1000}', que informa ao Earth Engine para reamostrar a imagem na escala solicitada. Para saber mais sobre como o Earth Engine processa o redimensionamento, consulte Escala na documentação do Google Earth Engine.

O cálculo de estatísticas para polígonos significativamente menores que os pixels do raster pode produzir resultados imprecisos ou nulos. Nesse caso, uma alternativa é substituir o polígono pelo ponto do centroide usando ST_CENTROID.

Faturamento

Quando você executa uma consulta, o uso da função ST_REGIONSTATS é faturado separadamente do restante da consulta porque o Earth Engine calcula os resultados da chamada de função. Você é cobrado por esse uso em horas de slot na SKU dos serviços do BigQuery, independentemente de usar o faturamento sob demanda ou reservas. Para conferir o valor faturado pelas chamadas do BigQuery para o Earth Engine, consulte o relatório de faturamento e use rótulos para filtrar pela chave do rótulo goog-bq-feature-type, com o valor EARTH_ENGINE. Se a função ST_REGIONSTATS falhar, você não será cobrado por nenhum cálculo do Earth Engine usado.

Para cada consulta, é possível usar o jobs.get método na API BigQuery para conferir as seguintes informações:

• O slotMs campo, que mostra o número de milissegundos de slot consumidos pelo Earth Engine quando o externalService campo é EARTH_ENGINE e o billingMethod campo é SERVICES_SKU.
• O campo totalServicesSkuSlotMs que mostra o número total de milissegundos de slot usados por todos os serviços externos do BigQuery que são faturados na SKU dos serviços do BigQuery.

Também é possível consultar o campo total_services_sku_slot_ms na visualização INFORMATION_SCHEMA.JOBS para encontrar o total de milissegundos de slot consumidos por serviços externos faturados na SKU dos serviços do BigQuery.

Fatores de custo

Os fatores a seguir afetam o uso de computação ao executar a função ST_REGIONSTATS:

• O número de linhas de entrada.
• A imagem rasterizada que você usa. Alguns rasters são composições criadas a partir de coleções de imagens de origem no catálogo de dados do Earth Engine, e os recursos computacionais para produzir o resultado composto variam.
• A resolução da imagem.
• O tamanho e a complexidade da geografia de entrada, o número de pixels que cruzam a geografia e o número de blocos de imagem e bytes lidos pelo Earth Engine.

• A localização da geografia de entrada na Terra em relação às imagens de origem e à projeção e resolução da imagem.

  • As projeções de imagem podem distorcer pixels, especialmente pixels em latitudes altas ou muito fora da área de cobertura pretendida da imagem.
  • Para rasters compostos, o número de imagens de origem que cruzam a geografia de entrada pode variar regionalmente e ao longo do tempo. Por exemplo, alguns satélites produzem mais imagens em latitudes baixas ou altas, dependendo da órbita e dos parâmetros de coleta de dados, ou podem omitir imagens dependendo das condições atmosféricas em mudança.

• O uso de fórmulas nos argumentos include ou band_name e o número de bandas envolvidas.

• O armazenamento em cache de resultados anteriores.

Controla os custos

Para controlar os custos associados à função ST_REGIONSTATS, ajuste a cota que controla a quantidade de tempo de slot que a função pode consumir. O padrão é de 350 horas de slot por dia. Ao visualizar as cotas, filtre a lista Métrica para earthengine.googleapis.com/bigquery_slot_usage_time para conferir a cota do Earth Engine associada a chamadas do BigQuery. Para mais informações, leia sobre as cotas de funções rasterizadas do BigQuery na documentação do Google Earth Engine.

Observação: assim como as cotas de consultas personalizadas no BigQuery, essa cota é aproximada. Ela oferece uma proteção contra gastos excessivos, mas não foi projetada para limitar estritamente o tempo de slot. O BigQuery pode ocasionalmente executar uma consulta que exceda o limite de cota, e você pode esgotar a cota sem ser cobrado pelo valor total consumido.

Regiões compatíveis

As consultas que chamam a função ST_REGIONSTATS precisam ser executadas em uma das seguintes regiões:

• Multirregião US
• us-central1
• us-central2
• Multirregião EU
• europe-west1

A seguir

• Confira o tutorial que mostra como usar dados rasterizados para analisar a temperatura.
• Saiba mais sobre as funções geográficas no BigQuery.
• Saiba mais sobre como trabalhar com dados geoespaciais.