基于云端 GeoTiff 的 Earth Engine 资产

在 Google Colab 中运行

在 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 存储分区读取权限

如需让协作者读取由 COG 提供支持的资产，他们必须先拥有 Google Cloud Storage 存储分区中底层 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 Legacy Bucket Reader” （提供 storage.buckets.get 和 其他存储分区级读取权限）。
   • “Storage Legacy Object Reader” （提供 storage.objects.get）。
   • （或者，您可以创建一个仅具有 storage.buckets.get 和 storage.objects.get 权限的新自定义角色，然后分配该角色。）
5. 保存

2. 共享 Earth Engine 资产以供读取

确保协作者拥有底层 GCS 存储分区和对象的必要权限后，您还必须共享 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”错误，因为预期的对象不再存在（除非存储分区启用了多个对象版本）。 此政策旨在使资产的元数据与对象的元数据保持同步。

配置

在 COG 的配置方面，TIFF 必须满足以下条件：

• 平铺，其中图块尺寸为以下其中一项：

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

• 排列方式应使所有 IFD 都位于开头。

为获得最佳性能，请执行以下操作：

• 使用 512x512 或更高的图块尺寸。
• 包含 2 的幂的概览。

根据您的预期用例， “INTERLEAVE” 创建选项可能会影响性能。我们建议在任何情况下都使用 BAND 交错。

如需详细了解优化配置，请参阅此 页面。

以下 gdal_translate 命令会将光栅转换为波段交错、zstd 压缩的 Cloud Optimized GeoTIFF，该 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。

如需详细了解如何导出 COG，请参阅此 文档 。

发送请求

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