Registrazione degli asset GeoTIFF ottimizzati per il cloud (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 agli asset standard inseriti (vedi la panoramica di GeoTIFF ottimizzati per il cloud (COG)).

Prerequisiti e configurazione di Cloud Storage

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

1. Località del bucket (requisito rigoroso)

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

• La multi-regione us
• Qualsiasi doppia regione degli Stati Uniti che includa 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.

2. Classe di archiviazione e fatturazione

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

Passaggio 1: prepara i COG

I file TIFF devono essere ottimizzati per il cloud. Il TIFF deve essere:

• Suddiviso in riquadri, con dimensioni dei riquadri di: 256x256, 512x512, 1024x1024 o 2048x2048. Per prestazioni ottimali, consigliamo 512x512 o valori superiori.
• Organizzato in modo che tutte le directory dei file immagine (IFD) si trovino all'inizio.
• Includi le panoramiche di potenza di 2.
• Utilizza l'interleave BAND.

Puoi utilizzare GDAL per convertire le immagini.

Utilizzo del driver GDAL COG (GDAL >= 3.1 consigliato):

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

Utilizzo del driver GTiff standard:

Innanzitutto, genera panoramiche interne di potenza di 2 (utilizzando gdal raster overview add o gdaladdo), quindi copia l'immagine e le panoramiche in un layout COG suddiviso in riquadri:

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

Passaggio 2: crea il manifest

Indipendentemente dal fatto che tu 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 di Google Cloud Storage e i metadati delle bande facoltativi.

Esempio: un singolo COG che supporta tutte le bande Se il COG contiene tutte le bande (ad es. 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 es. rosso, verde, 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 }
  ]
}

Passaggio 3: 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 notebook 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. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
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. Submit the external image upload task
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json
      

API REST (Python)

Per i flussi di lavoro automatizzati senza la libreria client, invia una richiesta autorizzata POST 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 in genere viene completata in pochi secondi.

Registrazione sincrona: poiché la registrazione COG è una chiamata API sincrona e veloce anziché un job di calcolo batch asincrono, non crea un'attività in background nella scheda Attività dell'editor di codice o nel gestore delle attività batch. La chiamata API viene bloccata fino al completamento della convalida dei metadati e dell'indicizzazione, dopodiché l'asset è immediatamente disponibile nella scheda Asset dell'editor di codice o utilizzando ee.data.getAsset().

Limitazioni del manifest per gli asset COG

Quando crei un manifest per gli asset basati su COG, tieni presente queste limitazioni rigorose (che differiscono dai manifest di importazione standard):

• Un solo bucket: tutti gli URI nel manifest devono risiedere nello stesso bucket GCS.
• Un URI per origine: ogni ImageSource deve contenere esattamente un URI. Non puoi unire più file in mosaico in un'unica origine tileset. Per unire in mosaico più scene COG, registra ogni COG come asset e combinali in un ee.ImageCollection utilizzando .mosaic().
• Nessun mask_bands: 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.
• Nessun subdataset_prefix / subdataset_suffix.
• Nessun min_tile_area_ratio o skip_metadata_read.

Passaggio 4: configura le autorizzazioni (fondamentale per la condivisione)

A differenza degli asset Earth Engine standard, i dati dei pixel di un COG rimangono in GCS. 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 GCS.

1. Concedi le autorizzazioni del bucket GCS

I collaboratori hanno bisogno delle autorizzazioni per leggere i file da GCS.

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 standard di Cloud Storage:

• Visualizzatore bucket Storage (fornisce storage.buckets.get per leggere i metadati e la località del bucket)
• Visualizzatore oggetti Storage (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 un gruppo Google o allUsers per l'accesso pubblico).
6. Assegna i ruoli Visualizzatore bucket Storage e Visualizzatore oggetti Storage.
7. Fai clic su Salva.

2. Condividi l'asset Earth Engine

Condividi l'asset stesso utilizzando Earth Engine Asset Manager o CLI. Per maggiori dettagli, consulta la Guida alla gestione degli asset.

Gestire le generazioni di oggetti

Quando registri un COG, Earth Engine memorizza la generazione (versione) specifica dell'oggetto GCS. Se aggiorni il file in GCS, la sua generazione cambia.

• Per impostazione predefinita, Earth Engine non riuscirà a caricare l'asset e restituirà un errore: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
• Questa operazione è progettata per impedire che i metadati (come la proiezione o l'impronta) non siano sincronizzati con i pixel sottostanti.

• Best practice: se devi aggiornare i dati dell'immagine sottostante, registrali come nuovo asset o esegui di nuovo il comando di caricamento con il flag --force anziché sovrascrivere i file in loco:

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

Utilizzare gli asset registrati

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