Enregistrer des éléments Cloud Optimized GeoTIFF (COG)

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

Lorsque vous enregistrez un élément basé sur un COG, Earth Engine indexe les champs spatiaux et de métadonnées de l'image au moment de sa création. Cela rend l'image performante lorsqu'elle est utilisée dans des collections, avec des performances comparables à celles des éléments ingérés standards (voir la présentation de Cloud Optimized GeoTIFF (COG)).

Ce guide explique comment préparer vos fichiers, rédiger le fichier manifeste, envoyer la demande d'enregistrement, configurer les autorisations, et mettre à jour ou supprimer des éléments enregistrés.

Avant de commencer

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

Emplacement du bucket

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 :

  • L'emplacement multirégional us
  • Toute birégion 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 refusera l'enregistrement et les requêtes de lecture. Consultez les emplacements de buckets Cloud Storage compatibles.

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 pour suppression anticipée si vous mettez à jour ou remplacez des fichiers temporaires.
  • Bien que les boucles de calcul Earth Engine n'entraînent pas de frais supplémentaires pour la 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 élevés.
  • Vous devez activer la facturation sur votre projet Google Cloud pour utiliser Cloud Storage. Pour commencer, consultez le guide de démarrage rapide de Cloud Storage.

Préparer vos CMV

Earth Engine lit les COG directement depuis Cloud Storage, en ne récupérant que l'en-tête et les tuiles dont un calcul a besoin. La mise en page du fichier est donc importante. Le fichier TIFF doit :

  • Mosaïque, avec des dimensions de mosaïque carrées de puissance 2 allant de 16 x 16 à 2 048 x 2 048. Nous vous recommandons d'utiliser une taille de 512 x 512 pour des performances optimales.
  • Organisé de manière à ce que tous les répertoires de fichiers image (IFD) se trouvent au début.
  • Incluez les aperçus de puissance de 2, le cas échéant. Les aperçus ne sont pas obligatoires, mais ils sont recommandés pour les images plus grandes qu'une seule tuile.
  • Utilisez l'entrelacement BAND ou PIXEL (consultez la section Fichiers à bande unique ou fichiers multibandes pour connaître les compromis).

Pour convertir une image, utilisez le pilote COG de GDAL, qui produit la mise en page requise (mosaïque, aperçus et emplacement de l'en-tête) en une seule étape. Ajoutez OVERVIEW_RESAMPLING=NEAREST pour les données catégorielles. La valeur par défaut est CUBIC. Pour obtenir des recommandations sur la compression, la présentation et la mise en page, consultez les bonnes pratiques pour préparer des COG externes.

CLI GDAL 3.11+

gdal raster convert in.tif out.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co OVERVIEWS=IGNORE_EXISTING \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

CLI classique

Omettez INTERLEAVE=BAND sur les versions de GDAL antérieures à la version 3.11.

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

Créer le fichier manifeste

Que vous enregistriez un 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'élément, les URI Cloud Storage et les métadonnées de bande facultatives. L'API et l'outil de ligne de commande font référence aux éléments basés sur COG en tant qu'images externes (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal).

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

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

Exemple : Plusieurs COG (un par bande) Si vous avez des 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 }
  ]
}

Restrictions du fichier manifeste

Les fichiers manifestes des éléments basés sur COG sont soumis à des restrictions qui ne s'appliquent pas aux fichiers manifestes d'ingestion standards :

  • Bucket unique : tous les URI du fichier manifeste doivent se trouver dans le même bucket Cloud Storage.
  • Un URI par source : chaque ImageSource doit contenir exactement un URI. Vous ne pouvez pas mosaïquer plusieurs fichiers ensemble dans une seule source d'ensemble de tuiles. Pour mosaïquer plusieurs scènes COG, enregistrez chaque COG en tant qu'élément et combinez-les dans un ee.ImageCollection à l'aide de .mosaic().
  • Aucun mask_bands : le champ mask_bands de premier niveau n'est pas accepté. Utilisez missingData dans le fichier manifeste ou assurez-vous que votre fichier TIFF possède une valeur nodata interne.
  • Pas de data_type dans l'ensemble de tuiles : ne spécifiez pas data_type dans la section tilesets, car il est détecté automatiquement.
  • Pas de dimensions dans la source : ne spécifiez pas dimensions dans ImageSource.
  • Non subdataset_prefix / subdataset_suffix.
  • No min_tile_area_ratio ou skip_metadata_read.

Envoyer 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 qui correspond le mieux à 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. Register the asset
result = ee.data.startExternalImageIngestion(manifest)
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. Register the asset
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

API REST

Pour les workflows automatisés sans la bibliothèque cliente, envoyez une requête POST autorisée directement au point de terminaison de l'API REST Earth Engine projects.image.importExternal (illustré ici en 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 des métadonnées légère. Comme l'enregistrement COG ne copie pas les données de pixels, cette opération ne prend généralement que quelques secondes.

Configurer les autorisations

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

Accorder des autorisations sur le bucket Cloud Storage

Les collaborateurs doivent disposer des autorisations nécessaires pour lire les fichiers depuis Cloud Storage.

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

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

  • Lecteur de buckets Storage (fournit storage.buckets.get pour lire les métadonnées et l'emplacement du bucket)
  • Lecteur des 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 d'un groupe Google, ou allUsers pour un accès public).
  6. Attribuez les rôles Lecteur de buckets Storage et Lecteur d'objets Storage.
  7. Cliquez sur Enregistrer.

Partager l'élément Earth Engine

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

Mettre à jour, remplacer et supprimer des éléments basés sur un COG

Un élément basé sur un COG est un pointeur vers une version spécifique d'un fichier dans Cloud Storage, ainsi que des métadonnées (empreinte, projection, bandes et mise en page de la vue d'ensemble) que Earth Engine a indexées lorsque vous l'avez enregistré. Earth Engine épingle la version du fichier afin que ces métadonnées ne se désynchronisent pas des pixels. C'est ce qui différencie la mise à jour des éléments basés sur un COG de celle des éléments standards.

Générations d'objets

Lorsque vous enregistrez un COG, Earth Engine enregistre la génération de l'objet Cloud Storage (son numéro de version) ainsi que l'URI. Vous pouvez voir la génération épinglée dans les métadonnées de l'élément. Elle apparaît sous la forme d'un suffixe #<generation> sur l'URI :

Python

asset = ee.data.getAsset('projects/your-project-id/assets/my_cog_asset')
print(asset['tilesets'][0]['sources'][0]['uris'])
# ['gs://google-sample-bucket/my_optimized_image.tif#1750427474244728']

Vous pouvez également bloquer les mises à jour à une version spécifique en incluant le suffixe #<generation> dans l'URI du fichier manifeste lorsque vous enregistrez (ou réenregistrez) l'élément. Sans cela, Earth Engine lit l'objet actuel et épingle la génération qu'il trouve. L'épinglage explicite est utile pour effectuer un rollback vers une version antérieure qu'un bucket avec gestion des versions d'objets a conservée.

Si vous écrasez le fichier dans Cloud Storage, une nouvelle génération est créée. Si vous le supprimez, la génération épinglée disparaît. Dans les deux cas, la lecture des pixels de l'élément échoue, sauf si la gestion des versions d'objets sur le bucket conserve l'ancienne génération, auquel cas Earth Engine continue de lire les anciens pixels. Les opérations de métadonnées qui utilisent l'enregistrement indexé (comme ee.data.getAsset(), bandNames() et le filtrage de collection) continuent de fonctionner dans les deux cas.

Mettre à jour un asset après avoir modifié son fichier

Pour faire pointer un asset existant vers une nouvelle version de son fichier, enregistrez-le à nouveau avec le même nom d'asset et l'option d'écrasement activée. Earth Engine relit l'en-tête GeoTIFF, réindexe les métadonnées et épingle la nouvelle génération, en un seul appel synchrone. Les autorisations existantes de l'élément sont conservées, mais ses propriétés, sa période et ses noms de bande proviennent du nouveau fichier manifeste. Incluez donc tout ce que vous avez précédemment défini avec ee.data.updateAsset().

  • Python : ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Ligne de commande : earthengine upload external_image --force --manifest manifest.json
  • API REST : incluez "overwrite": true en tant que champ de premier niveau à côté de "imageManifest" dans le corps de la requête projects.image.importExternal.

Vous n'avez pas besoin de supprimer l'asset au préalable, et cela est contre-productif : un asset autonome perd ses autorisations, et une image d'une collection disparaît brièvement de la collection. Notez que ee.data.updateAsset() (projects.assets.patch) ne peut modifier que les propriétés, la période et les noms des bandes. Il ne peut pas modifier le fichier vers lequel pointe un asset.

Cycles de vie indépendants

Les éléments Earth Engine et les objets Cloud Storage sont gérés séparément :

  • La suppression de l'élément Earth Engine (earthengine rm ou ee.data.deleteAsset()) ne supprime que l'enregistrement de l'élément. Vos fichiers dans Cloud Storage ne sont pas modifiés.
  • La suppression du fichier dans Cloud Storage ne supprime pas l'élément. Il apparaît toujours dans les listes et dans sa collection (voir Générations d'objets).

Utiliser de grandes collections

Il n'existe pas de suppression par lot ou récursive dans l'API Earth Engine : chaque élément doit être supprimé individuellement, et une collection doit être vide avant de pouvoir être supprimée. earthengine rm -r gère cela pour vous, mais supprime les images une par une. Par conséquent, la suppression d'une collection contenant des dizaines de milliers d'images peut prendre des heures.

  • Pour remplacer les images d'une collection, écrasez-les au lieu de les supprimer. Réenregistrez chaque image par son nom en activant l'option d'écrasement (voir ci-dessus). Cela nécessite une requête par image au lieu de deux, permet de conserver la collection remplie tout au long du processus et évite de supprimer et de recréer la collection elle-même, qui contient ses autorisations. Supprimez uniquement les images qui ne figurent pas dans le nouvel ensemble.
  • Pour supprimer de nombreux éléments, parallélisez l'opération à partir d'un script. Répertoriez les éléments avec ee.data.listAssets() (à l'aide de la vue BASIC, qui ne renvoie que les noms et les types plutôt que les métadonnées complètes de chaque image) et supprimez-les d'un petit pool de threads. Les requêtes d'éléments partagent des limites de débit à l'échelle du projet. Par conséquent, limitez la simultanéité (environ 10 workers) et laissez les nouvelles tentatives intégrées de la bibliothèque cliente gérer les réponses 429 Too Many Requests :

    Python

    import concurrent.futures
    import ee
    
    ee.Initialize(project='your-project-id')
    collection = 'projects/your-project-id/assets/my_collection'
    
    listing = ee.data.listAssets({'parent': collection, 'view': 'BASIC'})
    asset_ids = [a['name'] for a in listing['assets']]
    
    def delete(asset_id):
      try:
        ee.data.deleteAsset(asset_id)
      except ee.EEException as e:
        return f'{asset_id}: {e}'
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
      failures = [f for f in executor.map(delete, asset_ids) if f]
    
    if failures:
      print('\n'.join(failures))
    else:
      ee.data.deleteAsset(collection)
    

    La collection n'est supprimée que si toutes les images l'ont été. Par conséquent, un échec partiel la laisse en place pour une nouvelle exécution.

    Le même schéma s'applique à l'enregistrement de plusieurs images : remplacez ee.data.deleteAsset(asset_id) dans l'assistant par ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) et mappez-le sur votre liste de fichiers manifestes. Transmettre allow_overwrite=True même lors de la première exécution permet de réexécuter le lot en toute sécurité après un échec partiel, car tout élément déjà créé est remplacé au lieu de générer une erreur.

Utiliser des assets enregistrés

Une fois enregistré, un composant Image basé sur un COG est accessible dans les scripts Earth Engine, comme n'importe quel composant 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')

Pour obtenir des réponses aux questions fréquentes sur les autorisations, la mise à jour des fichiers et la gestion de grandes collections, consultez la section COG des questions fréquentes.