基于云端 GeoTiff 的 Earth Engine 资产

Colab 徽标 在 Google Colab 中运行 GitHub 徽标 在 GitHub 上查看源代码

Earth Engine 支持由 Cloud 优化型 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 的 ImageManifest。如果未指定任何波段，则生成的资产将包含 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

您可以使用 tilesetId 和 tilesetBandIndex 字段指定包含多个 Tileset 的 ImageManifest，其中生成的资产的每个频段都由 Tileset 的某个频段提供支持。如果不同波段具有不同的分辨率或数据类型，这种方法非常有用。频段可以按任何顺序从任何可用的 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

存储类别

存储分区的存储类别必须为“标准存储”。

共享权限

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 将使用调用 ImportExternalImage 时 TIFF 的生成版本存储该 URI。

这意味着，如果包含 GCS 中外部资产的任何 TIFF 文件发生更新（因此更改了其生成版本），Earth Engine 将返回“Failed to load the GeoTIFF at gs://my-bucket/my-object#123456”（无法加载 gs://my-bucket/my-object#123456 中的 GeoTIFF 文件）错误，因为预期对象已不存在（除非存储分区启用了多个对象版本）。此政策旨在使资产的元数据与对象的元数据保持同步。

配置

关于 COG 的配置方式，TIFF 必须：

  • 平铺，其中功能块尺寸为：

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

  • 排列方式为所有 IFD 都在开头。

为了实现最佳性能，请执行以下操作：

  • 使用 512x512 或更高的功能块尺寸。
  • 添加了“2 的幂”概览。

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

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

以下 gdal_translate 命令会将光栅图转换为带有波段交错、采用 zstd 压缩且经过 Cloud 优化的 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，每个 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))