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
ImageSourcemusi 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 wee.ImageCollectionza pomocą.mosaic(). - No
mask_bands: polemask_bandsnajwyższego poziomu nie jest obsługiwane. UżyjmissingDataw pliku manifestu lub upewnij się, że plik TIFF ma wewnętrzną wartość nodata. - Brak
data_typew zbiorze kafelków: nie podawajdata_typew sekcjitilesets, ponieważ jest on wykrywany automatycznie. - Brak
dimensionsw źródle: nie podawajdimensionswImageSource. - Nie
subdataset_prefix/subdataset_suffix. - No
min_tile_area_ratiolubskip_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.getdo odczytu metadanych i lokalizacji zasobnika) - Wyświetlający obiekty Cloud Storage (zapewnia uprawnienie
storage.objects.getdo odczytu danych piksela)
Kroki konfiguracji w konsoli Google Cloud:
- Otwórz Przeglądarkę Cloud Storage.
- Kliknij nazwę zasobnika.
- Wybierz kartę Uprawnienia.
- Kliknij PRZYZNAJ DOSTĘP.
- Dodaj adresy e-mail współpracowników (lub grupy dyskusyjnej Google albo
allUsers, aby zapewnić dostęp publiczny). - Przypisz role Wyświetlający zasobnik Cloud Storage i Wyświetlający obiekty Cloud Storage.
- 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": truejako pole najwyższego poziomu obok"imageManifest"w treści żądaniaprojects.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 rmlubee.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 widokuBASIC, 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 odpowiedzi429 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 przezee.data.startExternalImageIngestion(manifest, allow_overwrite=True)i zmapuj go na listę manifestów. Przekazanie parametruallow_overwrite=Truenawet 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.