TFRecord
es un formato binario para codificar de manera eficiente secuencias largas de
prototipos de
tf.Example. TensorFlow carga con facilidad los archivos TFRecord a través del paquete tf.data, como se describe aquí y aquí.
En esta página, se describe cómo Earth Engine convierte entre ee.FeatureCollection
o ee.Image y el formato TFRecord.
Exporta datos a TFRecord
Puedes exportar tablas (ee.FeatureCollection) o imágenes (ee.Image)
a archivos TFRecord en Google Drive o Cloud Storage. La configuración de la exportación depende
de lo que exportes, como se describe a continuación. Todos los números exportados de Earth Engine a
TFRecord se convierten al tipo float.
Exporta tablas
Cuando se exporta un ee.FeatureCollection a un archivo TFRecord, hay una correspondencia de 1:1 entre cada ee.Feature de la tabla y cada tf.train.Example (es decir, cada registro) del archivo TFRecord. Cada propiedad de ee.Feature se
codifica como un
tf.train.Feature
con una lista de números de punto flotante que corresponden al número o ee.Array almacenados en la
propiedad. Si exportas una tabla con arrays en las propiedades, debes indicarle a TensorFlow
la forma del array cuando se lee. Una tabla exportada a un archivo TFRecord siempre
se comprimirá con el tipo de compresión GZIP. Siempre obtienes exactamente un archivo TFRecord por
cada exportación.
En el siguiente ejemplo, se muestra cómo analizar datos de una tabla exportada de propiedades escalares
('B2',…,'B7', 'landcover'). Ten en cuenta que la dimensión de las listas de números de punto flotante es
[1] y el tipo es 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))
Ten en cuenta que en este ejemplo se ilustra la lectura de atributos escalares (es decir, shape=[1]).
Si exportas arrays en 2D o 3D (p. ej., parches de imágenes), debes especificar la
forma de tus parches en el momento del análisis, por ejemplo, shape=[16, 16] para un parche de 16 x 16
píxeles.
Exporta imágenes
Cuando exportas una imagen, los datos se ordenan como canales, altura y ancho (CHW). La
exportación se puede dividir en varios archivos TFRecord, y cada uno de ellos puede contener uno o más
parches de tamaño patchSize, que el usuario especifica en la exportación. El
tamaño de los archivos en bytes se especifica en el parámetro maxFileSize.
Hay una correspondencia de 1:1 entre cada parche y cada tf.train.Example en el archivo TFRecord resultante. Cada banda de la imagen se almacena como un tf.train.Feature independiente en cada tf.train.Example, donde la longitud de la lista de números de punto flotante almacenada en cada atributo es el ancho * la altura del parche. Las listas compactadas se pueden dividir en
varios píxeles individuales, como se muestra en
este ejemplo.
O bien, la forma del parche exportado se puede recuperar como en
este ejemplo.
Para ayudar a reducir los efectos de borde, los parches exportados se pueden superponer. Específicamente, puedes
especificar un kernelSize, lo que dará como resultado tarjetas con el siguiente tamaño:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Cada mosaico se superpone con los mosaicos adyacentes en un [kernelSize[0]/2, kernelSize[1]/2]. Como resultado, un kernel de tamaño kernelSize centrado en un píxel de borde de un parche de tamaño patchSize contiene datos completamente válidos. La disposición espacial de los parches en el espacio se ilustra en la Figura 1, en la que la dimensión del relleno corresponde a la parte del kernel que se superpone con la imagen adyacente:
kernelSize/2.
formatOptions
Los parámetros patchSize, maxFileSize y kernelSize
se pasan a la llamada ee.Export (JavaScript) o ee.batch.Export
(Python) a través de un diccionario formatOptions, en el que las claves son los nombres
de los parámetros adicionales que se pasan a Export. Los posibles valores de formatOptions
para una imagen exportada al formato TFRecord son los siguientes:
| Propiedad | Descripción | Tipo |
|---|---|---|
patchDimensions |
Son las dimensiones que se colocan en mosaico sobre el área de exportación y que cubren cada píxel del cuadro delimitador exactamente una vez (excepto cuando las dimensiones del parche no dividen de manera uniforme el cuadro delimitador, en cuyo caso se descartarán los mosaicos de borde a lo largo de los bordes x/y más grandes). Las dimensiones deben ser > 0. | Array<int>[2]. |
kernelSize |
Si se especifica, las tarjetas se almacenarán en búfer según las dimensiones del margen, tanto de forma positiva como negativa, lo que generará una superposición entre los parches vecinos. Si se especifica, se deben proporcionar dos dimensiones (X e Y, respectivamente). | Array<int>[2]. Valor predeterminado: [1, 1] |
compressed |
Si es verdadero, comprime los archivos .tfrecord con gzip y agrega el sufijo ".gz". | Booleano. Configuración predeterminada: true |
maxFileSize |
Es el tamaño máximo, en bytes, de un archivo .tfrecord exportado (antes de la compresión). Un tamaño de archivo más pequeño generará una mayor fragmentación (y, por lo tanto, más archivos de salida). | Int. Valor predeterminado: 1 GiB |
defaultValue |
Es el valor establecido en cada banda de un píxel que está enmascarado de forma parcial o total, y el valor establecido en cada valor de un atributo 3D de salida creado a partir de una banda de array en la que la longitud del array en el píxel de origen era menor que la profundidad del valor del atributo (es decir, el valor en el índice 3 de un píxel de array de longitud 2 en una banda de array con una profundidad de atributo correspondiente de 3). La parte fraccionaria se descarta para las bandas de tipo entero y se limita al rango del tipo de banda. La configuración predeterminada es 0. | Int. Valor predeterminado: 0 |
tensorDepths |
Asignación de los nombres de las bandas de arrays de entrada a la profundidad de los tensores 3D que crean. Los arrays se truncarán o se rellenarán con valores predeterminados para que se ajusten a la forma especificada. Para cada banda de array, debe haber una entrada correspondiente. | Array<int>[]. Valor predeterminado: [] |
sequenceData |
Si es verdadero, cada píxel se genera como un SequenceExample que asigna bandas escalares al contexto y bandas de array a las secuencias del ejemplo. Los SequenceExamples se generan en el orden de fila principal de los píxeles de cada parche y, luego, en el orden de fila principal de los parches de área en la secuencia de archivos. | Booleano. Valor predeterminado: false |
collapseBands |
Si es verdadero, todas las bandas se combinarán en un solo tensor 3D, que tomará el nombre de la primera banda de la imagen. Todas las bandas se promocionan a bytes, int64 y, luego, a números de punto flotante en ese orden, según el tipo más alejado de esa secuencia en todas las bandas. Se permiten las bandas de arrays siempre que se especifique tensor_depths. | Booleano. Valor predeterminado: false |
maskedThreshold |
Es la proporción máxima permitida de píxeles enmascarados en un parche. Los parches que superen este límite se descartarán en lugar de escribirse en archivos. Si este campo se establece en cualquier valor que no sea 1, no se producirá el archivo adicional JSON. El valor predeterminado es 1. | Es un argumento flotante. Predeterminado: 1 |
El archivo “mezclador” de TFRecord
Cuando exportes a TFRecord, Earth Engine generará un archivo adicional con tus archivos TFRecord llamado “mezclador”. Este es un archivo JSON simple que se usa para definir la disposición espacial de los parches (es decir, la georreferenciación). Este archivo es necesario para subir las predicciones realizadas en las imágenes, como se describe en la siguiente sección.
Exporta series temporales
Se admiten las exportaciones de imágenes a Examples y SequenceExamples. Cuando exportas a
Examples, la región de exportación se corta en parches y esos parches se exportan en
orden de fila principal a una cantidad de archivos .tfrecord con cada banda como su propio atributo
(a menos que especifiques collapseBands). Cuando exportas a SequenceExamples,
se exportará un SequenceExample por píxel, con esos SequenceExamples en orden de fila
principal dentro de un parche y, luego, en orden de fila principal de parches en la región de exportación original
(si tienes dudas, siempre asume que los elementos estarán en orden de fila principal de alguna manera).
Nota: Cualquier banda escalar de una imagen se empaquetará en el contexto de un SequenceExample,
mientras que las bandas de array se convertirán en los datos de secuencia reales.
Correas de eslabones
Las bandas de arrays se pueden exportar cuando una imagen se exporta al formato TFRecord. La exportación de
bandas de arrays proporciona un medio para propagar las “FeatureLists” de SequenceExamples y una
forma de crear tensores 3D cuando se exporta a Examples normales. Para obtener información sobre cómo se administran las longitudes y profundidades de las bandas de arrays, consulta collapseBands o tensorDepths en la tabla anterior. Nota: El uso de collapseBands
y la exportación a SequenceExamples (es decir, la configuración del parámetro sequenceData)
provocará que todas las bandas se contraigan en una sola serie temporal por píxel.
Sube TFRecords a Earth Engine
Puedes subir tablas (solo con la línea de comandos) y, también, imágenes
a Earth Engine como archivos TFRecord. Para las tablas, la relación 1:1 descrita anteriormente se aplica en la dirección inversa (es decir, tf.train.Example -> ee.Feature).
Cómo subir imágenes
Si generas predicciones sobre imágenes exportadas, proporciona el mezclador cuando subas las
predicciones (como archivos TFRecord) para obtener imágenes georreferenciadas. Ten en cuenta que se descartará la parte superpuesta
de los parches (dimensión de relleno en la figura 1) para que la cobertura de la región exportada sea
contigua. Las predicciones deben organizarse como una secuencia tf.train.Example de la misma cantidad y orden que los ejemplos de imágenes exportados originalmente (incluso entre una cantidad arbitraria de archivos).