註冊雲端最佳化 GeoTIFF (COG) 資產

Earth Engine 支援由儲存在 Google Cloud Storage (GCS) 的雲端最佳化 GeoTIFF (COG) 支援的資產。

註冊 COG 支援的資產時,Earth Engine 會在建立時為圖片的空間和中繼資料欄位建立索引。這樣一來,圖片在集合中使用時,效能會與標準擷取資產相當 (請參閱「雲端最佳化 GeoTIFF (COG) 總覽」)。

本指南涵蓋準備檔案、編寫資訊清單、提交註冊要求、設定權限,以及更新或刪除已註冊的素材資源。

事前準備

註冊 COG 前,請務必正確設定 Cloud Storage 資源。

Bucket 位置

如要讓 Earth Engine 存取 Cloud Storage bucket,bucket 必須位於下列其中一個資料中心區域或多區域:

  • us 多區域
  • 任何包含 us-central1 的美國雙區域
  • us-central1 區域

如果 bucket 位於其他區域資料中心 (例如 us-east4 或 europe-west1),Earth Engine 會拒絕註冊和讀取要求。請參閱支援的 Cloud Storage bucket 位置。

儲存空間級別和計費

  • 建議使用 Standard 儲存空間級別。Standard Storage 沒有最短儲存時間規則,因此更新或替換暫存檔案時,不會產生提前刪除的計費罰款。
  • 雖然 Earth Engine 運算迴圈不會產生 Cloud Storage 資料擷取附加費用,但從外部工具 (例如桌面 GIS 軟體) 存取非 Standard Storage 儲存空間級別,會產生高昂的擷取費用。
  • 您必須在 Google Cloud 專案啟用計費功能,才能使用 Cloud Storage。請參閱 Cloud Storage 快速入門導覽課程,瞭解如何開始使用。

準備銷貨成本

Earth Engine 會直接從 Cloud Storage 讀取 COG,只擷取運算所需的標頭和圖塊,因此檔案版面配置很重要。TIFF 必須符合下列條件:

  • 平鋪:正方形平鋪尺寸為 2 的次方,從 16x16 到 2048x2048。建議使用 512x512,以獲得最佳效果。
  • 所有圖片檔案目錄 (IFD) 都排在開頭。
  • 如有 2 的次方總覽,請一併提供。概覽並非必要,但建議用於大於單一圖塊的圖片。
  • 使用 BAND 或 PIXEL 交錯 (請參閱單一波段與多波段檔案,瞭解如何取捨)。

如要轉換圖片,請使用 GDAL 的 COG 驅動程式,這個驅動程式會透過一個步驟產生必要的版面配置 (圖塊、總覽和標頭位置)。為類別型資料新增 OVERVIEW_RESAMPLING=NEAREST,預設值為 CUBIC。如需壓縮、總覽和版面配置建議,請參閱準備外部 COG 的最佳做法。

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

如果 GDAL 版本早於 3.11,請省略 INTERLEAVE=BAND。

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

建構資訊清單

無論是使用 Earth Engine Python 用戶端程式庫、earthengine 指令列工具,還是 Earth Engine REST API 註冊 COG,都必須定義圖片上傳資訊清單,指定資產目的地、Cloud Storage URI 和選用的波段中繼資料。API 和指令列工具會將 COG 支援的資產稱為「外部圖片」(ee.data.startExternalImageIngestion()、earthengine upload external_image、projects.image.importExternal)。

範例:單一 COG 支援所有波段 如果 COG 包含所有波段 (例如 RGB),資訊清單只需要單一圖塊集:

{
  "name": "projects/my-project/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

範例:多個 COG (每個波段一個) 如果不同波段有獨立檔案 (例如紅色、綠色和藍色在不同檔案中):

{
  "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 }
  ]
}

資訊清單限制

COG 支援資產的資訊清單有限制,不適用於標準擷取資訊清單:

  • 單一 bucket:資訊清單中的所有 URI 都必須位於同一個 Cloud Storage bucket。
  • 每個來源一個 URI:每個 ImageSource 都必須包含一個 URI。您無法將多個檔案拼接成單一圖塊集來源。如要拼接多個 COG 場景,請將每個 COG 註冊為資產,並使用 .mosaic() 將其合併為 ee.ImageCollection。
  • 不含 mask_bands:不支援頂層 mask_bands 欄位。請在資訊清單中使用 missingData,或確保 TIFF 具有內部 nodata 值。
  • 圖塊集中沒有 data_type:請勿在 tilesets 區段中指定 data_type,系統會自動偵測。
  • 來源中沒有 dimensions:請勿在 ImageSource 中指定 dimensions。
  • 否 subdataset_prefix / subdataset_suffix。
  • 不含 min_tile_area_ratio 或 skip_metadata_read。

提交註冊要求

您可以使用 Earth Engine Python 用戶端程式庫、earthengine 指令列工具或 Earth Engine REST API,將資訊清單提交至 Earth Engine。請選擇最適合工作流程的方法。

Python 用戶端程式庫

在 Python 指令碼或 Jupyter 筆記本中,初始化專案後,使用 Earth Engine Python 用戶端程式庫 (ee.data):

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']}")

指令列工具

在終端機中,將資訊清單儲存至名為 manifest.json 的檔案,然後執行 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

如要使用自動化工作流程,但不使用用戶端程式庫,請直接將授權的 POST 要求傳送至 Earth Engine REST API 端點 projects.image.importExternal (此處以 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))

提交註冊要求後,系統會啟動輕量中繼資料索引作業。由於 COG 註冊不會複製像素資料,因此這項作業通常會在幾秒內完成。

設定權限

與標準 Earth Engine 資產不同,COG 的像素資料會保留在 Cloud Storage 中。與他人共用 COG 支援的資產時,您必須授予對方 Earth Engine 資產和 Cloud Storage 檔案的讀取權限。

授予 Cloud Storage bucket 權限

協作者必須具備從 Cloud Storage 讀取檔案的權限。

必要權限:

  • storage.buckets.get (用於擷取 bucket 中繼資料和位置)
  • storage.objects.get (讀取像素資料)

您可以使用下列標準 Cloud Storage 角色授予這些權限:

  • Storage bucket 檢視者 (提供 storage.buckets.get,可讀取 bucket 中繼資料和位置)
  • Storage 物件檢視者 (提供 storage.objects.get 權限,可讀取像素資料)

在 Google Cloud 控制台中的設定步驟:

  1. 前往「Cloud Storage Browser」頁面。
  2. 按一下 bucket 名稱。
  3. 選取 [權限] 分頁標籤。
  4. 點選「授予存取權」。
  5. 新增協作者的電子郵件地址 (或 Google 群組,或 allUsers 以開放公開存取)。
  6. 指派「Storage bucket 檢視者」和「Storage 物件檢視者」角色。
  7. 按一下「儲存」。

共用 Earth Engine 資產

使用 Earth Engine 資產管理工具或 CLI 分享資產本身。詳情請參閱資產管理指南。

更新、取代及刪除 COG 支援的資產

COG 支援的資產是指向 Cloud Storage 中特定版本檔案的指標,加上 Earth Engine 在您註冊時建立索引的中繼資料 (足跡、投影、波段和總覽版面配置)。Earth Engine 會固定檔案版本,確保中繼資料與像素保持同步,這也是更新 COG 支援資產與更新標準資產的不同之處。

物件生成

註冊 COG 時,Earth Engine 會記錄 Cloud Storage 物件的世代 (版本號碼) 和 URI。您可以在資產的中繼資料中查看固定的世代,該世代會顯示為 URI 的 #<generation> 後置字串:

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

您也可以在註冊 (或重新註冊) 資產時,在資訊清單 URI 中加入 #<generation> 尾碼,自行固定特定版本。如果沒有這個標頭,Earth Engine 會讀取目前的物件,並固定找到的任何世代。明確固定版本,有助於復原至已啟用物件版本管理功能的 bucket 所保留的先前版本。

如果您在 Cloud Storage 中覆寫檔案,系統會產生新的世代,而刪除檔案則會移除固定的世代。無論是哪種情況,讀取資產像素都會失敗,除非值區的物件版本管理保留舊版本,在這種情況下,Earth Engine 會繼續讀取舊像素。無論採用哪種方式,使用索引記錄的中繼資料作業 (例如 ee.data.getAsset()、bandNames() 和集合篩選) 都能正常運作。

變更檔案後更新素材資源

如要將現有素材資源指向新版檔案,請使用相同素材資源名稱重新註冊,並啟用覆寫功能。Earth Engine 會重新讀取 GeoTIFF 標頭、重新建立中繼資料索引,並固定新版本,這些動作都會在單一同步呼叫中完成。資產現有的權限會保留,但其屬性、時間範圍和頻帶名稱會來自新的資訊清單,因此請加入先前使用 ee.data.updateAsset() 設定的所有內容。

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • 指令列: earthengine upload external_image --force --manifest manifest.json
  • REST API:在 projects.image.importExternal 要求主體中,將 "overwrite": true 與 "imageManifest" 一併納入頂層欄位。

您不需要先刪除素材資源,刪除素材資源反而會造成反效果:獨立素材資源會失去權限,而集合中的圖片會短暫從集合中消失。請注意,ee.data.updateAsset() (projects.assets.patch) 只能變更屬性、日期範圍和波段名稱,無法變更資產指向的檔案。

獨立生命週期

Earth Engine 資產和 Cloud Storage 物件是分開管理:

  • 刪除 Earth Engine 資產 (earthengine rm 或 ee.data.deleteAsset()) 只會移除資產記錄,Cloud Storage 中的檔案不會受到影響。
  • 刪除 Cloud Storage 中的檔案不會移除資產,資產仍會顯示在清單和集合中 (請參閱物件世代)。

處理大型集合

Earth Engine API 沒有批次或遞迴刪除功能:每個資產都必須個別刪除,且集合必須為空白才能刪除。earthengine rm -r 會為您處理這項作業,但會一次刪除一個,因此移除含有數萬張圖片的集合可能需要數小時。

  • 如要更換集合的圖片,請覆寫而非刪除。 依名稱重新註冊每個映像檔,並啟用覆寫功能 (請參閱上方說明)。這樣一來,每張圖片只需要一個要求,而不是兩個,集合會一直保持填入狀態,而且可以避免刪除及重新建立集合本身 (權限所在位置)。只刪除不在新組合中的圖片。
  • 如要刪除多項資產,請透過指令碼平行處理。使用 ee.data.listAssets() 列出資產 (使用 BASIC 檢視畫面,只傳回名稱和類型,而非每個映像檔的完整中繼資料),並從小型執行緒集區中刪除這些資產。資產要求會共用專案層級的頻率限制,因此請保持適當的並行數量 (約 10 個 worker),並讓用戶端程式庫內建的重試機制處理任何 429 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)
    

    只有在所有圖片都刪除後,系統才會刪除集合,因此如果部分失敗,集合會保留在原處,以便重新執行。

    註冊多張圖片時也適用相同模式:將輔助程式中的 ee.data.deleteAsset(asset_id) 替換為 ee.data.startExternalImageIngestion(manifest, allow_overwrite=True),並對應至資訊清單清單。即使在第一次執行時傳遞 allow_overwrite=True,批次作業在部分失敗後仍可安全地重新執行,因為任何已建立的資產都會被取代,而不會導致錯誤。

使用已註冊的素材資源

註冊後,您就能在 Earth Engine 指令碼中存取 COG 支援的資產,就像存取任何標準擷取的圖片素材資源一樣:

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

如需權限、更新檔案和管理大型集合等常見問題的解答,請參閱常見問題的 COG 部分。