Registra gli asset Cloud Optimized GeoTIFF (COG)

Earth Engine supporta gli asset basati su GeoTIFF ottimizzati per il cloud (COG) archiviati in Google Cloud Storage (GCS).

Quando registri un asset basato su COG, Earth Engine indicizza i campi spaziali e dei metadati dell'immagine al momento della creazione. In questo modo, l'immagine è performante quando viene utilizzata nelle raccolte, con prestazioni paragonabili a quelle degli asset importati standard (consulta la panoramica di Cloud Optimized GeoTIFF (COG)).

Questa guida illustra come preparare i file, scrivere il manifest, inviare la richiesta di registrazione, configurare le autorizzazioni e aggiornare o eliminare gli asset registrati.

Prima di iniziare

Prima di registrare un COG, devi configurare correttamente le risorse Cloud Storage.

Località del bucket

Affinché Earth Engine possa accedere al tuo bucket Cloud Storage, il bucket deve trovarsi in una delle seguenti regioni o multi-regioni dei data center:

  • La multi-regione us
  • Qualsiasi regione doppia degli Stati Uniti che include us-central1
  • La regione us-central1

Se il bucket si trova in un altro data center regionale (ad esempio us-east4 o europe-west1), Earth Engine rifiuterà le richieste di registrazione e lettura. Consulta le località dei bucket Cloud Storage supportate.

Classe di archiviazione e fatturazione

  • Ti consigliamo di utilizzare la classe di archiviazione Standard. Standard Storage non prevede regole per la durata minima di archiviazione, evitando penali di fatturazione per l'eliminazione anticipata se aggiorni o sostituisci i file temporanei.
  • Sebbene i loop di calcolo di Earth Engine non comportino supplementi per il recupero dei dati di Cloud Storage, l'accesso a livelli di archiviazione non Standard Storage da strumenti esterni (come il software GIS desktop) comporta costi di recupero elevati.
  • Per utilizzare Cloud Storage, devi aver abilitato la fatturazione nel tuo progetto Google Cloud. Per iniziare, consulta la guida rapida di Cloud Storage.

Prepara i COG

Earth Engine legge i COG direttamente da Cloud Storage, recuperando solo l'intestazione e i riquadri necessari per un calcolo, quindi il layout del file è importante. Il file TIFF deve essere:

  • Affiancata, con dimensioni dei riquadri quadrati con potenza di 2 da 16x16 a 2048x2048. Per prestazioni ottimali, consigliamo 512 x 512.
  • Disposte in modo che tutte le directory dei file immagine (IFD) siano all'inizio.
  • Includi panoramiche delle potenze di 2, se presenti. Le panoramiche non sono obbligatorie, ma sono consigliate per le immagini più grandi di un singolo riquadro.
  • Utilizza l'interleave BAND o PIXEL (consulta i file a banda singola e multibanda per i compromessi).

Per convertire un'immagine, utilizza il driver COG di GDAL, che produce il layout richiesto (tassellatura, panoramiche e posizionamento dell'intestazione) in un unico passaggio. Aggiungi OVERVIEW_RESAMPLING=NEAREST per i dati categorici; il valore predefinito è CUBIC. Per i consigli su compressione, panoramica e layout, consulta le best practice per la preparazione di COG esterni.

GDAL 3.11+ CLI

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

Interfaccia a riga di comando classica

Ometti INTERLEAVE=BAND nelle versioni di GDAL precedenti alla 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

Crea il manifest

Sia che registri un COG utilizzando la libreria client Python di Earth Engine, lo strumento a riga di comando earthengine o l'API REST di Earth Engine, devi definire un manifest di caricamento delle immagini che specifichi la destinazione dell'asset, gli URI Cloud Storage e i metadati delle bande facoltativi. L'API e lo strumento a riga di comando fanno riferimento agli asset supportati da COG come immagini esterne (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal).

Esempio: un singolo COG che supporta tutte le bande Se il COG contiene tutte le bande (ad esempio RGB), il manifest richiede un solo tileset:

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

Esempio: più COG (uno per banda) Se hai file separati per bande diverse (ad esempio, rosso, verde e blu in file separati):

{
  "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 }
  ]
}

Limitazioni del manifest

I manifest per gli asset basati su COG presentano limitazioni che non si applicano ai manifest di importazione standard:

  • Bucket singolo: tutti gli URI nel manifest devono trovarsi nello stesso bucket Cloud Storage.
  • Un URI per origine: ogni elemento ImageSource deve contenere esattamente un URI. Non puoi unire più file in un'unica origine del set di riquadri. Per creare un mosaico di più scene COG, registra ogni COG come asset e combinali in un ee.ImageCollection utilizzando .mosaic().
  • No mask_bands: il campo mask_bands di primo livello non è supportato. Utilizza missingData nel manifest o assicurati che il TIFF abbia un valore nodata interno.
  • Nessun data_type nel tileset: non specificare data_type nella sezione tilesets; viene rilevato automaticamente.
  • Nessun dimensions nell'origine: non specificare dimensions in ImageSource.
  • No subdataset_prefix / subdataset_suffix.
  • No min_tile_area_ratio o skip_metadata_read.

Invia la richiesta di registrazione

Puoi inviare il manifest a Earth Engine utilizzando la libreria client Python di Earth Engine, lo strumento a riga di comando earthengine o l'API REST di Earth Engine. Scegli il metodo più adatto al tuo flusso di lavoro.

Libreria client Python

In uno script Python o in un blocco note Jupyter, utilizza la libreria client Python di Earth Engine (ee.data) dopo aver inizializzato il progetto:

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']}")

Strumento a riga di comando

Nel terminale, salva il manifest in un file denominato manifest.json ed esegui il comando di caricamento 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

Per i workflow automatizzati senza la libreria client, invia una richiesta POST autorizzata direttamente all'endpoint dell'API REST di Earth Engine projects.image.importExternal (mostrato qui utilizzando 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))

Una volta inviata, la richiesta di registrazione avvia un'operazione di indicizzazione dei metadati leggera. Poiché la registrazione COG non copia i dati dei pixel, questa operazione viene in genere completata in pochi secondi.

Configura autorizzazioni

A differenza degli asset Earth Engine standard, i dati dei pixel di un COG rimangono in Cloud Storage. Quando condividi un asset basato su COG con altri utenti, devi concedere loro l'accesso in lettura sia all'asset Earth Engine sia ai file Cloud Storage.

Concedi le autorizzazioni per il bucket Cloud Storage

I collaboratori devono disporre delle autorizzazioni per leggere i file da Cloud Storage.

Autorizzazioni obbligatorie:

  • storage.buckets.get (per recuperare i metadati e la località del bucket)
  • storage.objects.get (per leggere i dati dei pixel)

Puoi concedere queste autorizzazioni utilizzando i seguenti ruoli Cloud Storage standard:

  • Storage Bucket Viewer (fornisce storage.buckets.get per leggere i metadati e la località del bucket)
  • Storage Object Viewer (fornisce storage.objects.get per leggere i dati dei pixel)

Passaggi per la configurazione nella console Google Cloud:

  1. Vai al browser Cloud Storage.
  2. Fai clic sul nome del bucket.
  3. Seleziona la scheda Autorizzazioni.
  4. Fai clic su CONCEDI ACCESSO.
  5. Aggiungi gli indirizzi email dei tuoi collaboratori (o di un gruppo Google o allUsers per l'accesso pubblico).
  6. Assegna i ruoli Storage Bucket Viewer e Storage Object Viewer.
  7. Fai clic su Salva.

Condividi l'asset Earth Engine

Condividi l'asset stesso utilizzando Earth Engine Asset Manager o l'interfaccia a riga di comando. Per maggiori dettagli, consulta la guida alla gestione delle risorse.

Aggiorna, sostituisci ed elimina gli asset basati su COG

Un asset basato su COG è un puntatore a una versione specifica di un file in Cloud Storage, oltre ai metadati (footprint, proiezione, bande e layout della panoramica) indicizzati da Earth Engine al momento della registrazione. Earth Engine blocca la versione del file in modo che questi metadati non possano andare fuori sincronia con i pixel, il che rende l'aggiornamento degli asset basati su COG diverso dall'aggiornamento degli asset standard.

Generazioni di oggetti

Quando registri un COG, Earth Engine registra la generazione dell'oggetto Cloud Storage (il numero di versione) insieme all'URI. Puoi visualizzare la generazione bloccata nei metadati dell'asset, che viene visualizzata come suffisso #<generation> nell'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']

Puoi anche bloccare manualmente una versione specifica includendo il suffisso #<generation> nell'URI del manifest quando registri (o registri nuovamente) l'asset. Senza questo parametro, Earth Engine legge l'oggetto corrente e blocca qualsiasi generazione trovata. Il blocco esplicito è utile per eseguire il rollback a una versione precedente conservata da un bucket con il controllo delle versioni degli oggetti.

Se sovrascrivi il file in Cloud Storage, viene creata una nuova generazione, mentre se lo elimini, la generazione bloccata viene eliminata. In entrambi i casi, la lettura dei pixel dell'asset non va a buon fine, a meno che il controllo delle versioni degli oggetti nel bucket non conservi la generazione precedente, nel qual caso Earth Engine continua a leggere i vecchi pixel. Le operazioni sui metadati che utilizzano il record indicizzato (come ee.data.getAsset(), bandNames() e il filtro delle raccolte) continuano a funzionare in entrambi i casi.

Aggiorna un asset dopo aver modificato il file

Per indirizzare un asset esistente a una nuova versione del relativo file, registralo di nuovo con lo stesso nome dell'asset e con la sovrascrittura abilitata. Earth Engine rilegge l'intestazione GeoTIFF, reindicizza i metadati e blocca la nuova generazione in un'unica chiamata sincrona. Le autorizzazioni esistenti dell'asset vengono conservate, ma le sue proprietà, l'intervallo di tempo e i nomi delle bande provengono dal nuovo manifest, quindi includi tutto ciò che hai impostato in precedenza con ee.data.updateAsset().

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Riga di comando: earthengine upload external_image --force --manifest manifest.json
  • API REST: includi "overwrite": true come campo di primo livello insieme a "imageManifest" nel corpo della richiesta projects.image.importExternal.

Non è necessario eliminare prima l'asset, anzi, l'eliminazione è controproducente: un asset autonomo perde le autorizzazioni e un'immagine in una raccolta scompare brevemente dalla raccolta. Tieni presente che ee.data.updateAsset() (projects.assets.patch) può modificare solo le proprietà, l'intervallo di tempo e i nomi delle bande; non può modificare il file a cui punta un asset.

Cicli di vita indipendenti

Gli asset Earth Engine e gli oggetti Cloud Storage vengono gestiti separatamente:

  • L'eliminazione dell'asset Earth Engine (earthengine rm o ee.data.deleteAsset()) rimuove solo il record dell'asset. I tuoi file in Cloud Storage rimangono invariati.
  • L'eliminazione del file in Cloud Storage non rimuove l'asset, che viene comunque visualizzato negli elenchi e nella sua raccolta (vedi Generazioni di oggetti).

Lavora con raccolte di grandi dimensioni

Non esiste un'eliminazione batch o ricorsiva nell'API Earth Engine: ogni asset deve essere eliminato singolarmente e una raccolta deve essere vuota prima di poter essere eliminata. earthengine rm -r gestisce questa operazione per te, ma esegue le eliminazioni una alla volta, quindi la rimozione di una raccolta con decine di migliaia di immagini può richiedere ore.

  • Per sostituire le immagini di una raccolta, sovrascrivile anziché eliminarle. Registra nuovamente ogni immagine per nome con la sovrascrittura attivata (vedi sopra). In questo modo, è necessaria una richiesta per immagine anziché due, la raccolta rimane sempre compilata e si evita di eliminarla e ricrearla, il che è importante perché è lì che risiedono le autorizzazioni. Elimina solo le immagini che non sono presenti nel nuovo set.

  • Per eliminare molti asset, parallelizza da uno script. Elenca gli asset con ee.data.listAssets() (utilizzando la visualizzazione BASIC, che restituisce solo nomi e tipi anziché i metadati completi per ogni immagine) ed eliminali da un piccolo pool di thread. Le richieste di asset condividono i limiti di frequenza a livello di progetto, quindi mantieni la concorrenza moderata (circa 10 worker) e lascia che i tentativi di ripetizione integrati della libreria client gestiscano eventuali risposte 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 raccolta viene eliminata solo se sono state eliminate tutte le immagini, quindi un errore parziale la lascia invariata per una nuova esecuzione.

    Lo stesso pattern si applica alla registrazione di più immagini: sostituisci ee.data.deleteAsset(asset_id) nell'helper con ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) e mappalo nell'elenco dei manifest. Se passi allow_overwrite=True anche alla prima esecuzione, il batch può essere eseguito di nuovo in sicurezza dopo un errore parziale, poiché qualsiasi asset già creato viene sostituito anziché causare un errore.

Utilizza gli asset registrati

Una volta registrato, un asset basato su COG è accessibile negli script di Earth Engine proprio come qualsiasi asset immagine importato 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')

Per risposte alle domande comuni su autorizzazioni, aggiornamento dei file e gestione di raccolte di grandi dimensioni, consulta la sezione COG delle domande frequenti.