Éléments Earth Engine basés sur des fichiers GeoTiff cloud

Logo Colab Exécuter dans Google Colab Logo GitHub Afficher la source sur GitHub

Ce notebook explique comment créer des éléments Earth Engine basés sur des fichiers GeoTIFF optimisés pour le cloud (COG). Les éléments basés sur COG présentent un avantage : les champs spatiaux et les métadonnées de l'image sont indexés au moment de la création de l'élément, ce qui rend l'image plus performante dans les collections. Les performances des composants basés sur le COG sont comparables à celles des composants ingérés dans les cas d'utilisation courants.

Notez qu'un même composant peut être associé à plusieurs COG (par exemple, il peut y avoir un COG par bande). Toutefois, l'utilisation de plusieurs tuiles COG pour une seule bande n'est pas prise en charge.

(Earth Engine peut également charger directement des images à partir de COG dans Google Cloud Storage (en savoir plus). Toutefois, une image chargée via ee.Image.loadGeoTIFF et ajoutée à une collection d'images nécessitera une lecture du GeoTiff pour les opérations de filtrage sur la collection.)

Pour créer un composant basé sur un COG :

  1. Placez vos fichiers COG dans un bucket GCS (voir ci-dessous les régions autorisées).
  2. Écrire un fichier manifeste d'importation d'images
  3. Utilisez l'utilitaire de ligne de commande earthengine pour envoyer une commande d'importation:
earthengine upload external_image --manifest my_manifest.json

Exemple de fichier manifeste d'image avec un Tileset

Le ImageManifest le plus simple est celui qui ne comporte qu'un seul Tileset. Si aucune bande n'est spécifiée, l'élément obtenu contient toutes les bandes du GeoTIFF avec les noms de bandes encodés dans le GeoTIFF (dans ce cas, "vis-red", "vis-green" et "vis-blue").

request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo1',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': ['gs://ee-docs-demos/COG_demo.tif'] } ] }
    ],
    'properties': {
      'version': '1.1'
    },
    'startTime': '2016-01-01T00:00:00.000000000Z',
    'endTime': '2016-12-31T15:01:23.000000000Z',
  },
}

pprint(request)

Plus d'un Tileset

Vous pouvez spécifier un ImageManifest avec plusieurs Tileset, où chaque bande de l'élément généré est prise en charge par l'une des bandes d'un Tileset à l'aide des champs tilesetId et tilesetBandIndex. Cela est utile lorsque les différentes bandes ont des résolutions ou des types de données différents. Les bandes peuvent être listées dans n'importe quel ordre à partir de n'importe quel Tileset disponible. Dans l'exemple ci-dessous :

  • "b4b3b2.tif" a une échelle de 10 m, tandis que "b5b6b7" a une échelle de 20 m.
  • L'ordre des bandes de l'élément obtenu est mélangé à partir des COG d'entrée (par exemple, la bande de sortie 0 provient de Tileset 0, tandis que la bande de sortie 1 provient de Tileset 1).
request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo2',
    'uriPrefix': 'gs://ee-docs-demos/external_image_demo/',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': ['b4b3b2.tif'] } ] },
      { 'id': '1', 'sources': [ { 'uris': ['b5b6b7.tif'] } ] },
    ],
    'bands': [
      { 'id': 'red', 'tilesetId': '0', 'tilesetBandIndex': 0 },
      { 'id': 'rededge3', 'tilesetId': '1', 'tilesetBandIndex': 2 },
      { 'id': 'rededge2', 'tilesetId': '1', 'tilesetBandIndex': 1 },
      { 'id': 'green', 'tilesetId': '0', 'tilesetBandIndex': 1 },
      { 'id': 'blue', 'tilesetId': '1', 'tilesetBandIndex': 0 },
      { 'id': 'rededge1', 'tilesetId': '0', 'tilesetBandIndex': 2 },
    ],
  },
}

pprint(request)

Informations sur les composants basés sur le COG

Emplacement

L'emplacement du bucket Cloud Storage doit être l'un des suivants:

  • Multirégion des États-Unis
  • Toute région duale des États-Unis incluant US-CENTRAL1
  • Région US-CENTRAL1

Les métadonnées du bucket doivent être accessibles pour qu'Earth Engine puisse déterminer son emplacement. L'utilisateur appelant doit disposer de l'autorisation storage.buckets.get sur le bucket. Cette autorisation est fournie par le rôle "Storage Legacy Bucket Reader", entre autres.

Pour attribuer ce rôle : 1. Accédez à la page des autorisations du bucket : https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions. Cliquez sur "ACCORDER L'ACCÈS". 3. Ajoutez tous les comptes principaux auxquels l'accès doit être accordé. Attribuez le rôle "Storage Legacy Bucket Reader" (ou créez un rôle personnalisé avec uniquement l'autorisation storage.buckets.get et attribuez-le). 5. Enregistrer

Classe de stockage

La classe de stockage du bucket doit être "Stockage standard".

Autorisations

Les ACL des éléments Earth Engine basés sur des COG et des données sous-jacentes sont gérées séparément. Si un élément basé sur un COG est partagé dans Earth Engine, il appartient au propriétaire de s'assurer que les données de GCS sont partagées avec les mêmes parties. Si les données ne sont pas visibles, Earth Engine renvoie une erreur de la forme "Échec du chargement du GeoTIFF à gs://my-bucket/my-object#123456" (123456 correspond à la génération de l'objet).

Générations

Lorsqu'un élément basé sur un COG est créé, Earth Engine lit les métadonnées des fichiers TIFF spécifiés dans le fichier manifeste et crée une entrée dans le magasin d'éléments. Chaque URI associé à cette entrée peut avoir une génération. Pour en savoir plus sur les générations, consultez la documentation sur la gestion des versions d'objets. Si une génération est spécifiée, par exemple gs://foo/bar#123, Earth Engine stocke cet URI tel quel. Si aucune génération n'est spécifiée, Earth Engine stocke cet URI avec la génération du fichier TIFF au moment de l'appel de ImportExternalImage.

Cela signifie que si un TIFF comprenant un élément externe dans GCS est mis à jour (et donc que sa génération change), Earth Engine renvoie une erreur "Impossible de charger le GeoTIFF à gs://my-bucket/my-object#123456", car l'objet attendu n'existe plus (sauf si le bucket permet plusieurs versions d'objets). Cette règle est conçue pour synchroniser les métadonnées de l'élément avec celles de l'objet.

Configuration

Pour la configuration d'un COG, le fichier TIFF doit:

  • Carte en tuiles, dont les dimensions sont les suivantes:

    • 256 x 256
    • 512 x 512
    • 1024x1024
    • 2048 x 2048

  • Organisé de sorte que tous les IFD soient au début.

Pour de meilleures performances:

  • Utilisez des cartes de 512 x 512 pixels ou plus.
  • Incluez deux présentations.

Selon vos cas d'utilisation prévus, l'option de création INTERLEAVE peut avoir un impact sur les performances. Nous vous recommandons d'utiliser l'entrelacement BAND dans tous les cas.

Pour en savoir plus sur une configuration optimisée, consultez cette page.

La commande gdal_translate suivante convertit un raster en GeoTIFF optimisé pour le cloud, intercalé par bande et compressé avec zstd, qui fonctionnera bien dans Earth Engine:

gdal_translate in.tif out.tif \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=22 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS

Il est possible de réduire encore la taille du fichier de sortie en spécifiant un prédicteur (-co PREDICTOR=2 pour les types de données entiers et -co PREDICTOR=3 pour les types de données à virgule flottante).

Pour les utilisateurs disposant de GDAL 3.11 ou version ultérieure, le pilote COG peut produire des fichiers sans avoir à se soucier de créer et de conserver des aperçus.

gdal_translate in.tif out.tif \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=22 \
  -co PREDICTOR=2 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \

Créer des éléments Cloud GeoTiff à l'aide de l'API REST

Remarque:L'API REST contient de nouvelles fonctionnalités avancées qui ne sont pas forcément adaptées à tous les utilisateurs. Si vous débutez avec Earth Engine, nous vous recommandons de commencer par le guide JavaScript.

Pour créer un élément basé sur un COG à l'aide de l'API REST, envoyez une requête POST au point de terminaison ImportExternalImage d'Earth Engine. Comme indiqué ci-dessous, cette requête doit être autorisée à créer un composant dans votre dossier utilisateur.

Démarrer une session autorisée

Pour pouvoir créer un élément Earth Engine dans votre dossier utilisateur, vous devez pouvoir vous authentifier en tant que vous-même lorsque vous envoyez la requête. Vous pouvez utiliser les identifiants de l'authentificateur Earth Engine pour démarrer un AuthorizedSession. Vous pouvez ensuite utiliser AuthorizedSession pour envoyer des requêtes à Earth Engine.

import ee
import json
from pprint import pprint
from google.auth.transport.requests import AuthorizedSession

ee.Authenticate()  #  or !earthengine authenticate --auth_mode=gcloud

# Specify the cloud project you want associated with Earth Engine requests.
ee_project = 'your-project'

session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

Corps de la requête

Le corps de la requête est une instance d'un ImageManifest. C'est ici que le chemin d'accès au COG est spécifié, ainsi que d'autres propriétés utiles.

Pour en savoir plus sur la configuration d'un ImageManifest, consultez ce guide. Vous pouvez définir un ou plusieurs Tileset, chacun servant de support à une ou plusieurs bandes. Pour ImportExternalImage, un seul ImageSource est accepté par Tileset.

Pour en savoir plus sur l'exportation des coûts de production, consultez ce document.

Envoyer la requête

Envoyez la requête POST au point de terminaison projects.images.importExternal d'Earth Engine.

url = f'https://earthengine.googleapis.com/v1alpha/projects/{ee_project}/image:importExternal'

response = session.post(
  url = url,
  data = json.dumps(request)
)

pprint(json.loads(response.content))