基于云端 GeoTiff 的 Earth Engine 资产

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

此 Notebook 演示了如何创建由 Cloud 优化型 GeoTIFF (COG) 支持的 Earth Engine 资产。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

必须能够访问存储分区的元数据，以便 Earth Engine 确定其位置。调用方必须对存储分区拥有 storage.buckets.get 权限。该权限由“Storage Legacy Bucket Reader”（以及其他角色）提供，请参阅 https://cloud.google.com/storage/docs/access-control/iam-roles

如需分配此角色，请执行以下操作： 1. 前往存储分区权限页面：https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions 2. 点击“授予访问权限” 3. 添加应授予访问权限的所有主账号 4. 分配“Storage Legacy Bucket Reader”角色（或创建一个仅具有 storage.buckets.get 权限的新自定义角色并分配该角色） 5. 保存

存储类别

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

权限

COG 支持的 Earth Engine 资产和底层数据的 ACL 是单独管理的。如果在 Earth Engine 中共享了 COG 支持的资产，则所有者有责任确保与 GCS 中的数据共享对象相同。如果数据不可见，Earth Engine 会返回格式为“Failed to load the GeoTIFF at gs://my-bucket/my-object#123456”（123456 是对象的生成版本）的错误。

世代

创建 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 的幂”概览。

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

使用 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))