Bulut için optimize edilmiş GeoTIFF (COG) öğelerini kaydetme

Earth Engine, Google Cloud Storage'da (GCS) depolanan Cloud Optimized GeoTIFF'ler (COG) tarafından desteklenen öğeleri destekler.

COG destekli bir öğeyi kaydettiğinizde Earth Engine, oluşturma sırasında görüntünün uzamsal ve meta veri alanlarını dizine ekler. Bu sayede, koleksiyonlarda kullanıldığında görüntünün performansı, standart olarak beslenen öğelerle karşılaştırılabilir düzeyde olur (Cloud Optimized GeoTIFF (COG) genel bakış bölümüne bakın).

Bu kılavuzda dosyalarınızı hazırlama, manifesti yazma, kayıt isteğini gönderme, izinleri yapılandırma ve kayıtlı öğeleri güncelleme veya silme konuları ele alınmaktadır.

Başlamadan önce

COG kaydetmeden önce Cloud Storage kaynaklarınızı doğru şekilde ayarlamanız gerekir.

Paket konumu

Earth Engine'in Cloud Storage paketinize erişebilmesi için paketin aşağıdaki veri merkezi bölgelerinden veya çoklu bölgelerden birinde bulunması gerekir:

  • us çoklu bölgesi
  • us-central1 içeren herhangi bir ABD çift bölgesi
  • us-central1 bölgesi

Paketiniz başka bir bölgesel veri merkezine (ör. us-east4 veya europe-west1) yerleştirilirse Earth Engine, kayıt ve okuma isteklerini reddeder. Desteklenen Cloud Storage paketi konumlarını inceleyin.

Depolama sınıfı ve faturalandırma

  • Standard depolama sınıfını kullanmanızı öneririz. Standard Storage'da minimum depolama süresi kuralı yoktur. Bu sayede, geçici dosyaları günceller veya değiştirirseniz erken silme faturalandırma cezaları önlenir.
  • Earth Engine hesaplama döngüleri, Cloud Storage veri alma ek ücretlerine tabi olmasa da harici araçlardan (ör. masaüstü CBS yazılımı) Standard Storage dışındaki depolama katmanlarına erişmek yüksek veri alma ücretlerine neden olur.
  • Cloud Storage'ı kullanmak için Google Cloud projenizde faturalandırmayı etkinleştirmeniz gerekir. Başlamak için Cloud Storage hızlı başlangıç kılavuzunu inceleyin.

SMM'lerinizi hazırlama

Earth Engine, COG'leri doğrudan Cloud Storage'dan okur ve yalnızca bir hesaplamanın ihtiyaç duyduğu başlığı ve parçaları getirir. Bu nedenle, dosya düzeni önemlidir. TIFF dosyası şu özelliklere sahip olmalıdır:

  • Karolu: 16x16 ile 2048x2048 arasında kare 2'nin kuvveti karo boyutları. En iyi performans için 512x512 boyutunu öneririz.
  • Tüm Resim Dosyası Dizinleri (IFD'ler) başta olacak şekilde düzenlenmiş.
  • Varsa 2'nin kuvvetiyle ilgili genel bakışları ekleyin. Genel bakışlar zorunlu değildir ancak tek bir karodan daha büyük resimler için önerilir.
  • BAND veya PIXEL aralıklı yerleşim kullanın (farklılıklar için tek bantlı ve çok bantlı dosyalar bölümüne bakın).

Bir görüntüyü dönüştürmek için GDAL'ın COG sürücüsünü kullanın. Bu sürücü, gerekli düzeni (karolar, genel bakışlar ve başlık yerleşimi) tek adımda oluşturur. Kategorik veriler için OVERVIEW_RESAMPLING=NEAREST ekleyin. Varsayılan değer CUBIC şeklindedir. Sıkıştırma, genel bakış ve düzen önerileri için harici COG'leri hazırlamayla ilgili en iyi uygulamalar başlıklı makaleyi inceleyin.

GDAL 3.11+ CLI

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

Classic CLI

3.11'den önceki GDAL sürümlerinde INTERLEAVE=BAND parametresini atlayın.

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

Manifest dosyasını oluşturma

COG'yi Earth Engine Python istemci kitaplığı, earthengine komut satırı aracı veya Earth Engine REST API kullanarak kaydetmeniz fark etmeksizin öğe hedefini, Cloud Storage URI'larını ve isteğe bağlı bant meta verilerini belirten bir resim yükleme manifesti tanımlamanız gerekir. API ve komut satırı aracı, COG destekli öğeleri harici resimler (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal) olarak adlandırır.

Örnek: Tüm bantları destekleyen tek bir COG COG'niz tüm bantları (ör. RGB) içeriyorsa manifest için yalnızca tek bir karo grubu gerekir:

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

Örnek: Birden fazla COG (bant başına bir tane) Farklı bantlar için ayrı dosyalarınız varsa (ör. ayrı dosyalarda kırmızı, yeşil ve mavi):

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

Manifest kısıtlamaları

COG destekli öğelerin manifestleri, standart besleme manifestleri için geçerli olmayan kısıtlamalara sahiptir:

  • Tek paket: Manifestteki tüm URI'ler aynı Cloud Storage paketinde bulunmalıdır.
  • Kaynak başına bir URI: Her ImageSource tam olarak bir URI içermelidir. Birden fazla dosyayı tek bir karo grubu kaynağında mozaikleyemezsiniz. Birden fazla COG sahnesini mozaiklemek için her COG'yi öğe olarak kaydedin ve .mosaic() kullanarak bir ee.ImageCollection içinde birleştirin.
  • No mask_bands: Üst düzey mask_bands alanı desteklenmiyor. Manifest dosyasında missingData kullanın veya TIFF'inizin dahili bir nodata değeri olduğundan emin olun.
  • Karo grubunda data_type yok: tilesets bölümünde data_type belirtmeyin. Bu değer otomatik olarak algılanır.
  • Kaynakta dimensions yok: ImageSource içinde dimensions belirtmeyin.
  • Hayır subdataset_prefix / subdataset_suffix.
  • min_tile_area_ratio veya skip_metadata_read yok.

Kayıt isteğini gönderme

Manifestinizi Earth Engine Python istemci kitaplığı, earthengine komut satırı aracı veya Earth Engine REST API'yi kullanarak Earth Engine'e gönderebilirsiniz. İş akışınıza en uygun yöntemi seçin.

Python istemci kitaplığı

Projenizi başlattıktan sonra Python komut dosyasında veya Jupyter not defterinde Earth Engine Python istemci kitaplığını (ee.data) kullanın:

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

Komut satırı aracı

Terminalinizde manifest dosyanızı manifest.json adlı bir dosyaya kaydedin ve earthengine yükleme komutunu çalıştırın:

# 1. Verify your environment is authenticated
earthengine authenticate

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

REST API

İstemci kitaplığı olmayan otomatik iş akışları için doğrudan Earth Engine REST API uç noktasına yetkili bir POST isteği gönderin projects.image.importExternal (burada Python kullanılarak gösterilmiştir):

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

Kayıt isteği gönderildikten sonra basit bir meta veri dizine ekleme işlemi başlatılır. COG kaydı piksel verilerini kopyalamadığından bu işlem genellikle saniyeler içinde tamamlanır.

İzinleri yapılandır

Standart Earth Engine öğelerinin aksine, COG'un piksel verileri Cloud Storage'da kalır. COG destekli bir öğeyi başkalarıyla paylaşırken hem Earth Engine öğesine hem de Cloud Storage dosyalarına okuma erişimi vermeniz gerekir.

Cloud Storage paketi izinleri verme

Ortak çalışanların Cloud Storage'daki dosyaları okumak için izinlere ihtiyacı vardır.

Gerekli izinler:

  • storage.buckets.get (Paket meta verilerini ve konumunu almak için)
  • storage.objects.get (piksel verilerini okumak için)

Bu izinleri aşağıdaki standart Cloud Storage rollerini kullanarak verebilirsiniz:

  • Storage Bucket Viewer (paket meta verilerini ve konumunu okumak için storage.buckets.get sağlar)
  • Storage Object Viewer (piksel verilerini okumak için storage.objects.get sağlar)

Google Cloud Console'da yapılandırma adımları:

  1. Cloud Storage Tarayıcısı'na gidin.
  2. Paketinizin adını tıklayın.
  3. İzinler sekmesini seçin.
  4. ERİŞİM İZNİ VER'i tıklayın.
  5. Ortak çalışanlarınızın e-posta adreslerini (veya bir Google Grubu'nu ya da herkese açık erişim için allUsers) ekleyin.
  6. Storage Bucket Viewer (Depolama Paketi Görüntüleyici) ve Storage Object Viewer (Depolama Alanı Nesne Görüntüleyici) rollerini atayın.
  7. Kaydet'i tıklayın.

Earth Engine öğesini paylaşma

Earth Engine Öğe Yöneticisi'ni veya KSA'yı kullanarak öğeyi paylaşın. Ayrıntılar için Öğe Yönetimi Kılavuzu'na bakın.

COG destekli öğeleri güncelleme, değiştirme ve silme

COG destekli bir öğe, Cloud Storage'daki bir dosyanın belirli bir sürümüne işaret eden bir göstergedir. Ayrıca, kaydettiğinizde Earth Engine'in dizine eklediği meta verileri (ayak izi, projeksiyon, bantlar ve genel bakış düzeni) içerir. Earth Engine, dosya sürümünü sabitler. Böylece bu meta veriler piksellerle senkronizasyon dışına çıkamaz. COG destekli öğeleri güncellemek, standart öğeleri güncellemekten bu yönüyle farklıdır.

Nesne oluşturma

Bir COG kaydettiğinizde Earth Engine, Cloud Storage nesnesinin neslini (sürüm numarası) URI ile birlikte kaydeder. Sabitlenmiş nesne nesil numarasını öğenin meta verilerinde görebilirsiniz. Bu numara, URI'da #<generation> son eki olarak görünür:

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

Öğeyi kaydederken (veya yeniden kaydederken) manifest URI'sine #<generation> soneki ekleyerek belirli bir sürümü kendiniz de sabitleyebilirsiniz. Bu parametre olmadan Earth Engine, mevcut nesneyi okur ve bulduğu nesne neslini sabitler. Açıkça sabitleme, nesne sürüm oluşturma özelliğine sahip bir paketin sakladığı önceki bir sürüme geri dönmek için kullanışlıdır.

Cloud Storage'da dosyanın üzerine yazarsanız yeni bir nesil oluşturulur. Dosyayı silerseniz sabitlenen nesil kaldırılır. Her iki durumda da öğenin pikselleri okunamaz. Ancak paketteki nesne sürümü oluşturma özelliği eski nesli koruyorsa Earth Engine, eski pikselleri okumaya devam eder. Dizine eklenen kaydı kullanan meta veri işlemleri (ör. ee.data.getAsset(), bandNames() ve koleksiyon filtreleme) her iki durumda da çalışmaya devam eder.

Dosyasını değiştirdikten sonra öğeyi güncelleme

Mevcut bir öğeyi dosyasının yeni bir sürümüne yönlendirmek için aynı öğe adıyla ve üzerine yazma etkinleştirilmiş olarak yeniden kaydedin. Earth Engine, tek bir eşzamanlı çağrıda GeoTIFF başlığını yeniden okur, meta verileri yeniden dizine ekler ve yeni nesli sabitler. Öğenin mevcut izinleri korunur ancak özellikleri, zaman aralığı ve bant adları yeni manifest dosyasından alınır. Bu nedenle, daha önce ee.data.updateAsset() ile ayarladığınız her şeyi ekleyin.

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Komut satırı: earthengine upload external_image --force --manifest manifest.json
  • REST API: projects.image.importExternal istek gövdesinde "imageManifest" ile birlikte üst düzey alan olarak "overwrite": true değerini ekleyin.

Öğeyi önce silmeniz gerekmez. Silmek, ters etki yaratır: Bağımsız bir öğe izinlerini kaybeder ve bir koleksiyondaki resim, koleksiyondan kısa süreliğine kaybolur. ee.data.updateAsset() (projects.assets.patch) yalnızca özellikleri, zaman aralığını ve bant adlarını değiştirebilir; bir öğenin işaret ettiği dosyayı değiştiremez.

Bağımsız yaşam döngüleri

Earth Engine öğeleri ve Cloud Storage nesneleri ayrı ayrı yönetilir:

  • Earth Engine öğesini (earthengine rm veya ee.data.deleteAsset()) sildiğinizde yalnızca öğe kaydı kaldırılır. Cloud Storage'daki dosyalarınıza dokunulmaz.
  • Dosyanın Cloud Storage'dan silinmesi öğeyi kaldırmaz. Öğe, listelerde ve koleksiyonunda görünmeye devam eder (nesne nesilleri bölümüne bakın).

Büyük koleksiyonlarla çalışma

Earth Engine API'de toplu veya yinelemeli silme işlemi yoktur. Her öğe ayrı ayrı silinmelidir ve bir koleksiyonun silinebilmesi için boş olması gerekir. earthengine rm -r bu işlemi sizin için gerçekleştirir ancak silme işlemlerini tek tek yapar. Bu nedenle, on binlerce resim içeren bir koleksiyonun kaldırılması saatler sürebilir.

  • Bir koleksiyonun resimlerini değiştirmek için silmek yerine üzerine yazın. Üzerine yazma etkinleştirilmiş şekilde her resmi ada göre yeniden kaydedin (yukarıya bakın). Bu yöntem, iki istek yerine resim başına bir istek gerektirir, koleksiyonun her zaman dolu kalmasını sağlar ve koleksiyonun kendisinin silinip yeniden oluşturulmasını önler. Koleksiyonun izinleri de bu koleksiyonda yer alır. Yalnızca yeni grupta yer almayan resimleri silin.

  • Çok sayıda öğeyi silmek için bir komut dosyasından paralelleştirme yapın. ee.data.listAssets() ile öğeleri listeleyin (her resim için tam meta veriler yerine yalnızca adları ve türleri döndüren BASIC görünümünü kullanarak) ve bunları küçük bir iş parçacığı havuzundan silin. Öğe istekleri, proje genelindeki sıklık sınırlarını paylaşır. Bu nedenle, eşzamanlılığı düşük tutun (yaklaşık 10 çalışan) ve istemci kitaplığının yerleşik yeniden deneme özelliklerinin 429 Too Many Requests yanıtlarını işlemesine izin verin:

    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)

    Koleksiyon yalnızca her resim silindiğinde silinir. Bu nedenle, kısmi bir hata, koleksiyonu yeniden çalıştırma için yerinde bırakır.

    Aynı kalıp, birden fazla resim kaydetmek için de geçerlidir: Yardımcıdaki ee.data.deleteAsset(asset_id) ifadesini ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) ile değiştirin ve manifest listenizle eşleyin. İlk çalıştırmada bile allow_overwrite=True değerini iletmek, kısmi bir hatadan sonra toplu işlemin yeniden çalıştırılmasını güvenli hale getirir. Bunun nedeni, önceden oluşturulmuş tüm öğelerin hata oluşturmak yerine değiştirilmesidir.

Kayıtlı öğeleri kullanma

Kayıtlı bir COG destekli öğeye, Earth Engine komut dosyalarında standart bir içe aktarılan resim öğesi gibi erişilir:

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

İzinler, dosyaları güncelleme ve büyük koleksiyonları yönetme ile ilgili sık sorulan soruların yanıtları için SSS'nin COG bölümüne bakın.