Earth Engine 支援由儲存在 Google Cloud Storage (GCS) 的雲端最佳化 GeoTIFF (COG) 支援的資產。
註冊 COG 支援的資產時，Earth Engine 會在建立時為圖片的空間和中繼資料欄位建立索引。這樣一來，圖片在集合中使用時，效能會與標準擷取資產相當 (請參閱「雲端最佳化 GeoTIFF (COG) 總覽」)。
事前準備和 Cloud Storage 設定
註冊 COG 前，您必須正確設定 Google Cloud Storage 資源。
1. Bucket 位置 (嚴格規定)
如要讓 Earth Engine 存取 Cloud Storage bucket，bucket 必須位於下列其中一個資料中心區域或多區域：
us多區域- 任何包含
us-central1的美國雙區域 us-central1區域
如果 bucket 位於其他區域資料中心 (例如 us-east4 或 europe-west1)，Earth Engine 會拒絕註冊和讀取要求。
2. 儲存空間級別和計費
- 建議使用「標準」儲存空間類別。Standard Storage 沒有最短儲存時間規則，因此更新或取代暫存檔案時，不會因提早刪除而遭到罰款。
- 雖然 Earth Engine 運算迴圈不會產生 Cloud Storage 資料擷取附加費用，但從外部工具 (例如桌上型 GIS 軟體) 存取非 Standard Storage 層時，會產生高昂的擷取費用。
- 您必須在 Google Cloud 專案啟用計費功能，才能使用 GCS。如要開始使用，請參閱 Google Cloud Storage 快速入門導覽課程。
步驟 1：準備銷貨成本
TIFF 檔案必須經過雲端最佳化處理。TIFF 必須符合下列條件：
- 圖塊：圖塊尺寸為 256x256、512x512、1024x1024 或 2048x2048。建議使用 512x512 以上，以獲得最佳效果。
- 所有圖片檔案目錄 (IFD) 都位於開頭。
- 包含 2 的冪總覽。
- 使用 BAND 交錯。
您可以使用 GDAL 轉換圖片。
使用 GDAL COG 驅動程式 (建議使用 GDAL >= 3.1)：
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
使用標準 GTiff 驅動程式：
首先，請產生 2 的冪次方的內部總覽 (使用 gdal raster overview add 或 gdaladdo)，然後將圖片和總覽複製到分塊 COG 版面配置：
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
步驟 2：建構資訊清單
無論是使用 Earth Engine Python 用戶端程式庫、earthengine 指令列工具或 Earth Engine REST API 註冊 COG，都必須定義圖片上傳資訊清單，指定資產目的地、Google Cloud Storage URI 和選用的頻帶中繼資料。
範例：單一 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 }
]
}
步驟 3：提交註冊要求
您可以使用 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. Start the ingestion task (allow_overwrite=True corresponds to --force) result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) print(f"Asset registered: {result['name']}")
指令列工具
在終端機中，將資訊清單儲存至名為 manifest.json 的檔案，然後執行 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)
如要使用自動化工作流程，但不使用用戶端程式庫，請直接將授權的 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 註冊不會複製像素資料，因此這項作業通常會在幾秒內完成。
COG 資產的資訊清單限制
為 COG 支援的資產建立資訊清單時，請注意下列嚴格限制 (與標準擷取資訊清單不同)：
- 單一 bucket：資訊清單中的所有 URI 都必須位於同一個 GCS 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。
步驟 4：設定權限 (共用時必須設定)
與標準 Earth Engine 資產不同，COG 的像素資料會保留在 GCS 中。 與他人共用 COG 支援的資產時，您必須授予對方 Earth Engine 資產和 GCS 檔案的讀取權限。
1. 授予 GCS bucket 權限
協作者必須具備從 GCS 讀取檔案的權限。
必要權限：
storage.buckets.get(擷取 bucket 中繼資料和位置)storage.objects.get(讀取像素資料)
您可以使用下列標準 Cloud Storage 角色授予這些權限：
- Storage bucket 檢視者 (提供
storage.buckets.get，可讀取 bucket 中繼資料和位置) - Storage 物件檢視者 (提供
storage.objects.get權限，可讀取像素資料)
在 Google Cloud 控制台中的設定步驟：
- 前往「Cloud Storage Browser」頁面。
- 按一下 bucket 名稱。
- 選取 [權限] 分頁標籤。
- 點選「授予存取權」。
- 新增協作者的電子郵件地址 (或 Google 群組，或
allUsers，以便公開存取)。 - 指派「Storage bucket 檢視者」和「Storage 物件檢視者」角色。
- 按一下 [儲存]。
2. 共用 Earth Engine 資產
使用 Earth Engine 資產管理工具或 CLI 共用資產本身。詳情請參閱資產管理指南。
管理物件生成
註冊 COG 時，Earth Engine 會儲存 GCS 物件的特定世代 (版本)。如果您在 GCS 中更新檔案，檔案的世代也會變更。
- 根據預設，Earth Engine 無法載入資產，並會傳回錯誤：
Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation。 - 這是為了避免中繼資料 (例如投影或足跡) 與基礎像素不同步。
最佳做法：如要更新基礎圖片資料，請註冊為新素材資源，或使用
--force標記重新執行上傳指令，而非就地覆寫檔案：earthengine --project your-project-id upload external_image --force --manifest manifest.json
使用已註冊的素材資源
註冊後，您就能在 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')