Zasoby Earth Engine oparte na plikach GeoTIFF w Google Cloud

Logo Colab Uruchom w Google Colab Logo GitHuba Wyświetl źródło w GitHubie

Earth Engine obsługuje zasoby oparte na plikach GeoTIFF zoptymalizowanych pod kątem chmury (COG). Zaletą zasobów opartych na COG jest to, że pola przestrzenne i metadane obrazu są indeksowane podczas tworzenia zasobu, co zwiększa wydajność obrazu w kolekcjach. W typowych przypadkach użycia wydajność zasobów opartych na COG jest porównywalna z wydajnością zasobów pozyskanych.

Pamiętaj, że 1 zasób może być oparty na wielu plikach COG (np. może być 1 plik COG na pasmo). Nie jest jednak obsługiwane używanie wielu kafelków COG w przypadku 1 pasma.

(Earth Engine może też bezpośrednio wczytywać obrazy z plików COG w Cloud Storage (więcej informacji). Obraz wczytany za pomocą ee.Image.loadGeoTIFF i dodany do kolekcji obrazów będzie jednak wymagał odczytu pliku GeoTIFF w przypadku operacji filtrowania w kolekcji).

Aby utworzyć zasób oparty na COG:

  1. Umieść pliki COG w zasobniku GCS (dozwolone regiony znajdziesz w sekcji Lokalizacja).
  2. Napisz manifest przesyłania obrazu.
  3. Użyj narzędzia wiersza poleceń earthengine, aby wysłać polecenie przesyłania:
earthengine upload external_image --manifest my_manifest.json

Przykładowy manifest obrazu z 1 elementem Tileset

Najprostszy ImageManifest to taki, który zawiera tylko 1 element Tileset. Jeśli nie określono żadnych pasm, wynikowy zasób będzie zawierać wszystkie pasma pliku GeoTIFF z nazwami pasm zakodowanymi w pliku GeoTIFF (w tym przypadku „vis-red”, „vis-green” i „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)

Więcej niż 1 element Tileset

Możesz określić ImageManifest z więcej niż 1 elementem Tileset, gdzie każde pasmo wynikowego zasobu jest oparte na jednym z pasm elementu Tileset za pomocą pól tilesetId i tilesetBandIndex. Jest to przydatne, gdy różne pasma mają różne rozdzielczości lub typy danych. Pasma można wyświetlać w dowolnej kolejności z dowolnego dostępnego elementu Tileset. W tym przykładzie:

  • „b4b3b2.tif” ma skalę 10 m, a „b5b6b7” – 20 m.
  • Kolejność pasm wynikowego zasobu jest mieszana z wejściowych plików COG (np. pasmo wyjściowe 0 pochodzi z elementu Tileset 0, a pasmo wyjściowe 1 – z elementu 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)

Szczegóły zasobów opartych na COG

Lokalizacja

Lokalizacja zasobnika Cloud Storage musi być jedną z tych opcji:

  • obszar obejmujący wiele regionów w Stanach Zjednoczonych,
  • dowolny region podwójny w Stanach Zjednoczonych, który obejmuje region US-CENTRAL1,
  • region US-CENTRAL1.

Klasa pamięci masowej

Klasa pamięci masowej zasobnika musi być "Standard storage".

Uprawnienia do udostępniania

Listy ACL zasobów Earth Engine opartych na COG i danych źródłowych są zarządzane oddzielnie. Gdy udostępniasz zasoby oparte na COG współpracownikom do odczytu, właściciel musi się upewnić, że dostęp do odczytu jest przyznany zarówno w przypadku zasobu Earth Engine, jak i źródłowych plików COG.

1. Przyznaj uprawnienia do odczytu zasobnika Cloud Storage

Aby współpracownicy mogli odczytywać zasoby oparte na COG, muszą najpierw mieć dostęp do odczytu źródłowych plików COG w zasobniku Cloud Storage. Bez tych uprawnień Earth Engine nie będzie mógł pobrać dla nich danych. Jeśli dane w Cloud Storage nie są widoczne dla użytkownika Earth Engine, Earth Engine zwróci błąd w postaci „Failed to load the GeoTIFF at gs://my-bucket/my-object#123456” (gdzie 123456 to generacja obiektu).

Współpracownicy muszą mieć te uprawnienia:

  • storage.buckets.get w zasobniku (aby pobrać metadane i lokalizację zasobnika, co umożliwi Earth Engine prawidłowe rozwiązanie źródła zasobu).
  • storage.objects.get w zasobniku (aby odczytać rzeczywiste dane zasobu opartego na COG).

Te uprawnienia są dostępne m.in. w rolach „Odczytujący starsze zasobniki w pamięci masowej” i „Odczytujący starsze wersje obiektów w usłudze Storage”.

Aby przypisać te role współpracownikom:

  1. Otwórz stronę uprawnień zasobnika: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. Kliknij „PRZYZNAJ DOSTĘP”.
  3. Dodaj wszystkie podmioty zabezpieczeń (np. użytkowników, grupy, konta usługi), którym należy przyznać dostęp do odczytu.
  4. Przypisz te role:
    • „Odczytujący starsze zasobniki w pamięci masowej” (zapewnia storage.buckets.get i inne uprawnienia do odczytu na poziomie zasobnika).
    • „Odczytujący starsze wersje obiektów w usłudze Storage” (zapewnia storage.objects.get).
    • (Możesz też utworzyć nową rolę niestandardową z uprawnieniami storage.buckets.get i storage.objects.get i przypisać ją).
  5. Zapisz

2. Udostępnij zasób Earth Engine do odczytu

Po upewnieniu się, że współpracownicy mają niezbędne uprawnienia do źródłowego zasobnika i obiektów GCS, musisz też udostępnić sam zasób Earth Engine. Więcej informacji o ustawianiu uprawnień do zasobów Earth Engine znajdziesz w przewodniku po zarządzaniu zasobami Earth Engine.

Generacje

Gdy tworzony jest zasób oparty na COG, Earth Engine odczytuje metadane plików TIFF określonych w manifeście i tworzy wpis w magazynie zasobów. Każdy identyfikator URI powiązany z tym wpisem może mieć generację. Szczegółowe informacje o generacjach znajdziesz w dokumentacji dotyczącej obsługi wersji obiektów. Jeśli określono generację, np. gs://foo/bar#123, Earth Engine zapisze ten identyfikator URI dosłownie. Jeśli generacja nie jest określona, Earth Engine zapisze ten identyfikator URI z generacją pliku TIFF w momencie wywołania ImportExternalImage.

Oznacza to, że jeśli jakikolwiek plik TIFF składający się na zasób zewnętrzny w GCS zostanie zaktualizowany (a tym samym zmieni się jego generacja), Earth Engine zwróci błąd „Failed to load the GeoTIFF at gs://my-bucket/my-object#123456”, ponieważ oczekiwany obiekt już nie istnieje (chyba że w zasobniku włączono obsługę wielu wersji obiektów). Ta zasada ma na celu synchronizowanie metadanych zasobu z metadanymi obiektu.

Konfiguracja

Jeśli chodzi o konfigurację pliku COG, plik TIFF MUSI być:

  • podzielony na kafelki o wymiarach:

    • 256 × 256,
    • 512 × 512,
    • 1024 × 1024,
    • 2048 × 2048;

  • ułożony tak, aby wszystkie IFD znajdowały się na początku.

Aby uzyskać najlepszą wydajność:

  • używaj kafelków o wymiarach co najmniej 512 × 512 pikseli;
  • uwzględnij podglądy w potędze 2.

W zależności od zamierzonych przypadków użycia opcja tworzenia „INTERLEAVE” może wpływać na wydajność. We wszystkich okolicznościach zalecamy używanie przeplotu pasm.

Więcej informacji o zoptymalizowanej konfiguracji znajdziesz na tej stronie.

To polecenie gdal_translate przekonwertuje raster na plik GeoTIFF zoptymalizowany pod kątem chmury, skompresowany za pomocą zstd i z przeplotem pasm, który będzie dobrze działać w 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

Możesz dodatkowo zmniejszyć rozmiar pliku wyjściowego, określając a predyktor (-co PREDICTOR=2 w przypadku typów danych całkowitych i -co PREDICTOR=3 w przypadku typów danych zmiennoprzecinkowych).

W przypadku użytkowników korzystających z GDAL w wersji >= 3.11 sterownik COG może tworzyć pliki bez konieczności tworzenia i zachowywania podglądów.

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 \

Tworzenie zasobów opartych na plikach GeoTIFF w chmurze za pomocą interfejsu API REST

Uwaga: interfejs API REST zawiera nowe i zaawansowane funkcje, które mogą nie być odpowiednie dla wszystkich użytkowników. Jeśli dopiero zaczynasz korzystać z Earth Engine, zalecamy zapoznanie się z przewodnikiem po JavaScript.

Aby utworzyć zasób oparty na COG za pomocą interfejsu API REST, wyślij żądanie POST do punktu końcowego ImportExternalImage Earth Engine. Jak pokazano poniżej, to żądanie musi być autoryzowane, aby utworzyć zasób w folderze użytkownika.

Rozpoczęcie autoryzowanej sesji

Aby utworzyć zasób Earth Engine w folderze użytkownika, musisz się uwierzytelnić podczas wysyłania żądania. Aby rozpocząć AuthorizedSession, możesz użyć danych logowania z narzędzia do uwierzytelniania Earth Engine. Następnie możesz użyć AuthorizedSession, aby wysyłać żądania do 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)
)

Treść żądania

Treść żądania jest instancją an ImageManifest. W tym miejscu określa się ścieżkę do pliku COG oraz inne przydatne właściwości.

Szczegółowe informacje o konfigurowaniu ImageManifest znajdziesz w tym przewodniku. Możesz zdefiniować co najmniej 1 element Tileset, z których każdy będzie obsługiwać co najmniej 1 pasmo. W przypadku ImportExternalImage na każdy element Tileset obsługiwane jest co najwyżej 1 źródło obrazu ImageSource.

Szczegółowe informacje o eksportowaniu plików COG znajdziesz w tym dokumencie.

Wysyłanie żądania

Wyślij żądanie POST do punktu końcowego Earth Engine 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))