Trabalhe com dados rasterizados através do Earth Engine no BigQuery

Este documento explica como combinar dados raster e vetoriais através da função ST_REGIONSTATS, que usa o Google Earth Engine para aceder a dados de imagens e raster no BigQuery.

Vista geral

Um raster é uma grelha bidimensional de píxeis, a cada um dos quais é atribuído um ou mais valores denominados bandas. Por exemplo, cada píxel pode corresponder a um quilómetro quadrado específico na superfície da Terra e ter faixas para a temperatura média e a precipitação média. Os dados raster incluem imagens de satélite e outros dados contínuos baseados em grelhas, como previsões meteorológicas e cobertura do solo. Muitos formatos de imagem comuns, como ficheiros PNG ou JPEG, estão formatados como dados raster.

Os dados raster são frequentemente contrastados com os dados vetoriais, nos quais os dados são descritos por linhas ou curvas, em vez de uma grelha retangular fixa. Por exemplo, pode 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 através de uma operação de estatísticas zonais, que calcula um agregado de todos os valores raster numa determinada região vetorial. Por exemplo, pode querer calcular o seguinte:

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

O BigQuery destaca-se no tratamento de dados vetoriais e o Google Earth Engine destaca-se no tratamento de dados raster. Pode usar a ST_REGIONSTATS função de geografia para combinar dados rasterizados através do Earth Engine com os seus dados vetoriais armazenados no BigQuery.

Antes de começar

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

   Ative a API

2. Opcional: para subscrever e usar dados publicados na partilha do BigQuery (anteriormente Analytics Hub) através da função ST_REGIONSTATS, ative a API Analytics Hub.

   Ative a API

Autorizações necessárias

Para receber as autorizações de que precisa para chamar a função ST_REGIONSTATS, peça ao seu administrador para lhe conceder as seguintes funções da IAM no seu projeto:

• Earth Engine Resource Viewer (roles/earthengine.viewer)
• Consumidor de utilização do serviço (roles/serviceusage.serviceUsageConsumer)
• Inscreva-se em conjuntos de dados na partilha do BigQuery: Editor de dados do BigQuery (roles/bigquery.dataEditor)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Estas funções predefinidas contêm as autorizações necessárias para chamar a função ST_REGIONSTATS. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para chamar a função ST_REGIONSTATS:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Encontre dados rasterizados

O parâmetro raster_id na função ST_REGIONSTATS é uma string que especifica a origem dos seus dados raster. As secções seguintes explicam como encontrar e formatar o ID raster.

Tabelas de imagens do BigQuery

Pode usar a partilha do BigQuery (anteriormente Analytics Hub) para descobrir e aceder a conjuntos de dados raster no BigQuery. Para usar a partilha do BigQuery, tem de ativar a API Analytics Hub e garantir que tem as autorizações necessárias para ver e subscrever fichas.

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

1. Aceda à página Partilha (Centro de análise).

   Aceda à partilha (Analytics Hub)

2. Clique em Pesquisar fichas.

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

4. Clique num conjunto de dados ao qual quer subscrever.

5. Clique em Subscrever.

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

7. Clique em Guardar. O conjunto de dados associado é adicionado ao seu projeto.

O conjunto de dados contém uma tabela de imagens que armazena metadados para uma coleção de imagens raster de acordo com 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, com colunas que contêm propriedades e metadados da imagem. O ID raster de cada imagem é armazenado na coluna assets.image.href. Faça referência a imagens nas suas consultas através deste ID como o valor do parâmetro raster_id.

Filtre a tabela através das colunas de propriedades para selecionar imagens específicas ou subconjuntos de imagens que cumprem os seus critérios. Para mais informações sobre as bandas disponíveis, o tamanho dos píxeis e as definições das propriedades, abra a tabela e clique no separador Detalhes da imagem.

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

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 contém vários IDs de raster.climate A seguinte consulta filtra a tabela de imagens usando a coluna start_datetime para obter o ID raster da imagem correspondente a 1 de janeiro de 2025 e calcula a temperatura média para 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 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 ficheiro comum para armazenar dados raster geoespaciais. A função ST_REGIONSTATS suporta dados rasterizados armazenados no formato Cloud Optimized GeoTIFF (COG) em contentores do Cloud Storage localizados nas seguintes regiões:

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

Indique o URI do Cloud Storage como o ID do raster, por exemplo: gs://bucket/folder/raster.tif.

Recursos de imagens do Earth Engine

A função ST_REGIONSTATS suporta a 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. Estes dados existem na região US e só são compatíveis com consultas executadas na região US. Para encontrar o ID raster de uma imagem, siga estes passos:

1. Pesquise no catálogo de dados do Earth Engine o conjunto de dados que lhe interessa.

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 fragmento do Earth Engine for do formulário ee.Image('IMAGE_PATH'), o ID do raster é 'ee://IMAGE_PATH'.

   Se o fragmento do Earth Engine for do formulário ee.ImageCollection('IMAGE_COLLECTION_PATH'), 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 valor IMAGE_PATH dessa imagem na consola. O ID da imagem raster é 'ee://IMAGE_PATH'.

Pesos dos píxeis

Pode especificar um peso, por vezes denominado 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 têm de variar entre 0 e 1. Os pesos fora deste intervalo são definidos para o limite mais próximo, ou seja, 0 ou 1.

Um píxel é considerado válido se tiver um peso superior a 0. Uma ponderação de 0 indica um píxel inválido. Normalmente, os píxeis inválidos representam dados em falta ou não fiáveis, como áreas obscurecidas por nuvens, anomalias dos sensores, erros de processamento ou localizações fora de um limite definido.

Se não especificar um peso, cada píxel é automaticamente ponderado pela proporção do píxel que se enquadra na geometria, o que permite a inclusão proporcional nas estatísticas zonais. Se a geometria for inferior a 1/256 do tamanho do píxel, o peso do píxel é 0. Nestes casos, é devolvido null para todas as estatísticas, exceto count e area, que são 0.

Se um píxel parcialmente intersetado tiver um peso do argumento include para ST_REGIONSTATS, o BigQuery usa o mínimo desse peso e a fração do píxel que interseta 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 diferir do valor usado nos cálculos até 1/256 (cerca de 0,4%).

Pode fornecer uma expressão através da sintaxe de expressão de imagem do Earth Engine no argumento include para ponderar dinamicamente os píxeis com base em critérios específicos nas bandas raster. Por exemplo, a expressão seguinte restringe os cálculos aos píxeis em que a banda probability excede 70%:

include => 'probability > 0.7'

Se o conjunto de dados incluir uma banda de fator de ponderação, pode usá-la com a seguinte sintaxe:

include => 'weight_factor_band_name'

Tamanho do píxel e escala da análise

Uma imagem raster geoespacial é uma grelha de píxeis que corresponde a alguma localização na superfície da Terra. O tamanho do píxel de um raster, por vezes denominado escala, é o tamanho nominal de um limite de um píxel no sistema de referência de coordenadas da grelha. Por exemplo, um raster com uma resolução de 10 metros tem píxeis de 10 metros por 10 metros. A dimensão do píxel comunicada original pode variar drasticamente entre conjuntos de dados, desde menos de 1 metro a mais de 20 quilómetros.

Quando usa a função ST_REGIONSTATS para calcular estatísticas zonais, a dimensão dos píxeis 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 intensiva e desnecessariamente detalhada. 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 que escolha um tamanho do píxel adequado ao tamanho dos seus polígonos e ao objetivo da sua análise. Pode encontrar o tamanho do píxel de cada conjunto de dados raster na secção de descrição das tabelas de imagens na partilha do BigQuery.

A alteração do tamanho do píxel altera o número de píxeis que se intersetam com uma determinada geografia, o que afeta os resultados e a respetiva interpretação. Não recomendamos que altere a dimensão dos píxeis para análises de produção. No entanto, se estiver a criar um protótipo de uma consulta, aumentar o tamanho do píxel pode reduzir o tempo de execução e o custo da consulta, especialmente para dados de alta resolução.

Para alterar o tamanho em píxeis, defina o valor scale no argumento options para a função ST_REGIONSTATS. Por exemplo, para calcular estatísticas sobre píxeis de 1000 metros, use options => JSON '{"scale":1000}', que indica ao Earth Engine para voltar a amostrar a imagem na escala pedida. 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 mais pequenos do que os píxeis da imagem raster pode produzir resultados imprecisos ou nulos. Nesse caso, uma alternativa é substituir o polígono pelo respetivo ponto centroide através de ST_CENTROID.

Faturação

Quando executa uma consulta, a utilização da função ST_REGIONSTATS é faturada separadamente do resto da consulta porque o Earth Engine calcula os resultados da chamada de função. Esta utilização é faturada em horas de slots ao abrigo do SKU dos serviços do BigQuery, independentemente de usar a faturação a pedido ou as reservas. Para ver o valor faturado pelas chamadas do BigQuery para o Earth Engine, consulte o seu relatório de faturação e use etiquetas para filtrar pela chave da etiqueta goog-bq-feature-type, com o valor EARTH_ENGINE. Se a função ST_REGIONSTATS falhar, não lhe é faturada nenhuma computação do Earth Engine que tenha sido usada.

Para cada consulta, pode usar 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 espaço 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 slots usados por todos os serviços externos do BigQuery que são faturados na SKU dos serviços do BigQuery.

Fatores de custo

Os seguintes fatores afetam a utilização de computação quando executa a função ST_REGIONSTATS:

• O número de linhas de entrada.
• A imagem raster que usa. Alguns rasteres 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 geografia de entrada, o número de píxeis que se cruzam com a geografia e o número de mosaicos de imagens e bytes lidos pelo Earth Engine.

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

  • As projeções de imagens podem distorcer os píxeis, especialmente os píxeis a latitudes elevadas ou muito fora da área de cobertura pretendida da imagem.
  • Para os rásteres 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 a latitudes baixas ou altas, consoante a respetiva órbita e parâmetros de recolha de dados, ou podem omitir imagens consoante as condições atmosféricas em mudança.

• A utilização de fórmulas nos argumentos include ou band_name e o número de bandas que envolvem.

• O armazenamento em cache dos resultados anteriores.

Controlar os custos

Para controlar os custos associados à função ST_REGIONSTATS, pode ajustar a quota que controla a quantidade de tempo de intervalo que a função pode consumir. A predefinição é de 350 horas de espaço por dia. Quando vê as suas quotas, filtre a lista de métricas para earthengine.googleapis.com/bigquery_slot_usage_time ver a quota do Earth Engine associada a chamadas do BigQuery. Para mais informações, leia acerca das quotas das funções raster do BigQuery na documentação do Google Earth Engine.

Nota: tal como as quotas de consultas personalizadas no BigQuery, esta quota é aproximada. Oferece uma salvaguarda contra gastos excessivos, mas não foi concebido para limitar rigorosamente o tempo de espaço. O BigQuery pode, ocasionalmente, executar uma consulta que exceda o limite da quota, e pode esgotar a sua quota sem que lhe seja faturado o valor total consumido.

Regiões suportadas

As consultas que chamam a função ST_REGIONSTATS têm de ser executadas numa das seguintes regiões:

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

O que se segue?

• Experimente o tutorial que lhe mostra como usar dados rasterizados para analisar a temperatura.
• Saiba mais sobre as funções de geografia no BigQuery.
• Saiba mais sobre como trabalhar com dados geoespaciais.