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é spécifique à la surface de la Terre et comporter des bandes pour la température moyenne et les précipitations moyennes. Les données raster incluent des 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 mis en forme en tant que données raster.

Les données raster sont souvent comparé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 des pays, des villes ou d'autres régions.

Les données raster et vectorielles géospatiales sont souvent combinées à l'aide d'une opération de statistiques zonales, qui calcule un agrégat de toutes les valeurs raster 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 pour un ensemble de polygones de bâtiments.
  • Risque d'incendie résumé le long des corridors de lignes électriques dans les zones forestières.

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 les données raster à l'aide d'Earth Engine avec vos données vectorielles stockées dans BigQuery.

Avant de commencer

  1. Pour utiliser la fonction ST_REGIONSTATS dans vos requêtes, activez l'API Earth Engine.

    Activer l'API

  2. Facultatif : Pour vous abonner aux données publiées dans BigQuery Sharing (anciennement Analytics Hub) et les utiliser à 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 :

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 raster

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 les fiches et vous y abonner.

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

  1. Accédez à la page Partage (Analytics Hub).

    Accéder au partage (Analytics Hub)

  2. Cliquez sur  Rechercher des fiches.

  3. Dans le champ Rechercher des fiches, saisissez "Google Earth Engine".

  4. Cliquez sur un ensemble de données auquel vous souhaitez vous abonner.

  5. Cliquez sur S'abonner.

  6. Facultatif : Modifiez les champs Projet ou Nom de l'ensemble de données associé.

  7. 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 suivant les spécifications des éléments STAC. Une table d'images est analogue à une collection d'images Earth Engine (ImageCollection).

Chaque ligne du tableau correspond à une seule image raster. L'ID raster de chaque image est stocké dans la colonne assets.image.href. Pour trouver une image spécifique, vous pouvez filtrer les résultats 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 accessible 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, puis 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 les buckets Cloud Storage situés dans les régions US ou us-central1. Indiquez l'URI Cloud Storage comme ID 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 élément d'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 raster d'une image, procédez comme suit :

  1. Recherchez l'ensemble de données qui vous intéresse dans le catalogue de données Earth Engine.

  2. Pour ouvrir la page de description de cette entrée, cliquez sur le nom de l'ensemble de données. L'extrait Earth Engine décrit une seule image ou une collection d'images.

    Si l'extrait Earth Engine est de la forme ee.Image('IMAGE_PATH'), l'ID du raster est 'ee://IMAGE_PATH'.

    Si l'extrait de code Earth Engine est de la forme ee.ImageCollection('IMAGE_COLLECTION_PATH'), vous pouvez utiliser l'éditeur de code Earth Engine pour filtrer ImageCollection 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'.

Pondérations 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 ou 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 non 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 la géométrie est inférieure à 1/256 de la taille du pixel, le poids du pixel est de 0. Dans ce cas, null est renvoyé pour toutes les statistiques, sauf count et area, qui sont égales à 0.

Si un pixel partiellement intersecté a une pondération de l'argument include à ST_REGIONSTATS, BigQuery utilise la valeur minimale entre cette pondération et 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 celle utilisée dans les calculs d'un maximum de 1/256 (environ 0,4 %).

Vous pouvez fournir une expression à l'aide de la syntaxe d'expression d'image 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 bande de facteur 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 des coordonnées de la grille. Par exemple, un raster avec une résolution de 10 mètres comporte des pixels de 10 mètres sur 10 mètres. La taille des pixels signalée à l'origine peut varier considérablement d'un ensemble de données à l'autre, allant 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 élément crucial à prendre en compte. Par exemple, l'agrégation de données raster haute résolution sur la région d'un pays peut être gourmande en ressources de calcul et inutilement précise. À l'inverse, l'agrégation de données basse résolution sur la région, comme les parcelles urbaines, peut ne pas fournir suffisamment de détails.

Pour obtenir des résultats pertinents et efficaces à partir 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 des pixels pour chaque ensemble de données raster dans la section de description des tables d'images dans le partage BigQuery.

Modifier la taille des pixels change le nombre de pixels qui croisent une zone géographique donnée, ce qui affecte les résultats et leur interprétation. Nous ne recommandons pas de modifier la taille des pixels pour les analyses de production. Toutefois, si vous prototypez une requête, augmenter la taille des pixels peut réduire la durée d'exécution et le coût de la requête, en particulier pour les données haute résolution.

Pour modifier la taille des 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 rééchantillonner l'image à l'échelle demandée. Pour en savoir plus sur la façon dont Earth Engine gère le redimensionnement, consultez Scale dans la documentation de Google Earth Engine.

Le calcul de statistiques pour des polygones beaucoup plus petits que les pixels du raster peut produire des résultats inexacts ou nuls. Dans ce cas, une alternative consiste à remplacer le polygone par son centroïde à l'aide de ST_CENTROID.

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 SKU des services BigQuery, que vous utilisiez la facturation à la demande ou les réservations. Pour connaître le montant facturé pour les appels BigQuery à Earth Engine, consultez votre rapport sur la facturation et utilisez des libellés pour filtrer par clé de libellé goog-bq-feature-type, avec la valeur EARTH_ENGINE. Si la fonction ST_REGIONSTATS échoue, vous n'êtes pas facturé pour les calculs Earth Engine utilisés.

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 croisent la géographie, ainsi que le nombre de tuiles d'image et d'octets lus par Earth Engine.

  • Emplacement de la géographie d'entrée sur la Terre par rapport aux images sources, ainsi qu'à la projection et à la résolution de l'image.

    • Les projections d'images peuvent déformer les pixels, en particulier ceux situés à des latitudes élevées ou loin en dehors de la zone de couverture prévue de l'image.
    • Pour les rasters composites, le nombre d'images sources croisant la géographie d'entrée peut varier selon la région et au fil du temps. Par exemple, certains satellites produisent plus d'images à basse ou haute latitude, en fonction de leur orbite et de leurs 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, et le nombre de bandes qu'elles impliquent.

  • La 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 de slot que la fonction est autorisée à consommer. La valeur par défaut est de 350 heures de créneaux par jour. Lorsque vous affichez vos quotas, filtrez la liste Métrique sur earthengine.googleapis.com/bigquery_slot_usage_time pour afficher le quota Earth Engine associé aux appels depuis BigQuery. Pour en savoir plus, consultez les quotas des fonctions 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

Étapes suivantes