Rejestrowanie zasobów Cloud Optimized GeoTIFF (COG)

Earth Engine obsługuje zasoby oparte na plikach GeoTIFF zoptymalizowanych pod kątem chmury (COG) przechowywanych w Google Cloud Storage (GCS).

Gdy rejestrujesz zasób oparty na COG, Earth Engine indeksuje pola przestrzenne i metadane obrazu w momencie jego tworzenia. Dzięki temu obraz jest wydajny, gdy jest używany w kolekcjach, a jego wydajność jest porównywalna ze standardowymi pozyskanymi zasobami (patrz Omówienie Cloud Optimized GeoTIFF (COG)).

W tym przewodniku znajdziesz informacje o przygotowywaniu plików, pisaniu pliku manifestu, przesyłaniu prośby o rejestrację, konfigurowaniu uprawnień oraz aktualizowaniu i usuwaniu zarejestrowanych zasobów.

Zanim zaczniesz

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

Lokalizacja zasobnika

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

  • Obszar obejmujący wiele regionów us
  • Dowolny region w dwóch regionach w USA, który obejmuje us-central1
  • Region us-central1

Jeśli Twój zasobnik znajduje się w innym regionalnym centrum danych (np. us-east4 lub europe-west1), Earth Engine odrzuci żądania rejestracji i odczytu. Zobacz obsługiwane lokalizacje zasobników Cloud Storage.

Klasa pamięci masowej i płatności

  • Zalecamy korzystanie z klasy pamięci masowej Standard. Standardowy pakiet pamięci nie ma reguł dotyczących minimalnego czasu przechowywania, co zapobiega naliczaniu kar za przedwczesne 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 niestandardowych poziomów pamięci masowej z narzędzi zewnętrznych (takich jak oprogramowanie GIS na komputery) wiąże się z wysokimi opłatami za pobieranie.
  • Aby korzystać z Cloud Storage, musisz mieć włączone płatności w projekcie Google Cloud. Aby rozpocząć, zapoznaj się z krótkim wprowadzeniem do Cloud Storage.

Przygotowanie kosztu własnego sprzedaży

Earth Engine odczytuje pliki COG bezpośrednio z Cloud Storage, pobierając tylko nagłówek i kafelki potrzebne do obliczeń, dlatego układ pliku ma znaczenie. Plik TIFF musi:

  • Kafelkowy, z kwadratowymi kafelkami o wymiarach będących potęgą liczby 2, od 16 x 16 do 2048 x 2048. Aby uzyskać najlepsze wyniki, zalecamy rozmiar 512 x 512.
  • Uporządkowane tak, aby wszystkie katalogi plików graficznych (IFD) znajdowały się na początku.
  • Uwzględnij przeglądy potęg liczby 2, jeśli takie istnieją. Przeglądy nie są wymagane, ale są zalecane w przypadku obrazów większych niż pojedynczy kafelek.
  • Użyj przeplotu BAND lub PIXEL (informacje o kompromisach znajdziesz w artykule o plikach jednopasmowych i wielopasmowych).

Aby przekonwertować obraz, użyj sterownika COG GDAL, który w jednym kroku tworzy wymagany układ (kafelkowanie, przeglądy i umieszczenie nagłówka). Dodaj OVERVIEW_RESAMPLING=NEAREST w przypadku danych kategorialnych. Wartość domyślna to CUBIC. Zalecenia dotyczące kompresji, przeglądu i układu znajdziesz w artykule o sprawdzonych metodach przygotowywania zewnętrznych plików COG.

Interfejs wiersza poleceń GDAL 3.11 lub nowszego

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

Klasyczny interfejs wiersza poleceń

Pomiń INTERLEAVE=BAND w wersjach GDAL starszych niż 3.11.

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

Tworzenie pliku manifestu

Niezależnie od tego, czy rejestrujesz COG za pomocą biblioteki klienta Earth Engine w Pythonie, narzędzia wiersza poleceń earthengine czy interfejsu Earth Engine REST API, musisz zdefiniować plik manifestu przesyłania obrazu, który określa miejsce docelowe zasobu, identyfikatory URI obiektów w Cloud Storage i opcjonalne metadane pasma. Interfejs API i narzędzie wiersza poleceń określają zasoby COG jako obrazy zewnętrzne (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal).

Przykład: pojedynczy plik COG obsługujący wszystkie pasma Jeśli plik COG zawiera wszystkie pasma (np. RGB), plik manifestu wymaga tylko jednego zbioru 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):

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

Ograniczenia dotyczące pliku manifestu

Pliki manifestu zasobów opartych na COG mają ograniczenia, które nie dotyczą standardowych plików manifestu przesyłania:

  • Pojedynczy zasobnik: wszystkie identyfikatory URI w pliku manifestu muszą znajdować się w tym samym zasobniku Cloud Storage.
  • 1 identyfikator URI na źródło: każdy element ImageSource musi zawierać dokładnie 1 identyfikator URI. Nie możesz połączyć wielu plików w jednym źródle zbioru kafelków. Aby utworzyć mozaikę z wielu scen COG, zarejestruj każdy plik COG jako zasób i połącz je w ee.ImageCollection za pomocą .mosaic().
  • No mask_bands: pole mask_bands najwyższego poziomu nie jest obsługiwane. Użyj missingData w pliku manifestu lub upewnij się, że plik TIFF ma wewnętrzną wartość nodata.
  • Brak data_type w zbiorze kafelków: nie podawaj data_type w sekcji tilesets, ponieważ jest on wykrywany automatycznie.
  • Brak dimensions w źródle: nie podawaj dimensions w ImageSource.
  • Nie subdataset_prefix / subdataset_suffix.
  • No min_tile_area_ratio lub skip_metadata_read.

Przesyłanie prośby o rejestrację

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

Biblioteka klienta Python

W skrypcie Pythona lub notatniku Jupyter użyj biblioteki klienta Earth Engine w Pythonie (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. Register the asset
result = ee.data.startExternalImageIngestion(manifest)
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:

# 1. Verify your environment is authenticated
earthengine authenticate

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

Interfejs API typu REST

W przypadku zautomatyzowanych przepływów pracy bez biblioteki klienta wyślij autoryzowane żądanie POST bezpośrednio do punktu końcowego interfejsu Earth Engine REST API projects.image.importExternal (tutaj pokazano to za pomocą Pythona):

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śba o rejestrację inicjuje uproszczoną operację indeksowania metadanych. Rejestracja COG nie kopiuje danych pikseli, więc ta operacja zwykle trwa kilka sekund.

Skonfiguruj uprawnienia

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

Przyznawanie uprawnień do zasobnika Cloud Storage

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

Wymagane uprawnienia:

  • storage.buckets.get (aby pobrać metadane i lokalizację zasobnika)
  • storage.objects.get (do odczytu danych piksela)

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

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

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 grupy dyskusyjnej Google albo allUsers, aby zapewnić dostęp publiczny).
  6. Przypisz role Wyświetlający zasobnik Cloud Storage i Wyświetlający obiekty Cloud Storage.
  7. Kliknij Zapisz.

Udostępnianie zasobu 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.

Aktualizowanie, zastępowanie i usuwanie zasobów COG

Komponent oparty na COG to wskaźnik do konkretnej wersji pliku w Cloud Storage oraz metadane (obszar, projekcja, pasma i układ podglądu), które Earth Engine zindeksował podczas rejestracji. Earth Engine przypina wersję pliku, aby te metadane nie mogły się rozsynchronizować z pikselami. To właśnie odróżnia aktualizowanie zasobów opartych na COG od aktualizowania standardowych zasobów.

Generowanie obiektów

Gdy rejestrujesz COG, Earth Engine rejestruje generację obiektu Cloud Storage (jego numer wersji) wraz z identyfikatorem URI. Przypiętą generację możesz zobaczyć w metadanych obiektu. Pojawia się ona jako sufiks #<generation> w identyfikatorze URI:

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

Możesz też samodzielnie przypiąć konkretną wersję, dodając sufiks #<generation> do identyfikatora URI pliku manifestu podczas rejestrowania (lub ponownego rejestrowania) zasobu. Bez tego Earth Engine odczytuje bieżący obiekt i przypina dowolną znalezioną generację. Jawne przypinanie jest przydatne do przywracania wcześniejszej wersji, która została zachowana w zasobniku z obsługą wersji obiektów.

Jeśli zastąpisz plik w Cloud Storage, zostanie utworzona nowa generacja, a jeśli go usuniesz, przypięta generacja zostanie usunięta. W obu przypadkach odczytanie pikseli zasobu nie powiedzie się, chyba że obsługa wersji obiektów w zasobniku zachowa starą generację. W takim przypadku Earth Engine będzie nadal odczytywać stare piksele. Operacje na metadanych, które używają zindeksowanego rekordu (takie jak ee.data.getAsset(), bandNames() i filtrowanie kolekcji), będą nadal działać.

Aktualizowanie zasobu po zmianie pliku

Aby wskazać nową wersję pliku istniejącego zasobu, zarejestruj go ponownie z tą samą nazwą zasobu i włączoną opcją zastępowania. Earth Engine ponownie odczytuje nagłówek GeoTIFF, ponownie indeksuje metadane i przypina nową generację w jednym wywołaniu synchronicznym. Istniejące uprawnienia zasobu zostaną zachowane, ale jego właściwości, zakres czasu i nazwy pasm będą pochodzić z nowego pliku manifestu, więc uwzględnij wszystko, co zostało wcześniej ustawione za pomocą ee.data.updateAsset().

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Wiersz poleceń: earthengine upload external_image --force --manifest manifest.json
  • Interfejs API typu REST: uwzględnij "overwrite": true jako pole najwyższego poziomu obok "imageManifest" w treści żądania projects.image.importExternal.

Nie musisz najpierw usuwać zasobu, a usunięcie go przynosi efekt przeciwny do zamierzonego: samodzielny zasób traci uprawnienia, a obraz w kolekcji na chwilę z niej znika. Pamiętaj, że ee.data.updateAsset() (projects.assets.patch) może zmieniać tylko właściwości, zakres czasu i nazwy pasm. Nie może zmienić pliku, na który wskazuje zasób.

Niezależne cykle życia

Zasoby Earth Engine i obiekty Cloud Storage są zarządzane oddzielnie:

  • Usunięcie zasobu Earth Engine (earthengine rm lub ee.data.deleteAsset()) powoduje usunięcie tylko rekordu zasobu. Pliki w Cloud Storage pozostaną nienaruszone.
  • Usunięcie pliku w Cloud Storage nie powoduje usunięcia zasobu. Nadal będzie on widoczny na listach i w kolekcji (patrz generacje obiektów).

Praca z dużymi kolekcjami

W interfejsie Earth Engine API nie ma funkcji usuwania zbiorczego ani rekurencyjnego: każdy zasób musi zostać usunięty osobno, a kolekcja musi być pusta, zanim będzie można ją usunąć. earthengine rm -r zajmuje się tym za Ciebie, ale usuwa obrazy pojedynczo, więc usunięcie kolekcji z dziesiątkami tysięcy obrazów może zająć wiele godzin.

  • Aby zastąpić obrazy w kolekcji, zastąp je, zamiast usuwać. Ponownie zarejestruj każdy obraz według nazwy z włączonym zastępowaniem (patrz wyżej). Wymaga to jednego żądania na obraz zamiast dwóch, utrzymuje kolekcję przez cały czas i pozwala uniknąć usuwania i ponownego tworzenia samej kolekcji, w której znajdują się uprawnienia. Usuń tylko te obrazy, których nie ma w nowym zestawie.
  • Aby usunąć wiele zasobów, użyj skryptu do równoległego wykonywania operacji. Wyświetl listę zasobów za pomocą ee.data.listAssets() (używając widoku BASIC, który zwraca tylko nazwy i typy, a nie pełne metadane każdego obrazu) i usuń je z małej puli wątków. Żądania zasobów współdzielą ograniczenia liczby żądań na poziomie projektu, więc zachowaj umiarkowaną równoczesność (około 10 procesów roboczych) i pozwól, aby wbudowane w bibliotekę klienta ponowne próby obsługiwały odpowiedzi 429 Too Many Requests:

    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)
    

    Kolekcja jest usuwana tylko wtedy, gdy usunięto wszystkie obrazy, więc częściowe niepowodzenie pozostawia ją na miejscu do ponownego uruchomienia.

    Ten sam wzorzec dotyczy rejestrowania wielu obrazów: zastąp ee.data.deleteAsset(asset_id) w funkcji pomocniczej przez ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) i zmapuj go na listę manifestów. Przekazanie parametru allow_overwrite=True nawet przy pierwszym uruchomieniu sprawia, że po częściowym niepowodzeniu można bezpiecznie ponownie uruchomić zadanie wsadowe, ponieważ każdy utworzony już zasób zostanie zastąpiony, a nie spowoduje błąd.

Używanie zarejestrowanych zasobów

Po zarejestrowaniu zasób oparty na COG jest dostępny w skryptach Earth Engine tak samo jak każdy standardowy przetworzony komponent z obrazem:

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

Odpowiedzi na najczęstsze pytania dotyczące uprawnień, aktualizowania plików i zarządzania dużymi kolekcjami znajdziesz w sekcji COG w Najczęstszych pytaniach.