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

Uma raster é uma grade bidimensional de pixels, cada um 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 faixas para a temperatura e a 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 raster.

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

  • Qualidade do ar média em cada município do seu estado.
  • Potencial solar para uma coleção de polígonos de edifícios.
  • Resumo do risco de incêndio ao longo dos corredores de linhas de transmissão em áreas florestais.

O BigQuery é excelente para processar dados vetoriais, e o Google Earth Engine é excelente para processar dados de raster. É possível usar a função geográfica ST_REGIONSTATS para combinar dados raster 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 compartilhamento do BigQuery (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:

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 raster

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 de raster.

Tabelas de imagens do BigQuery

Você pode usar o compartilhamento do BigQuery (antigo Analytics Hub) para descobrir e acessar conjuntos de dados raster no BigQuery. Para usar o compartilhamento do BigQuery, é necessário ativar a API Analytics Hub e garantir que você tenha as permissões necessárias para visualizar e assinar listagens.

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

  1. Acesse a página Compartilhamento.

    Acessar "Compartilhamento"

  2. Clique em Pesquisar anúncios.

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

  4. Clique em um conjunto de dados para 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 seu 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 do 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 de raster de cada imagem é armazenado na coluna assets.image.href. Para encontrar uma imagem específica, você pode filtrar por propriedades de imagem na coluna properties. Você pode encontrar informações sobre as bandas 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 de 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 oferece suporte a dados raster 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 oferece suporte à transmissão de 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 o conjunto de dados do 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 fragmento do Earth Engine descreve uma única imagem ou uma coleção de imagens.

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

    Se o snippet do Earth Engine for do tipo ee.ImageCollection('IMAGE_COLLECTION_PATH'), use 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'.

Pesos de pixels

É 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 pesar 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. Os pixels inválidos geralmente representam dados ausentes ou não confiáveis, como áreas obscuradas por nuvens, anomalias do sensor, 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 está dentro da geometria, permitindo a inclusão proporcional nas estatísticas zonais.

Se um pixel parcialmente que se cruza tem um peso do argumento include para ST_REGIONSTATS, o BigQuery usa 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 dos valores de FLOAT64. Na prática, o valor real pode ser até 1/256 (cerca de 0,4%) diferente do valor usado nas computações.

É 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 ultrapassa 70%:

include => 'probability > 0.7'

Se o conjunto de dados incluir uma faixa de fator de peso, ela poderá ser usada com a seguinte sintaxe:

include => 'weight_factor_band_name'

Tamanho do pixel e escala da análise

Uma imagem raster 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 10 x 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, a agregação de dados raster de alta resolução na região de um país pode ser computacionalmente intensa e desnecessariamente granular. Por outro lado, a agregação de dados de baixa resolução na região, como parcelas da cidade, pode não fornecer detalhes suficientes.

Para obter resultados significativos e eficientes da sua análise, recomendamos escolher um tamanho de pixel adequado para o tamanho dos polígonos e o 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 compartilhamento do BigQuery.

Alterar o tamanho do pixel muda o número de pixels que se cruzam em uma determinada região, 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, principalmente 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 amostrar a imagem na escala solicitada. Para saber mais sobre como o Earth Engine processa a redimensionamento, consulte Escala na documentação do Google Earth Engine.

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. O faturamento desse uso é feito em horas de slot no SKU dos Serviços do BigQuery, independente de você usar o faturamento sob demanda ou as reservas. Para conferir o valor faturado das 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.

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 raster que você usa. Alguns rasters são compostos criados 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 região geográfica de entrada, o número de pixels que cruzam 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 a projeção e resolução da imagem.

    • As projeções de imagem podem distorcer pixels, especialmente pixels em altas latitudes 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 dos parâmetros de órbita e coleta de dados, ou podem omitir imagens dependendo das 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. Ao acessar suas cotas, filtre a lista Métrica para earthengine.googleapis.com/bigquery_slot_usage_time e conferir a cota do Earth Engine associada às chamadas do BigQuery. Para mais informações, leia sobre as cotas de funções de 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