Earth Engine-Assets mit GeoTIFF-Dateien in der Cloud

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

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

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

Alternativ können in Earth Engine Bilder direkt aus COGs in Google Cloud Storage geladen werden (weitere Informationen). Wenn ein Bild jedoch über ee.Image.loadGeoTIFF geladen und einer Bildsammlung hinzugefügt wird, muss das GeoTiff für Filtervorgänge in der Sammlung gelesen werden.

So erstellst du ein COG-gestütztes Asset:

  1. Legen Sie Ihre COG-Dateien in einen GCS-Bucket ab (zulässige Regionen siehe unten).
  2. Manifest für den Bildupload schreiben
  3. Verwenden Sie das earthengine-Befehlszeilentool, um einen Uploadbefehl zu senden:
earthengine upload external_image --manifest my_manifest.json

Beispielbildmanifest mit einer Tileset

Die einfachste ImageManifest ist eine mit einem einzelnen Tileset. Wenn keine Bänder angegeben werden, enthält das resultierende Asset alle Bänder des GeoTIFF mit den im GeoTIFF codierten Bändernamen (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 eine Tileset

Es ist möglich, eine ImageManifest mit mehreren Tileset anzugeben, wobei jeder Band des resultierenden Assets von einem der Bänder eines Tileset unterstützt wird. Dazu werden die Felder tilesetId und tilesetBandIndex verwendet. Das ist nützlich, wenn verschiedene Bänder unterschiedliche Auflösungen oder Datentypen haben. Die Bänder können in beliebiger Reihenfolge aus beliebigen verfügbaren Tileset aufgeführt werden. Im Beispiel unten gilt Folgendes:

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

Standort

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

  • USA (mehrere Regionen)
  • Beliebige zweigleisige Region in den USA, die US-CENTRAL1 enthält
  • Die Region US-CENTRAL1

Speicherklasse

Die storageClass des Buckets muss „Standardspeicher“ sein.

Berechtigungen für die Freigabe

Die ACLs von COG-gestützten Earth Engine-Assets und die zugrunde liegenden Daten werden getrennt verwaltet. Wenn Sie COG-basierte Assets für Mitbearbeiter zum Lesen freigeben, liegt es in der Verantwortung des Eigentümers, dafür zu sorgen, dass Lesezugriff sowohl auf das Earth Engine-Asset als auch auf die zugrunde liegenden COG-Dateien gewährt wird.

1. Google Cloud Storage-Bucket-Berechtigungen zum Lesen gewähren

Damit Mitbearbeiter COG-basierte Assets lesen können, benötigen sie Lesezugriff auf die zugrunde liegenden COG-Dateien im Google Cloud Storage-Bucket. 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 vom Typ „Failed to load the GeoTIFF at gs://my-bucket/my-object#123456“ zurück (wobei 123456 die Generation des Objekts ist).

Insbesondere benötigen Mitbearbeiter die folgenden Berechtigungen:

  • storage.buckets.get für den Bucket (zum Abrufen von Bucket-Metadaten und -Speicherort, damit Earth Engine die Quelle des Assets korrekt auflösen kann).
  • storage.objects.get auf den Bucket, um die tatsächlichen COG-gestützten Asset-Daten zu lesen.

Diese Berechtigungen sind unter anderem in den Rollen Storage Legacy Bucket Reader und Storage Legacy Object Reader enthalten.

So weisen Sie Mitbearbeitern diese Rollen zu:

  1. Rufen Sie die Seite „Bucket-Berechtigungen“ auf: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. Klicken Sie auf ZUGRIFF ERLAUBEN.
  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 (ermöglicht storage.buckets.get und andere Leseberechtigungen auf Bucketebene)
    • „Leser alter Storage-Objekte“ (ermöglicht storage.objects.get).
    • Alternativ können Sie eine neue benutzerdefinierte Rolle mit nur den Berechtigungen storage.buckets.get und storage.objects.get erstellen und zuweisen.
  5. Speichern

2. Earth Engine-Asset zum Lesen freigeben

Nachdem Sie dafür gesorgt haben, dass Ihre Mitbearbeiter 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 Earth Engine-Asset-Verwaltung.

Generierungen

Wenn ein COG-gestütztes Asset erstellt wird, liest Earth Engine die Metadaten der im Manifest angegebenen TIFFs und erstellt einen Asset-Store-Eintrag. 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, wird dieser URI in Earth Engine unverändert gespeichert. Wenn keine Generation angegeben ist, speichert Earth Engine diesen URI mit der TIFF-Generation zum Zeitpunkt des Aufrufs von ImportExternalImage.

Wenn also ein TIFF-Format mit einem externen Asset in GCS aktualisiert wird (wodurch sich die Generation ändert), gibt Earth Engine den Fehler „GeoTIFF unter gs://my-bucket/my-object#123456 konnte nicht geladen werden“ zurück, da das erwartete Objekt nicht mehr vorhanden ist, es sei denn, für den Bucket sind mehrere Objektversionen aktiviert. Mit dieser Richtlinie sollen die Metadaten des Assets mit den Metadaten des Objekts synchronisiert werden.

Konfiguration

Für die Konfiguration eines COG muss die TIFF-Datei folgende Anforderungen erfüllen:

  • „Gekachelt“, wobei die Kachelabmessungen entweder

    • 256 × 256
    • 512 x 512
    • 1024x1024
    • 2.048 x 2.048

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

So erzielen Sie die beste Leistung:

  • Verwenden Sie Kacheln mit einer Größe von mindestens 512 × 512 Pixeln.
  • Fügen Sie Übersichten mit Potenzen von 2 hinzu.

Je nach Anwendungsfall kann sich die Erstellungsoption INTERLEAVE auf die Leistung auswirken. Wir empfehlen in jedem Fall die Verwendung von BAND-Interleave.

Auf dieser Seite finden Sie weitere Informationen zu einer optimierten Konfiguration.

Mit dem folgenden gdal_translate-Befehl wird ein Raster in ein bandüberlagerndes, mit ZSTD komprimiertes, cloudoptimiertes GeoTIFF konvertiert, das in Earth Engine eine gute Leistung erzielt:

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 Größe der Ausgabedatei weiter reduzieren, indem Sie einen Prognosewert angeben (-co PREDICTOR=2 für Ganzzahldatentypen und -co PREDICTOR=3 für Gleitkommadatentypen).

Nutzer mit GDAL >= 3.11 können mit dem COG-Treiber Dateien erstellen, ohne sich um das Erstellen und Speichern von Übersichten kümmern zu 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 \

Mit der REST API Cloud-Assets mit GeoTIFF-Unterstützung 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.

Wenn Sie ein COG-gestütztes Asset mit der REST API erstellen möchten, senden Sie eine POST-Anfrage an den ImportExternalImage-Endpunkt von Earth Engine. Wie unten gezeigt, muss diese Anfrage autorisiert sein, 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 mit AuthorizedSession Anfragen an Earth Engine 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 ImageManifest. Hier wird der Pfad zum COG sowie andere nützliche Eigenschaften angegeben.

In dieser Anleitung erfahren Sie, wie Sie eine ImageManifest konfigurieren. Es ist möglich, eine oder mehrere Tileset zu definieren, die jeweils eine oder mehrere Bänder unterstützen. Bei ImportExternalImage wird pro Tileset maximal eine ImageSource unterstützt.

In diesem Dokument finden Sie weitere Informationen zum Exportieren von Kosten- und Gewinnaufschlüsselungen.

Anfrage senden

Stellen Sie die POST-Anfrage an den Earth Engine-Endpunkt 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))