注册云优化 GeoTIFF (COG) 资产

Earth Engine 支持由存储在 Google Cloud Storage (GCS) 中的 Cloud Optimized GeoTIFF (COG) 提供支持的资产。

注册 COG 支持的资产时，Earth Engine 会在创建时为图像编制空间和元数据字段的索引。这样一来，图像在集合中使用时性能良好 ，与标准摄取 资产的性能相当（请参阅 Cloud Optimized GeoTIFF (COG) 概览）。

前提条件和 Cloud Storage 设置

在注册 COG 之前，您必须正确设置您的 Google Cloud Storage 资源。

1. 存储桶位置（严格要求）

为了让 Earth Engine 能够访问您的 Cloud Storage 存储桶，该存储桶必须 位于以下数据中心区域或多区域之一：

• us 多区域
• 任何包含 us-central1 的 美国双区域
• us-central1 区域

如果您的存储桶位于任何其他区域数据中心（例如 us-east4 或 europe-west1），Earth Engine 将拒绝注册和读取请求。

2. 存储类别和结算

• 我们建议使用 Standard 存储类别。Standard Storage 没有最短存储时长规则，因此如果您更新或替换临时文件，就不会产生提前删除结算罚款。
• 虽然 Earth Engine 计算循环不会产生 Cloud Storage 数据检索附加费，但从外部工具（例如桌面 GIS 软件）访问非 Standard Storage 存储层级会产生高昂的检索费用。
• 您必须在 Google Cloud 项目中启用结算功能才能使用 GCS。如需开始使用，请参阅 Google Cloud Storage 快速入门 。

第 1 步：准备 COG

您的 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 注册是快速的 同步 API 调用，而不是异步批量计算作业，因此它不会在代码编辑器 任务 标签页或批量任务 管理器中创建后台任务。API 调用会一直阻塞，直到元数据验证和索引编制完成，之后资产会立即在代码编辑器 资产 标签页中或使用 ee.data.getAsset() 提供。

COG 资产的清单限制

为 COG 支持的资产创建清单时，请注意以下严格限制（与标准摄取清单不同）：

• 单个存储桶： 清单中的所有 URI 都必须位于同一 GCS 存储桶中。
• 每个来源一个 URI： 每个 ImageSource 必须仅包含一个 URI。您无法将多个文件拼接成单个图块集来源。如需拼接多个 COG 场景，请将每个 COG 注册为资产，然后使用 .mosaic() 将它们合并到 ee.ImageCollection 中。
• 无 mask_bands： 不支持顶级 mask_bands。在清单中使用 missingData，或确保您的 TIFF 具有内部 nodata 值。
• 图块集中无 data_type： 请勿在 tilesets 部分中指定 data_type；系统会自动检测。
• 来源中无 dimensions： 请勿在 中指定 dimensions。ImageSource
• 无 subdataset_prefix / subdataset_suffix。
• 无 min_tile_area_ratio 或 skip_metadata_read。

第 4 步：配置权限（对于共享至关重要）

与标准 Earth Engine 资产不同，COG 的像素数据保留在 GCS 中。 与他人共享 COG 支持的资产时，您必须授予他们对 Earth Engine 资产和 GCS 文件的读取权限。

1. 授予 GCS 存储桶权限

协作者需要权限才能从 GCS 读取文件。

所需权限：

• storage.buckets.get（用于检索存储桶元数据和位置）
• storage.objects.get（用于读取像素数据）

您可以使用以下标准 Cloud Storage 角色授予这些权限：

• Storage Bucket Viewer （提供 storage.buckets.get 以读取存储桶元数据和位置）
• Storage Object Viewer （提供 storage.objects.get 以读取像素数据）

在 Google Cloud 控制台中进行配置的步骤：

1. 前往 Cloud Storage 浏览器。
2. 点击您的存储桶名称。
3. 选择权限 标签页。
4. 点击授予访问权限 。
5. 添加协作者的电子邮件地址（或 Google 群组，或 allUsers 以进行公开访问）。
6. 分配角色 Storage Bucket Viewer 和 Storage Object Viewer 。
7. 点击保存 。

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
  

使用已注册的资产

注册后，COG 支持的资产在 Earth Engine 脚本中的访问方式与任何标准摄取图片素材资源相同：

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