Travailler avec des données raster à l'aide d'Earth Engine dans BigQuery

Ce document explique comment combiner des données raster et vectorielles à l'aide de la fonction ST_REGIONSTATS, qui appelle Google Earth Engine pour effectuer une analyse géospatiale dans BigQuery.

Présentation

Un raster est une grille bidimensionnelle de pixels, chacun étant associé à une ou plusieurs valeurs appelées bandes. Par exemple, chaque pixel peut correspondre à un kilomètre carré particulier à la surface de la Terre et comporter des bandes pour la température moyenne et les précipitations moyennes. Les données raster incluent les images satellite et d'autres données continues basées sur une grille, telles que les prévisions météorologiques et la couverture terrestre. De nombreux formats d'image courants, tels que les fichiers PNG ou JPEG, sont au format de données matricielles.

Les données raster sont souvent opposées aux données vectorielles, dans lesquelles les données sont décrites par des lignes ou des courbes plutôt que par une grille rectangulaire fixe. Par exemple, vous pouvez utiliser le type de données GEOGRAPHY dans BigQuery pour décrire les limites de pays, de villes ou d'autres régions.

Les données vectorielles et raster géospatiales sont souvent combinées à l'aide d'une opération statistiques zonales, qui calcule une agrégation de toutes les valeurs de trame dans une région vectorielle donnée. Par exemple, vous pouvez calculer les éléments suivants:

Qualité de l'air moyenne dans chaque comté de votre État
Potentiel solaire d'un ensemble de polygones de bâtiments.
Résumé du risque d'incendie le long des corridors de lignes électriques dans les zones boisées.

BigQuery excelle dans le traitement des données vectorielles, tandis que Google Earth Engine excelle dans le traitement des données raster. Vous pouvez utiliser la fonction de géographie ST_REGIONSTATS pour combiner des données raster à l'aide d'Earth Engine avec vos données vectorielles stockées dans BigQuery.

Avant de commencer

Pour utiliser la fonction ST_REGIONSTATS dans vos requêtes, activez l'API Earth Engine.
Activer l'API
Facultatif: Pour vous abonner et utiliser les données publiées dans BigQuery Sharing (anciennement Analytics Hub) à l'aide de la fonction ST_REGIONSTATS, activez l'API Analytics Hub.
Activer l'API

Autorisations requises

Pour obtenir les autorisations nécessaires pour appeler la fonction ST_REGIONSTATS, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet:

Lecteur de ressources Earth Engine (roles/earthengine.viewer)
Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer)
S'abonner à des ensembles de données dans le partage BigQuery : Éditeur de données BigQuery (roles/bigquery.dataEditor)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour appeler la fonction ST_REGIONSTATS. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour appeler la fonction ST_REGIONSTATS:

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

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Rechercher des données matricielles

Le paramètre raster_id de la fonction ST_REGIONSTATS est une chaîne qui spécifie la source de vos données raster. Les sections suivantes expliquent comment trouver et mettre en forme l'ID de raster.

Tables d'images BigQuery

Vous pouvez utiliser BigQuery Sharing (anciennement Analytics Hub) pour découvrir et accéder aux ensembles de données raster dans BigQuery. Pour utiliser BigQuery Sharing, vous devez activer l'API Analytics Hub et vous assurer de disposer des autorisations requises pour afficher et vous abonner aux fiches.

Google Earth Engine publie des ensembles de données accessibles au public contenant des données matricielles. Pour vous abonner à un ensemble de données Earth Engine contenant des données raster, procédez comme suit:

Accédez à la page Partage (Analytics Hub).
Accéder à "Partage" (Analytics Hub)
Cliquez sur Rechercher des fiches.
Dans le champ Rechercher des fiches, saisissez "Google Earth Engine".
Cliquez sur un ensemble de données auquel vous souhaitez vous abonner.
Cliquez sur S'abonner.
Facultatif: Modifiez les champs Project (Projet) ou Linked dataset name (Nom de l'ensemble de données associé).
Cliquez sur Enregistrer. L'ensemble de données associé est ajouté à votre projet.

L'ensemble de données contient une table, parfois appelée table d'images, qui stocke les métadonnées d'une collection d'images raster conformément aux spécifications des éléments STAC. Une table d'images est semblable à une collection d'images Earth Engine (ImageCollection).

Chaque ligne du tableau correspond à une seule image raster. L'ID de raster de chaque image est stocké dans la colonne assets.image.href. Pour trouver une image spécifique, vous pouvez filtrer par propriétés d'image dans la colonne properties. Vous trouverez des informations sur les bandes dans la description du tableau.

Par exemple, l'ensemble de données ERA5-Land fournit des statistiques quotidiennes sur les variables climatiques et est disponible au public. La table climate contient plusieurs ID de raster. La requête suivante filtre la table d'images à l'aide de la colonne properties.start_datetime pour obtenir l'ID de raster de l'image correspondant au 1er janvier 2025 et calcule la température moyenne pour chaque pays à l'aide de la bande 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;

Cloud Storage GeoTIFF

GeoTIFF est un format de fichier courant pour stocker des données raster géospatiales. La fonction ST_REGIONSTATS est compatible avec les données raster stockées au format GeoTIFF dans des buckets Cloud Storage situés dans les régions US ou us-central1. Indiquez l'URI Cloud Storage comme ID de raster, par exemple gs://bucket/folder/raster.tif.

Composants Image Earth Engine

La fonction ST_REGIONSTATS permet de transmettre un chemin d'accès à un composant Image Earth Engine pour l'argument raster_id. Les données raster Earth Engine sont disponibles sous forme d'images individuelles ou de collections d'images. Pour trouver l'ID de raster d'une image, procédez comme suit:

Recherchez l'ensemble de données qui vous intéresse dans le catalogue de données Earth Engine.
Pour ouvrir la page de description de cette entrée, cliquez sur le nom de l'ensemble de données. Le extrait Earth Engine décrit une seule image ou une collection d'images.
Si l'extrait Earth Engine est au format ee.Image('IMAGE_PATH'), l'ID de raster est 'ee://IMAGE_PATH'.
Si l'extrait de code Earth Engine est au format ee.ImageCollection('IMAGE_COLLECTION_PATH'), vous pouvez utiliser l'éditeur de code Earth Engine pour filtrer la collection d'images sur une seule image. Utilisez la méthode ee.Image.get('system:id') pour imprimer la valeur IMAGE_PATH de cette image dans la console. L'ID du raster est 'ee://IMAGE_PATH'.

Poids des pixels

Vous pouvez spécifier un poids, parfois appelé valeur de masque, pour le paramètre include dans la fonction ST_REGIONSTATS, qui détermine le poids de chaque pixel dans les calculs. Les valeurs de pondération doivent être comprises entre 0 et 1. Les pondérations en dehors de cette plage sont définies sur la limite la plus proche, soit 0, soit 1.

Un pixel est considéré comme valide s'il a une pondération supérieure à 0. Une pondération de 0 indique un pixel non valide. Les pixels non valides représentent généralement des données manquantes ou peu fiables, telles que des zones masquées par des nuages, des anomalies de capteur, des erreurs de traitement ou des emplacements en dehors d'une limite définie.

Si vous ne spécifiez pas de pondération, chaque pixel est automatiquement pondéré en fonction de la proportion du pixel qui se trouve dans la géométrie, ce qui permet une inclusion proportionnelle dans les statistiques zonales.

Si un pixel partiellement intersectant a un poids de l'argument include à ST_REGIONSTATS, BigQuery utilise le minimum de ce poids et de la fraction du pixel qui intersecte la région.

Les valeurs de poids n'ont pas la même précision que les valeurs FLOAT64. En pratique, leur valeur réelle peut différer de la valeur utilisée dans les calculs jusqu'à 1/256 (environ 0,4%).

Vous pouvez fournir une expression à l'aide de la syntaxe d'expression d'image d'Earth Engine dans votre argument include pour pondérer dynamiquement les pixels en fonction de critères spécifiques dans les bandes raster. Par exemple, l'expression suivante limite les calculs aux pixels où la bande probability dépasse 70%:

include => 'probability > 0.7'

Si l'ensemble de données inclut une plage de facteurs de pondération, vous pouvez l'utiliser avec la syntaxe suivante:

include => 'weight_factor_band_name'

Taille des pixels et échelle d'analyse

Une image raster géospatiale est une grille de pixels qui correspond à un emplacement sur la surface de la Terre. La taille en pixels d'un raster, parfois appelée échelle, correspond à la taille nominale d'un bord de pixel dans le système de référence de coordonnées de la grille. Par exemple, un raster avec une résolution de 10 mètres comporte des pixels de 10 x 10 mètres. La taille de pixel d'origine indiquée peut varier considérablement d'un ensemble de données à l'autre, de moins d'un mètre à plus de 20 kilomètres.

Lorsque vous utilisez la fonction ST_REGIONSTATS pour calculer des statistiques zonales, la taille des pixels des données raster est un facteur crucial. Par exemple, l'agrégation de données raster haute résolution sur la région d'un pays peut être gourmande en calculs et trop détaillée. À l'inverse, l'agrégation de données basse résolution sur la région, telles que les parcelles urbaines, peut ne pas fournir suffisamment de détails.

Pour obtenir des résultats pertinents et efficaces de votre analyse, nous vous recommandons de choisir une taille de pixel adaptée à la taille de vos polygones et à l'objectif de votre analyse. Vous trouverez la taille en pixels de chaque ensemble de données raster dans la section de description des tables d'images dans le partage BigQuery.

Modifier la taille des pixels modifie le nombre de pixels qui croisent une zone géographique donnée, ce qui a une incidence sur les résultats et leur interprétation. Nous vous déconseillons de modifier la taille des pixels pour les analyses de production. Toutefois, si vous effectuez un prototypage d'une requête, augmenter la taille des pixels peut réduire le temps d'exécution et les coûts des requêtes, en particulier pour les données haute résolution.

Pour modifier la taille en pixels, définissez scale dans l'argument options sur la fonction ST_REGIONSTATS. Par exemple, pour calculer des statistiques sur des pixels de 1 000 mètres, utilisez options => JSON '{"scale":1000}', qui indique à Earth Engine de reéchantillonner l'image à l'échelle demandée. Pour en savoir plus sur la façon dont Earth Engine gère le redimensionnement, consultez la section Échelle dans la documentation Google Earth Engine.

Facturation

Lorsque vous exécutez une requête, l'utilisation de la fonction ST_REGIONSTATS est facturée séparément du reste de la requête, car Earth Engine calcule les résultats de l'appel de fonction. Cette utilisation vous est facturée en heures d'emplacement sous le code SKU des services BigQuery, que vous utilisiez la facturation à la demande ou des réservations. Pour afficher le montant facturé pour les appels BigQuery vers Earth Engine, consultez votre rapport de facturation et utilisez des libellés pour filtrer par clé de libellé goog-bq-feature-type, avec la valeur EARTH_ENGINE.

Facteurs de coût

Les facteurs suivants ont une incidence sur l'utilisation du calcul lorsque vous exécutez la fonction ST_REGIONSTATS:

Nombre de lignes d'entrée.
Image matricielle que vous utilisez. Certains rasters sont des composites créés à partir de collections d'images sources dans le catalogue de données Earth Engine. Les ressources de calcul nécessaires pour produire le résultat composite varient.
Résolution de l'image.
La taille et la complexité de la géographie d'entrée, le nombre de pixels qui l'intersectent, ainsi que le nombre de tuiles d'image et d'octets lus par Earth Engine.
Emplacement géographique de la géographie d'entrée sur Terre par rapport aux images sources, ainsi que projection et résolution de l'image.
- Les projections d'images peuvent déformer les pixels, en particulier ceux situés à des latitudes élevées ou très en dehors de la zone de couverture prévue de l'image.
- Pour les rasters composites, le nombre d'images sources qui croisent la zone géographique d'entrée peut varier selon les régions et au fil du temps. Par exemple, certains satellites produisent plus d'images aux latitudes basses ou élevées, en fonction de leur orbite et des paramètres de collecte de données, ou peuvent omettre des images en fonction des conditions atmosphériques changeantes.
L'utilisation de formules dans les arguments include ou band_name, ainsi que le nombre de bandes qu'elles impliquent.
Mise en cache des résultats précédents.

Contrôlez les coûts

Pour contrôler les coûts associés à la fonction ST_REGIONSTATS, vous pouvez ajuster le quota qui contrôle la quantité de temps d'emplacement que la fonction est autorisée à consommer. La valeur par défaut est de 350 heures par jour. Lorsque vous consultez vos quotas, filtrez la liste Métrique sur earthengine.googleapis.com/bigquery_slot_usage_time pour afficher le quota Earth Engine associé aux appels provenant de BigQuery. Pour en savoir plus, consultez les quotas de fonctions de raster BigQuery dans la documentation Google Earth Engine.

Limites

Les requêtes qui appellent la fonction ST_REGIONSTATS doivent s'exécuter dans l'une des régions suivantes:

US
us-central1
us-central2

Étape suivante

Suivez le tutoriel qui vous explique comment utiliser des données raster pour analyser la température.
En savoir plus sur les fonctions de géographie dans BigQuery
Découvrez comment utiliser des données géospatiales.