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

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

Earth Engine 支援以雲端最佳化 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 bucket 位置必須是下列其中之一：

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

儲存空間級別

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

共用權限

COG 支援的 Earth Engine 資產和基礎資料的 ACL 是分開管理的。與協作者共用 COG 支援的資產以供讀取時，擁有者有責任確保 Earth Engine 資產和基礎 COG 檔案都授予讀取權。

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

協作者必須先取得 Google Cloud Storage bucket 中基礎 COG 檔案的讀取權限，才能讀取 COG 支援的資產。如果沒有這些權限，Earth Engine 就無法為他們擷取資料。如果 Earth Engine 使用者無法查看 Google Cloud Storage 中的資料，Earth Engine 會傳回「Failed to load the GeoTIFF at gs://my-bucket/my-object#123456」(無法載入的 GeoTIFF) 形式的錯誤 (其中 123456 是物件的產生時間)。

具體來說，協作者必須具備下列權限：

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

這些權限分別由「Storage Legacy Bucket Reader」和「Storage Legacy Object Reader」角色提供，以及其他角色。

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

  1. 前往 bucket 權限頁面： 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 會儲存該 URI，並採用呼叫 ImportExternalImage 時的 TIFF 產生方式。

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

設定

就 COG 的設定方式而言，TIFF 必須符合下列條件：

  • 分塊：圖塊尺寸為下列其中一種：

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

  • 所有 IFD 都會排在開頭。

為獲得最佳成效，請注意下列事項：

  • 使用 512x512 以上的圖塊尺寸。
  • 包含 2 的次方總覽。

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

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

下列 gdal_translate 指令會將點陣轉換為帶交錯、zstd 壓縮的雲端最佳化 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，每個 都支援一或多個頻段。如果是 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))