Cloud-optimierte GeoTIFF-Assets (COG) registrieren

Earth Engine unterstützt Assets, die auf Cloud-optimierten GeoTIFFs (COGs) basieren und 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 leistungsstark wenn es in Sammlungen verwendet wird. Die Leistung ist mit der von standardmäßig aufgenommenen Assets vergleichbar (siehe die Übersicht zu Cloud-optimierten GeoTIFFs (COGs)).

Voraussetzungen und Cloud Storage-Einrichtung

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

1. Bucket-Standort (zwingende Voraussetzung)

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

  • Die Multi-Region us
  • Jede US-Dual-Region , 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 Registrierungs- und Leseanfragen ab.

2. Speicherklasse und Abrechnung

  • Wir empfehlen die Verwendung der Speicherklasse Standard. Für den Standard Storage gelten keine Regeln zur Mindestspeicherdauer. So werden keine Gebühren für die vorzeitige Löschung berechnet, wenn Sie temporäre Dateien aktualisieren oder ersetzen.
  • Bei Earth Engine-Berechnungsschleifen fallen keine Aufschläge für den Datenabruf aus Cloud Storage an. Wenn Sie jedoch mit externen Tools (z. B. Desktop-GIS-Software) auf Speicherklassen zugreifen, die nicht dem Standard Storage entsprechen, fallen hohe Abrufgebühren an.
  • Die Abrechnung muss für Ihr Google Cloud-Projekt aktiviert sein, damit Sie GCS verwenden können. Weitere Informationen finden Sie in der Kurzanleitung zu Google Cloud Storage.

Schritt 1: COGs vorbereiten

Ihre TIFF-Dateien müssen für die Cloud optimiert sein. Das TIFF muss folgende Anforderungen erfüllen:

  • Gekachelt mit Kachelgrößen von 256 × 256, 512 × 512, 1.024 × 1.024 oder 2.048 × 2.048. Für eine optimale Leistung empfehlen wir 512 × 512 oder höher.
  • So angeordnet, dass sich alle Image File Directories (IFDs) am Anfang befinden.
  • Übersichten mit Zweierpotenzen enthalten.
  • BAND -Interleave verwenden.

Sie können Ihre Bilder mit GDAL konvertieren.

GDAL COG-Treiber verwenden (GDAL >= 3.1 empfohlen):

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Standard-GTiff-Treiber verwenden:

Generieren Sie zuerst interne Übersichten mit Zweierpotenzen (mit gdal raster overview add oder gdaladdo) und kopieren Sie dann das Bild und die Übersichten in ein gekacheltes COG-Layout:

gdaladdo -r nearest in.tif 2 4 8 16 32  # or -r cubic for continuous/float data

gdal_translate in.tif out.tif \
  -co BIGTIFF=YES \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=16 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Schritt 2: Manifest erstellen

Unabhängig davon, ob Sie ein COG mit der Earth Engine-Python-Clientbibliothek, dem Befehlszeilentool earthengine oder der Earth Engine REST API registrieren, müssen Sie ein Manifest für den Bild-Upload definieren, in dem das Ziel-Asset, die Google Cloud Storage-URIs und optionale Band-Metadaten angegeben sind.

Beispiel: Ein einzelnes COG für alle Bänder Wenn Ihr COG alle Bänder enthält (z.B. RGB), ist im Manifest nur ein 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 (eines pro Band) Wenn Sie separate Dateien für verschiedene Bänder haben (z.B. Rot, Grün, 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 }
  ]
}

Schritt 3: Registrierungsanfrage senden

Sie können Ihr Manifest mit der Earth Engine-Python-Clientbibliothek, dem Befehlszeilentool earthengine 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-Skript 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. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
print(f"Asset registered: {result['name']}")

Befehlszeilentool

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

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Submit the external image upload task
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

REST API (Python)

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

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 mit der Registrierungsanfrage ein einfacher Metadatenindexierungsvorgang gestartet. Da bei der COG-Registrierung keine Pixeldaten kopiert werden, ist dieser Vorgang in der Regel in wenigen Sekunden abgeschlossen.

Manifesteinschränkungen für COG-Assets

Beachten Sie beim Erstellen eines Manifests für COG-basierte Assets die folgenden strengen Einschränkungen (die sich von Standardmanifesten für die Aufnahme unterscheiden):

  • Ein einzelner Bucket:Alle URIs im Manifest müssen sich im selben GCS-Bucket befinden.
  • Ein URI pro Quelle:Jede ImageSource muss genau einen URI enthalten. Sie können nicht mehrere Dateien zu einer einzelnen Tileset-Quelle zusammenfügen. Wenn Sie mehrere COG-Szenen zusammenfügen möchten, registrieren Sie jedes COG als Asset und kombinieren Sie sie mit .mosaic() zu einer ee.ImageCollection.
  • Keine mask_bands: `mask_bands`mask_bands auf oberster Ebene wird nicht unterstützt. Verwenden Sie missingData im Manifest oder sorgen Sie dafür, dass Ihr TIFF einen internen Wert für „Keine Daten“ hat.
  • Kein data_type im Tileset: Geben Sie data_type nicht im Abschnitt tilesets an. Er wird automatisch erkannt.
  • Keine dimensions in der Quelle: Geben Sie dimensions nicht in der ImageSource an.
  • Kein subdataset_prefix / subdataset_suffix.
  • Kein min_tile_area_ratio oder skip_metadata_read.

Schritt 4: Berechtigungen konfigurieren (wichtig für die Freigabe)

Im Gegensatz zu Standard-Earth Engine-Assets bleiben die Pixeldaten eines COG in GCS. Wenn Sie ein COG-basiertes Asset für andere freigeben, müssen Sie ihnen Lesezugriff auf das Earth Engine-Asset und die GCS-Dateien gewähren.

1. Berechtigungen für GCS-Bucket gewähren

Mitarbeiter benötigen Berechtigungen, um die Dateien aus GCS zu lesen.

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 Standardrollen für Cloud Storage gewähren:

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

Konfigurationsschritte 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 Mitarbeiter hinzu (oder eine Google-Gruppe oder allUsers für öffentlichen Zugriff).
  6. Weisen Sie die Rollen Storage-Bucket-Betrachter und Storage-Objekt-Betrachter zu.
  7. Klicken Sie auf Speichern.

2. Earth Engine-Asset freigeben

Geben Sie das Asset selbst mit dem Earth Engine Asset Manager oder der CLI frei. Weitere Informationen finden Sie in der Anleitung zur Asset-Verwaltung für Details.

Objektgenerationen verwalten

Wenn Sie ein COG registrieren, speichert Earth Engine die spezifische Generation (Version) des GCS-Objekts. Wenn Sie die Datei in GCS aktualisieren, ändert sich ihre Generation.

  • Standardmäßig kann Earth Engine das Asset nicht laden und gibt einen Fehler zurück: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
  • So wird verhindert, dass Metadaten (z. B. Projektion oder Footprint) mit den zugrunde liegenden Pixeln nicht mehr synchron sind.

  • Best Practice:Wenn Sie die zugrunde liegenden Bilddaten aktualisieren müssen, registrieren Sie sie als neues Asset oder führen Sie den Upload-Befehl mit dem Flag --force noch einmal aus, anstatt Dateien direkt zu überschreiben:

    earthengine --project your-project-id upload external_image --force --manifest manifest.json

Registrierte Assets verwenden

Nach der Registrierung wird auf ein COG-basiertes Asset in Earth Engine-Skripten genauso zugegriffen wie auf jedes andere standardmäßig aufgenommene Bild-Asset:

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