Zasoby Earth Engine oparte na plikach GeoTIFF w Google Cloud

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

Earth Engine obsługuje zasoby oparte na zoptymalizowanych w chmurze plikach GeoTIFF (COG). Zaletą zasobów opartych na COG jest to, że pola przestrzenne i metadane obrazu są indeksowane w momencie jego tworzenia, co zwiększa wydajność obrazu w kolekcjach. W typowych przypadkach użycia skuteczność komponentów opartych na COG jest porównywalna ze skutecznością przetworzonych komponentów.

Pamiętaj, że jeden komponent może być obsługiwany przez wiele kosztów operacyjnych (na przykład może istnieć jeden koszt operacyjny na pasmo). Korzystanie z wielu płytek COG dla jednego pasma nie jest jednak obsługiwane.

(Earth Engine może też wczytywać obrazy bezpośrednio z pliku COG w Google Cloud Storage; więcej informacji). Jednak obraz wczytany za pomocą funkcji ee.Image.loadGeoTIFF i dodany do zbioru obrazów wymaga odczytu pliku GeoTiff na potrzeby operacji filtrowania zbioru.

Aby utworzyć zasób oparty na kosztach bezpośrednich:

  1. Umieść pliki COG w zasobniku GCS (poniżej znajdziesz listę dozwolonych regionów).
  2. Tworzenie pliku manifestu przesyłania obrazu
  3. Aby wysłać polecenie przesyłania, użyj narzędzia wiersza poleceń earthengine:
earthengine upload external_image --manifest my_manifest.json

Przykładowy plik manifestu obrazu z 1 elementem Tileset

Najprostsza ImageManifest to taka, która zawiera tylko 1 Tileset. Jeśli nie zostaną określone żadne pasma, utworzony 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ż Tileset

Można określić ImageManifest z większą liczbą Tileset, gdzie każdy pasek uzyskanego komponentu jest obsługiwany przez jeden z pasm Tileset za pomocą pól tilesetId i tilesetBandIndex. Jest to przydatne, gdy różne pasma mają różne rozdzielczości lub typy danych. Pasma mogą być wymienione w dowolnej kolejności z dowolnego dostępnego Tileset. W tym przykładzie:

  • Plik „b4b3b2.tif” ma skalę 10 m, a plik „b5b6b7” ma skalę 20 m.
  • Kolejność pasm w wynikowym zasobie jest mieszana z wejściowych COG (np. pasmo wyjściowe 0 pochodzi z Tileset 0, a pasmo wyjściowe 1 – z 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 dotyczące komponentów z podpięciem do ZP

Lokalizacja

Lokalizacja zasobnika Cloud Storage musi być jednym z tych elementów:

  • Stany Zjednoczone – wiele regionów
  • Każdy region podwójny w Stanach Zjednoczonych, który obejmuje US-CENTRAL1
  • Region US-CENTRAL1

Klasa pamięci

Klasa pamięci zasobnika musi być „Standardowa pamięć masowa”.

Uprawnienia do udostępniania

Zarządzanie uprawnieniami do zasobów Earth Engine obsługiwanych przez COG oraz danych źródłowych odbywa się oddzielnie. Gdy udostępniasz zasoby oparte na COG innym osobom do odczytu, właściciel musi zadbać o to, aby dostęp do odczytu był udzielany zarówno do zasobu Earth Engine, jak i do plików COG.

1. Przyznawanie uprawnień do odczytu zasobnika Google Cloud Storage

Aby współpracownicy mogli odczytywać zasoby obsługiwane przez COG, muszą mieć uprawnienia odczytu do plików COG w zasobniku Google Cloud Storage. Bez tych uprawnień Earth Engine nie będzie mógł pobierać danych w imieniu tych użytkowników. Jeśli dane w Google Cloud Storage są niewidoczne dla użytkownika Earth Engine, Earth Engine zwróci błąd w formie „Nie udało się załadować pliku GeoTIFF na poziomiegs://my-bucket/my-object#123456” (gdzie 123456 to generacja obiektu).

Współpracownicy muszą mieć te uprawnienia:

  • storage.buckets.get na koszu (aby pobrać metadane i lokalizację kosza, umożliwiając Earth Engine prawidłowe rozwiązywanie źródła zasobu).
  • storage.objects.get w przypadku puli (aby odczytać rzeczywiste dane zasobu z uwzględnieniem kosztów bezpośrednich).

Te uprawnienia są dostępne w rolach „Odczytujący starsze zasobniki w pamięci masowej” i „Odczytujący starsze obiekty w pamięci masowej”, między innymi.

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:
    • „Storage Legacy Bucket Reader” (przyznawane uprawnienia storage.buckets.get i inne uprawnienia do odczytu na poziomie zasobnika).
    • „Storage Legacy Object Reader” (zapewnia storage.objects.get).
    • (możesz też utworzyć nową rolę niestandardową z tylko uprawnieniami storage.buckets.get i storage.objects.get i przypisać ją).
  5. Zapisz

2. Udostępnianie zasobu Earth Engine do odczytu

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

Generacje

Gdy tworzony jest zasób obsługiwany przez COG, Earth Engine odczytuje metadane plików TIFF określone w pliku manifestu i utworzy wpis w sklepie z zasobami. Każdy identyfikator URI powiązany z tym wpisem może mieć generację. Szczegółowe informacje o generowaniu znajdziesz w dokumentacji dotyczącej wersji obiektów. Jeśli zostanie określona generacja, np. gs://foo/bar#123, Earth Engine przechowuje identyfikator URI dosłownie. Jeśli nie określisz wersji, Earth Engine zapisze ten identyfikator URI z wersją pliku TIFF w momencie wywołania funkcji ImportExternalImage.

Oznacza to, że jeśli dowolny plik TIFF zawierający zasób zewnętrzny w GCS zostanie zaktualizowany (co spowoduje zmianę jego generacji), Earth Engine zwróci błąd „Nie udało się załadować pliku GeoTIFF o identyfikatorze gs://my-bucket/my-object#123456”, ponieważ oczekiwany obiekt już nie istnieje (chyba że zasób umożliwia tworzenie wielu wersji obiektu). Ta zasada ma na celu zapewnienie synchronizacji metadanych zasobu z metadanymi obiektu.

Konfiguracja

Jeśli chodzi o sposób konfigurowania COG, plik TIFF MUSI:

  • Układ kafelkowy, w którym wymiary kafelka są:

    • 256 x 256
    • 512 x 512
    • 1024 x 1024
    • 2048 x 2048

  • uporządkowane tak, aby wszystkie IFD znajdowały się na początku;

Aby uzyskać najlepsze wyniki:

  • Użyj wymiarów płytek 512 x 512 lub większych.
  • Obejmuje 2 omówienia.

W zależności od planowanych zastosowań opcja „INTERLEAVE” może mieć wpływ na wydajność. Zalecamy stosowanie interpolacji BAND we wszystkich przypadkach.

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

Poniższe polecenie gdal_translate przekonwertuje raster na interpolowany między pasmami, skompresowany za pomocą zstd i zoptymalizowany pod kątem chmury plik GeoTIFF, 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

Rozmiar pliku wyjściowego można jeszcze bardziej zmniejszyć, podając przewidywalność (-co PREDICTOR=2 w przypadku typów danych całkowitych i -co PREDICTOR=3 w przypadku typów danych zmiennoprzecinkowych).

Użytkownicy GDAL w wersji co najmniej 3.11 mogą używać sterownika COG do tworzenia plików bez konieczności tworzenia i przechowywania podsumowań.

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 chmurze GeoTiff 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 JavaScriptzie.

Aby utworzyć zasób obsługiwany przez COG za pomocą interfejsu API REST, wyślij POST do punktu końcowego ImportExternalImage Earth Engine. Jak widać poniżej, ta prośba musi być autoryzowana, aby można było utworzyć zasób w Twoim folderze użytkownika.

Rozpoczynanie sesji autoryzowanej

Aby utworzyć zasób Earth Engine w swoim folderze użytkownika, musisz mieć możliwość uwierzytelnienia się jako siebie podczas wysyłania żądania. Aby rozpocząć AuthorizedSession, możesz użyć danych logowania z aplikacji uwierzytelniającej Earth Engine. Następnie możesz używać interfejsu AuthorizedSession do wysyłania żądań 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 to instancja ImageManifest. Tutaj określana jest ścieżka do pliku COG oraz inne przydatne właściwości.

Więcej informacji o konfigurowaniu ImageManifest znajdziesz w tym przewodniku. Można zdefiniować co najmniej 1 Tileset, z których każdy obsługuje co najmniej 1 pasmo. W przypadku ImportExternalImage obsługiwany jest co najwyżej 1 element ImageSource na Tileset.

Szczegółowe informacje o eksportowaniu kosztów operacyjnych znajdziesz w tym dokumencie.

Wysyłanie żądania

Wyślij żądanie POST do punktu końcowego projects.images.importExternal w Earth Engine.

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