Asset Earth Engine basati su GeoTiff di Cloud

Logo Colab Esegui in Google Colab Logo di GitHub Visualizza l'origine su GitHub

Earth Engine supporta gli asset basati su GeoTIFF ottimizzati per il cloud (COG). Un vantaggio degli asset basati su COG è che i campi spaziali e dei metadati dell'immagine vengono indicizzati al momento della creazione dell'asset, il che rende l'immagine più performante nelle raccolte. Le prestazioni degli asset basati su COG sono paragonabili a quelle degli asset importati nei casi d'uso tipici.

Tieni presente che un singolo asset può essere supportato da più COG (ad esempio, può esistere un COG per banda). 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à una lettura del GeoTIFF per le operazioni di filtro sulla raccolta.

Per creare un asset basato su COG:

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

Esempio di manifest di immagini con un Tileset

L'ImageManifest più semplice è quello con un singolo Tileset. Se non vengono specificate bande, l'asset risultante conterrà tutte le bande del GeoTIFF con i nomi delle bande codificati nel 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 in cui ogni banda dell'asset risultante è supportata da una delle bande di un Tileset utilizzando i campi tilesetId e tilesetBandIndex. Questa opzione è utile quando bande diverse hanno risoluzioni o tipi di dati diversi. Le bande possono essere elencate in qualsiasi ordine da qualsiasi Tileset disponibile. Nel seguente esempio:

  • "b4b3b2.tif" ha una scala di 10 m, mentre "b5b6b7" ha una scala di 20 m.
  • L'ordine delle bande dell'asset risultante è misto rispetto ai 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 multi-regione Stati Uniti
  • Qualsiasi doppia regione degli Stati Uniti che includa US-CENTRAL1
  • La regione US-CENTRAL1

Classe di archiviazione

La classe di archiviazione del bucket deve essere "Standard Storage".

Autorizzazioni per la condivisione

Le ACL degli asset Earth Engine basati su COG e i dati sottostanti vengono gestiti separatamente. Quando condividi asset basati su COG con i collaboratori per la lettura, è responsabilità del proprietario assicurarsi che l'accesso in lettura sia concesso sia all' asset 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 avere accesso in lettura ai file COG sottostanti nel bucket Google Cloud Storage. Senza queste autorizzazioni, Earth Engine non sarà in grado di 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 "Failed to load the GeoTIFF at gs://my-bucket/my-object#123456" (dove 123456 è la generazione dell'oggetto).

Nello specifico, i collaboratori devono disporre delle seguenti autorizzazioni:

  • storage.buckets.get sul bucket (per recuperare i metadati e la località del bucket, consentendo a Earth Engine di risolvere correttamente l'origine dell'asset).
  • storage.objects.get sul bucket (per leggere i dati effettivi dell'asset basato su COG).

Queste autorizzazioni sono fornite rispettivamente 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, service account) 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).
    • "Storage Legacy Object Reader" (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. Condividi l'asset Earth Engine per la lettura

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

Generazioni

Quando viene creato un asset basato su COG, Earth Engine legge i metadati dei TIFF specificati nel manifest e crea una voce di asset store. Ogni URI associato a questa voce può avere una generazione. Per i dettagli sulle generazioni, consulta la documentazione sul controllo delle versioni degli oggetti. Se viene specificata una generazione, ad esempio gs://foo/bar#123, Earth Engine memorizzerà l'URI verbatim. Se non viene specificata una generazione, Earth Engine memorizzerà l'URI con la generazione del TIFF al momento della chiamata di ImportExternalImage.

Ciò significa che se un TIFF che comprende un asset esterno in GCS viene aggiornato (modificando quindi la sua generazione), Earth Engine restituirà un errore "Failed to load the GeoTIFF at gs://my-bucket/my-object#123456" perché l'oggetto previsto non esiste più (a meno che il bucket non consenta più versioni dell'oggetto). Questa policy è progettata per mantenere i metadati dell'asset sincronizzati con i metadati dell'oggetto.

Configurazione

Per quanto riguarda la configurazione di un COG, il TIFF DEVE essere:

  • A riquadri, dove le dimensioni dei riquadri sono:

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

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

Per prestazioni ottimali:

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

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

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

Il seguente comando gdal_translate convertirà un raster in un GeoTIFF ottimizzato per il cloud, compresso con zstd e con interleave delle bande, che funzionerà bene 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 a 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 Cloud GeoTIFF 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 familiarità con Earth Engine, ti consigliamo di iniziare con la guida di JavaScript.

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

Avvia una sessione autorizzata

Per poter creare un asset Earth Engine nella cartella utente, devi essere in grado di autenticarti come te stesso quando effettui la richiesta. Puoi utilizzare le credenziali dell'autenticatore 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.

Per i dettagli su come configurare un ImageManifest, consulta questa guida. È possibile definire uno o più Tileset, ognuno dei quali supporta una o più bande. Per ImportExternalImage, è supportata al massimo una ImageSource per Tileset.

Per i dettagli sull'esportazione dei COG, consulta questo documento.

Invia la richiesta

Invia la richiesta POST all'endpoint projects.images.importExternal di Earth Engine.

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