Cloud GeoTiff Destekli Earth Engine Öğeleri

Colab logosu Google Colab'de çalıştır GitHub logosu Kaynağı GitHub'da görüntüle

Earth Engine, Cloud Optimized GeoTIFF'ler (COG'ler) tarafından desteklenen öğeleri destekler. COG destekli öğelerin avantajlarından biri, resmin mekansal ve meta veri alanlarının öğe oluşturma sırasında dizine eklenmesidir. Bu sayede resim, koleksiyonlarda daha iyi performans gösterir. COG destekli öğelerin performansı, tipik kullanım alanlarında alınan öğelerin performansıyla karşılaştırılabilir.

Tek bir öğenin birden fazla MM tarafından desteklenebileceğini (ör. her bant için bir MM olabilir) unutmayın. Ancak tek bir bant için çok sayıda COG döşemesi kullanmak desteklenmez.

(Alternatif olarak, Earth Engine, Google Cloud Storage'daki COG'lardan doğrudan resim yükleyebilir (daha fazla bilgi). Ancak ee.Image.loadGeoTIFF üzerinden yüklenen ve bir resim koleksiyonuna eklenen resimler, koleksiyonda filtreleme işlemleri için GeoTiff'in okunmasını gerektirir.)

COG destekli bir öğe oluşturmak için:

  1. COG dosyalarınızı bir GCS paketine yerleştirin (İzin verilen bölgeler için Konum bölümüne bakın).
  2. Resim yükleme manifesti yazma
  3. Yükleme komutu göndermek için earthengine komut satırı yardımcı programını kullanın:
earthengine upload external_image --manifest my_manifest.json

Bir Tileset içeren örnek resim manifesti

En basit ImageManifest, tek bir Tileset içeren'dır. Bant belirtilmezse sonuçta elde edilen öğe, GeoTIFF'in tüm bantlarını ve GeoTIFF'te kodlanmış bant adlarını (bu örnekte "vis-red", "vis-green" ve "vis-blue") içerir.

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)

Birden fazla Tileset

tilesetId ve tilesetBandIndex alanları kullanılarak, sonuçtaki öğenin her bandının bir Tileset bandı tarafından desteklendiği birden fazla Tileset içeren bir ImageManifest belirtmek mümkündür. Bu, farklı bantların farklı çözünürlüklere veya veri türlerine sahip olduğu durumlarda kullanışlıdır. Gruplar, mevcut Tileset arasından herhangi bir sırada listelenebilir. Aşağıdaki örnekte:

  • "b4b3b2.tif" 10 m ölçeğe, "b5b6b7" ise 20 m ölçeğe sahiptir.
  • Elde edilen öğenin bant sırası, giriş COG'lerinden karıştırılır (ör. çıkış bandı 0, Tileset 0'dan, çıkış bandı 1 ise Tileset 1'den alınır).
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)

COG destekli varlıklarla ilgili ayrıntılar

Konum

Cloud Storage paketi konumu şunlardan biri olmalıdır:

  • ABD çoklu bölgesi
  • ABD-CENTRAL1'i içeren herhangi bir ABD çift bölgeli bölgesi
  • US-CENTRAL1 bölgesi

Depolama sınıfı

Paketin depolama sınıfı "Standard Storage" olmalıdır.

Paylaşım izinleri

COG destekli Earth Engine öğelerinin ve temel verilerin erişim kontrol listeleri ayrı ayrı yönetilir. Okuma amacıyla COG destekli öğeleri ortak çalışanlarla paylaşırken hem Earth Engine öğesine hem de temel COG dosyalarına okuma erişimi verilmesini sağlamak öğe sahibinin sorumluluğundadır.

1. Okuma için Google Cloud Storage paketi izinleri verme

Ortak çalışanların COG destekli öğeleri okuyabilmesi için öncelikle Google Cloud Storage paketindeki temel COG dosyalarına okuma erişiminin olması gerekir. Bu izinler olmadan Earth Engine, verileri alamaz. Google Cloud Storage'daki veriler bir Earth Engine kullanıcısı tarafından görülemiyorsa Earth Engine, "gs://my-bucket/my-object#123456 konumundaki GeoTIFF yüklenemedi" (burada 123456, nesnenin oluşturulma zamanıdır) şeklinde bir hata döndürür.

Özellikle, ortak çalışanların aşağıdaki izinlere sahip olması gerekir:

  • storage.buckets.get (paket meta verilerini ve konumunu almak için, Earth Engine'in öğenin kaynağını düzgün şekilde çözmesine olanak tanır).
  • storage.objects.get (COG destekli gerçek öğe verilerini okumak için).

Bu izinler, "Storage Legacy Bucket Reader" ve "Storage Legacy Object Reader" rolleri tarafından sağlanır. Diğer roller de bu izinleri sağlayabilir.

Bu rolleri ortak çalışanlara atamak için:

  1. Paket izni sayfasına gidin: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. "ERİŞİM İZNİ VER"i tıklayın.
  3. Okuma erişimi verilmesi gereken tüm ana hesapları (ör. kullanıcılar, gruplar, hizmet hesapları) ekleyin.
  4. Aşağıdaki rolleri atayın:
    • "Storage Legacy Bucket Reader" (storage.buckets.get ve diğer paket düzeyinde okuma izinlerini sağlar).
    • "Storage Eski Nesne Okuyucu" (storage.objects.get sağlar).
    • (Alternatif olarak, yalnızca storage.buckets.get ve storage.objects.get izinlerine sahip yeni bir özel rol oluşturup bu rolü atayabilirsiniz.)
  5. Kaydet

2. Earth Engine öğesini okuma için paylaşma

Ortak çalışanlarınızın temel GCS paketi ve nesneler üzerinde gerekli izinlere sahip olduğundan emin olduktan sonra Earth Engine öğesini de paylaşmanız gerekir. Earth Engine öğe izinlerini ayarlama hakkında daha fazla bilgi için Earth Engine öğe yönetimi kılavuzuna bakın.

Nesiller

COG destekli bir öğe oluşturulduğunda Earth Engine, manifestte belirtilen TIFF'lerin meta verilerini okur ve bir öğe deposu girişi oluşturur. Bu girişle ilişkili her URI'nin bir oluşturma işlemi olabilir. Nesil oluşturma hakkında ayrıntılı bilgi için nesne sürümü oluşturma belgelerine bakın. Bir nesil belirtilmişse (ör. gs://foo/bar#123), Earth Engine bu URI'yi olduğu gibi saklar. Bir nesil belirtilmezse Earth Engine, bu URI'yi ImportExternalImage çağrıldığında TIFF'in nesliyle birlikte depolar.

Bu nedenle, GCS'deki harici bir öğeyi içeren herhangi bir TIFF güncellenirse (böylece oluşturma işlemi değişirse) Earth Engine, beklenen nesne artık mevcut olmadığı için "gs://my-bucket/my-object#123456 konumundaki GeoTIFF yüklenemedi" hatasını döndürür (paket birden fazla nesne sürümünü etkinleştirmediği sürece). Bu politika, öğenin meta verilerinin nesnenin meta verileriyle senkronize kalmasını sağlamak için tasarlanmıştır.

Yapılandırma

Bir COG'nin nasıl yapılandırılması gerektiğiyle ilgili olarak TIFF şunları YAPMALIDIR:

  • Döşeme: Karo boyutları şunlardan biri olmalıdır:

    • 256x256
    • 512x512
    • 1024x1024
    • 2048x2048

  • Tüm IFD'ler başlangıçta olacak şekilde düzenlenir.

En iyi performans için:

  • 512x512 veya daha yüksek karo boyutları kullanın.
  • 2'nin gücüyle ilgili genel bakışları dahil edin.

Kullanım alanlarınıza bağlı olarak, "INTERLEAVE" oluşturma seçeneği performansı etkileyebilir. Her durumda BAND interleave kullanılmasını öneririz.

Optimize edilmiş yapılandırma hakkında daha fazla bilgi için bu sayfayı inceleyin.

Aşağıdaki gdal_translate komutu, bir rasteri Earth Engine'de iyi performans gösterecek şekilde bantlar arası, zstd ile sıkıştırılmış, Cloud Optimized GeoTIFF'e dönüştürür:

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

Bir tahmin edici belirterek çıkış dosyasının boyutunu daha da küçültmek mümkün olabilir (tam sayı veri türleri için -co PREDICTOR=2, kayan nokta veri türleri için -co PREDICTOR=3).

GDAL >= 3.11 sürümünü kullananlar, COG sürücüsü ile genel bakış oluşturma ve koruma konusunda endişelenmeden dosya oluşturabilir.

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 \

REST API'yi kullanarak Cloud GeoTiff destekli öğeler oluşturma

Not: REST API, tüm kullanıcılar için uygun olmayabilecek yeni ve ileri seviye özellikler içerir. Earth Engine'i yeni kullanmaya başladıysanız JavaScript kılavuzu ile başlamanızı öneririz.

REST API'yi kullanarak COG destekli bir öğe oluşturmak için Earth Engine ImportExternalImage uç noktasına bir POST isteği gönderin. Aşağıda gösterildiği gibi, bu isteğin kullanıcı klasörünüzde öğe oluşturmak için yetkilendirilmesi gerekir.

Yetkili oturum başlatma

Kullanıcı klasörünüzde bir Earth Engine öğesi oluşturabilmek için isteği gönderirken kendiniz olarak kimliğinizi doğrulayabilmeniz gerekir. AuthorizedSession başlatmak için Earth Engine kimlik doğrulayıcısından alınan kimlik bilgilerini kullanabilirsiniz. Daha sonra Earth Engine'e istek göndermek için AuthorizedSession kullanabilirsiniz.

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

İstek metni

İstek metni, ImageManifest öğesinin bir örneğidir. Bu bölümde, COG'a giden yol diğer faydalı özelliklerle birlikte belirtilir.

ImageManifest yapılandırma hakkında ayrıntılı bilgi için bu kılavuza bakın. Her biri bir veya daha fazla bant tarafından desteklenen bir veya daha fazla Tileset tanımlayabilirsiniz. ImportExternalImage için, Tileset başına en fazla bir ImageSource desteklenir.

SMM'nin dışa aktarılmasıyla ilgili ayrıntılar için bu dokümana bakın.

İsteği gönderin

Earth Engine projects.images.importExternal uç noktasına POST isteğinde bulunun.

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