É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

Earth Engine est compatible avec les éléments basés sur des fichiers GeoTIFF optimisés pour le cloud (COG). L'avantage des éléments basés sur des fichiers COG est que les champs spatiaux et de 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 éléments basés sur des fichiers COG sont comparables à celles des éléments ingérés dans les cas d'utilisation classiques.

Notez qu'un seul élément peut être basé sur plusieurs fichiers COG (par exemple, un fichier COG par bande). Toutefois, l'utilisation de nombreuses tuiles COG pour une seule bande n'est pas acceptée.

(Earth Engine peut également charger directement des images à partir de fichiers 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 fichier GeoTIFF pour les opérations de filtrage sur la collection.)

Pour créer un élément basé sur un fichier COG :

  1. Placez vos fichiers COG dans un bucket GCS (consultez la section Emplacement pour connaître les régions autorisées).
  2. Rédigez un fichier manifeste d'importation d'image.
  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 résultant contiendra toutes les bandes du fichier GeoTIFF avec les noms de bande encodés dans le fichier 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)

Plusieurs Tileset

Il est possible de spécifier un ImageManifest avec plusieurs Tileset, où chaque bande de l'élément résultant est basée sur l'une des bandes d'un Tileset à l'aide des champs tilesetId et tilesetBandIndex. Cela est utile lorsque 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 suivant :

  • "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 résultant est mélangé à partir des fichiers 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 éléments basés sur des fichiers COG

Emplacement

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

  • Multirégion des États-Unis
  • N'importe quelle birégion des États-Unis incluant US-CENTRAL1
  • Région US-CENTRAL1

Classe de stockage

La classe destockage du bucket doit être "Stockage standard".

Autorisations de partage

Les LCA des éléments Earth Engine basés sur des fichiers COG et les données sous-jacentes sont gérées séparément. Lorsque vous partagez des éléments basés sur des fichiers COG avec des collaborateurs pour la lecture, il incombe au propriétaire de s'assurer que l'accès en lecture est accordé à la fois à l' élément Earth Engine et aux fichiers COG sous-jacents.

1. Accorder des autorisations de lecture pour le bucket Google Cloud Storage

Pour que les collaborateurs puissent lire les éléments basés sur des fichiers COG, ils doivent d'abord disposer d'un accès en lecture aux fichiers COG sous-jacents dans le bucket Google Cloud Storage. Sans ces autorisations, Earth Engine ne pourra pas récupérer les données pour eux. Si les données de Google Cloud Storage ne sont pas visibles pour un utilisateur Earth Engine, Earth Engine renverra une erreur de la forme "Failed to load the GeoTIFF at gs://my-bucket/my-object#123456" (où 123456 correspond à la génération de l'objet).

Plus précisément, les collaborateurs doivent disposer des autorisations suivantes :

  • storage.buckets.get sur le bucket (pour récupérer les métadonnées et l'emplacement du bucket, ce qui permet à Earth Engine de résoudre correctement la source de l'élément).
  • storage.objects.get sur le bucket (pour lire les données réelles de l'élément basé sur un fichier COG).

Ces autorisations sont fournies par les rôles "Lecteur des anciens buckets Storage" et "Lecteur des anciens objets de l'espace de stockage", entre autres.

Pour attribuer ces rôles à des collaborateurs :

  1. Accédez à la page des autorisations du bucket : https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions.
  2. Cliquez sur ACCORDER L'ACCÈS.
  3. Ajoutez tous les comptes principaux (par exemple, les utilisateurs, les groupes ou les comptes de service) auxquels l'accès en lecture doit être accordé.
  4. Attribuez les rôles suivants :
    • "Lecteur des anciens buckets Storage" (fournit storage.buckets.get et d'autres autorisations de lecture au niveau du bucket).
    • "Lecteur des anciens objets de l'espace de stockage" (fournit storage.objects.get).
    • (Vous pouvez également créer un rôle personnalisé avec uniquement les autorisations storage.buckets.get et storage.objects.get, puis l'attribuer.)
  5. Enregistrez.

2. Partager l'élément Earth Engine pour la lecture

Une fois que vous vous êtes assuré que vos collaborateurs disposent des autorisations nécessaires sur le bucket et les objets GCS sous-jacents, vous devez également partager l'élément Earth Engine lui-même. Pour en savoir plus sur la configuration des autorisations des éléments Earth Engine, consultez le guide de gestion des éléments Earth Engine.

Générations

Lorsqu'un élément basé sur un fichier 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 fichier TIFF comprenant un élément externe dans GCS est mis à jour (et que sa génération est donc modifiée), Earth Engine renverra une erreur "Failed to load the GeoTIFF at gs://my-bucket/my-object#123456" (Échec du chargement du fichier GeoTIFF à l'adresse gs://my-bucket/my-object#123456) car l'objet attendu n'existe plus (sauf si le bucket autorise plusieurs versions d'objet). Cette règle est conçue pour que les métadonnées de l'élément soient synchronisées avec celles de l'objet.

Configuration

En termes de configuration d'un fichier COG, le fichier TIFF DOIT être :

  • en mosaïque, avec des dimensions de tuile de :

    • 256x256
    • 512x512
    • 1024x1024
    • 2048x2048

  • organisé de sorte que tous les IFD se trouvent au début.

Pour des performances optimales :

  • Utilisez des dimensions de tuile de 512 x 512 ou plus.
  • Incluez des aperçus de puissance de 2.

Selon les cas d'utilisation prévus, l' option de création "INTERLEAVE" peut avoir une incidence sur les performances. Nous vous recommandons d'utiliser l'entrelacement de bandes dans tous les cas.

Pour en savoir plus sur une configuration optimisée, consultez cette page pour plus de détails.

La commande gdal_translate suivante convertit un raster en un fichier GeoTIFF optimisé pour le cloud, compressé avec zstd et entrelacé par bande, qui fonctionnera correctement 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 davantage 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, le pilote COG peut générer des fichiers sans avoir à se soucier de la création et de la conservation des aperçus.

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

Créer des éléments basés sur des fichiers GeoTIFF dans le cloud à l'aide de l'API REST

Remarque : L'API REST contient des fonctionnalités nouvelles et avancées qui ne conviennent pas à 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 fichier COG à l'aide de l'API REST, envoyez une POST requête au point de terminaison ImportExternalImage Earth Engine. Comme indiqué ci-dessous, cette requête doit être autorisée à créer un élément 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 lorsque vous effectuez la requête. Vous pouvez utiliser les identifiants de l'authentificateur Earth Engine pour démarrer une AuthorizedSession. Vous pouvez ensuite utiliser la 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 là que le chemin d'accès au fichier 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 pour plus de détails. Il est possible de définir un ou plusieurs Tileset, chacun étant basé sur une ou plusieurs bandes. Pour ImportExternalImage, au maximum un ImageSource est accepté par Tileset.

Pour en savoir plus sur l'exportation de fichiers COG, consultez ce document.

Envoyer la requête

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

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))