Enregistrer des éléments GeoTIFF optimisés pour le cloud (COG)

Earth Engine est compatible avec les assets basés sur des fichiers GeoTIFF optimisés pour le cloud (COG) stockés dans Google Cloud Storage (GCS).

Lorsque vous enregistrez un asset basé sur un fichier COG, Earth Engine indexe les champs spatiaux et de métadonnées de l'image au moment de la création. L'image est ainsi performante lorsqu'elle est utilisée dans des collections, avec des performances comparables à celles des assets ingérés standards (consultez la présentation des fichiers GeoTIFF optimisés pour le cloud).

Prérequis et configuration de Cloud Storage

Avant d'enregistrer un fichier COG, vous devez configurer correctement vos ressources Google Cloud Storage.

1. Emplacement du bucket (exigence stricte)

Pour qu'Earth Engine puisse accéder à votre bucket Cloud Storage, celui-ci doit se trouver dans l'une des régions ou zones multirégionales de centre de données suivantes :

  • La zone multirégionale us
  • Toute zone birégionale des États-Unis incluant us-central1
  • La région us-central1

Si votre bucket est placé dans un autre centre de données régional (tel que us-east4 ou europe-west1), Earth Engine rejettera les demandes d'enregistrement et de lecture.

2. Classe de stockage et facturation

  • Nous vous recommandons d'utiliser la classe de stockage Standard. Le stockage standard n'est soumis à aucune règle de durée de stockage minimale, ce qui évite les pénalités de facturation en cas de suppression anticipée si vous mettez à jour ou remplacez des fichiers temporaires.
  • Bien que les boucles de calcul d'Earth Engine n'entraînent pas de frais supplémentaires de récupération de données Cloud Storage, l'accès à des niveaux de stockage non standards à partir d'outils externes (tels que des logiciels SIG de bureau) entraîne des frais de récupération coûteux.
  • Vous devez avoir activé la facturation dans votre projet Google Cloud pour utiliser GCS. Pour commencer, consultez le guide de démarrage rapide de Google Cloud Storage.

Étape 1 : Préparez vos fichiers COG

Vos fichiers TIFF doivent être optimisés pour le cloud. Le fichier TIFF doit être :

  • Mosaïqué, avec des dimensions de mosaïque de 256 x 256, 512 x 512, 1 024 x 1 024 ou 2 048 x 2 048. Pour des performances optimales, nous vous recommandons d'utiliser une taille de 512 x 512 ou plus.
  • Organisé de sorte que tous les répertoires de fichiers image (IFD) se trouvent au début.
  • Incluez des aperçus de puissance de deux.
  • Utilisez l'entrelacement BAND.

Vous pouvez utiliser GDAL pour convertir vos images.

Utiliser le pilote GDAL COG (GDAL >= 3.1 recommandé) :

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Utiliser le pilote GTiff standard :

Commencez par générer des aperçus internes de puissance de deux (à l'aide de gdal raster overview add ou gdaladdo), puis copiez l'image et les aperçus dans une mise en page COG mosaïquée :

gdaladdo -r nearest in.tif 2 4 8 16 32  # or -r cubic for continuous/float data

gdal_translate in.tif out.tif \
  -co BIGTIFF=YES \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=16 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Étape 2 : Créez le fichier manifeste

Que vous enregistriez un fichier COG à l'aide de la bibliothèque cliente Python Earth Engine, de l'outil de ligne de commande earthengine ou de l'API REST Earth Engine, vous devez définir un fichier manifeste d'importation d'image spécifiant la destination de l'asset, les URI Google Cloud Storage et les métadonnées de bande facultatives.

Exemple : Un seul fichier COG pour toutes les bandes Si votre fichier COG contient toutes les bandes (par exemple, RVB), le fichier manifeste ne nécessite qu'un seul ensemble de mosaïques :

{
  "name": "projects/my-project/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

Exemple : Plusieurs fichiers COG (un par bande) Si vous disposez de fichiers distincts pour différentes bandes (par exemple, rouge, vert et bleu dans des fichiers distincts) :

{
  "name": "projects/my-project/assets/my_multi_band_cog",
  "tilesets": [
    {
      "id": "red_tileset",
      "sources": [ { "uris": [ "gs://google-sample-bucket/band_red.tif" ] } ]
    },
    {
      "id": "green_tileset",
      "sources": [ { "uris": [ "gs://google-sample-bucket/band_green.tif" ] } ]
    }
  ],
  "bands": [
    { "id": "R", "tilesetId": "red_tileset", "tilesetBandIndex": 0 },
    { "id": "G", "tilesetId": "green_tileset", "tilesetBandIndex": 0 }
  ]
}

Étape 3 : Envoyez la demande d'enregistrement

Vous pouvez envoyer votre fichier manifeste à Earth Engine à l'aide de la bibliothèque cliente Python Earth Engine, de l'outil de ligne de commande earthengine ou de l'API REST Earth Engine. Choisissez la méthode la plus adaptée à votre workflow.

Bibliothèque cliente Python

Dans un script Python ou un notebook Jupyter, utilisez la bibliothèque cliente Python Earth Engine (ee.data) après avoir initialisé votre projet :

import ee

# 1. Authenticate and initialize
ee.Authenticate()
ee.Initialize(project='your-project-id')

# 2. Define the manifest as a Python dictionary
manifest = {
  "name": "projects/your-project-id/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

# 3. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
print(f"Asset registered: {result['name']}")

Outil de ligne de commande

Dans votre terminal, enregistrez votre fichier manifeste dans un fichier nommé manifest.json et exécutez la commande d'importation earthengine :

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Submit the external image upload task
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

API REST (Python)

Pour les workflows automatisés sans bibliothèque cliente, envoyez une requête autorisée POST directement au point de terminaison de l'API REST Earth Engine projects.image.importExternal (illustré ici à l'aide de Python) :

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

# 1. Authenticate and start an authorized HTTP session
ee.Authenticate()
ee_project = 'your-project-id'
session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

# 2. Define the REST request body wrapping the manifest
request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/my_cog_asset',
    'tilesets': [
      {
        'id': 'default_tileset',
        'sources': [
          {
            'uris': [
              'gs://google-sample-bucket/my_optimized_image.tif'
            ]
          }
        ]
      }
    ]
  }
}

# 3. Send the POST request
url = (
    'https://earthengine.googleapis.com/v1alpha/'
    f'projects/{ee_project}/image:importExternal'
)
response = session.post(url=url, data=json.dumps(request))
pprint(json.loads(response.content))

Une fois envoyée, la demande d'enregistrement lance une opération d'indexation de métadonnées légère. Comme l'enregistrement COG ne copie pas les données de pixels, cette opération se termine généralement en quelques secondes.

Restrictions du fichier manifeste pour les assets COG

Lorsque vous créez un fichier manifeste pour des assets basés sur des fichiers COG, tenez compte de ces restrictions strictes (qui diffèrent des fichiers manifestes d'ingestion standards) :

  • Un seul bucket : toutes les URI du fichier manifeste doivent résider dans le même bucket GCS.
  • Une URI par source : chaque ImageSource ne doit contenir qu'une seule URI. Vous ne pouvez pas assembler plusieurs fichiers dans une seule source d'ensemble de mosaïques. Pour assembler plusieurs scènes COG, enregistrez chaque fichier COG en tant qu'asset et combinez-les dans un ee.ImageCollection à l'aide de .mosaic().
  • Pas de mask_bands: mask_bands de premier niveau n'est pas compatible. Utilisez missingData dans le fichier manifeste ou assurez-vous que votre fichier TIFF comporte une valeur nodata interne.
  • Pas de data_type dans l'ensemble de mosaïques : ne spécifiez pas data_type dans la section tilesets . Il est détecté automatiquement.
  • Pas de dimensions dans la source : ne spécifiez pas dimensions dans le ImageSource.
  • Pas de subdataset_prefix / subdataset_suffix.
  • Pas de min_tile_area_ratio ni de skip_metadata_read.

Étape 4 : Configurez les autorisations (essentiel pour le partage)

Contrairement aux assets Earth Engine standards, les données de pixels d'un fichier COG restent dans GCS. Lorsque vous partagez un asset basé sur un fichier COG avec d'autres utilisateurs, vous devez leur accorder un accès en lecture à l'asset Earth Engine et aux fichiers GCS.

1. Accorder des autorisations pour le bucket GCS

Les collaborateurs ont besoin d'autorisations pour lire les fichiers à partir de GCS.

Autorisations requises :

  • storage.buckets.get (pour récupérer les métadonnées et l'emplacement du bucket)
  • storage.objects.get (pour lire les données de pixels)

Vous pouvez accorder ces autorisations à l'aide des rôles Cloud Storage standards suivants :

  • Lecteur de bucket Storage (fournit storage.buckets.get pour lire les métadonnées et l'emplacement du bucket)
  • Lecteur d'objets Storage (fournit storage.objects.get pour lire les données de pixels)

Étapes de configuration dans la console Google Cloud :

  1. Accédez au navigateur Cloud Storage.
  2. Cliquez sur le nom de votre bucket.
  3. Sélectionnez l'onglet Autorisations.
  4. Cliquez sur ACCORDER L'ACCÈS.
  5. Ajoutez les adresses e-mail de vos collaborateurs (ou un groupe Google, ou allUsers pour un accès public).
  6. Attribuez les rôles Lecteur de bucket Storage et Lecteur d'objets Storage.
  7. Cliquez sur Enregistrer.

2. Partagez l'asset Earth Engine

Partagez l'asset lui-même à l'aide du gestionnaire d'assets Earth Engine ou de la CLI. Pour en savoir plus, consultez le guide de gestion des assets.

Gérer les générations d'objets

Lorsque vous enregistrez un fichier COG, Earth Engine stocke la génération (version) spécifique de l'objet GCS. Si vous mettez à jour le fichier dans GCS, sa génération change.

  • Par défaut, Earth Engine ne parvient pas à charger l'asset et renvoie une erreur : Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
  • Cette conception vise à empêcher la désynchronisation des métadonnées (telles que la projection ou l'empreinte) avec les pixels sous-jacents.

  • Bonne pratique : si vous devez mettre à jour les données d'image sous-jacentes, enregistrez-les en tant que nouvel asset ou réexécutez la commande d'importation avec l'option --force au lieu d'écraser les fichiers sur place :

    earthengine --project your-project-id upload external_image --force --manifest manifest.json

Utiliser des assets enregistrés

Une fois enregistré, un asset basé sur un fichier COG est accessible dans les scripts Earth Engine comme n'importe quel asset d'image ingéré standard :

JavaScript

var image = ee.Image('projects/your-project-id/assets/my_cog_asset');

Python

image = ee.Image('projects/your-project-id/assets/my_cog_asset')