Earth Engine 中的 Cloud Optimized GeoTIFF (COG)

借助 Google Earth Engine，您可以处理存储在您自己的 Google Cloud Storage (GCS) 存储桶中的光栅数据。通过使用云优化 GeoTIFF (COG)，您可以直接在 Earth Engine 中访问和分析数据，而无需将其作为 Earth Engine 资源注入。

这种方法具有多项优势，尤其是在管理大型数据集或将 Earth Engine 集成到更广泛的 Google Cloud 工作流或外部工具和平台中时。

为何要使用 Cloud Storage 和 COG？

• 灵活性和互操作性：将数据保留在标准 Cloud Storage 存储桶中，以便其他工具和服务访问。无论您是直接上传数据还是从 Earth Engine 导出数据，Cloud Storage 都是 Earth Engine 和外部工作流的单一事实来源。
• 数据控制功能和出站流量：将数据存储在 Cloud Storage 中可提供标准对象存储区管理功能。这样，您就可以使用 Requester Pays 或公共存储桶等 Cloud Storage 功能下载、迁移或共享数据，并使用标准 Cloud IAM 管理访问权限。
• 灵活扩缩：避免 Earth Engine 存储空间限制。Cloud Storage 提供近乎无限的自助式存储空间，可扩缩至 PB 级。
• 无需等待提取：注册 COG 的过程很快，因为 Earth Engine 仅从文件头读取元数据（例如投影和维度）以进行索引和验证。实际像素数据仍保留在 Cloud Storage 中，并在计算期间按需读取，从而无需单独的提取任务。

Earth Engine 中的 COG 工作流

Earth Engine 支持在 Cloud Storage 上使用 COG 进行双向工作流：您可以直接从 Cloud Storage 将 COG 读取到 Earth Engine 中，也可以将 Earth Engine 的计算结果直接作为 COG 写入 Cloud Storage。

从 Cloud Storage 读取 COG

如需将 Cloud Storage 托管的 COG 导入 Earth Engine，您有两种选择：

1. 直接加载 (ee.Image.loadGeoTIFF())：使用单张图片的 Cloud Storage URI 直接加载该图片。每次计算或地图图块请求都会读取文件的当前版本，但已渲染的地图图块会被缓存，因此在您替换文件后，地图可能会显示新旧图块的混合；请将 #<generation> 附加到 URI 以固定特定版本。这最适合快速测试、临时分析或临时数据：

   JavaScript

   var image = ee.Image.loadGeoTIFF('gs://google-sample-bucket/my_image.tif');
   

   Python

   image = ee.Image.loadGeoTIFF('gs://google-sample-bucket/my_image.tif')
   

   如需查看已完成示例，请参阅云优化 GeoTIFF 中的图片。

2. 注册的资产：使用上传清单将一个或多个 COG 注册为 Earth Engine 资产（请参阅 COG 注册指南）。这是生产工作流的推荐路径，尤其是在构建图片合集时。

将 COG 写入 Cloud Storage

如需将 Earth Engine 计算结果作为 COG 保存在 Cloud Storage 存储桶中，请使用 Export.image.toCloudStorage() 批量导出函数（请参阅导出图片），并在 formatOptions 中将 cloudOptimized 参数设置为 true。这会指示 Earth Engine 编译图片，并将其作为完全合规的 COG 直接写入 Cloud Storage 存储桶。

支持的 Cloud Storage 存储桶位置

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

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

如果您的存储桶位于任何其他区域数据中心，Earth Engine 将拒绝注册和读取请求。Earth Engine 仅访问存储在 Google Cloud Storage 存储桶中的 COG。不支持外部云端存储空间服务提供商和通用 HTTP 网址。

Earth Engine COG 导出规范

在 formatOptions 中使用 Export.image.toCloudStorage() 和 cloudOptimized: true 从 Earth Engine 导出分析结果时，Earth Engine 的内置导出工具会自动应用以下标准：

• 文件结构：生成具有内部平铺 (TILED=YES) 的 BigTIFF (BIGTIFF=YES)，并将所有概览复制到文件开头。
• 自动概览：如果输出栅格尺寸为 512x512 像素或更大，Earth Engine 会自动构建五个级别的 2 的幂概览 ([2, 4, 8, 16, 32])。Earth Engine 会根据输出像素数据类型动态选择概览重采样方法：对浮点图像进行立方重采样，对所有其他整数或离散图像进行最近邻重采样。
• 默认压缩和切片：Earth Engine 导出 COG 时，会采用 256x256 像素块切片和 LZW 压缩 (COMPRESS=LZW)。在 formatOptions 中，无法自定义压缩和切片尺寸。
• 自动分片：如果导出的栅格很大（超过 4 GiB 未压缩），Earth Engine 会自动将导出内容拆分为多个名为 baseFilename-yMin-xMin 的空间图块（请参阅大文件导出）。
• 替换分片限制：如需将大型栅格（未压缩时上限为 16 GiB，每条边上限为 131,072 像素）导出为单个文件而不进行分片，请在 formatOptions 中指定 fileDimensions。每个维度都必须是图块大小（默认为 256，例如 [65536, 65536]）的正整数倍。由于 fileDimensions 设置的是最大文件维度，而不是输出边界框，因此传递一个较大的上限会强制将导出内容放入单个文件中，而无需进行精确的网格计算。您还可以传递 skipEmptyFiles: true，以防止生成空的背景图块。
• 优化权衡：配置大型导出作业时，请权衡文件数量与导出速度。指定较小的 fileDimensions 或 shardSize 会产生更多文件片段，但会最大限度地提高后端工作器之间的并行处理能力，从而缩短导出完成时间。相反，替换限制以生成单个大文件可简化文件管理和数据共享，但由于单文件组装和 I/O 瓶颈，可能会增加导出执行时间。接近 16 GiB 未压缩限制的超大单文件 COG 导出（尤其是压缩效果不佳的图片）也可能在概览和 COG 组装期间超出临时存储容量；如果导出失败，请考虑分片为较小的文件或在外部转换标准 GeoTIFF 导出。

在 Earth Engine 之外自定义 COG 创建

虽然对于大多数工作流而言，直接使用 cloudOptimized: true 导出是生成即用型 COG 的最简单方法，但您也可以导出标准 GeoTIFF（cloudOptimized: false，默认），然后使用 GDAL 等外部工具自行将其转换为 COG。在以下情况下，两步式导出和转换工作流非常有用：

• 自定义压缩和布局：根据数据集定制块大小（例如 512x512）、预测器、概览重采样方法或压缩编解码器（例如 ZSTD）（请参阅准备外部 COG 的最佳实践和准备 COG）。
• 避免在导出大型单文件时出现容量错误：在导出过程中跳过概览生成和 COG 布局重写，可减少内存和临时存储空间开销，从而降低超大单文件导出超出容量限制的可能性。
• 缩短 Earth Engine 导出执行时间：将概览构建和 COG 格式设置分流到您自己的计算环境，可缩短 Earth Engine 导出阶段。

准备外部 COG 的最佳实践

由常见地理空间工具（例如 GDAL、Rasterio、QGIS、ArcGIS 或 R 的 terra 软件包）生成的 COG 通常可在 Earth Engine 中使用，前提是它们使用受支持的压缩方案和像素数据类型。以下指南可帮助您整理文件并调整压缩和布局设置，以优化存储空间和性能。

内部图块尺寸

始终生成内部平铺栅格。Earth Engine 要求使用 16x16 到 2048x2048 像素之间的正方形、2 的幂次方图块。专用 COG 导出工具（例如 GDAL 的 COG 驱动程序，带有 -of COG）会自动将图片切片为 512x512 像素块 (-co BLOCKSIZE=512)，而标准 GeoTIFF 导出工具 (-of GTiff) 需要显式切片 (-co TILED=YES)，并且通常默认使用 256x256 块。如果图块太小，则需要从 Cloud Storage 进行多次单独读取才能覆盖一个区域；如果图块太大，则会迫使 Earth Engine 下载和解压缩超出请求所需的数据。512x512 像素的图块在这两者之间取得了良好的平衡。

选择文件尺寸

在决定是将数据集存储为单个 COG 还是将其拆分为多个文件时，请在文件数量与每个文件的大小之间取得平衡：

• 避免数千个小文件：读取跨越数百个小文件的区域需要针对每个文件发出单独的 Cloud Storage 请求和标头读取，这会增加延迟时间。
• 避免使用单个大文件：将大陆或全球数据集存储在一个大文件中可能会限制并行读取吞吐量，因为许多工作器会同时从同一对象读取数据。此外，还有一个硬性限制：Earth Engine 在加载或注册文件时，最多读取文件的前 10000000 字节 (10 MB)，并且它所需的所有内容（所有 IFD，包括图块偏移量和字节数表，这些内容会随着图块数量以及波段交错文件的波段数量而增加）都必须在此范围内。 如果图片包含数十万个图块，或者 GeoTIFF 文件大于 10 MB 且其 IFD 位于文件末尾而非开头，则无法加载。为避免超出限制，请使用更大的图块（最大 2048x2048），或将图片拆分为多个注册为 ee.ImageCollection 的 COG。
• 建议的文件大小：将大型数据集拆分为多个文件时，请尽量使单个文件的大小介于大约 2000x2000 到 5000x5000 像素之间（压缩后约为 20 MB 到 500 MB）。请注意，COG 资源清单中的每个 Tileset 都引用一个 Cloud Storage URI，因此各个文件在 ee.ImageCollection 中注册为单独的 ee.Image 资源，而不是在单个 COG 资源中拼接。

单波段文件与多波段文件

• 每个波段一个文件：适用于多光谱或高光谱图像，其中工作流通常仅读取波段子集（例如，根据红色和近红外波段计算 NDVI）。通过在注册清单中列出多个 tilesets，仍可将单独的单波段 COG 合并为单个多波段 ee.Image 资源。当波段具有不同的像素分辨率（例如 Sentinel-2 的 10 米、20 米和 60 米波段）时，也需要单独的文件，因为单个 COG 文件在其所有波段中只能有一个像素大小。
• 多波段文件（像素交错与波段交错）：Earth Engine 支持像素交错（INTERLEAVE=PIXEL，GDAL 的 COG 驱动程序中的默认设置）和波段交错 (INTERLEAVE=BAND) 多波段 COG：
  • 像素交错 (INTERLEAVE=PIXEL)：将空间图块的所有波段一起存储在单个压缩块中。这非常适合具有少数几个几乎总是同时读取的波段的数据集（例如 RGB 图像），因为单个范围请求会提取所有波段。但是，如果查询仅从像素交错文件中读取一个波段，Earth Engine 仍必须提取并解压缩该图块中的所有波段。
  • 波段交错 (INTERLEAVE=BAND)：将每个波段的图块存储在单独的压缩块中，以便 Earth Engine 仅提取和解压缩请求的波段。在 GDAL 中，从 GDAL 3.11 开始，COG 驱动程序支持 -co INTERLEAVE=BAND（使用 GTiff 驱动程序时，所有 GDAL 版本都支持）。请勿使用 INTERLEAVE=TILE。

压缩、概览和创建选项

• 压缩：Earth Engine 支持使用 ZSTD、DEFLATE (ZLIB)、LZW、PACKBITS、JPEG（适用于 8 位数据）或 NONE（未压缩）压缩的 COG。COG 支持的资源不支持 LZMA、WEBP、LERC 和 JXL (JPEG-XL)；如需在 Earth Engine 中使用通过这些编解码器压缩的文件，请将其作为标准资源注入。虽然许多 COG 导出器（例如 GDAL 的 COG 驱动程序）默认使用 LZW 压缩，不使用预测器，但我们建议使用 Zstandard (ZSTD) 压缩（在 GDAL 中为 -co COMPRESS=ZSTD），压缩级别为 16（如果文件大小较小比压缩时间较长更重要，则使用 18–22，COG 驱动程序使用 -co LEVEL=16，GTiff 驱动程序使用 -co ZSTD_LEVEL=16）。将 ZSTD 与预测器（COG 驱动程序中的 -co PREDICTOR=YES，或 GTiff 驱动程序中用于整数的 -co PREDICTOR=2 和用于浮点数的 -co PREDICTOR=3）结合使用。
• 概览放置和重新采样：确保所有图片文件目录 (IFD) 和 2 的幂概览都位于 TIFF 文件的前面，以便 Earth Engine 和 Web 地图查看器可以在单个范围请求中读取概览。专用 COG 导出工具（例如 GDAL 的 COG 驱动程序）默认会在文件开头构建并放置概览。请注意，除非图片具有颜色表，否则 GDAL 的 COG 驱动程序默认采用 CUBIC 概览重采样；对于分类或离散数据（例如土地覆盖分类或 QA 位掩码），请传递 -co OVERVIEW_RESAMPLING=NEAREST（或 MODE），以便缩小的概览不会插值无效的类值。
• 无数据和遮罩：Earth Engine 会自动遮盖与文件的 GDAL_NODATA 标记（在 GDAL 中使用 -a_nodata 设置；浮点数据也支持 NaN）或注册清单中指定的 missingData 值（会覆盖 GDAL_NODATA）匹配的像素。Earth Engine 还支持具有匹配的低分辨率遮罩概览的内部 1 位 TIFF 透明度遮罩。标准额外 Alpha 波段 (ExtraSamples) 会被读取为常规图像波段，而不是自动遮罩。
• 支持的像素数据类型：Earth Engine 支持 uint8、int8、uint16、int16、uint32、int32、int64、float32 和 float64 COG（不支持 uint64、float16、复数和子字节整数类型）。
• BigTIFF 和多线程：始终传递 -co BIGTIFF=YES。GDAL 的默认 BigTIFF 检测会在压缩前估算文件大小，并可能为最终超出 4 GB 限制的文件选择经典 TIFF，从而产生损坏的输出；BigTIFF 使用的额外标头空间可以忽略不计。此外，还需传递 -co NUM_THREADS=ALL_CPUS，以便在所有可用 CPU 核心上并行执行压缩。

以下示例使用统一的 gdal raster convert CLI（在 GDAL 3.11+ 中提供）或 gdal_translate 将 GeoTIFF 转换为经过优化的 COG。在 3.11 之前的 GDAL 版本中省略 INTERLEAVE=BAND，并为分类数据添加 OVERVIEW_RESAMPLING=NEAREST：

# Using the GDAL 3.11+ unified CLI
gdal raster convert src.tif dst.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

# Using gdal_translate (all GDAL versions)
gdal_translate src.tif dst.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

费用注意事项和存储类别

在分析已注册的 COG 资产时，从 Earth Engine 读取数据不会在您的 Google Cloud 项目中产生 Cloud Storage 读取操作或数据检索费用。

Cloud Storage 主要按月度标准静态数据存储（GB/月）以及任何外部客户端数据传输或网络出站流量费用（取决于您的存储桶位置和客户端网络配置）向您收费。

存储类别建议

• Standard Storage（推荐）：Standard Storage 最适合活跃的 Earth Engine 工作流。由于它没有最短存储时长规则，因此您可以自由覆盖、更新或删除临时 COG，而不会产生提前删除罚金。此外，如果您或您的协作者使用桌面 GIS 软件、GDAL 脚本或 Earth Engine 之外的机器学习笔记本访问存储桶，Standard Storage 不会产生任何数据检索费用。
• Nearline、Coldline 和 Archive Storage：所有 Cloud Storage 类别都提供与 Standard Storage 相同的低延迟访问和吞吐量，因此在 Earth Engine 中使用较冷的存储层级时不会影响读取性能。虽然从这些层级读取 Earth Engine 数据也不会产生数据检索费用，但 Cloud Storage 会强制执行严格的最短存储时长（Nearline 为 30 天，Coldline 为 90 天，Archive 为 365 天）。在文件达到最短存储时长之前修改或删除文件会触发提前删除附加费。此外，从任何外部客户端工具访问冷对象都会产生高昂的数据检索附加费。

如需详细了解价格和最短时长政策，请参阅 Google Cloud Storage 价格指南。

简要工作流程

在 Earth Engine 中使用 COG 的典型工作流包括以下步骤：

对于导入外部数据：

• 优化：使用外部工具（例如 GDAL、本地工作站脚本或云处理流水线）将栅格文件转换为 COG 格式。
• 上传：将 COG 上传到受支持位置的 Cloud Storage 存储桶。
• 权限：确保您和所有项目协作者都拥有对文件的 Cloud Storage 读取权限（请参阅 COG 权限）。
• 注册：使用 Python 客户端库、earthengine 命令行工具或 REST API 将 COG 注册为 Earth Engine 资产（请参阅 COG 注册）。

对于导出结果：

• 导出：运行从 Earth Engine 到 Cloud Storage 的批量导出，并将 cloudOptimized 设置为 true（请参阅导出图片）。
• 注册（可选）：将导出的 COG 作为新资产重新注册到 Earth Engine 中，以便进行进一步分析（请参阅 COG 注册）。

准备好开始了吗？请按照详细的 COG 注册指南注册您的第一个资产。如需常见问题的解答，请参阅常见问题解答的 COG 部分。