Jika Anda memerlukan fleksibilitas yang lebih besar saat mengupload gambar ke Google Earth Engine (EE) daripada yang disediakan oleh
UI Editor Kode
atau perintah upload
dari
alat command line'earthengine', Anda dapat melakukannya dengan mendeskripsikan upload gambar menggunakan file JSON yang dikenal sebagai "manifes"
dan menggunakan perintah upload image --manifest
dari alat command line.
Lihat contoh lengkap di notebook Colab ini yang menunjukkan cara mengupload ubin gambar sebagai satu aset menggunakan manifes.
Penyiapan satu kali
- Upload manifes hanya berfungsi dengan file yang berada di Google Cloud Storage. Untuk mulai menggunakan Google Cloud Storage, buat project Google Cloud, jika Anda belum memilikinya. Perhatikan bahwa penyiapan memerlukan penentuan kartu kredit untuk penagihan. EE sendiri tidak menagih siapa pun saat ini, tetapi mentransfer file ke Google Cloud Storage sebelum menguploadnya ke EE akan dikenai biaya kecil. Untuk ukuran data upload standar (puluhan atau ratusan gigabyte), biayanya akan cukup rendah.
- Dalam project Anda, aktifkan Cloud Storage API dan buat bucket.
- Instal klien Earth Engine Python. Library ini mencakup alat command line
earthengine
, yang akan kita gunakan untuk mengupload data. - Untuk upload otomatis, sebaiknya gunakan akun layanan Google Cloud yang terkait dengan project Anda. Anda tidak memerlukan akun layanan untuk pengujian, tetapi jika ada waktu, mulailah membiasakan diri untuk menggunakannya.
File sumber yang sangat besar (100 GB atau lebih) mungkin diupload lebih cepat jika dibagi menjadi beberapa ubin.
ID dan nama aset
Untuk aset milik project Cloud, gunakan konvensi ini untuk nama aset:
projects/some-project-id/assets/some-asset-id
.
Mempelajari nama aset untuk project lama dan aset milik pengguna
Untuk project lama, nama aset dalam manifes harus sedikit berbeda dengan ID aset yang terlihat di tempat lain di Earth Engine. Untuk mengupload aset yang ID asetnya diawali dengan
users/some_user
atau projects/some_project
, nama aset dalam
manifes harus memiliki string projects/earthengine-legacy/assets/
di awal
ID. Misalnya, ID aset EE users/username/my_geotiff
harus diupload menggunakan nama projects/earthengine-legacy/assets/users/username/my_geotiff
.
Ya, ini berarti ID seperti projects/some_projects/some_asset
akan
dikonversi menjadi nama dengan projects
disebutkan dua kali:
projects/earthengine-legacy/assets/projects/some_projects/some_asset
.
Hal ini membingungkan, tetapi diperlukan untuk mematuhi standar Google Cloud API.
Menggunakan manifes
Manifes dasar ditampilkan dalam blok kode berikut. Fungsi ini mengupload file bernama
small.tif
dari bucket Google Cloud Storage bernama
gs://earthengine-test
.
{ "name": "projects/some-project-id/assets/some-asset-id", "tilesets": [ { "sources": [ { "uris": [ "gs://earthengine-test/small.tif" ] } ] } ] }
Untuk menggunakannya, simpan ke file bernama manifest.json
dan jalankan:
earthengine upload image --manifest /path/to/manifest.json
(File gs://earthengine-test/small.tif
ada dan dapat dibaca oleh publik. Anda dapat menggunakannya untuk pengujian.)
Kumpulan Kartu
Struktur manifes JSON yang agak rumit diperlukan untuk memberikan fleksibilitas yang memadai untuk mengatasi tantangan upload yang umum: cara mendeskripsikan semua kemungkinan cara menggabungkan piksel dari beberapa file sumber menjadi satu aset. Secara khusus, ada dua cara independen untuk mengelompokkan file:
- Mosaik. Terkadang beberapa file mewakili beberapa ubin (misalnya, setiap ubin adalah persegi 1x1 derajat). File tersebut harus dibuat mosaik (digabungkan) ke dalam band yang sama di aset EE.
- Pisahkan band. Terkadang, beberapa file mewakili beberapa band. File tersebut harus ditumpuk bersama sebagai band dalam aset EE.
(Kedua cara tersebut mungkin harus digunakan secara bersamaan, tetapi itu adalah situasi yang jarang terjadi.)
Untuk menjelaskan opsi ini, manifes memperkenalkan konsep tileset. Satu tileset sesuai dengan satu sumber GDAL. Oleh karena itu, semua sumber dalam satu tileset harus memiliki struktur GDAL yang sama (jumlah dan jenis band, proyeksi, transformasi, nilai yang hilang). Karena sumber GDAL dapat memiliki beberapa band, satu tileset dapat berisi data untuk beberapa band EE.
Untuk penyerapan mosaik, manifes akan terlihat seperti ini:
{ "name": "projects/some-project-id/assets/some-asset-id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/N30W22.tif" ] }, { "uris": [ "gs://bucket/N31W22.tif" ] } ] } ] }
Untuk band terpisah, manifes akan terlihat
seperti ini (Anda juga perlu menambahkan bagian bands
seperti yang dijelaskan di bawah):
{ "name": "projects/some-project-id/assets/some-asset-id", "bands": ..., "tilesets": [ { "id": "tileset_for_band1", "sources": [ { "uris": [ "gs://bucket/band1.tif" ] } ] }, { "id": "tileset_for_band2", "sources": [ { "uris": [ "gs://bucket/band2.tif" ] } ] } ] }
Perhatikan bahwa dalam kasus band terpisah, kita harus memberikan ID tileset yang berbeda untuk setiap tileset agar lebih jelas. ID tileset dapat berupa string arbitrer - string ini tidak disimpan dalam aset yang diupload. ID set ubin hanya digunakan dalam proses transfer untuk membedakan set ubin yang ditumpuk satu sama lain.
Band
Konsep penting kedua adalah mencocokkan file sumber dengan band aset EE.
Hal ini dilakukan menggunakan bagian bands
dalam manifes.
Bagian bands
dapat dihilangkan, dalam hal ini band dibuat terlebih dahulu
dari file dalam tileset pertama, lalu dari tileset berikutnya, dan seterusnya.
Secara default, band diberi nama "b1", "b2", dll. Untuk mengganti nama band default, sertakan
bagian "band" di bagian akhir, seperti ini:
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/rgb.tif" ] } ] } ], "bands": [ { "id": "R", "tilesetBandIndex": 0 }, { "id": "G", "tilesetBandIndex": 1 }, { "id": "B", "tilesetBandIndex": 2 } ] }
Jumlah band EE harus sama dengan jumlah total band di semua set kartu.
Jika tidak ingin menyerap semua band dari file, Anda dapat menggunakan kolom tilesetBandIndex
untuk menunjukkan band GDAL mana yang harus diserap.
Band pertama memiliki tilesetBandIndex 0.
Contoh:
Misalkan file sumber memiliki empat band: "tmin", "tmin_error", "tmax", "tmax_error". Kita hanya ingin memasukkan "tmin" dan "tmax". Bagian manifes yang relevan akan terlihat seperti ini:
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "id": "temperature", "sources": [ { "uris": [ "gs://bucket/temperature.tif" ] } ] } ], "bands": [ { "id": "tmin", "tilesetBandIndex": 0, "tilesetId": "temperature" }, { "id": "tmax", "tilesetBandIndex": 2, "tilesetId": "temperature" } ] }
Mask band
Masking band dikontrol oleh komponen maskBands
dari manifes.
Tiga kemungkinan konfigurasi mask didukung (tetapi band mask selalu dianggap
sebagai band terakhir dalam file tertentu).
- Sembunyikan semua band data dalam file yang sama.
- Topeng untuk semua band data yang berasal dari semua file lainnya.
- Menyamarkan beberapa band data.
1. Kasus yang paling umum adalah satu GeoTIFF yang band terakhirnya digunakan sebagai mask untuk band lainnya. Ini hanya berfungsi untuk GeoTIFF jenis Byte. Gunakan manifes berikut:
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "id": "data_tileset", "sources": [ { "uris": [ "gs://bucket/data_file.tif" ] } ] } ], "bands": [ { "id": "data_band", "tilesetId": "data_tileset" }, { "id": "qa_band", "tilesetId": "data_tileset" } ], "maskBands": [ { "tilesetId": "data_tileset" } ] }
2. Untuk menggunakan GeoTIFF mask sebagai mask untuk semua band di GeoTIFF lain, gunakan manifes berikut:
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "id": "data_tileset", "sources": [ { "uris": [ "gs://bucket/data_file.tif" ] } ] }, { "id": "mask_tileset", "sources": [ { "uris": [ "gs://bucket/mask_file.tif" ] } ] } ], "bands": [ { "id": "data_band", "tilesetId": "data_tileset" }, { "id": "qa_band", "tilesetId": "data_tileset" } ], "maskBands": [ { "tilesetId": "mask_tileset" } ] }
3. Untuk menggunakan GeoTIFF sebagai mask untuk band tertentu dalam file lain, gunakan
manifes berikut (perbedaan dengan kasus sebelumnya adalah kolom
bandIds
di maskBands
ditetapkan):
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "id": "data_tileset", "sources": [ { "uris": [ "gs://bucket/data_file.tif" ] } ] }, { "id": "mask_tileset", "sources": [ { "uris": [ "gs://bucket/mask_file.tif" ] } ] } ], "bands": [ { "id": "data_band", "tilesetId": "data_tileset" }, { "id": "qa_band", "tilesetId": "data_tileset" } ], "maskBands": [ { "tilesetId": "mask_tileset", "bandIds": ["data_band"] } ] }
Pada contoh terakhir, kita menggunakan dua band dari tileset data_tileset
, tetapi hanya menerapkan mask ke salah satu band (data_band
), seperti yang ditetapkan oleh kolom bandIds
dari satu-satunya objek daftar maskBands
yang disediakan.
Perhatikan bahwa hanya band terakhir dari tileset yang disebutkan dalam maskBands
yang digunakan sebagai
band mask.
Kebijakan piramida
Saat membuat
piramida gambar
selama proses transfer, Earth Engine harus berulang kali mengurangi petak 2x2 piksel menjadi satu piksel,
yang mengubah nilai piksel dengan cara tertentu. Secara default, nilai piksel dirata-ratakan, yang
merupakan hal yang tepat untuk dilakukan dalam sebagian besar kasus saat band raster mewakili data yang kurang lebih
kontinu. Namun, ada dua situasi saat mengandalkan default
akan menghasilkan hasil yang salah, dalam hal ini kolom pyramidingPolicy
di
definisi band harus ditetapkan (jika tidak ditetapkan, nilainya diasumsikan sebagai "MEAN"
secara default).
Untuk klasifikasi gambar raster (misalnya, klasifikasi tutupan lahan), cara paling logis untuk membuat piramida piksel adalah mengambil sebagian besar dari empat nilai untuk menghasilkan nilai berikutnya. Hal ini dilakukan menggunakan kebijakan piramida "MODE":
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/landcover.tif" ] } ] } ], "bands": [ { "id": "landcover", "pyramidingPolicy": "MODE" } ] }
Untuk band raster yang tidak memiliki "MEAN" atau "MODE" yang masuk akal (misalnya, piksel bitpack), kebijakan piramida "SAMPLE" harus digunakan. "SAMPLE" selalu mengambil nilai piksel kiri atas dari setiap petak 2x2. Contoh berikut menetapkan kebijakan piramida "MEAN" ke band yang mewakili variabel kontinu ("NDVI") dan "SAMPLE" ke band "QA" data.
{ "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/ndvi.tif" ] } ] } ], "bands": [ { "id": "NDVI", "tilesetBandIndex": 0, "pyramidingPolicy": "MEAN" }, { "id": "QA", "tilesetBandIndex": 1, "pyramidingPolicy": "SAMPLE" } ] }
Waktu mulai dan berakhir
Semua aset harus menentukan waktu mulai dan waktu berakhir untuk memberikan lebih banyak konteks ke data, terutama jika aset disertakan dalam koleksi. Kolom ini tidak wajib, tetapi sebaiknya gunakan kolom ini jika memungkinkan.
Waktu mulai dan waktu berakhir biasanya berarti waktu pengamatan, bukan waktu file sumber dibuat.
Waktu akhir diperlakukan sebagai batas eksklusif untuk memudahkan. Misalnya, untuk aset yang berlangsung tepat satu hari, gunakan tengah malam dari dua hari berturut-turut (misalnya, 1980-01-31T00:00:00 dan 1980-02-01T00:00:00) untuk waktu mulai dan waktu berakhir. Jika aset tidak memiliki durasi, tetapkan waktu berakhir sama dengan waktu mulai. Merepresentasikan waktu dalam manifes sebagai string ISO 8601. Sebaiknya asumsikan bahwa waktu berakhir bersifat eksklusif (misalnya, tengah malam hari berikutnya untuk aset harian) untuk menyederhanakan nilai tanggal.
Contoh:
{ "name": "projects/some-project-id/assets/some-asset-id", "tilesets": [ { "sources": [ { "uris": [ "gs://bucket/img_20190612.tif" ] } ] } ], "startTime": "1980-01-31T00:00:00Z", "endTime": "1980-02-01T00:00:00Z" }
Referensi struktur manifes
Struktur JSON berikut mencakup semua kemungkinan kolom manifes upload gambar. Temukan definisi kolom di bagian Definisi kolom manifes berikut.
{ "name": <string>, "tilesets": [ { "dataType": <string>, "id": <string>, "crs": <string>, "sources": [ { "uris": [ <string> ], "affineTransform": { "scaleX": <double>, "shearX": <double>, "translateX": <double>, "shearY": <double>, "scaleY": <double>, "translateY": <double> } } ] } ], "bands": [ { "id": <string>, "tilesetId": <string>, "tilesetBandIndex": <int32>, "missingData": { "values": [<double>] }, "pyramindingPolicy": <string> } ], "maskBands": [ { "tilesetId": <string>, "bandIds": [ <string> ] } ], "footprint": { "points": [ { "x": <double>, "y": <double> } ], "bandId": <string> }, "missingData": { "values": [<double>] }, "pyramidingPolicy": <string>, "uriPrefix": <string>, "startTime": { "seconds": <integer> }, "endTime": { "seconds": <integer> }, "properties": { <unspecified> } }
Definisi kolom manifes
nama
string
Nama aset yang akan dibuat.
name
memiliki format "projects/*/assets/**"
(misalnya, "projects/earthengine-legacy/assets/users/USER/ASSET").
set kartu
list
Daftar kamus yang menentukan properti untuk set kartu.
Lihat kolom elemen kamus tilesets
berikut
untuk mengetahui informasi selengkapnya.
tilesets[i].dataType
string
Menentukan jenis data numerik dari data. Default-nya adalah jenis yang dilaporkan GDAL, sehingga tidak perlu ditentukan.
Jenis data | Nilai |
---|---|
Tidak ditentukan | "DATA_TYPE_UNSPECIFIED" |
Bilangan bulat 8-bit yang telah ditandai | "INT8" |
Bilangan bulat 8-bit tanpa tanda | "UINT8" |
Bilangan bulat 16-bit yang telah ditandai | "INT16" |
Bilangan bulat 16-bit tanpa tanda | "UINT16" |
Bilangan bulat 32-bit bertanda | "INT32" |
Bilangan bulat 32-bit tanpa tanda | "UINT32" |
Float 32-bit | "FLOAT32" |
Float 64-bit | "FLOAT64" |
tilesets[i].id
string
ID tileset. Harus unik di antara tileset yang ditentukan dalam manifes aset. ID ini dihapus selama langkah pemrosesan; ID ini hanya digunakan untuk menautkan tileset ke band. String kosong adalah ID yang valid.
tilesets[i].crs
string
Sistem referensi koordinat petak piksel, yang ditentukan sebagai kode standar jika memungkinkan (misalnya, kode EPSG), dan dalam format WKT jika tidak.
tilesets[i].sources
list
Daftar kamus yang menentukan properti file gambar dan
sidecar-nya. Lihat kolom elemen kamus sources
berikut
untuk mengetahui informasi selengkapnya.
tilesets[i].sources[j].uris
list
Daftar URI data yang akan diserap. Hanya URI Google Cloud Storage yang didukung. Setiap URI harus ditentukan dalam format berikut:
gs://bucket-id/object-id
.
Objek utama harus berupa elemen pertama dalam daftar, dan sidecar
dicantumkan setelahnya. Setiap URI diawali dengan
ImageManifest.uriPrefix
jika ditetapkan.
tilesets[i].sources[j].affineTransform
dictionary
Transformasi afin opsional. Hanya boleh ditentukan jika data dari
uris
(termasuk sidecar apa pun) tidak memadai untuk menempatkan piksel.
Disediakan sebagai kamus dengan kunci berikut:
"scaleX", "shearX", "translateX", "shearY", "scaleY", "translateY".
Lihat
referensi ini untuk informasi selengkapnya.
Contoh kunci dan nilai:
{ "scaleX": 0.1, "shearX": 0.0, "translateX": -180.0, "shearY": 0.0, "scaleY": -0.1, "translateY": 90.0 }
band
list
Daftar kamus yang menentukan properti satu band yang bersumber dari tileset.
Perhatikan bahwa urutan band aset sama dengan urutan bands
.
Lihat kolom elemen kamus bands
berikut untuk mengetahui informasi selengkapnya.
bands[i].id
string
ID (nama) band.
bands[i].tilesetId
string
ID tileset yang sesuai dengan band.
bands[i].tilesetBandIndex
int32
Indeks band berbasis nol dari tileset yang sesuai dengan band.
bands[i].missingData.values
list
Daftar nilai (jenis ganda) yang tidak mewakili data dalam band.
bands[i].pyramidingPolicy
string
Kebijakan piramida. Lihat link ini untuk informasi selengkapnya. Opsi mencakup:
- "MEAN" (default)
- "MODE"
- "SAMPLE"
maskBands
list
Daftar kamus yang menentukan properti satu band mask yang bersumber dari tileset.
Maksimal 1 band masker dapat disediakan.
Lihat kolom elemen kamus maskBands
berikut untuk mengetahui informasi selengkapnya.
maskBands[i].tilesetId
string
ID tileset yang sesuai dengan band mask. Band terakhir dari tileset selalu digunakan sebagai band mask.
maskBands[i].bandIds
list of strings
Daftar ID band yang berlaku untuk band mask. Jika kosong, band mask akan diterapkan ke semua band dalam aset. Setiap band hanya boleh memiliki satu band mask yang sesuai.
jejak
dictionary
Kamus yang menentukan properti jejak semua piksel yang valid dalam gambar.
Jika kosong, jejak default adalah seluruh gambar. Lihat
kolom elemen kamus footprint
berikut untuk mengetahui informasi selengkapnya.
footprint.points
list
Daftar titik yang menentukan jejak semua piksel yang valid dalam gambar. Titik ditentukan oleh kamus dengan kunci "x" dan "y" yang memiliki nilai float. Daftar
titik adalah untuk mendeskripsikan cincin yang membentuk bagian luar poligon sederhana yang harus berisi
pusat semua piksel gambar yang valid. Ini harus berupa cincin linear: titik
terakhir harus sama dengan titik pertama. Koordinat berada dalam proyeksi
band yang ditentukan oleh bandId
.
Catatan: Gunakan koordinat non-bilangan bulat seperti tengah setiap piksel karena
footprint
diambil untuk menyertakan piksel jika piksel (persegi panjang 1x1)
memotong jejak. Untuk menghindari pemilihan piksel
tetangga secara tidak sengaja, jangan gunakan koordinat bernilai bilangan bulat, karena itu adalah
batas antara piksel. Menggambar jejak di sepanjang pusat piksel
mencegah penyertaan piksel yang tidak diinginkan, yang dapat menyebabkan error saat piksel yang dimaksud
berbatasan dengan batas peta seperti antimeridian atau kutub.
Misalnya, untuk gambar 2x2 dengan keempat piksel yang valid, berikut adalah salah satu kemungkinan cincin:
[ { "x": 0.5, "y": 0.5 }, { "x": 0.5, "y": 1.5 }, { "x": 1.5, "y": 1.5 }, { "x": 1.5, "y": 0.5 }, { "x": 0.5, "y": 0.5 } ]
footprint.bandId
string
ID band yang CRS-nya menentukan koordinat jejak. Jika kosong, band pertama akan digunakan.
missingData.values
list
Daftar nilai (jenis ganda) yang tidak merepresentasikan data di semua band gambar. Berlaku untuk
semua band yang tidak menentukan missingData
-nya sendiri.
pyramidingPolicy
string
Kebijakan piramida. Jika tidak ditentukan, kebijakan "MEAN" akan diterapkan secara default. Berlaku untuk semua band yang tidak menentukan bandnya sendiri. Lihat link ini untuk informasi selengkapnya. Opsi mencakup:
- "MEAN" (default)
- "MODE"
- "SAMPLE"
uriPrefix
string
Awalan opsional yang ditambahkan ke semua uris
yang ditentukan dalam manifes.
startTime
integer
Stempel waktu yang terkait dengan aset, jika ada. Hal ini biasanya sesuai dengan waktu pengambilan gambar satelit. Untuk aset yang sesuai dengan interval waktu, seperti nilai rata-rata selama sebulan atau setahun, stempel waktu ini sesuai dengan awal interval tersebut. Ditentukan sebagai detik dan (opsional) nanodetik sejak epoch (1970-01-01). Diasumsikan berada di zona waktu UTC.
endTime
integer
Untuk aset yang sesuai dengan interval waktu, seperti nilai rata-rata selama sebulan atau setahun, stempel waktu ini sesuai dengan akhir interval tersebut (eksklusif). Ditentukan sebagai detik dan (opsional) nanodetik sejak epoch (1970-01-01). Diasumsikan berada di zona waktu UTC.
properti
dictionary
Kamus datar arbitrer dari pasangan nilai kunci. Kunci harus berupa string dan nilai dapat berupa angka atau string. Nilai daftar belum didukung untuk aset yang diupload pengguna.
Batasan
Ukuran manifes JSON
Batas ukuran file manifes JSON adalah 10 MB. Jika Anda memiliki banyak file untuk diupload,
pertimbangkan cara untuk mengurangi jumlah karakter yang diperlukan untuk mendeskripsikan set data. Misalnya,
gunakan kolom uriPrefix
untuk menghilangkan
kebutuhan untuk memberikan jalur bucket Google Cloud untuk setiap URI dalam
daftar uris
. Jika pengurangan ukuran lebih lanjut
diperlukan, coba perpendek nama file.
Format file gambar
Setiap file gambar harus berupa gambar TIFF. Jika CRS tidak ditentukan dalam manifes, file harus berupa GeoTIFF dengan CRS tersemat.
File TIFF dapat dikompresi dengan DEFLATE, JPEG-XL/JXL, LERC, LERC_DEFLATE, LERC_ZSTD, LZMA, LZW, WEBP, atau ZSTD.
Rekomendasi untuk mendapatkan pengalaman upload terbaik untuk file besar:
- Pilihan terbaik: ZSTD menawarkan keseimbangan kecepatan dan kompresi yang baik.
- Hindari: LZMA dapat sangat lambat meskipun kompresinya bagus.
- File yang tidak dikompresi: Akan menghasilkan file yang lebih besar dan waktu upload yang lebih lama.
- Kompresi lossy (misalnya, JPEG): Dapat mengubah nilai piksel. Gunakan kompresi lossless (misalnya, DEFLATE, LZMA, LZW, ZSTD) kecuali jika Anda memahami potensi dampaknya terhadap data Anda.