Rejestrowanie zasobów GeoTIFF zoptymalizowanych pod kątem chmury (COG)

Earth Engine obsługuje zasoby oparte na plikach Cloud Optimized GeoTIFF (COG) przechowywanych w Google Cloud Storage (GCS).

Gdy zarejestrujesz zasób oparty na pliku COG, Earth Engine zaindeksuje pola przestrzenne i metadane obrazu podczas tworzenia. Dzięki temu obraz jest wydajny gdy jest używany w kolekcjach, a jego wydajność jest porównywalna ze standardowymi zasobami (więcej informacji znajdziesz w artykule Cloud optimized GeoTIFF (COG)).

Wymagania wstępne i konfiguracja Cloud Storage

Zanim zarejestrujesz plik COG, musisz prawidłowo skonfigurować zasoby Google Cloud Storage.

1. Lokalizacja zasobnika (wymaganie bezwzględne)

Aby Earth Engine mógł uzyskać dostęp do zasobnika Cloud Storage, musi on znajdować się w jednym z tych regionów centrum danych lub regionów w wielu regionach:

• us w wielu regionach
• Dowolny region w dwóch regionach w USA , który obejmuje region us-central1
• Region us-central1

Jeśli zasobnik znajduje się w innym regionalnym centrum danych (np. us-east4 lub europe-west1), Earth Engine odrzuci rejestrację i żądania odczytu.

2. Klasa pamięci masowej i płatności

• Zalecamy używanie klasy pamięci masowej Standard. W przypadku pamięci masowej Standard nie obowiązują minimalne reguły dotyczące czasu przechowywania, co zapobiega naliczaniu opłat za wcześniejsze usunięcie, jeśli zaktualizujesz lub zastąpisz pliki tymczasowe.
• Pętle obliczeniowe Earth Engine nie powodują naliczania dodatkowych opłat za pobieranie danych z Cloud Storage, ale dostęp do warstw pamięci masowej innych niż Standard z narzędzi zewnętrznych (np. oprogramowania GIS na komputer) wiąże się z wysokimi opłatami za pobieranie.
• Aby korzystać z GCS, musisz mieć włączone płatności w projekcie Google Cloud. Aby rozpocząć, przeczytaj Krótkie wprowadzenie do Google Cloud Storage.

Krok 1. Przygotuj pliki COG

Pliki TIFF muszą być zoptymalizowane pod kątem chmury. Plik TIFF musi być:

• Podzielony na kafelki o wymiarach: 256 x 256, 512 x 512, 1024 x 1024 lub 2048 x 2048. Aby uzyskać najlepszą wydajność, zalecamy używanie kafelków o wymiarach 512 x 512 lub większych.
• Uporządkowany tak, aby wszystkie katalogi plików obrazów (IFD) znajdowały się na początku.
• Zawierał podglądy w potęgach liczby 2.
• Używał przeplotu BAND.

Do konwertowania obrazów możesz używać GDAL.

Używanie sterownika GDAL COG (zalecana wersja GDAL >= 3.1):

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

Używanie standardowego sterownika GTiff:

Najpierw wygeneruj wewnętrzne podglądy w potęgach liczby 2 (za pomocą gdal raster overview add lub gdaladdo), a następnie skopiuj obraz i podglądy do układu COG z kafelkami:

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

Krok 2. Utwórz plik manifestu

Niezależnie od tego, czy rejestrujesz plik COG za pomocą biblioteki klienta Earth Engine Python, narzędzia wiersza poleceń earthengine czy interfejsu Earth Engine REST API, musisz zdefiniować plik manifestu przesyłania obrazu, w którym określisz miejsce docelowe zasobu, identyfikatory URI Google Cloud Storage i opcjonalne metadane pasma.

Przykład: pojedynczy plik COG obejmujący wszystkie pasma Jeśli plik COG zawiera wszystkie pasma (np. RGB), plik manifestu wymaga tylko jednego zestawu kafelków:

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

Przykład: wiele plików COG (po jednym na pasmo) Jeśli masz osobne pliki dla różnych pasm (np. czerwonego, zielonego i niebieskiego w osobnych plikach):

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

Krok 3. Prześlij prośbę o rejestrację

Plik manifestu możesz przesłać do Earth Engine za pomocą biblioteki klienta Earth Engine Python, narzędzia wiersza poleceń earthengine lub interfejsu Earth Engine REST API. Wybierz metodę, która najlepiej pasuje do Twojego sposobu pracy.

Biblioteka klienta Python

W skrypcie Python lub notatniku Jupyter użyj biblioteki klienta Earth Engine Python (ee.data) po zainicjowaniu projektu:

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']}")
      

Narzędzie wiersza poleceń

W terminalu zapisz plik manifestu w pliku o nazwie manifest.json i uruchom polecenie przesyłania earthengine command:

# 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
      

Interfejs API REST (Python)

W przypadku zautomatyzowanych procesów bez biblioteki klienta wyślij autoryzowane POST żądanie bezpośrednio do punktu końcowego interfejsu Earth Engine REST API projects.image.importExternal (jak pokazano tutaj na przykładzie języka Python):

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

Po przesłaniu prośby o rejestrację rozpocznie się lekka operacja indeksowania metadanych. Ponieważ rejestracja pliku COG nie powoduje kopiowania danych pikseli, ta operacja zwykle trwa kilka sekund.

Rejestracja synchroniczna: rejestracja pliku COG to szybkie, synchroniczne wywołanie interfejsu API, a nie asynchroniczne zadanie obliczeniowe, dlatego nie powoduje utworzenia zadania w tle na karcie Zadania w edytorze kodu ani w menedżerze zadań zbiorczych. Wywołanie interfejsu API jest blokowane do momentu zakończenia weryfikacji i indeksowania metadanych, po czym zasób jest natychmiast dostępny na karcie Zasoby w edytorze kodu lub za pomocą polecenia ee.data.getAsset().

Ograniczenia dotyczące plików manifestu w przypadku zasobów COG

Podczas tworzenia pliku manifestu dla zasobów opartych na plikach COG pamiętaj o tych ścisłych ograniczeniach (które różnią się od standardowych plików manifestu):

• Pojedynczy zasobnik: wszystkie identyfikatory URI w pliku manifestu muszą znajdować się w tym samym zasobniku GCS.
• Jeden identyfikator URI na źródło: każdy element ImageSource musi zawierać dokładnie 1 identyfikator URI. Nie możesz łączyć wielu plików w jeden zestaw kafelków. Aby połączyć wiele scen COG, zarejestruj każdy plik COG jako zasób i połącz je w ee.ImageCollection za pomocą polecenia .mosaic().
• Brak mask_bands: element mask_bands najwyższego poziomu nie jest obsługiwany. Użyj elementu missingData w pliku manifestu lub upewnij się, że plik TIFF ma wewnętrzną wartość nodata.
• Brak data_type w zestawie kafelków: nie określaj elementu data_type w sekcji tilesets ; jest on wykrywany automatycznie.
• Brak dimensions w źródle: nie określaj elementu dimensions w elemencie ImageSource.
• Brak subdataset_prefix / subdataset_suffix.
• Brak min_tile_area_ratio lub skip_metadata_read.

Krok 4. Skonfiguruj uprawnienia (ważne w przypadku udostępniania)

W przeciwieństwie do standardowych zasobów Earth Engine dane pikseli pliku COG pozostają w GCS. Gdy udostępniasz innym zasób oparty na pliku COG, musisz przyznać im dostęp do odczytu zarówno zasobu Earth Engine, jak i plików GCS.

1. Przyznaj uprawnienia do zasobnika GCS

Współpracownicy muszą mieć uprawnienia do odczytu plików z GCS.

Wymagane uprawnienia:

• storage.buckets.get (do pobierania metadanych i lokalizacji zasobnika)
• storage.objects.get (do odczytywania danych pikseli)

Te uprawnienia możesz przyznać za pomocą tych standardowych ról Cloud Storage:

• Wyświetlający zasobnik Cloud Storage (przyznaje uprawnienie storage.buckets.get do odczytywania metadanych i lokalizacji zasobnika)
• Wyświetlający obiekty Cloud Storage (przyznaje uprawnienie storage.objects.get do odczytywania danych pikseli)

Kroki konfiguracji w konsoli Google Cloud:

1. Otwórz przeglądarkę Cloud Storage.
2. Kliknij nazwę zasobnika.
3. Wybierz kartę Uprawnienia.
4. Kliknij PRZYZNAJ DOSTĘP.
5. Dodaj adresy e-mail współpracowników (lub grupę dyskusyjną Google albo allUsers w przypadku dostępu publicznego).
6. Przypisz role Wyświetlający zasobnik Cloud Storage i Wyświetlający obiekty Cloud Storage.
7. Kliknij Zapisz.

2. Udostępnij zasób Earth Engine

Udostępnij sam zasób za pomocą Menedżera zasobów Earth Engine lub interfejsu wiersza poleceń. Szczegółowe informacje znajdziesz w przewodniku po zarządzaniu zasobami .

Zarządzanie generacjami obiektów

Gdy zarejestrujesz plik COG, Earth Engine zapisze konkretną generację (wersję) obiektu GCS. Jeśli zaktualizujesz plik w GCS, jego generacja się zmieni.

• Domyślnie Earth Engine nie będzie mógł wczytać zasobu i zwróci błąd: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
• Ma to zapobiec utracie synchronizacji metadanych (np. projekcji lub obszaru) z pikselami.

• Sprawdzona metoda: jeśli musisz zaktualizować dane obrazu, zarejestruj je jako nowy zasób lub ponownie uruchom polecenie przesyłania z flagą --force zamiast zastępować pliki w miejscu:

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

Korzystanie z zarejestrowanych zasobów

Po zarejestrowaniu dostęp do zasobu opartego na pliku COG w skryptach Earth Engine jest taki sam jak w przypadku każdego standardowego zasobu obrazu:

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