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

Earth Engine, Google Cloud Storage'da (GCS) depolanan Cloud Optimized GeoTIFF'ler (COG'ler) ile 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 (Bulut için optimize edilmiş GeoTIFF (COG) genel bakış bölümüne bakın).

Ön koşullar ve Cloud Storage kurulumu

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

1. Paket konumu (kesin koşul)

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.

2. Depolama sınıfı ve faturalandırma

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

1. adım: COG'lerinizi hazırlayın

TIFF dosyalarınız bulut için optimize edilmiş olmalıdır. TIFF dosyası şu özelliklere sahip olmalıdır:

• Döşeme: 256x256, 512x512, 1024x1024 veya 2048x2048 boyutlarında döşeme. En iyi performans için 512x512 veya daha yüksek bir çözünürlük öneririz.
• Tüm resim dosyası dizinleri (IFD'ler) başlangıçta olacak şekilde düzenlenir.
• 2'nin kuvvetiyle ilgili genel bakışları dahil edin.
• BAND interleave'i kullanın.

Görüntülerinizi dönüştürmek için GDAL'yi kullanabilirsiniz.

GDAL COG sürücüsünü kullanma (GDAL >= 3.1 önerilir):

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

Standart GTiff sürücüsünü kullanma:

Öncelikle, dahili 2'nin kuvveti genel bakışlar oluşturun (gdal raster overview add veya gdaladdo kullanarak), ardından resmi ve genel bakışları parçalı bir COG düzenine kopyalayın:

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

2. adım: Manifest dosyasını oluşturun

Earth Engine Python istemci kitaplığını, earthengine komut satırı aracını veya Earth Engine REST API'yi kullanarak COG kaydederken, öğe hedefi, Google Cloud Storage URI'leri ve isteğe bağlı bant meta verilerini belirten bir görüntü yükleme manifestosu tanımlamanız gerekir.

Örnek: Tüm bantları destekleyen tek COG COG'niz tüm bantları (ör. RGB) içeriyorsa manifest için yalnızca tek bir döşeme seti 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, 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 }
  ]
}

3. adım: Kayıt isteğini gönderin

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ığı

Python komut dosyasında veya Jupyter not defterinde, projenizi başlattıktan sonra 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. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
print(f"Asset registered: {result['name']}")
      

Komut satırı aracı

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

# 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
      

REST API (Python)

İstemci kitaplığı olmadan otomatikleştirilmiş iş akışları için yetkili bir POST isteğini doğrudan Earth Engine REST API uç noktasına projects.image.importExternal gönderin (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.

Eşzamanlı kayıt: COG kaydı, eşzamansız bir toplu işlem görevi yerine hızlı ve eşzamanlı bir API çağrısı olduğundan Kod Düzenleyici'nin Görevler sekmesinde veya toplu işlem yöneticisinde arka plan görevi oluşturmaz. API çağrısı, meta veri doğrulama ve indeksleme tamamlanana kadar engellenir. Ardından öğe, Kod Düzenleyici'deki Öğeler sekmesinde veya ee.data.getAsset() kullanılarak hemen kullanılabilir.

COG öğeleriyle ilgili manifest kısıtlamaları

COG destekli öğeler için manifest oluştururken aşağıdaki katı kısıtlamalara dikkat edin (Bunlar standart besleme manifestlerinden farklıdır.):

• Tek paket: Manifestteki tüm URI'ler aynı GCS 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 birleştiremezsiniz. Birden fazla COG sahnesini mozaiklemek için her bir COG'yi öğe olarak kaydedin ve .mosaic() kullanarak bunları bir ee.ImageCollection içinde birleştirin.
• Hayır mask_bands: Üst düzey mask_bands desteklenmez. 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, otomatik olarak algılanır.
• Kaynakta dimensions yok: ImageSource içinde dimensions belirtmeyin.
• Hayır subdataset_prefix / subdataset_suffix.
• Hayır min_tile_area_ratio veya skip_metadata_read.

4. adım: İzinleri yapılandırın (paylaşım için çok önemlidir)

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

1. GCS paketi izinleri verme

Ortak çalışanların GCS'deki 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.

2. Earth Engine öğesini paylaşma

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

Nesne oluşturma işlemlerini yönetme

COG kaydettiğinizde Earth Engine, GCS nesnesinin belirli neslini (sürüm) depolar. Dosyayı GCS'de güncellerseniz nesil bilgisi değişir.

• Varsayılan olarak Earth Engine, öğeyi yükleyemez ve bir hata döndürür: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
• Bu, meta verilerin (projeksiyon veya ayak izi gibi) temel piksellerle senkronizasyonunun bozulmasını önlemek için tasarlanmıştır.

• En iyi uygulama: Temel görüntü verilerini güncellemeniz gerekiyorsa dosyaların üzerine yazmak yerine yeni bir öğe olarak kaydedin veya yükleme komutunu --force işaretiyle yeniden çalıştırın:

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

Kayıtlı öğeleri kullanma

Kayıtlı bir COG destekli öğeye, Earth Engine komut dosyalarında standart olarak alınan herhangi bir 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')