Trabalhar com dados rasterizados usando o Earth Engine no BigQuery

A combinação de dados raster e vetoriais com a função ST_REGIONSTATS permite calcular estatísticas zonais, como a qualidade média do ar ou o risco de incêndio, em regiões geográficas específicas. É possível usar o Google Earth Engine diretamente no BigQuery para analisar imagens de satélite e previsões do tempo com seus limites vetoriais atuais.

Visão geral

Um raster é uma grade bidimensional de pixels, cada um com 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 da imagem comuns, como arquivos PNG ou JPEG, são formatados como dados rasterizados.

Os dados rasterizados costumam ser contrastados com os 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 geoespaciais raster e vetoriais geralmente são combinados usando uma operação de estatísticas zonais, que calcula um agregado de todos os valores raster em uma determinada região vetorial. Por exemplo, talvez você queira calcular o seguinte:

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

O BigQuery é excelente no processamento de dados vetoriais, e o Google Earth Engine é excelente no processamento de dados rasterizados. Use a função geográfica ST_REGIONSTATS 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 receber 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)
• Inscrever-se em 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 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 funções personalizadas 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 de rasterização.

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 garantir que você tenha 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 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 de uma coleção de imagens rasterizadas seguindo a especificação de itens do STAC. Uma tabela de imagens é análoga a um acervo de imagens do Earth Engine (ImageCollection).

Cada linha na tabela corresponde a uma única imagem rasterizada, com colunas contendo propriedades e metadados da imagem. O ID de raster de cada imagem é armazenado na coluna assets.image.href. Faça referência a imagens de referência nas suas 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 imagem inclui uma tabela *_metadata correspondente que fornece informações de suporte para a tabela de imagem.

Por exemplo, o conjunto de dados ERA5-Land fornece estatísticas diárias de variáveis climáticas e está disponível publicamente. A tabela climate contém vários IDs de raster. A consulta a seguir filtra a tabela de imagens usando a coluna start_datetime para receber o ID do raster 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 é compatível com 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 do raster, como gs://bucket/folder/raster.tif.

Recursos de imagem do Earth Engine

A função ST_REGIONSTATS aceita a 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 estão na região US e são compatíveis apenas com consultas executadas na região US. Para encontrar o ID de uma imagem rasterizada, siga estas etapas:

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

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 do raster será 'ee://IMAGE_PATH'.

   Se o snippet do Earth Engine estiver no formato ee.ImageCollection('IMAGE_COLLECTION_PATH'), use o editor de código do Earth Engine para filtrar o ImageCollection em uma única imagem. Use o método ee.Image.get('system:id') para mostrar o valor de IMAGE_PATH dessa imagem no console. O ID do raster é '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 função ST_REGIONSTATS, que determina o peso de cada pixel nos cálculos. Os valores de peso precisam variar de 0 a 1. As ponderações fora desse intervalo são definidas 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 sensores, erros de processamento 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 se enquadra na 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 interseccionado tiver um peso do argumento include para ST_REGIONSTATS, o BigQuery vai usar o mínimo desse peso e a fração do pixel que intersecciona a região.

Os valores de peso não têm a mesma precisão que os valores de FLOAT64. Na prática, o valor real 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 pixels dinamicamente com base em critérios específicos nas bandas raster. 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 ponderação, 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 em pixels 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 10 metros por 10 metros. O tamanho original do pixel informado pode variar drasticamente entre os 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 raster é 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 sobre a região, como lotes de cidades, pode não fornecer detalhes suficientes.

Para conseguir resultados significativos e eficientes na análise, recomendamos escolher um tamanho de pixel adequado ao tamanho dos polígonos e ao objetivo da análise. Você pode encontrar o tamanho do pixel de cada conjunto de dados raster na seção de descrição das tabelas de imagens no BigQuery Sharing.

Mudar o tamanho do pixel altera o número de pixels que se cruzam com uma determinada geografia, o que afeta os resultados e a interpretação deles. Não recomendamos alterar o tamanho do pixel para análises de produção. No entanto, se você estiver prototipando uma consulta, aumentar o tamanho do pixel pode 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 o scale no argumento options para a 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 lida com 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 central 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. Esse uso é cobrado em horas de slot na SKU do BigQuery Services, independentemente de você usar o faturamento on demand ou as reservas. Para conferir o valor cobrado pelas chamadas do BigQuery para o Earth Engine, acesse seu relatório de faturamento e use rótulos para filtrar pela chave de rótulo goog-bq-feature-type, com o valor EARTH_ENGINE. Se a função ST_REGIONSTATS falhar, você não vai receber cobranças por nenhuma computação do Earth Engine que tenha sido usada.

Para cada consulta, use o método jobs.get na API BigQuery para ver as seguintes informações:

• O campo slotMs, que mostra o número de milissegundos de slot consumidos pelo Earth Engine quando o campo externalService é EARTH_ENGINE e o campo billingMethod é 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 de 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 do BigQuery Services.

Fatores de custo

Os fatores a seguir afetam o uso de computação quando você executa 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 com base em coleções de imagens de origem no Data Catalog do Earth Engine, e os recursos computacionais para produzir o resultado composto variam.
• A resolução da imagem.
• O tamanho e a complexidade da região geográfica de entrada, o número de pixels que se cruzam com a região geográfica 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 de acordo com a região 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 mudanças nas condições atmosféricas.

• 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 é 350 horas de slot por dia. Ao visualizar suas cotas, filtre a lista Métrica para earthengine.googleapis.com/bigquery_slot_usage_time para ver a cota do Earth Engine associada às chamadas do BigQuery. Para mais informações, leia sobre as cotas de funções raster do BigQuery na documentação do Google Earth Engine.

Observação : assim como as cotas de consulta personalizadas no BigQuery, essa cota é aproximada. Ele oferece uma proteção contra gastos excessivos, mas não foi projetado para limitar estritamente o tempo de slot. De vez em quando, o BigQuery pode executar uma consulta que exceda o limite da cota, e você pode esgotar sua cota sem receber uma cobrança 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.