Asset Earth Engine basati su GeoTiff di Cloud

Logo Colab Esegui in Google Colab Logo di GitHub Visualizza il codice sorgente su GitHub

Earth Engine supporta gli asset basati su COG (GeoTIFF ottimizzati per il cloud). Un vantaggio degli asset basati su COG è che i campi spaziali e dei metadati dell'immagine verranno indicizzati al momento della creazione dell'asset, migliorando le prestazioni dell'immagine nelle raccolte. Il rendimento degli asset basati su COG è paragonabile a quello degli asset importati nei casi d'uso tipici.

Tieni presente che un singolo asset può essere supportato da più COG (ad esempio, può essercene uno per fascia). Tuttavia, l'utilizzo di molti riquadri COG per una singola banda non è supportato.

In alternativa, Earth Engine può caricare direttamente le immagini dai COG in Google Cloud Storage (scopri di più). Tuttavia, un'immagine caricata tramite ee.Image.loadGeoTIFF e aggiunta a una raccolta di immagini richiederà la lettura del file GeoTiff per le operazioni di filtro sulla raccolta.

Per creare una risorsa basata su COG:

  1. Inserisci i file COG in un bucket GCS (vedi di seguito le regioni consentite).
  2. Scrivi un manifest per il caricamento di immagini
  3. Utilizza l'utilità a riga di comando earthengine per inviare un comando di caricamento:
earthengine upload external_image --manifest my_manifest.json

File manifest dell'immagine di esempio con un Tileset

Il ImageManifest più semplice è quello con un singolo Tileset. Se non vengono specificati, la risorsa risultante conterrà tutti i canali del file GeoTIFF con i nomi dei canali codificati nel file GeoTIFF (in questo caso, "vis-red", "vis-green" e "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)

Più di un Tileset

È possibile specificare un ImageManifest con più di un Tileset, dove ogni banda della risorsa risultante è supportata da una delle bande di un Tileset utilizzando i campi tilesetId e tilesetBandIndex. Questo è utile nel caso in cui bande diverse abbiano risoluzioni o tipi di dati diversi. Le bande possono essere elencate in qualsiasi ordine da qualsiasi Tileset disponibile. Nell'esempio seguente:

  • "b4b3b2.tif" ha una scala di 10 m, mentre "b5b6b7" ha una scala di 20 m.
  • L'ordine delle bande dell'asset risultante è misto da COG di input (ad es. la banda di output 0 proviene da Tileset 0, mentre la banda di output 1 proviene da 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)

Dettagli sugli asset basati su COG

Località

La località del bucket Cloud Storage deve essere una delle seguenti:

  • La multiregione degli Stati Uniti
  • Qualsiasi regione doppia degli Stati Uniti che include US-CENTRAL1
  • La regione US-CENTRAL1

Classe di archiviazione

La classe di archiviazione del bucket deve essere "Spazio di archiviazione standard".

Autorizzazioni per la condivisione

Le ACL degli asset Earth Engine basati su COG e i dati sottostanti vengono gestiti distintamente. Quando condividi risorse basate su COG con i collaboratori per la lettura, è compito del proprietario assicurarsi che l'accesso in lettura sia concesso sia alla risorsa Earth Engine sia ai file COG sottostanti.

1. Concedi le autorizzazioni di lettura per il bucket Google Cloud Storage

Affinché i collaboratori possano leggere gli asset basati su COG, devono prima disporre dell'accesso in lettura ai file COG sottostanti nel bucket Google Cloud Storage. Senza queste autorizzazioni, Earth Engine non potrà recuperare i dati per loro. Se i dati in Google Cloud Storage non sono visibili a un utente di Earth Engine, Earth Engine restituirà un errore del tipo "Impossibile caricare il file GeoTIFF in gs://my-bucket/my-object#123456" (dove 123456 è la generazione dell'oggetto).

In particolare, i collaboratori devono disporre delle seguenti autorizzazioni:

  • storage.buckets.get sul bucket (per recuperare i metadati e la posizione del bucket, consentendo a Earth Engine di risolvere correttamente l'origine della risorsa).
  • storage.objects.get nel bucket (per leggere i dati effettivi degli asset basati su COG).

Queste autorizzazioni sono fornite dai ruoli "Storage Legacy Bucket Reader" e "Storage Legacy Object Reader", tra gli altri.

Per assegnare questi ruoli ai collaboratori:

  1. Vai alla pagina delle autorizzazioni del bucket: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. Fai clic su "CONCEDI ACCESSO".
  3. Aggiungi tutte le entità (ad es. utenti, gruppi, account di servizio) a cui deve essere concesso l'accesso in lettura.
  4. Assegna i seguenti ruoli:
    • "Storage Legacy Bucket Reader" (fornisce storage.buckets.get e altre autorizzazioni di lettura a livello di bucket).
    • "Lettore oggetti legacy Storage" (fornisce storage.objects.get).
    • In alternativa, puoi creare un nuovo ruolo personalizzato con solo le autorizzazioni storage.buckets.get e storage.objects.get e assegnarlo.
  5. Salva

2. Condividere l'asset Earth Engine per la lettura

Dopo aver verificato che i tuoi collaboratori dispongano delle autorizzazioni necessarie per gli oggetti e il bucket GCS sottostanti, devi anche condividere l'asset Earth Engine stesso. Per ulteriori informazioni sull'impostazione delle autorizzazioni delle risorse di Earth Engine, consulta la guida alla gestione delle risorse di Earth Engine.

Generazioni

Quando viene creato un asset basato su COG, Earth Engine legge i metadati dei file TIFF specificati nel manifest e crea una voce dello Store asset. Ogni URI associato a quella voce può avere una generazione. Per informazioni sulle generazioni, consulta la documentazione sul versionamento degli oggetti. Se viene specificata una generazione, ad esempio gs://foo/bar#123, Earth Engine memorizza l'URI esattamente come è stato specificato. Se non viene specificata una generazione, Earth Engine memorizza l'URI con la generazione del TIFF al momento dell'esecuzione della chiamata a ImportExternalImage.

Ciò significa che se un TIFF contenente una risorsa esterna in GCS viene aggiornato (modificando quindi la relativa generazione), Earth Engine restituirà un errore "Impossibile caricare il file GeoTIFF in gs://my-bucket/my-object#123456" perché l'oggetto previsto non esiste più (a meno che il bucket non consenta più versioni dell'oggetto). Questo criterio è progettato per mantenere sincronizzati i metadati della risorsa con quelli dell'oggetto.

Configurazione

In termini di configurazione di un COG, il file TIFF DEVE essere:

  • A riquadri, dove le dimensioni dei riquadri sono:

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

  • Disposti in modo che tutti gli IFD siano all'inizio.

Per ottenere il massimo rendimento:

  • Utilizza dimensioni dei riquadri pari o superiori a 512 x 512.
  • Includi le panoramiche Potenza di 2.

A seconda dei casi d'uso previsti, l'opzione di creazione "INTERLEAVE" potrebbe influire sulle prestazioni. Ti consigliamo di utilizzare l'interlacciamento BAND in tutte le circostanze.

Per maggiori dettagli su una configurazione ottimizzata, consulta questa pagina.

Il seguente comando gdal_translate consente di convertire un raster in un file GeoTIFF ottimizzato per il cloud con interlacciamento delle bande e compressione zstd che avrà un buon rendimento in 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

Potrebbe essere possibile ridurre ulteriormente le dimensioni del file di output specificando un predittore (-co PREDICTOR=2 per i tipi di dati interi e -co PREDICTOR=3 per i tipi di dati con virgola mobile).

Per gli utenti con GDAL >= 3.11, il driver COG può produrre file senza doversi preoccupare di creare e conservare le panoramiche.

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 \

Creazione di asset basati su file GeoTiff di Cloud utilizzando l'API REST

Nota: l'API REST contiene funzionalità nuove e avanzate che potrebbero non essere adatte a tutti gli utenti. Se non hai mai utilizzato Earth Engine, ti consigliamo di iniziare con la guida su JavaScript.

Per creare una risorsa basata su COG utilizzando l'API REST, invia una richiesta POST all'ImportExternalImage endpoint di Earth Engine. Come mostrato di seguito, questa richiesta deve essere autorizzata per creare un asset nella tua cartella utente.

Avviare una sessione autorizzata

Per poter creare una risorsa Earth Engine nella tua cartella utente, devi essere in grado di autenticarti come te stesso quando effettui la richiesta. Puoi utilizzare le credenziali dell'autenticatore di Earth Engine per avviare un AuthorizedSession. Puoi quindi utilizzare AuthorizedSession per inviare richieste a 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)
)

Corpo della richiesta

Il corpo della richiesta è un'istanza di un ImageManifest. Qui viene specificato il percorso del COG, insieme ad altre proprietà utili.

Consulta questa guida per maggiori dettagli su come configurare un ImageManifest. È possibile definire uno o più Tileset con ciascuno che supporta una o più bande. Per ImportExternalImage, è supportato al massimo un ImageSource per Tileset.

Consulta questo documento per informazioni dettagliate sull'esportazione dei COG.

Invia la richiesta

Invia la richiesta POST all'endpoint 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))