Cloud Optimized GeoTIFF-Assets (COG) registrieren

Earth Engine unterstützt Assets, die auf Cloud Optimized GeoTIFFs (COGs) basieren, die in Google Cloud Storage (GCS) gespeichert sind.

Wenn Sie ein COG-basiertes Asset registrieren, indexiert Earth Engine die räumlichen und Metadatenfelder des Bildes zum Zeitpunkt der Erstellung. Dadurch ist das Bild bei der Verwendung in Sammlungen leistungsstark und die Leistung ist mit der von standardmäßig aufgenommenen Assets vergleichbar (siehe Übersicht über Cloud Optimized GeoTIFF (COG)).

In diesem Leitfaden wird beschrieben, wie Sie Ihre Dateien vorbereiten, das Manifest schreiben, die Registrierungsanfrage senden, Berechtigungen konfigurieren und registrierte Assets aktualisieren oder löschen.

Hinweis

Bevor Sie ein COG registrieren, müssen Sie Ihre Cloud Storage-Ressourcen korrekt einrichten.

Bucket-Standort

Damit Earth Engine auf Ihren Cloud Storage-Bucket zugreifen kann, muss sich der Bucket in einer der folgenden Rechenzentrumsregionen oder multiregionalen Standorte befinden:

  • Die Multiregion us
  • Beliebige Dual-Region in den USA, die us-central1 enthält
  • Die Region us-central1

Wenn sich Ihr Bucket in einem anderen regionalen Rechenzentrum befindet (z. B. us-east4 oder europe-west1), lehnt Earth Engine die Registrierung und Leseanfragen ab. Unterstützte Cloud Storage-Bucket-Standorte

Speicherklasse und Abrechnung

  • Wir empfehlen die Verwendung der Speicherklasse Standard. Für Standard Storage gelten keine Regeln für die Mindestspeicherdauer. Dadurch werden Abrechnungsstrafen für vorzeitiges Löschen vermieden, wenn Sie temporäre Dateien aktualisieren oder ersetzen.
  • Für Earth Engine-Berechnungsschleifen fallen keine Aufschläge für den Datenabruf aus Cloud Storage an. Der Zugriff auf nicht standardmäßige Speicherebenen über externe Tools (z. B. Desktop-GIS-Software) ist jedoch mit hohen Abrufgebühren verbunden.
  • Damit Sie Cloud Storage verwenden können, muss die Abrechnung für Ihr Google Cloud-Projekt aktiviert sein. Informationen zu den ersten Schritten finden Sie in der Cloud Storage-Kurzanleitung.

COGs vorbereiten

Earth Engine liest COGs direkt aus Cloud Storage und ruft nur den Header und die Kacheln ab, die für eine Berechnung erforderlich sind. Daher ist das Dateilayout wichtig. Die TIFF-Datei muss:

  • Gekachelt, mit quadratischen Kachelabmessungen von 16 × 16 bis 2048 × 2048, die Zweierpotenzen sind. Für eine optimale Leistung empfehlen wir 512 × 512.
  • So angeordnet, dass sich alle Image File Directories (IFDs) am Anfang befinden.
  • Fügen Sie gegebenenfalls Übersichten mit Zweierpotenzen hinzu. Übersichten sind nicht erforderlich, werden aber für Bilder empfohlen, die größer als eine einzelne Kachel sind.
  • Verwenden Sie die Interleave-Option BAND oder PIXEL (Informationen zu den Vor- und Nachteilen finden Sie unter Einzelband- und Multiband-Dateien).

Verwenden Sie zum Konvertieren eines Bildes den GDAL-Treiber COG, der das erforderliche Layout (Kacheln, Übersichten und Header-Platzierung) in einem Schritt erstellt. Fügen Sie OVERVIEW_RESAMPLING=NEAREST für kategoriale Daten hinzu. Der Standardwert ist CUBIC. Empfehlungen zu Komprimierung, Übersicht und Layout finden Sie unter Best Practices für die Vorbereitung externer COGs.

GDAL 3.11+ CLI

gdal raster convert in.tif out.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co OVERVIEWS=IGNORE_EXISTING \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

Klassische Befehlszeile

Lassen Sie INTERLEAVE=BAND bei GDAL-Versionen vor 3.11 weg.

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

Manifest erstellen

Unabhängig davon, ob Sie ein COG mit der Earth Engine Python-Clientbibliothek, dem earthengine-Befehlszeilentool oder der Earth Engine REST API registrieren, müssen Sie ein Manifest für den Bildupload definieren, in dem das Asset-Ziel, die Cloud Storage-URIs und optionale Bandmetadaten angegeben sind. In der API und im Befehlszeilentool werden COG-gestützte Assets als externe Bilder (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal) bezeichnet.

Beispiel: Einzelnes COG, das alle Bänder unterstützt Wenn Ihr COG alle Bänder enthält (z. B. RGB), ist im Manifest nur ein einzelnes Tileset erforderlich:

{
  "name": "projects/my-project/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

Beispiel: Mehrere COGs (eine pro Band) Wenn Sie separate Dateien für verschiedene Bänder haben (z. B. Rot, Grün und Blau in separaten Dateien):

{
  "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 }
  ]
}

Manifesteinschränkungen

Für Manifeste für COG-gestützte Assets gelten Einschränkungen, die für Standard-Aufnahmemanifeste nicht gelten:

  • Einzelner Bucket: Alle URIs im Manifest müssen sich im selben Cloud Storage-Bucket befinden.
  • Ein URI pro Quelle: Jedes ImageSource-Element darf genau einen URI enthalten. Es ist nicht möglich, mehrere Dateien zu einer einzigen Tileset-Quelle zusammenzufügen. Wenn Sie mehrere COG-Szenen zu einem Mosaik zusammenfügen möchten, registrieren Sie jedes COG als Asset und kombinieren Sie sie mit .mosaic() zu einem ee.ImageCollection.
  • Kein mask_bands: Das übergeordnete Feld mask_bands wird nicht unterstützt. Verwenden Sie missingData im Manifest oder achten Sie darauf, dass Ihr TIFF einen internen nodata-Wert hat.
  • Keine data_type im Tileset: Geben Sie im Abschnitt tilesets keine data_type an. Sie werden automatisch erkannt.
  • Kein dimensions in der Quelle: Geben Sie dimensions nicht im ImageSource an.
  • Nein, subdataset_prefix / subdataset_suffix.
  • Kein min_tile_area_ratio oder skip_metadata_read.

Registrierungsanfrage senden

Sie können Ihr Manifest mit der Earth Engine Python-Clientbibliothek, dem earthengine-Befehlszeilentool oder der Earth Engine REST API an Earth Engine senden. Wählen Sie die Methode aus, die am besten zu Ihrem Workflow passt.

Python-Clientbibliothek

Verwenden Sie in einem Python-Script oder Jupyter-Notebook die Earth Engine-Python-Clientbibliothek (ee.data), nachdem Sie Ihr Projekt initialisiert haben:

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. Register the asset
result = ee.data.startExternalImageIngestion(manifest)
print(f"Asset registered: {result['name']}")

Befehlszeilentool

Speichern Sie Ihr Manifest in Ihrem Terminal in einer Datei mit dem Namen manifest.json und führen Sie den Uploadbefehl earthengine aus:

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Register the asset
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

REST API

Für automatisierte Workflows ohne die Clientbibliothek senden Sie eine autorisierte POST-Anfrage direkt an den Earth Engine REST API-Endpunkt projects.image.importExternal (hier mit Python demonstriert):

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

Nach dem Senden wird durch die Registrierungsanfrage ein einfacher Metadatenindexierungsvorgang gestartet. Da bei der COG-Registrierung keine Pixeldaten kopiert werden, ist dieser Vorgang in der Regel innerhalb von Sekunden abgeschlossen.

Berechtigungen konfigurieren

Im Gegensatz zu Standard-Earth Engine-Assets verbleiben die Pixeldaten eines COG in Cloud Storage. Wenn Sie ein COG-basiertes Asset mit anderen teilen, müssen Sie ihnen Lesezugriff sowohl auf das Earth Engine-Asset als auch auf die Cloud Storage-Dateien gewähren.

Cloud Storage-Bucket-Berechtigungen gewähren

Mitbearbeiter benötigen Berechtigungen zum Lesen der Dateien aus Cloud Storage.

Erforderliche Berechtigungen:

  • storage.buckets.get (zum Abrufen von Bucket-Metadaten und -Standort)
  • storage.objects.get (zum Lesen der Pixeldaten)

Sie können diese Berechtigungen mit den folgenden Cloud Storage-Standardrollen gewähren:

  • Storage Bucket Viewer (bietet storage.buckets.get zum Lesen von Bucket-Metadaten und -Standort)
  • Storage-Objekt-Betrachter (bietet storage.objects.get zum Lesen von Pixeldaten)

Schritte zur Konfiguration in der Google Cloud Console:

  1. Rufen Sie den Cloud Storage-Browser auf.
  2. Klicken Sie auf den Namen Ihres Buckets.
  3. Wählen Sie den Tab Berechtigungen aus.
  4. Klicken Sie auf ZUGRIFF GEWÄHREN.
  5. Fügen Sie die E‑Mail-Adressen Ihrer Mitbearbeiter (oder einer Google-Gruppe oder allUsers für den öffentlichen Zugriff) hinzu.
  6. Weisen Sie die Rollen Storage Bucket Viewer und Storage Object Viewer zu.
  7. Klicken Sie auf Speichern.

Earth Engine-Asset freigeben

Geben Sie das Asset selbst über den Earth Engine Asset Manager oder die Befehlszeile frei. Weitere Informationen finden Sie im Leitfaden zur Asset-Verwaltung.

COG-gestützte Assets aktualisieren, ersetzen und löschen

Ein COG-basiertes Asset ist ein Verweis auf eine bestimmte Version einer Datei in Cloud Storage sowie Metadaten (Footprint, Projektion, Bänder und Übersichtslayout), die Earth Engine bei der Registrierung indexiert hat. Earth Engine pinnt die Dateiversion an, damit diese Metadaten nicht von den Pixeln abweichen. Das ist der Unterschied zwischen dem Aktualisieren von COG-gestützten Assets und dem Aktualisieren von Standard-Assets.

Objektgenerierungen

Wenn Sie ein COG registrieren, zeichnet Earth Engine die Generierung des Cloud Storage-Objekts (seine Versionsnummer) zusammen mit dem URI auf. Sie können die angepinnte Generierung in den Metadaten des Assets sehen. Sie wird als #<generation>-Suffix im URI angezeigt:

Python

asset = ee.data.getAsset('projects/your-project-id/assets/my_cog_asset')
print(asset['tilesets'][0]['sources'][0]['uris'])
# ['gs://google-sample-bucket/my_optimized_image.tif#1750427474244728']

Sie können auch selbst eine bestimmte Version festlegen, indem Sie das Suffix #<generation> in den Manifest-URI einfügen, wenn Sie das Asset registrieren (oder neu registrieren). Ohne diese Angabe liest die Earth Engine das aktuelle Objekt und pinnt die gefundene Generierung an. Das explizite Anpinnen ist nützlich, um ein Rollback auf eine frühere Version durchzuführen, die in einem Bucket mit Objektversionsverwaltung beibehalten wurde.

Wenn Sie die Datei in Cloud Storage überschreiben, erhält sie eine neue Generierung. Wenn Sie sie löschen, ist die angepinnte Generierung nicht mehr vorhanden. In beiden Fällen schlägt das Lesen der Pixel des Assets fehl, es sei denn, die Objektversionierung für den Bucket behält die alte Generation bei. In diesem Fall liest Earth Engine weiterhin die alten Pixel. Metadatenvorgänge, die den indexierten Eintrag verwenden (z. B. ee.data.getAsset(), bandNames() und Sammlungsfilterung), funktionieren weiterhin.

Asset nach dem Ändern der Datei aktualisieren

Wenn Sie ein vorhandenes Asset auf eine neue Version der Datei verweisen möchten, registrieren Sie es noch einmal mit demselben Asset-Namen und aktivieren Sie das Überschreiben. Earth Engine liest den GeoTIFF-Header noch einmal, indexiert die Metadaten neu und pinnt die neue Generation in einem einzigen synchronen Aufruf. Die vorhandenen Berechtigungen des Assets bleiben erhalten, aber die Attribute, der Zeitraum und die Bandnamen stammen aus dem neuen Manifest. Nehmen Sie daher alles auf, was Sie zuvor mit ee.data.updateAsset() festgelegt haben.

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Befehlszeile: earthengine upload external_image --force --manifest manifest.json
  • REST API: Fügen Sie "overwrite": true als Feld auf oberster Ebene neben "imageManifest" in den projects.image.importExternal-Anfragetext ein.

Sie müssen das Asset nicht zuerst löschen. Das wäre sogar kontraproduktiv: Ein eigenständiges Asset verliert seine Berechtigungen und ein Bild in einer Sammlung verschwindet kurzzeitig aus der Sammlung. Beachten Sie, dass mit ee.data.updateAsset() (projects.assets.patch) nur Properties, Zeitraum und Bandnamen geändert werden können. Es kann nicht geändert werden, auf welche Datei ein Asset verweist.

Unabhängige Lebenszyklen

Earth Engine-Assets und Cloud Storage-Objekte werden separat verwaltet:

  • Wenn Sie das Earth Engine-Asset (earthengine rm oder ee.data.deleteAsset()) löschen, wird nur der Asset-Eintrag entfernt. Ihre Dateien in Cloud Storage bleiben unverändert.
  • Durch das Löschen der Datei in Cloud Storage wird das Asset nicht entfernt. Es wird weiterhin in Listen und in der Sammlung angezeigt (siehe Objektgenerationen).

Mit großen Sammlungen arbeiten

In der Earth Engine API gibt es kein Batch- oder rekursives Löschen: Jedes Asset muss einzeln gelöscht werden und eine Sammlung muss leer sein, bevor sie gelöscht werden kann. earthengine rm -r übernimmt das für Sie, löscht die Bilder jedoch einzeln. Das Entfernen einer Sammlung mit Zehntausenden von Bildern kann daher Stunden dauern.

  • Wenn Sie die Bilder einer Sammlung ersetzen möchten, überschreiben Sie sie, anstatt sie zu löschen. Registrieren Sie jedes Image noch einmal mit dem Namen und aktivieren Sie die Option zum Überschreiben (siehe oben). Dafür ist nur eine Anfrage pro Bild statt zwei erforderlich, die Sammlung bleibt durchgehend gefüllt und die Sammlung selbst, in der die Berechtigungen gespeichert sind, muss nicht gelöscht und neu erstellt werden. Löschen Sie nur die Images, die nicht im neuen Set enthalten sind.

  • Wenn Sie viele Assets löschen möchten, parallelisieren Sie den Vorgang über ein Script. Listen Sie die Assets mit ee.data.listAssets() auf (mit der Ansicht BASIC, die nur Namen und Typen anstelle der vollständigen Metadaten für jedes Image zurückgibt) und löschen Sie sie aus einem kleinen Threadpool. Asset-Anfragen unterliegen projektweiten Ratenbegrenzungen. Halten Sie die Nebenläufigkeit daher moderat (etwa 10 Worker) und lassen Sie die integrierten Wiederholungsversuche der Clientbibliothek alle 429 Too Many Requests-Antworten verarbeiten:

    Python

    import concurrent.futures
import ee

ee.Initialize(project='your-project-id')
collection = 'projects/your-project-id/assets/my_collection'

listing = ee.data.listAssets({'parent': collection, 'view': 'BASIC'})
asset_ids = [a['name'] for a in listing['assets']]

def delete(asset_id):
  try:
    ee.data.deleteAsset(asset_id)
  except ee.EEException as e:
    return f'{asset_id}: {e}'

with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
  failures = [f for f in executor.map(delete, asset_ids) if f]

if failures:
  print('\n'.join(failures))
else:
  ee.data.deleteAsset(collection)

    Die Sammlung wird nur gelöscht, wenn alle Bilder gelöscht wurden. Bei einem teilweisen Fehler bleibt sie für eine erneute Ausführung erhalten.

    Das gleiche Muster gilt für die Registrierung mehrerer Images: Ersetzen Sie ee.data.deleteAsset(asset_id) im Hilfsprogramm durch ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) und ordnen Sie es Ihrer Liste von Manifesten zu. Wenn Sie allow_overwrite=True auch beim ersten Durchlauf übergeben, kann der Batch nach einem Teilausfall sicher noch einmal ausgeführt werden, da alle bereits erstellten Assets ersetzt werden, anstatt einen Fehler zu verursachen.

Registrierte Assets verwenden

Nach der Registrierung wird auf ein COG-basiertes Asset in Earth Engine-Skripts wie auf jedes standardmäßige aufgenommene Bild-Asset zugegriffen:

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

Antworten auf häufig gestellte Fragen zu Berechtigungen, zum Aktualisieren von Dateien und zum Verwalten großer Sammlungen finden Sie im COG-Abschnitt der FAQs.