Earth Engine-Assets mit GeoTIFF-Dateien in der Cloud

Colab-Logo In Google Colab ausführen Logo: GitHub Quelle auf GitHub ansehen

Earth Engine unterstützt Assets, die auf Cloud-optimierten GeoTIFFs (COGs) basieren. Ein Vorteil von COG-basierten Assets ist, dass die räumlichen und Metadatenfelder des Bildes bei der Erstellung des Assets indexiert werden. Dadurch ist das Bild in Sammlungen leistungsfähiger. Die Leistung von COG-basierten Assets ist in typischen Anwendungsfällen mit der von aufgenommenen Assets vergleichbar.

Ein einzelnes Asset kann auf mehreren COGs basieren (z. B. ein COG pro Band). Die Verwendung vieler COG-Kacheln für ein einzelnes Band wird jedoch nicht unterstützt.

Alternativ kann Earth Engine Bilder direkt aus COGs in Google Cloud Storage (weitere Informationen). Für ein Bild, das über ee.Image.loadGeoTIFF geladen und einer Bildsammlung hinzugefügt wurde, muss das GeoTIFF jedoch gelesen werden, um Filtervorgänge für die Sammlung auszuführen.

So erstellen Sie ein COG-basiertes Asset:

  1. Platzieren Sie Ihre COG-Dateien in einem GCS-Bucket (siehe Standort für die zulässigen Regionen).
  2. Manifest für den Bild-Upload erstellen
  3. Verwenden Sie das Befehlszeilenprogramm earthengine, um einen Upload-Befehl zu senden:
earthengine upload external_image --manifest my_manifest.json

Beispiel für ein Bildmanifest mit einem Tileset

Das einfachste ImageManifest enthält ein einzelnes Tileset. Wenn keine Bänder angegeben sind, enthält das resultierende Asset alle Bänder des GeoTIFF mit den in GeoTIFF codierten Bandnamen (in diesem Fall „vis-red“, „vis-green“ und „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)

Mehr als ein Tileset

Es ist möglich, ein ImageManifest mit mehr als einem Tileset anzugeben, wobei jedes Band des resultierenden Assets mit einem der Bänder eines Tileset über die Felder tilesetId und tilesetBandIndex verknüpft ist. Dies ist nützlich, wenn verschiedene Bänder unterschiedliche Auflösungen oder Datentypen haben. Bänder können in beliebiger Reihenfolge aus einem beliebigen verfügbaren Tileset aufgelistet werden. Im folgenden Beispiel gilt:

  • „b4b3b2.tif“ hat einen Maßstab von 10 m, während „b5b6b7“ einen Maßstab von 20 m hat.
  • Die Bandreihenfolge des resultierenden Assets ist aus den Eingabe-COGs gemischt (z.B. stammt das Ausgabeband 0 aus Tileset 0, während das Ausgabeband 1 aus Tileset 1 stammt).
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)

Details zu COG-basierten Assets

Standort

Der Standort des Cloud Storage-Buckets muss einer der folgenden sein:

  • Die Multiregion „USA“
  • Eine beliebige duale Region in den USA, die US-CENTRAL1 umfasst
  • Die Region US-CENTRAL1

Speicherklasse

Die Speicher klasse des Buckets muss „Standard Storage“ sein.

Berechtigungen für die Freigabe

Die ACLs von COG-basierten Earth Engine-Assets und den zugrunde liegenden Daten werden separat verwaltet. Wenn Sie COG-basierte Assets für die Lesezugriffe mit Mitarbeitern teilen, liegt es in der Verantwortung des Eigentümers, dafür zu sorgen, dass sowohl für das Earth Engine-Asset als auch für die zugrunde liegenden COG-Dateien Lesezugriff gewährt wird.

1. Berechtigungen für das Lesen von Google Cloud Storage-Buckets gewähren

Damit Mitarbeiter COG-basierte Assets lesen können, müssen sie zuerst Lesezugriff auf die zugrunde liegenden COG-Dateien im Google Cloud Storage-Bucket haben. Ohne diese Berechtigungen kann Earth Engine die Daten nicht für sie abrufen. Wenn die Daten in Google Cloud Storage für einen Earth Engine-Nutzer nicht sichtbar sind, gibt Earth Engine einen Fehler im Format „Failed to load the GeoTIFF at gs://my-bucket/my-object#123456“ zurück (wobei 123456 die Generation des Objekts ist).

Mitarbeiter benötigen die folgenden Berechtigungen:

  • storage.buckets.get für den Bucket (zum Abrufen von Bucket-Metadaten und -Standort, damit Earth Engine die Quelle des Assets richtig auflösen kann).
  • storage.objects.get für den Bucket (zum Lesen der tatsächlichen COG-basierten Asset-Daten).

Diese Berechtigungen werden unter anderem durch die Rollen „Leser alter Storage-Buckets“ und „Leser alter Storage-Objekte“ gewährt.

So weisen Sie Mitarbeitern diese Rollen zu:

  1. Rufen Sie die Seite mit den Bucket-Berechtigungen auf: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. Klicken Sie auf ZUGRIFF GEWÄHREN.
  3. Fügen Sie alle Hauptkonten (z.B. Nutzer, Gruppen, Dienstkonten) hinzu, denen Lesezugriff gewährt werden soll.
  4. Weisen Sie die folgenden Rollen zu:
    • "Leser alter Storage-Buckets" (gewährt storage.buckets.get und andere Leseberechtigungen auf Bucket-Ebene).
    • Leser alter Storage-Objekte (gewährt storage.objects.get).
    • Alternativ können Sie eine neue benutzerdefinierte Rolle mit den Berechtigungen storage.buckets.get und storage.objects.get erstellen und diese zuweisen.
  5. Speichern

2. Earth Engine-Asset für Lesezugriff freigeben

Nachdem Sie dafür gesorgt haben, dass Ihre Mitarbeiter die erforderlichen Berechtigungen für den zugrunde liegenden GCS-Bucket und die Objekte haben, müssen Sie auch das Earth Engine-Asset selbst freigeben. Weitere Informationen zum Festlegen von Berechtigungen für Earth Engine-Assets finden Sie im Leitfaden zur Verwaltung von Earth Engine-Assets.

Generierungen

Wenn ein COG-basiertes Asset erstellt wird, liest Earth Engine die Metadaten der im Manifest angegebenen TIFFs und erstellt einen Asset-Speichereintrag. Jeder mit diesem Eintrag verknüpfte URI kann eine Generation haben. Weitere Informationen zu Generationen finden Sie in der Dokumentation zur Objektversionsverwaltung. Wenn eine Generation angegeben ist, z. B. gs://foo/bar#123, speichert Earth Engine diesen URI unverändert. Wenn keine Generation angegeben ist, speichert Earth Engine diesen URI mit der Generation des TIFFs zum Zeitpunkt des Aufrufs von ImportExternalImage.

Wenn also ein TIFF, das ein externes Asset in GCS enthält, aktualisiert wird (wodurch sich die Generation ändert), gibt Earth Engine den Fehler „Failed to load the GeoTIFF at gs://my-bucket/my-object#123456“ zurück, da das erwartete Objekt nicht mehr vorhanden ist (es sei denn, im Bucket sind mehrere Objektversionen aktiviert). Diese Richtlinie soll dafür sorgen, dass die Metadaten des Assets mit den Metadaten des Objekts synchronisiert werden.

Konfiguration

In Bezug auf die Konfiguration eines COG muss das TIFF Folgendes sein:

  • Gekachelt, wobei die Kachelabmessungen entweder:

    • 256 × 256
    • 512 × 512
    • 1024 × 1024
    • 2048 × 2048

  • So angeordnet, dass sich alle IFDs am Anfang befinden.

Für eine optimale Leistung:

  • Verwenden Sie Kachelabmessungen von mindestens 512 × 512.
  • Fügen Sie Übersichten mit Zweierpotenzen hinzu.

Je nach Anwendungsfall kann sich die „INTERLEAVE“ Erstellungsoption auf die Leistung auswirken. Wir empfehlen, unter allen Umständen die Band-Interleave-Option zu verwenden.

Weitere Informationen zu einer optimierten Konfiguration finden Sie auf dieser Seite.

Mit dem folgenden gdal_translate-Befehl wird ein Raster in ein bandweise verschachteltes, mit zstd komprimiertes, Cloud-optimiertes GeoTIFF konvertiert, das in Earth Engine gut funktioniert:

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

Möglicherweise lässt sich die Ausgabedateigröße weiter reduzieren, indem Sie einen Prädiktor (-co PREDICTOR=2 für Ganzzahldatentypen und -co PREDICTOR=3 für Gleitkomma datentypen) angeben.

Für Nutzer mit GDAL >= 3.11 kann der COG-Treiber Dateien erstellen, ohne dass Übersichten erstellt und beibehalten werden müssen.

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 \

Cloud-GeoTIFF-basierte Assets mit der REST API erstellen

Hinweis:Die REST API enthält neue und erweiterte Funktionen, die möglicherweise nicht für alle Nutzer geeignet sind. Wenn Sie Earth Engine noch nicht kennen, empfehlen wir Ihnen, mit dem JavaScript Leitfaden zu beginnen.

Um ein COG-basiertes Asset mit der REST API zu erstellen, senden Sie eine POST Anfrage an den Earth Engine ImportExternalImage Endpunkt. Wie unten gezeigt, muss diese Anfrage autorisiert sein, um ein Asset in Ihrem Nutzerordner zu erstellen.

Autorisierte Sitzung starten

Damit Sie ein Earth Engine-Asset in Ihrem Nutzerordner erstellen können, müssen Sie sich bei der Anfrage als Sie selbst authentifizieren können. Sie können Anmeldedaten aus dem Earth Engine-Authenticator verwenden, um eine AuthorizedSession zu starten. Anschließend können Sie die AuthorizedSession verwenden, um Anfragen an Earth Engine zu senden.

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

Anfragetext

Der Anfragetext ist eine Instanz von einem ImageManifest. Hier wird der Pfad zum COG zusammen mit anderen nützlichen Eigenschaften angegeben.

Weitere Informationen zum Konfigurieren eines ImageManifest finden Sie in diesem Leitfaden. Es ist möglich, ein oder mehrere Tileset zu definieren, wobei jedes ein oder mehrere Bänder unterstützt. Für ImportExternalImage wird maximal eine ImageSource pro Tileset unterstützt.

Weitere Informationen zum Exportieren von COGs finden Sie in diesem Dokument.

Anfrage senden

Senden Sie die POST-Anfrage an den Earth Engine projects.images.importExternal Endpunkt.

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