Mendaftarkan aset Cloud Optimized GeoTIFF (COG)

Earth Engine mendukung aset yang didukung oleh GeoTIFF yang Dioptimalkan Cloud (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 gambar berperforma baik saat digunakan dalam koleksi, dengan performa yang sebanding dengan aset standar yang di-ingest (lihat ringkasan GeoTIFF yang dioptimalkan Cloud (COG)).

Prasyarat dan penyiapan Cloud Storage

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

1. Lokasi bucket (persyaratan ketat)

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

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

Jika bucket Anda ditempatkan di pusat data regional lainnya (seperti us-east4 atau europe-west1), Earth Engine akan menolak permintaan pendaftaran dan pembacaan.

2. Kelas penyimpanan dan penagihan

  • Sebaiknya gunakan kelas penyimpanan Standar. Standard Storage tidak memiliki aturan durasi penyimpanan minimum, sehingga mencegah penalti 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-Standar dari alat eksternal (seperti software GIS desktop) akan dikenai biaya pengambilan yang mahal.
  • Anda harus mengaktifkan penagihan di project Google Cloud untuk menggunakan GCS. Lihat Panduan Memulai Google Cloud Storage untuk memulai.

Langkah 1: Siapkan COG

File TIFF Anda harus dioptimalkan untuk cloud. TIFF harus:

  • Dibuat dalam petak, dengan dimensi petak: 256x256, 512x512, 1024x1024, atau 2048x2048. Sebaiknya gunakan 512x512 atau lebih tinggi untuk performa terbaik.
  • Diatur agar semua Direktori File Gambar (IFD) berada di awal.
  • Menyertakan ringkasan pangkat 2.
  • Menggunakan interleave BAND.

Anda dapat menggunakan GDAL untuk mengonversi gambar.

Menggunakan Driver COG GDAL (GDAL >= 3.1 direkomendasikan):

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Menggunakan driver GTiff standar:

Pertama, buat ringkasan pangkat 2 internal (menggunakan gdal raster overview add atau gdaladdo), lalu salin gambar dan ringkasan ke dalam tata letak COG yang dibuat dalam petak:

gdaladdo -r nearest in.tif 2 4 8 16 32  # or -r cubic for continuous/float data

gdal_translate in.tif out.tif \
  -co BIGTIFF=YES \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=16 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Langkah 2: Buat 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 Google Cloud Storage, dan metadata band opsional.

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, 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 }
  ]
}

Langkah 3: Kirim permintaan pendaftaran

Anda dapat mengirimkan manifes ke Earth Engine menggunakan library klien Python Earth Engine, alat command line earthengine, atau Earth Engine REST API. 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 menginisialisasi project Anda:

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. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
print(f"Asset registered: {result['name']}")

Alat command line

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

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Submit the external image upload task
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

REST API (Python)

Untuk alur kerja otomatis tanpa library klien, kirim permintaan yang diotorisasi POST langsung ke endpoint Earth Engine REST API 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 dikirimkan, permintaan pendaftaran akan memulai operasi pengindeksan metadata ringan. Karena pendaftaran COG tidak menyalin data piksel, operasi ini biasanya selesai dalam hitungan detik.

Batasan manifes untuk aset COG

Saat membuat manifes untuk aset yang didukung COG, perhatikan batasan ketat berikut (yang berbeda dengan manifes ingestion standar):

  • Satu bucket: Semua URI dalam manifes harus berada di bucket GCS yang sama.
  • Satu URI per sumber: Setiap ImageSource harus berisi tepat satu URI. Anda tidak dapat menggabungkan beberapa file menjadi satu sumber tileset. Untuk menggabungkan beberapa adegan COG, daftarkan setiap COG sebagai aset dan gabungkan ke dalam ee.ImageCollection menggunakan .mosaic().
  • Tidak ada mask_bands: mask_bands tingkat atas tidak didukung. Gunakan missingData dalam manifes atau pastikan TIFF Anda memiliki nilai nodata internal.
  • Tidak ada data_type di tileset: Jangan tentukan data_type di bagian tilesets ; data_type akan terdeteksi secara otomatis.
  • 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.

Langkah 4: Konfigurasi izin (penting untuk berbagi)

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

1. Memberikan izin bucket GCS

Kolaborator memerlukan izin untuk membaca file dari GCS.

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 (memberikan storage.buckets.get untuk membaca metadata dan lokasi bucket)
  • Storage Object Viewer (memberikan 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.

2. Membagikan aset Earth Engine

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

Mengelola generasi objek

Saat Anda mendaftarkan COG, Earth Engine akan menyimpan generasi (versi) tertentu dari objek GCS. Jika Anda memperbarui file di GCS, generasinya akan berubah.

  • Secara default, Earth Engine akan gagal memuat aset dan menampilkan error: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
  • Hal ini dirancang untuk mencegah metadata (seperti proyeksi atau footprint) menjadi tidak sinkron dengan piksel yang mendasarinya.

  • Praktik terbaik: Jika Anda perlu memperbarui data gambar yang mendasarinya, daftarkan sebagai aset baru atau jalankan kembali perintah upload dengan tanda --force, bukan menimpa file di tempat:

    earthengine --project your-project-id upload external_image --force --manifest manifest.json

Menggunakan aset terdaftar

Setelah terdaftar, aset yang didukung COG akan diakses dalam skrip Earth Engine seperti aset gambar yang di-ingest standar:

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