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
ImageSourceharus 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 menjadiee.ImageCollectionmenggunakan.mosaic(). - Tidak ada
mask_bands: Kolommask_bandstingkat teratas tidak didukung. GunakanmissingDatadalam manifes atau pastikan TIFF Anda memiliki nilai nodata internal. - Tidak ada
data_typedalam tileset: Jangan tentukandata_typedi bagiantilesets; ini akan otomatis terdeteksi. - Tidak ada
dimensionsdi sumber: Jangan tentukandimensionsdiImageSource. - Tidak ada
subdataset_prefix/subdataset_suffix. - Tidak ada
min_tile_area_ratioatauskip_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.getuntuk membaca metadata dan lokasi bucket) - Storage Object Viewer (menyediakan
storage.objects.getuntuk membaca data piksel)
Langkah-langkah untuk mengonfigurasi di Konsol Google Cloud:
- Buka Browser Cloud Storage.
- Klik nama bucket Anda.
- Pilih tab Izin.
- Klik GRANT ACCESS.
- Tambahkan alamat email kolaborator Anda (atau Grup Google,
atau
allUsersuntuk akses publik). - Tetapkan peran Storage Bucket Viewer dan Storage Object Viewer.
- 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": truesebagai kolom tingkat atas bersama"imageManifest"dalam isi permintaanprojects.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 rmatauee.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 tampilanBASIC, 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 respons429 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 denganee.data.startExternalImageIngestion(manifest, allow_overwrite=True)dan petakan ke daftar manifes Anda. Meneruskanallow_overwrite=Truebahkan 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.