此页面由 Cloud Translation API 翻译。

TFRecord 和 Earth Engine

TFRecord 是一种二进制格式，用于高效编码长序列的 tf.Example proto。TensorFlow 可以通过 tf.data 软件包轻松加载 TFRecord 文件，如此处和此处所述。本页介绍了 Earth Engine 如何在 ee.FeatureCollection 或 ee.Image 与 TFRecord 格式之间进行转换。

将数据导出到 TFRecord

您可以将表格 (ee.FeatureCollection) 或图片 (ee.Image) 导出到 Google 云端硬盘或 Cloud Storage 中的 TFRecord 文件。导出的配置取决于您要导出的内容，如下所述。从 Earth Engine 导出到 TFRecord 的所有数字都会强制转换为浮点类型。

导出表

将 ee.FeatureCollection 导出到 TFRecord 文件时，表中的每个 ee.Feature 与 TFRecord 文件中的每个 tf.train.Example（即每条记录）之间存在 1:1 对应关系。ee.Feature 的每个属性都编码为 tf.train.Feature，其中包含与属性中存储的数字或 ee.Array 对应的浮点数列表。如果您导出包含属性数组的表格，则需要在读取数组时告知 TensorFlow 数组的形状。导出到 TFRecord 文件的表始终会使用 GZIP 压缩类型进行压缩。对于每次导出，您始终会得到一个 TFRecord 文件。

以下示例演示了如何从导出的标量属性表（“B2”“B3”...“B7”“landcover”）中解析数据。请注意，浮点列表的维度为 [1]，类型为 tf.float32：

Python

dataset = tf.data.TFRecordDataset(exportedFilePath)

featuresDict = {
  'B2': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B3': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B4': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B5': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B6': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'B7': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32),
  'landcover': tf.io.FixedLenFeature(shape=[1], dtype=tf.float32)
}

parsedDataset = dataset.map(lambda example: tf.io.parse_single_example(example, featuresDict))

请注意，此示例展示了如何读取标量特征（即 shape=[1]）。如果您要导出二维或三维数组（例如图片补丁），则需要在解析时指定补丁的形状，例如，对于 16x16 像素的补丁，应指定 shape=[16, 16]。

导出图片

导出图片时，数据的顺序为通道、高度、宽度 (CHW)。导出内容可能会拆分为多个 TFRecord 文件，每个文件包含一个或多个大小为 patchSize 的补丁（由用户在导出内容中指定）。文件的大小（以字节为单位）由用户在 maxFileSize 参数中指定。生成的 TFRecord 文件中的每个补丁与每个 tf.train.Example 之间存在 1:1 对应关系。图像的每个波段都存储为每个 tf.train.Example 中的单独 tf.train.Feature，其中每个地图项中存储的浮点数列的长度为补丁宽度 * 高度。扁平化的列表可以拆分为多个单独的像素，如此示例所示。或者，您也可以恢复导出的补丁的形状，如此示例所示。

为减少边缘效应，导出的补丁可以重叠。具体而言，您可以指定一个 kernelSize，以生成大小为：

[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]

每个功能块都与相邻的功能块重叠 [kernelSize[0]/2, kernelSize[1]/2]。因此，以大小为 patchSize 的补丁边缘像素为中心的大小为 kernelSize 的内核包含完全有效的数据。图 1 展示了空间中补丁的空间排列方式，其中 Padding Dimension 对应于内核与相邻图片重叠的部分：

TFRecord 图片示意图 — 图 1. 图片补丁的导出方式。内边距维度为 `kernelSize/2`。

`formatOptions`

patchSize、maxFileSize 和 kernelSize 参数会通过 formatOptions 字典传递给 ee.Export（JavaScript）或 ee.batch.Export（Python）调用，其中键是传递给 Export 的其他参数的名称。导出为 TFRecord 格式的图片的可能 formatOptions 如下：

属性	说明	类型
`patchDimensions`	在导出区域内平铺的尺寸，将完全覆盖边界框中的每个像素一次（除非补丁尺寸无法均匀划分边界框，在这种情况下，系统会舍弃沿最大 x/y 边缘的边界图块）。尺寸必须大于 0。	数组<int>[2]。
`kernelSize`	如果指定，功能块将在正负方向上由边距尺寸缓冲，导致相邻补丁之间出现重叠。如果指定，则必须提供两个尺寸（分别为 X 和 Y）。	数组<int>[2]。默认值：[1, 1]
`compressed`	如果为 true，则使用 gzip 压缩 .tfrecord 文件并附加“.gz”后缀	布尔值。默认值：true
`maxFileSize`	导出的 .tfrecord 的大小上限（压缩前，以字节为单位）。文件越小，分片越多（因此输出文件也越多）。	整数。默认：1 GiB
`defaultValue`	部分或完全被遮盖的像素的每个波段中设置的值，以及由数组波段（源像素的数组长度小于特征值的深度）构成的输出 3D 地图项中的每个值所设置的值（即，数组波段中长度为 2 且对应特征深度为 3 的数组像素的编号为 3 的值）。对于整数类型的频段，系统会舍弃小数部分，并将其限制在频段类型的范围内。默认值为 0。	int。默认值：0
`tensorDepths`	将输入数组波段的名称映射到它们创建的 3D 张量的深度。数组将被截断或用默认值填充，以适应指定的形状。对于每个阵列频段，此字段都必须有相应的条目。	数组<int>[]。默认值：[]
`sequenceData`	如果为 true，则每个像素都会作为 SequenceExample 输出，将标量波段映射到上下文，将数组波段映射到示例的序列。SequenceExample 按每个补丁中的像素行主序输出，然后按文件序列中的区域补丁行主序输出。	布尔值。默认值：false
`collapseBands`	如果为 true，则所有波段都将合并到单个 3D 张量中，并采用图像中第一个波段的名称。所有频段都会依次提升为字节、int64 和浮点数，具体取决于所有频段中序列最靠后的类型。只要指定了 tensor_depths，就可以使用数组波段。	布尔值。默认值：false
`maskedThreshold`	补丁中允许的最大遮盖像素比例。超出此许可的补丁将被舍弃，而不是写入文件。如果将此字段设置为除 1 以外的值，系统将不会生成 JSON 边车。默认为 1。	浮点数。默认值：1

TFRecord“混合器”文件

当您导出到 TFRecord 时，Earth Engine 会生成一个名为“mixer”的与 TFRecord 文件关联的边车文件。这是一个简单的 JSON 文件，用于定义补丁的空间排列（即地理参照）。此文件用于上传基于图像生成的预测结果，如下一部分所述。

导出时间序列

支持将图片导出到 Examples 和 SequenceExamples。当您导出到 Examples 时，导出区域会被切割成多个 patch，这些 patch 会按行优先顺序导出到多个 .tfrecord 文件，每个波段都有自己的特征（除非您指定 collapseBands）。当您导出到 SequenceExample 时，系统会按像素导出一个 SequenceExample，这些 SequenceExample 在 patch 内按行优先顺序排列，然后在原始导出区域内按 patch 的按行优先顺序排列（如果您不确定，请始终假定内容会以某种方式按行优先顺序排列）。注意：图片的任何标量波段都将打包到 SequenceExample 的上下文中，而数组波段将成为实际的序列数据。

数组表带

将图片导出为 TFRecord 格式时，可以导出数组波段。导出数组波段提供了一种填充 SequenceExamples 的“FeatureLists”的方法，以及在导出到常规 Examples 时创建 3D 张量的一种方法。如需了解如何管理数组带的长度/深度，请参阅上表中的 collapseBands 和/或 tensorDepths。注意：使用 collapseBands 并导出到 SequenceExamples（即设置参数 sequenceData）会导致所有波段都被收起为每个像素的单个时间序列。

将 TFRecord 上传到 Earth Engine

您可以将表格（仅限命令行）和图片作为 TFRecord 文件上传到 Earth Engine。对于表，前面介绍的一对一关系在相反方向（即 tf.train.Example -> ee.Feature）也适用。

上传影像

如果您要针对导出的图像生成预测，请在上传预测（以 TFRecord 文件的形式）时提供混合器，以获取已标定地理位置的图像。请注意，系统会舍弃补丁的重叠部分（图 1 中的“Padding Dimension”），以便导出的区域具有连续的覆盖范围。预测结果应排列为与原始导出的图片示例相同数量和顺序的 tf.train.Example 序列（即使在任意数量的文件之间也是如此）。