Mendaftarkan aset Cloud Optimized GeoTIFF (COG)

Earth Engine mendukung aset yang didukung oleh Cloud Optimized GeoTIFF (COG) yang disimpan di Google Cloud Storage (GCS).

Saat Anda mendaftarkan aset yang didukung COG, Earth Engine akan mengindeks kolom spasial dan metadata gambar pada waktu pembuatan. Hal ini membuat citra berperforma baik saat digunakan dalam koleksi, dengan performa yang sebanding dengan aset standar yang diserap (lihat ringkasan Cloud Optimized GeoTIFF (COG)).

Panduan ini membahas cara menyiapkan file, menulis manifes, mengirimkan permintaan pendaftaran, mengonfigurasi izin, dan memperbarui atau menghapus aset terdaftar.

Sebelum memulai

Sebelum mendaftarkan COG, Anda harus menyiapkan resource Cloud Storage dengan benar.

Lokasi bucket

Agar Earth Engine dapat mengakses bucket Cloud Storage Anda, bucket tersebut harus berada di salah satu region atau multi-region pusat data berikut:

  • Multi-region us
  • Dual-region AS mana pun yang mencakup us-central1
  • Region us-central1

Jika bucket Anda ditempatkan di pusat data regional lain (seperti us-east4 atau europe-west1), Earth Engine akan menolak permintaan pendaftaran dan pembacaan. Lihat lokasi bucket Cloud Storage yang didukung.

Kelas penyimpanan dan penagihan

  • Sebaiknya gunakan kelas penyimpanan Standard. Standard Storage tidak memiliki aturan durasi penyimpanan minimum, sehingga mencegah denda penagihan penghapusan awal jika Anda memperbarui atau mengganti file sementara.
  • Meskipun loop komputasi Earth Engine tidak dikenai biaya tambahan pengambilan data Cloud Storage, mengakses tingkat penyimpanan non-Standard dari alat eksternal (seperti software GIS desktop) akan dikenai biaya pengambilan yang mahal.
  • Anda harus mengaktifkan penagihan di project Google Cloud untuk menggunakan Cloud Storage. Lihat panduan memulai Cloud Storage untuk memulai.

Menyiapkan COG Anda

Earth Engine membaca COG langsung dari Cloud Storage, hanya mengambil header dan ubin yang diperlukan komputasi, sehingga tata letak file menjadi penting. TIFF harus:

  • Berpetak, dengan dimensi petak persegi pangkat 2 dari 16x16 hingga 2048x2048. Sebaiknya gunakan 512x512 untuk performa terbaik.
  • Diatur agar semua Image File Directory (IFD) berada di awal.
  • Sertakan ringkasan pangkat 2, jika ada. Ringkasan tidak diperlukan, tetapi direkomendasikan untuk gambar yang lebih besar dari satu ubin.
  • Gunakan interleave BAND atau PIXEL (lihat file band tunggal versus multi-band untuk mengetahui konsekuensinya).

Untuk mengonversi gambar, gunakan driver COG GDAL, yang menghasilkan tata letak yang diperlukan (penempatan ubin, ringkasan, dan header) dalam satu langkah. Tambahkan OVERVIEW_RESAMPLING=NEAREST untuk data kategoris; defaultnya adalah CUBIC. Untuk rekomendasi kompresi, ringkasan, dan tata letak, lihat praktik terbaik untuk menyiapkan COG eksternal.

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

CLI Klasik

Hilangkan INTERLEAVE=BAND pada GDAL versi sebelum 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

Membuat manifes

Baik Anda mendaftarkan COG menggunakan library klien Python Earth Engine, alat command line earthengine, atau Earth Engine REST API, Anda harus menentukan manifes upload gambar yang menentukan tujuan aset, URI Cloud Storage, dan metadata band opsional. API dan alat command line merujuk ke aset yang didukung COG sebagai gambar eksternal (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal).

Contoh: Satu COG yang mendukung semua band Jika COG Anda berisi semua band (misalnya, RGB), manifes hanya memerlukan satu tileset:

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

Contoh: Beberapa COG (satu per band) Jika Anda memiliki file terpisah untuk band yang berbeda (misalnya, merah, hijau, dan biru dalam file terpisah):

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

Batasan manifes

Manifes untuk aset yang didukung COG memiliki batasan yang tidak berlaku untuk manifes penyerapan standar:

  • Bucket tunggal: Semua URI dalam manifes harus berada di bucket Cloud Storage yang sama.
  • Satu URI per sumber: Setiap ImageSource harus berisi tepat satu URI. Anda tidak dapat menggabungkan beberapa file menjadi satu sumber tileset. Untuk membuat mosaik beberapa scene COG, daftarkan setiap COG sebagai aset dan gabungkan menjadi ee.ImageCollection menggunakan .mosaic().
  • Tidak ada mask_bands: Kolom mask_bands tingkat teratas tidak didukung. Gunakan missingData dalam manifes atau pastikan TIFF Anda memiliki nilai nodata internal.
  • Tidak ada data_type dalam tileset: Jangan tentukan data_type di bagian tilesets; ini akan otomatis terdeteksi.
  • Tidak ada dimensions di sumber: Jangan tentukan dimensions di ImageSource.
  • Tidak ada subdataset_prefix / subdataset_suffix.
  • Tidak ada min_tile_area_ratio atau skip_metadata_read.

Mengirim permintaan pendaftaran

Anda dapat mengirimkan manifes ke Earth Engine menggunakan library klien Python Earth Engine, alat command line earthengine, atau REST API Earth Engine. Pilih metode yang paling sesuai dengan alur kerja Anda.

Library klien Python

Dalam skrip Python atau notebook Jupyter, gunakan library klien Python Earth Engine (ee.data) setelah melakukan inisialisasi project:

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

Alat command line

Di terminal, simpan manifes ke file bernama manifest.json dan jalankan perintah upload earthengine:

# 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

Untuk alur kerja otomatis tanpa library klien, kirim permintaan POST yang diotorisasi langsung ke endpoint REST API Earth Engine projects.image.importExternal (ditunjukkan di sini menggunakan Python):

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

Setelah dikirim, permintaan pendaftaran akan memulai operasi pengindeksan metadata ringan. Karena pendaftaran COG tidak menyalin data piksel, operasi ini biasanya selesai dalam hitungan detik.

Konfigurasi izin

Tidak seperti aset Earth Engine standar, data piksel COG tetap berada di Cloud Storage. Saat membagikan aset yang didukung COG kepada orang lain, Anda harus memberi mereka akses baca ke aset Earth Engine dan file Cloud Storage.

Memberikan izin bucket Cloud Storage

Kolaborator memerlukan izin untuk membaca file dari Cloud Storage.

Izin yang diperlukan:

  • storage.buckets.get (untuk mengambil metadata dan lokasi bucket)
  • storage.objects.get (untuk membaca data piksel)

Anda dapat memberikan izin ini menggunakan peran Cloud Storage standar berikut:

  • Storage Bucket Viewer (menyediakan storage.buckets.get untuk membaca metadata dan lokasi bucket)
  • Storage Object Viewer (menyediakan storage.objects.get untuk membaca data piksel)

Langkah-langkah untuk mengonfigurasi di Konsol Google Cloud:

  1. Buka Browser Cloud Storage.
  2. Klik nama bucket Anda.
  3. Pilih tab Izin.
  4. Klik GRANT ACCESS.
  5. Tambahkan alamat email kolaborator Anda (atau Grup Google, atau allUsers untuk akses publik).
  6. Tetapkan peran Storage Bucket Viewer dan Storage Object Viewer.
  7. Klik Simpan.

Membagikan aset Earth Engine

Bagikan aset itu sendiri menggunakan Earth Engine Asset Manager atau CLI. Lihat Panduan Pengelolaan Aset untuk mengetahui detailnya.

Memperbarui, mengganti, dan menghapus aset yang didukung COG

Aset yang didukung COG adalah pointer ke versi file tertentu di Cloud Storage, ditambah metadata (footprint, proyeksi, band, dan tata letak ringkasan) yang diindeks Earth Engine saat Anda mendaftarkannya. Earth Engine menyematkan versi file sehingga metadata ini tidak dapat menyimpang dari sinkronisasi dengan piksel, yang membuat pembaruan aset yang didukung COG berbeda dengan pembaruan aset standar.

Pembuatan objek

Saat Anda mendaftarkan COG, Earth Engine akan mencatat generasi (nomor versinya) objek Cloud Storage bersama dengan URI. Anda dapat melihat pembuatan yang disematkan dalam metadata aset; pembuatan tersebut muncul sebagai akhiran #<generation> pada 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']

Anda juga dapat menyematkan versi tertentu sendiri dengan menyertakan akhiran #<generation> dalam URI manifes saat mendaftarkan (atau mendaftarkan ulang) aset. Tanpa itu, Earth Engine akan membaca objek saat ini dan menyematkan generasi apa pun yang ditemukannya. Penyematan secara eksplisit berguna untuk melakukan roll back ke versi sebelumnya yang telah dipertahankan oleh bucket dengan pembuatan versi objek.

Jika Anda menimpa file di Cloud Storage, file tersebut akan mendapatkan pembuatan baru, dan jika Anda menghapusnya, pembuatan yang disematkan akan hilang. Bagaimanapun, pembacaan piksel aset akan gagal, kecuali jika pembuatan versi objek di bucket mempertahankan generasi lama, sehingga Earth Engine akan terus membaca piksel lama. Operasi metadata yang menggunakan data yang diindeks (seperti ee.data.getAsset(), bandNames(), dan pemfilteran koleksi) akan tetap berfungsi.

Memperbarui aset setelah mengubah filenya

Untuk mengarahkan aset yang ada ke versi baru filenya, daftarkan ulang aset tersebut dengan nama aset yang sama dan aktifkan penimpaan. Earth Engine membaca ulang header GeoTIFF, mengindeks ulang metadata, dan menyematkan generasi baru, dalam satu panggilan sinkron. Izin aset yang ada akan dipertahankan, tetapi properti, rentang waktu, dan nama band-nya berasal dari manifes baru, jadi sertakan apa pun yang sebelumnya Anda tetapkan dengan ee.data.updateAsset().

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Command line: earthengine upload external_image --force --manifest manifest.json
  • REST API: sertakan "overwrite": true sebagai kolom tingkat atas bersama "imageManifest" dalam isi permintaan projects.image.importExternal.

Anda tidak perlu menghapus aset terlebih dahulu, dan menghapusnya akan menjadi kontraproduktif: aset mandiri akan kehilangan izinnya, dan gambar dalam koleksi akan menghilang sebentar dari koleksi. Perhatikan bahwa ee.data.updateAsset() (projects.assets.patch) hanya dapat mengubah properti, rentang waktu, dan nama band; tidak dapat mengubah file yang ditunjuk oleh aset.

Siklus proses independen

Aset Earth Engine dan objek Cloud Storage dikelola secara terpisah:

  • Menghapus aset Earth Engine (earthengine rm atau ee.data.deleteAsset()) hanya akan menghapus data aset. File Anda di Cloud Storage tidak akan terpengaruh.
  • Menghapus file di Cloud Storage tidak akan menghapus aset; aset tersebut masih muncul dalam listingan dan dalam koleksinya (lihat pembuatan objek).

Menggunakan koleksi besar

Tidak ada penghapusan batch atau rekursif di Earth Engine API: setiap aset harus dihapus satu per satu, dan koleksi harus kosong sebelum dapat dihapus. earthengine rm -r akan menangani hal ini untuk Anda, tetapi akan menghapus satu per satu, sehingga koleksi dengan puluhan ribu gambar dapat memerlukan waktu berjam-jam untuk dihapus.

  • Untuk mengganti gambar koleksi, timpa gambar, bukan menghapusnya. Daftarkan ulang setiap gambar berdasarkan nama dengan mengaktifkan penimpaan (lihat di atas). Tindakan ini memerlukan satu permintaan per gambar, bukan dua, menjaga koleksi tetap terisi sepanjang waktu, dan menghindari penghapusan serta pembuatan ulang koleksi itu sendiri, yang merupakan tempat izinnya berada. Hapus hanya gambar yang tidak ada dalam set baru.
  • Untuk menghapus banyak aset, lakukan paralelisasi dari skrip. Cantumkan aset dengan ee.data.listAssets() (menggunakan tampilan BASIC, yang hanya menampilkan nama dan jenis, bukan metadata lengkap untuk setiap gambar) dan hapus aset tersebut dari kumpulan thread kecil. Permintaan aset berbagi batas kapasitas di seluruh project, jadi pertahankan konkurensi yang moderat (sekitar 10 worker) dan biarkan percobaan ulang bawaan library klien menangani respons 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)
    

    Koleksi hanya akan dihapus jika setiap gambar telah dihapus, sehingga kegagalan parsial akan membiarkannya tetap ada untuk dijalankan ulang.

    Pola yang sama berlaku untuk mendaftarkan banyak gambar: ganti ee.data.deleteAsset(asset_id) di helper dengan ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) dan petakan ke daftar manifes Anda. Meneruskan allow_overwrite=True bahkan pada operasi pertama membuat batch aman untuk dijalankan ulang setelah kegagalan parsial, karena aset apa pun yang telah dibuat akan diganti, bukan menyebabkan error.

Menggunakan aset terdaftar

Setelah terdaftar, aset yang didukung COG diakses dalam skrip Earth Engine seperti aset gambar standar yang diserap:

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

Untuk mendapatkan jawaban atas pertanyaan umum tentang izin, memperbarui file, dan mengelola koleksi besar, lihat bagian COG di FAQ.