TFRecord – двоичный формат для эффективного кодирования длинных последовательностей прототипов tf.Example. Файлы TFRecord легко загружаются в TensorFlow с помощью пакета tf.data, как описано здесь и здесь.
На этой странице описано, как Earth Engine преобразует данные из формата ee.FeatureCollection или ee.Image в формат TFRecord и обратно.
Экспорт данных в TFRecord
Вы можете экспортировать таблицы (ee.FeatureCollection) или изображения (ee.Image) в файлы TFRecord на Google Диске или в Cloud Storage. Конфигурация экспорта зависит от того, что именно вы экспортируете. Все числа, экспортируемые из Earth Engine в TFRecord, приводятся к типу float.
Экспорт таблиц
При экспорте ee.FeatureCollection в файл TFRecord между каждой ee.Feature в таблице и каждым tf.train.Example (т.е. каждой записью) в файле TFRecord устанавливается соответствие 1:1. Каждое свойство ee.Feature кодируется как tf.train.Feature со списком чисел с плавающей запятой, соответствующих числу или ee.Array, хранящемуся в свойстве. Если вы экспортируете таблицу с массивами в свойствах, вам нужно сообщить TensorFlow форму массива при его чтении. Таблица, экспортированная в файл TFRecord, всегда будет сжата с использованием типа сжатия GZIP. При каждом экспорте вы всегда получаете ровно один файл TFRecord.
В следующем примере показан синтаксический анализ данных из экспортированной таблицы скалярных свойств ('B2',...,'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]). Если вы экспортируете двумерные или трехмерные массивы (например, фрагменты изображений), то вам нужно будет указать форму фрагментов во время синтаксического анализа, например shape=[16, 16] для фрагмента размером 16 x 16 пикселей.
Экспорт изображений…
При экспорте изображения данные упорядочиваются по каналам, высоте и ширине (CHW). Экспортируемые данные могут быть разделены на несколько файлов TFRecord, каждый из которых содержит один или несколько фрагментов размером patchSize, указанным пользователем при экспорте. Размер файлов в байтах указывается пользователем в параметре maxFileSize.
Между каждым фрагментом и каждым объектом tf.train.Example в итоговом файле TFRecord существует соответствие 1:1. Каждая полоса изображения хранится как отдельный объект tf.train.Feature в каждом tf.train.Example, где длина списка чисел с плавающей запятой, хранящегося в каждом объекте, равна ширине фрагмента, умноженной на высоту. Выровненные списки можно разделить на несколько отдельных пикселей, как показано в этом примере.
или восстановить форму экспортированного фрагмента, как показано в этом примере.
Чтобы уменьшить краевые эффекты, экспортируемые фрагменты могут перекрываться. В частности, вы можете указать kernelSize, в результате чего получатся фрагменты следующего размера:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Каждый фрагмент перекрывает соседние на [kernelSize[0]/2, kernelSize[1]/2]. В результате ядро размером kernelSize с центром в пикселе на краю фрагмента размером patchSize содержит полностью действительные данные. Пространственное расположение фрагментов показано на рисунке 1, где размер отступа соответствует части ядра, которая перекрывает соседнее изображение.
kernelSize/2.
formatOptions
Параметры patchSize, maxFileSize и kernelSize передаются в вызов ee.Export (JavaScript) или ee.batch.Export (Python) через словарь formatOptions, где ключи – это названия дополнительных параметров, передаваемых в Export. Возможные значения formatOptions для изображения, экспортированного в формате TFRecord:
| Свойство | Описание | Тип |
|---|---|---|
patchDimensions |
Размеры фрагментов, на которые разбивается область экспорта. Каждый пиксель в граничной рамке должен быть покрыт ровно один раз (если размеры фрагмента не делят граничную рамку на равные части, то фрагменты вдоль границ с наибольшими значениями x/y будут отброшены). Размеры должны быть больше нуля. | Массив<int>[2]. |
kernelSize |
Если указано, фрагменты будут буферизованы по размерам полей как положительно, так и отрицательно, что приведет к перекрытию между соседними фрагментами. Если вы указываете это свойство, необходимо задать два размера (X и Y). | Массив<int>[2]. Значение по умолчанию: [1, 1]. |
compressed |
Если задано значение true, сжимает файлы .tfrecord с помощью gzip и добавляет суффикс .gz. | Логическое значение. Значение по умолчанию: true. |
maxFileSize |
Максимальный размер экспортированного файла .tfrecord в байтах (до сжатия). Чем меньше размер файла, тем больше будет сегментов (и, следовательно, выходных файлов). | Целое число. Значение по умолчанию: 1 ГиБ. |
defaultValue |
Значение, заданное в каждом диапазоне пикселя, который частично или полностью замаскирован, и значение, заданное для каждого значения в выходном трехмерном объекте, созданном из диапазона массива, где длина массива в исходном пикселе была меньше глубины значения объекта (т.е. значение с индексом 3 пикселя массива длиной 2 в диапазоне массива с соответствующей глубиной объекта 3). Для целочисленных типов полос дробная часть отбрасывается и ограничивается диапазоном типа полосы. Значение по умолчанию – 0. | Целое число. Значение по умолчанию: 0. |
tensorDepths |
Сопоставление названий каналов входного массива с глубиной создаваемых ими трехмерных тензоров. Массивы будут усечены или дополнены значениями по умолчанию, чтобы соответствовать указанной форме. Для каждого диапазона массива должна быть соответствующая запись. | Массив<int>[]. По умолчанию: [] |
sequenceData |
Если задано значение true, каждый пиксель выводится как SequenceExample, сопоставляющий скалярные полосы с контекстом, а полосы массива – с последовательностями примера. Объекты SequenceExample выводятся в порядке построчного сканирования пикселей в каждом фрагменте, а затем в порядке построчного сканирования фрагментов в последовательности файлов. | Логическое значение. Значение по умолчанию: false. |
collapseBands |
Если задано значение True, все полосы будут объединены в один трехмерный тензор, который получит название первой полосы на изображении. Все каналы преобразуются в байты, int64, а затем в числа с плавающей запятой в указанном порядке в зависимости от типа, наиболее удаленного в этой последовательности во всех каналах. Полосы массива разрешены, если указан параметр tensor_depths. | Логическое значение. Значение по умолчанию: false. |
maskedThreshold |
Максимально допустимая доля замаскированных пикселей в фрагменте. Исправления, превышающие это ограничение, будут удалены, а не записаны в файлы. Если в этом поле указано любое значение, кроме 1, то сопутствующий файл JSON не будет создан. (значение по умолчанию – 1). | число с плавающей запятой. Значение по умолчанию: 1. |
Файл TFRecord mixer
При экспорте в TFRecord Earth Engine создаст сопутствующий файл с вашими файлами TFRecord, который называется "микшер". Это простой файл JSON, используемый для определения пространственного расположения фрагментов (т.е. геопривязки). Этот файл нужен для загрузки прогнозов, сделанных на основе снимков, как описано в следующем разделе.
Экспорт временных рядов
Поддерживается экспорт изображений в Examples и SequenceExamples. При экспорте в Examples регион экспорта разбивается на фрагменты, которые экспортируются в порядке построчного сканирования в несколько файлов .tfrecord, причем каждый диапазон представляет собой отдельный признак (если вы не укажете collapseBands). При экспорте в SequenceExamples будет экспортирован один SequenceExample на пиксель, причем эти SequenceExamples будут расположены в порядке построчного сканирования в пределах фрагмента, а затем в порядке построчного сканирования фрагментов в исходном регионе экспорта (если вы не уверены, всегда предполагайте, что элементы будут расположены в порядке построчного сканирования в той или иной степени).
Примечание. Любые скалярные полосы изображения будут упакованы в контекст SequenceExample, а полосы массива станут фактическими данными последовательности.
Ремешки Array
Полосы массива можно экспортировать, когда изображение экспортируется в формате TFRecord. Экспорт массивов позволяет заполнять FeatureLists в SequenceExamples и создавать трехмерные тензоры при экспорте в обычные Examples. Информацию о том, как управлять длиной и глубиной полос массива, можно найти в строках collapseBands и tensorDepths таблицы выше. Примечание. Использование collapseBands и экспорт в SequenceExamples (то есть настройка параметра sequenceData) приведет к тому, что все диапазоны будут свернуты в один временной ряд на пиксель.
Загрузка TFRecords в Earth Engine
Вы можете загружать таблицы (только командная строка) и изображения в Earth Engine в виде файлов TFRecord. Для таблиц отношение "один к одному", описанное выше, применяется в обратном направлении (то есть tf.train.Example -> ee.Feature).
Загрузка изображений
Если вы генерируете прогнозы на основе экспортированных изображений, предоставьте микшер при загрузке прогнозов (в виде файлов TFRecord), чтобы получить изображения с географической привязкой. Обратите внимание, что перекрывающаяся часть фрагментов (размер отступа на рисунке 1) будет отброшена, чтобы получить смежное покрытие экспортируемого региона. Прогнозы должны быть упорядочены в виде последовательности tf.train.Example с тем же количеством и порядком, что и в исходно экспортированных примерах изображений (даже между произвольным количеством файлов).