Aset Earth Engine yang Didukung GeoTiff Cloud

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

Notebook ini menunjukkan cara membuat aset Earth Engine 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

Metadata bucket harus dapat diakses agar Earth Engine dapat menentukan lokasinya. Pengguna yang memanggil harus memiliki izin storage.buckets.get di bucket. Izin tersebut diberikan oleh peran "Storage Legacy Bucket Reader", di antara peran lainnya.

Untuk menetapkan peran ini: 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 yang harus diberi akses 4. Tetapkan peran "Storage Legacy Bucket Reader" (atau, buat peran kustom baru hanya dengan izin storage.buckets.get dan tetapkan peran tersebut) 5. Simpan

Kelas penyimpanan

Kelas penyimpanan bucket harus berupa "Penyimpanan standar".

Izin

ACL aset Earth Engine yang didukung COG dan data pokok dikelola secara terpisah. Jika aset yang didukung COG dibagikan di Earth Engine, pemiliknya bertanggung jawab untuk memastikan bahwa data di GCS dibagikan kepada pihak yang sama. Jika data tidak terlihat, Earth Engine akan menampilkan error dalam bentuk "Gagal memuat GeoTIFF di gs://my-bucket/my-object#123456" (123456 adalah pembuatan objek).

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 integral dan -co PREDICTOR=3 untuk jenis data floating point).

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