Aset Earth Engine yang Didukung GeoTiff Cloud

Logo Colab Jalankan di Google Colab Logo GitHub Lihat sumber di GitHub

Earth Engine mendukung aset yang didukung oleh GeoTIFF (COG) yang dioptimalkan Cloud. Keuntungan aset yang didukung COG adalah kolom spasial dan metadata gambar akan diindeks pada waktu pembuatan aset, sehingga gambar akan berperforma lebih baik dalam koleksi. Performa aset yang didukung COG sebanding dengan aset yang diserap dalam kasus penggunaan umum.

Perhatikan bahwa satu aset dapat didukung oleh beberapa COG (misalnya, dapat ada satu COG per band). Namun, penggunaan banyak ubin COG untuk satu band tidak didukung.

(Atau, Earth Engine dapat langsung memuat gambar dari COG di Google Cloud Storage (pelajari lebih lanjut). Namun, gambar yang dimuat melalui ee.Image.loadGeoTIFF dan ditambahkan ke koleksi gambar akan memerlukan pembacaan GeoTiff untuk operasi pemfilteran pada koleksi.)

Untuk membuat aset yang didukung COG,

  1. Tempatkan file COG Anda ke bucket GCS (lihat di bawah untuk mengetahui region yang diizinkan).
  2. Menulis manifes upload gambar
  3. Gunakan utilitas command line earthengine untuk mengirim perintah upload:
earthengine upload external_image --manifest my_manifest.json

Contoh manifes gambar dengan satu Tileset

ImageManifest yang paling sederhana adalah ImageManifest dengan satu Tileset. Jika tidak ada band yang ditentukan, aset yang dihasilkan akan berisi semua band GeoTIFF dengan nama band yang dienkode dalam GeoTIFF (dalam hal ini, "vis-red", "vis-green", dan "vis-blue").

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)

Lebih dari satu Tileset

Anda dapat menentukan ImageManifest dengan lebih dari satu Tileset dengan setiap band aset yang dihasilkan didukung oleh salah satu band Tileset menggunakan kolom tilesetId dan tilesetBandIndex. Hal ini berguna jika band yang berbeda memiliki resolusi atau jenis data yang berbeda. Band dapat didaftarkan dalam urutan apa pun dari Tileset yang tersedia. Pada contoh di bawah:

  • "b4b3b2.tif" memiliki skala 10 m, sedangkan "b5b6b7" memiliki skala 20 m.
  • Urutan band aset yang dihasilkan dicampur dari COG input (misalnya, band output 0 berasal dari Tileset 0, sedangkan band output 1 berasal dari Tileset 1).
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)

Detail tentang aset yang didukung COG

Lokasi

Lokasi bucket Cloud Storage harus salah satu dari:

  • Multi-region AS
  • Setiap dual-region AS yang menyertakan US-CENTRAL1
  • Region US-CENTRAL1

Kelas penyimpanan

Kelas penyimpanan bucket harus berupa "Penyimpanan standar".

Izin untuk berbagi

ACL aset Earth Engine yang didukung COG dan data pokoknya dikelola secara terpisah. Saat membagikan aset yang didukung COG kepada kolaborator untuk dibaca, pemilik bertanggung jawab untuk memastikan bahwa akses baca diberikan ke aset Earth Engine dan file COG yang mendasarinya.

1. Memberikan izin bucket Google Cloud Storage untuk membaca

Agar kolaborator dapat membaca aset yang didukung COG, mereka harus memiliki akses baca terlebih dahulu ke file COG yang mendasarinya di bucket Google Cloud Storage. Tanpa izin ini, Earth Engine tidak akan dapat mengambil data untuk mereka. Jika data di Google Cloud Storage tidak terlihat oleh pengguna Earth Engine, Earth Engine akan menampilkan error dalam bentuk "Gagal memuat GeoTIFF di gs://my-bucket/my-object#123456" (dengan 123456 adalah pembuatan objek).

Secara khusus, kolaborator harus memiliki izin berikut:

  • storage.buckets.get di bucket (untuk mengambil metadata dan lokasi bucket, sehingga Earth Engine dapat me-resolve sumber aset dengan benar).
  • storage.objects.get di bucket (untuk membaca data aset yang didukung COG sebenarnya).

Izin ini diberikan oleh peran "Storage Legacy Bucket Reader" dan "Storage Legacy Object Reader", di antara lainnya.

Untuk menetapkan peran ini kepada kolaborator:

  1. Buka halaman izin bucket: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. Klik "BERIKAN AKSES"
  3. Tambahkan semua akun utama (misalnya, pengguna, grup, akun layanan) yang harus diberi akses baca.
  4. Tetapkan peran berikut:
    • "Storage Legacy Bucket Reader" (memberikan storage.buckets.get dan izin baca tingkat bucket lainnya).
    • "Storage Legacy Object Reader" (menyediakan storage.objects.get).
    • (Atau, Anda dapat membuat peran khusus baru hanya dengan izin storage.buckets.get dan storage.objects.get, lalu menetapkannya.)
  5. Simpan

2. Membagikan aset Earth Engine untuk dibaca

Setelah memastikan kolaborator Anda memiliki izin yang diperlukan pada bucket dan objek GCS yang mendasarinya, Anda juga harus membagikan aset Earth Engine itu sendiri. Untuk informasi selengkapnya tentang cara menetapkan izin aset Earth Engine, lihat panduan pengelolaan aset Earth Engine.

Generasi

Saat aset yang didukung COG dibuat, Earth Engine akan membaca metadata TIFF yang ditentukan dalam manifes dan membuat entri penyimpanan aset. Setiap URI yang terkait dengan entri tersebut dapat memiliki generasi. Lihat dokumen pembuatan versi objek untuk mengetahui detail tentang pembuatan. Jika generasi ditentukan, misalnya gs://foo/bar#123, Earth Engine akan menyimpan URI tersebut secara verbatim. Jika pembuatan tidak ditentukan, Earth Engine akan menyimpan URI tersebut dengan pembuatan TIFF pada saat ImportExternalImage dipanggil.

Artinya, jika TIFF yang berisi aset eksternal di GCS diperbarui (sehingga mengubah pembuatannya), Earth Engine akan menampilkan error "Gagal memuat GeoTIFF di gs://my-bucket/my-object#123456" karena objek yang diharapkan tidak ada lagi (kecuali jika bucket mengaktifkan beberapa versi objek). Kebijakan ini dirancang untuk menjaga metadata aset tetap sinkron dengan metadata objek.

Konfigurasi

Dalam hal cara mengonfigurasi COG, TIFF HARUS:

  • Disusun bersusun, dengan dimensi ubin:

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

  • Diatur agar semua IFD berada di awal.

Untuk performa terbaik:

  • Gunakan dimensi kartu 512x512 atau lebih tinggi.
  • Sertakan ringkasan kekuatan 2.

Bergantung pada kasus penggunaan yang Anda inginkan, opsi pembuatan 'INTERLEAVE' dapat memengaruhi performa. Sebaiknya gunakan interleave BAND dalam semua situasi.

Lihat halaman ini untuk mengetahui detail selengkapnya tentang konfigurasi yang dioptimalkan.

Perintah gdal_translate berikut akan mengonversi raster menjadi GeoTIFF yang dioptimalkan Cloud, yang dikompresi zstd dan interleaved band yang akan berperforma baik di Earth Engine:

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

Anda mungkin dapat mengurangi ukuran file output lebih lanjut dengan menentukan prediktor (-co PREDICTOR=2 untuk jenis data bilangan bulat dan -co PREDICTOR=3 untuk jenis data floating point).

Untuk pengguna dengan GDAL >= 3.11, driver COG dapat menghasilkan file tanpa harus khawatir membuat dan mempertahankan ringkasan.

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 \

Membuat Aset Berbasis GeoTiff Cloud menggunakan REST API

Catatan: REST API berisi fitur baru dan lanjutan yang mungkin tidak cocok untuk semua pengguna. Jika Anda baru menggunakan Earth Engine, sebaiknya mulai dengan panduan JavaScript.

Untuk membuat aset yang didukung COG menggunakan REST API, buat permintaan POST ke endpoint ImportExternalImage Earth Engine. Seperti yang ditunjukkan di bawah ini, permintaan ini harus diberi otorisasi untuk membuat aset di folder pengguna Anda.

Memulai sesi yang diotorisasi

Agar dapat membuat aset Earth Engine di folder pengguna, Anda harus dapat melakukan autentikasi sebagai diri sendiri saat membuat permintaan. Anda dapat menggunakan kredensial dari pengautentikasi Earth Engine untuk memulai AuthorizedSession. Kemudian, Anda dapat menggunakan AuthorizedSession untuk mengirim permintaan ke Earth Engine.

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

Isi permintaan

Isi permintaan adalah instance ImageManifest. Di sinilah jalur ke COG ditentukan, beserta properti berguna lainnya.

Lihat panduan ini untuk mengetahui detail tentang cara mengonfigurasi ImageManifest. Anda dapat menentukan satu atau beberapa Tileset dengan setiap dukungan satu atau beberapa band. Untuk ImportExternalImage, maksimal satu ImageSource didukung per Tileset.

Lihat dokumen ini untuk mengetahui detail tentang cara mengekspor COG.

Kirim permintaan

Buat permintaan POST ke endpoint projects.images.importExternal Earth Engine.

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