使用 Cloud 地理 TIF 格式的 Earth Engine 資產

Colab 標誌 在 Google Colab 中執行 GitHub 標誌 在 GitHub 上查看來源

Earth Engine 支援由 Cloud Optimized GeoTIFF (COG) 支援的資產。COG 支援的資產的好處在於，圖片的空間和中繼資料欄位會在資產建立時建立索引，讓圖片在集合中的效能更佳。在一般用途中，COG 支援素材資源的成效與擷取的素材資源相當。

請注意，單一資產可由多個 COG 支援 (例如，每個頻帶可有一個 COG)。不過，我們不支援為單一頻帶使用多個 COG 圖塊。

(或者，Earth Engine 可以直接從 Google Cloud Storage 中的 COG 載入圖片 (瞭解詳情)。不過，如果是透過 ee.Image.loadGeoTIFF 載入圖片並新增至圖片集合，則需要讀取 GeoTiff，才能對集合執行篩選作業。)

如要建立 COG 擔保資產，請按照下列步驟操作：

  1. 將 COG 檔案放入 GCS 值區 (請參閱下方允許的區域)。
  2. 編寫圖片上傳資訊清單
  3. 使用 earthengine 指令列公用程式傳送上傳指令：
earthengine upload external_image --manifest my_manifest.json

含有一個 Tileset 的圖片資訊清單範例

最簡單的 ImageManifest 只有一個 Tileset。如果未指定任何頻帶，產生的資產將包含 GeoTIFF 的所有頻帶，並且在 GeoTIFF 中編碼頻帶名稱 (在本例中為「vis-red」、「vis-green」和「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)

多個 Tileset

您可以指定具有多個 Tileset 的 ImageManifest，其中產生的資產的每個頻帶都由 Tileset 的其中一個頻帶支援，並使用 tilesetId 和 tilesetBandIndex 欄位。這在不同頻帶具有不同解析度或資料類型的情況下非常實用。您可以從任何可用的 Tileset 中，以任意順序列出頻帶。在以下範例中：

  • 「b4b3b2.tif」的比例尺為 10 公尺，而「b5b6b7」的比例尺為 20 公尺。
  • 產生的資產頻帶順序會從輸入 COG 混合而成 (例如輸出頻帶 0 來自 Tileset 0，而輸出頻帶 1 來自 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)

COG 擔保資產的詳細資料

位置

Cloud Storage 值區位置必須為下列其中一個：

  • 美國多個區域
  • 任何包含 US-CENTRAL1 的美國雙區域
  • 區域：US-CENTRAL1

儲存空間級別

值區的儲存空間級別必須是「Standard Storage」。

共用權限

COG 支援的 Earth Engine 資產和基礎資料的 ACL 會分別管理。與協作者分享 COG 支援資產以供讀取時，擁有者有責任確保 Earth Engine 資產和底層 COG 檔案都授予讀取權限。

1. 授予 Google Cloud Storage 值區的讀取權限

協作者必須先具備 Google Cloud Storage 值區中基礎 COG 檔案的讀取權限，才能讀取 COG 支援的素材資源。如果沒有這些權限，Earth Engine 就無法擷取相關資料。如果 Earth Engine 使用者無法查看 Google Cloud Storage 中的資料，Earth Engine 會傳回「Failed to load the GeoTIFF at gs://my-bucket/my-object#123456」(123456 是物件產生的時間) 這類錯誤訊息。

具體而言，協作者必須具備下列權限：

  • 值區上的 storage.buckets.get (用於擷取值區中繼資料和位置，讓 Earth Engine 正確解析資產來源)。
  • 在資料集上執行 storage.objects.get (讀取實際的 COG 支援素材資源資料)。

這些權限分別由 「Storage Legacy Bucket Reader」和 「Storage Legacy Object Reader」 等角色提供。

如要將這些角色指派給協作者，請按照下列步驟操作：

  1. 前往值區權限頁面： https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. 按一下「授予存取權」
  3. 新增應授予讀取權的主體 (例如使用者、群組、服務帳戶)。
  4. 指派下列角色：
    • 「Storage 舊版值區讀取者」 (提供 storage.buckets.get 和其他值區層級讀取權限)。
    • 「Storage 舊版物件讀取器」 (提供 storage.objects.get)。
    • (或者，您也可以只建立具備 storage.buckets.get 和 storage.objects.get 權限的新自訂角色，然後指派該角色)。
  5. 儲存

2. 共用 Earth Engine 資產以供讀取

確認協作者擁有基礎 GCS bucket 和物件的必要權限後，您也必須分享 Earth Engine 資產本身。如要進一步瞭解如何設定 Earth Engine 素材資源權限，請參閱 Earth Engine 素材資源管理指南。

產生

建立 COG 支援資產時，Earth Engine 會讀取資訊清單中指定的 TIFF 中繼資料，並建立資產商店項目。與該項目相關聯的每個 URI 都可以有一個世代。如要進一步瞭解世代，請參閱物件版本管理說明文件。如果指定了世代，例如 gs://foo/bar#123，Earth Engine 會逐字儲存該 URI。如果未指定世代，Earth Engine 會在呼叫 ImportExternalImage 時，將該 URI 與 TIFF 的世代一併儲存。

也就是說，如果 GCS 中包含外部資產的任何 TIFF 更新 (因此變更其世代)，Earth Engine 會傳回「無法載入 gs://my-bucket/my-object#123456 的 GeoTIFF」錯誤，因為預期的物件已不存在 (除非值區啟用多個物件版本)。這項政策旨在讓資產中繼資料與物件中繼資料保持同步。

設定

在設定 COG 的方式方面，TIFF 必須符合以下條件：

  • 平鋪，其中圖塊尺寸為：

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

  • 並安排所有 IFD 位於開頭。

為確保最佳效能，請注意下列事項：

  • 使用 512x512 以上大小的圖塊。
  • 納入 2 個總覽的功率。

視用途而定，'INTERLEAVE' 建立選項可能會影響效能。我們建議在所有情況下都使用 BAND 交錯。

如要進一步瞭解最佳化設定，請參閱這個頁面。

下列 gdal_translate 指令會將光柵轉換為帶狀交錯、zstd 壓縮、Cloud 最佳化 GeoTIFF，以便在 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

您可以指定預測器 (-co PREDICTOR=2 適用於整數資料類型，-co PREDICTOR=3 適用於浮點資料類型)，進一步縮減輸出檔案大小。

如果使用者使用 GDAL 3.11 以上版本，COG 驅動程式就能產生檔案，不必擔心建立和保留概覽。

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 \

使用 REST API 建立 Cloud GeoTIFF 影像資產

注意： REST API 包含新功能和進階功能，可能不一定適合所有使用者。如果您是 Earth Engine 新手，建議先參閱 JavaScript 指南，再開始使用。

如要使用 REST API 建立 COG 支援的素材資源，請向 Earth Engine ImportExternalImage 端點提出 POST 要求。如以下所示，此要求必須經過授權，才能在使用者資料夾中建立素材資源。

啟動授權工作階段

如要在使用者資料夾中建立 Earth Engine 素材資源，您必須在提出要求時以自己的身分驗證。您可以使用 Earth Engine 驗證工具的憑證，啟動 AuthorizedSession。接著，您可以使用 AuthorizedSession 向 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)
)

要求主體

要求主體是 ImageManifest 的例項。這裡會指定 COG 路徑，以及其他實用的屬性。

如要進一步瞭解如何設定 ImageManifest，請參閱這份指南。您可以定義一或多個 Tileset，每個 Tileset 都支援一或多個頻帶。對於 ImportExternalImage，每個 Tileset 最多支援一個 ImageSource。

如要進一步瞭解如何匯出總毛利，請參閱這份文件。

傳送要求

向 Earth Engine projects.images.importExternal 端點提出 POST 要求。

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