Trabalhar com dados raster usando o Earth Engine no BigQuery

Este documento explica como combinar dados raster e vetoriais usando a função ST_REGIONSTATS, que chama o Google Earth Engine para realizar análises geoespaciais no BigQuery.

Visão geral

Um raster é uma grade bidimensional de pixels, cada um deles atribuído a um ou mais valores chamados de 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 comuns de imagem, como arquivos PNG ou JPEG, são formatados como dados rasterizados.

Os dados raster são frequentemente contrastados com os dados vetoriais, em que as informações são descritas 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 raster e vetoriais geoespaciais são frequentemente 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.
• Risco de incêndio resumido ao longo de corredores de linhas de energia em áreas florestais.

O BigQuery é excelente para processar dados vetoriais, e o Google Earth Engine é excelente para processar dados raster. Você pode usar a função geográfica ST_REGIONSTATS para combinar dados raster usando o Earth Engine com seus 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 os 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 compartilhamento do BigQuery: 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:

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 raster. As seções a seguir explicam como encontrar e formatar o ID do raster.

Tabelas de imagens do BigQuery

É possível usar o compartilhamento do BigQuery (antigo Analytics Hub) para descobrir e acessar conjuntos de dados raster no BigQuery. Para usar o BigQuery Sharing, você precisa ativar a API Analytics Hub e garantir que tem as permissões necessárias para ver e assinar listagens.

O Google Earth Engine publica conjuntos de dados disponíveis publicamente que contêm dados raster. Para inscrever-se em um conjunto de dados do Earth Engine com dados raster, siga estas etapas:

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

   Acessar Compartilhamento (Analytics Hub)

2. Clique em search Pesquisar fichas.

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

4. Clique no conjunto de dados a que você quer se inscrever.

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 projeto.

O conjunto de dados contém uma tabela, às vezes chamada de tabela de imagens, que armazena metadados de uma coleção de imagens raster 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 raster. O ID do raster de cada imagem é armazenado na coluna assets.image.href. Para encontrar uma imagem específica, filtre por propriedades na coluna properties. Você encontra informações sobre os intervalos na descrição da tabela.

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 properties.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:

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;

GeoTIFF do Cloud Storage

O GeoTIFF é um formato de arquivo comum para armazenar dados raster geoespaciais. A função ST_REGIONSTATS é compatível com dados rasterizados armazenados no formato GeoTIFF em buckets do Cloud Storage localizados nas regiões US ou us-central1. 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 permite transmitir um caminho de recurso de imagem do Earth Engine para o argumento raster_id. Os dados raster do Earth Engine estão disponíveis como imagens individuais ou coleções de imagens. Para encontrar o ID de raster de uma imagem, siga estas etapas:

1. Pesquise no catálogo de dados do Earth Engine o conjunto de dados que você quer.

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 for da forma ee.Image('IMAGE_PATH'), o ID do raster será 'ee://IMAGE_PATH'.

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

Ponderações 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 quanto ponderar 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 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 uma ponderação, cada pixel será ponderado automaticamente pela proporção do pixel que está dentro da geometria, permitindo a inclusão proporcional nas 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 uma ponderação do argumento include para ST_REGIONSTATS, o BigQuery usará o mínimo dessa ponderação e a fração do pixel que se cruza com 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 dinamicamente os pixels 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 um intervalo de fator de ponderação, use-o com a seguinte sintaxe:

include => 'weight_factor_band_name'

Tamanho do pixel e escala da 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 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 raster de alta resolução na região de um país pode ser computacionalmente intenso e desnecessariamente granular. Por outro lado, agregar dados de baixa resolução na região, como lotes urbanos, pode não fornecer detalhes suficientes.

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

Mudar o tamanho do pixel altera o número de pixels que se cruzam em uma determinada região geográfica, 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 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 como 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 reescalonamento, consulte Escala na documentação do Google Earth Engine.

Calcular estatísticas para polígonos significativamente menores que os pixels do raster pode gerar resultados imprecisos ou nulos. Nesse caso, uma alternativa é substituir o polígono pelo ponto 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 de serviços do BigQuery, independente de usar o faturamento sob demanda ou reservas. Para conferir o valor faturado pelas chamadas do BigQuery para o Earth Engine, consulte 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 nenhum cálculo do Earth Engine usado.

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 com base em coleções de imagens de origem no catálogo de dados do Earth Engine, e os recursos computacionais para produzir o resultado da composição 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 e o número de blocos de imagens 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 em altas latitudes ou muito fora da área de cobertura pretendida da imagem.
  • Para rasters compostos, o número de imagens de origem que se cruzam com 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 variáveis.

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

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

Limitações

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

• US
• us-central1
• us-central2

A seguir

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