TFRecord es un formato binario para codificar de forma eficiente secuencias largas de protos de tf.Example. TensorFlow carga fácilmente 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.
Cómo exportar 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 de número de punto flotante.
Cómo exportar tablas
Cuando se exporta un ee.FeatureCollection a un archivo TFRecord, existe una correspondencia de 1:1 entre cada ee.Feature en la tabla y cada tf.train.Example (es decir, cada registro) en el 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 para cada exportación.
En el siguiente ejemplo, se muestra cómo analizar datos de una tabla exportada de propiedades escalares ('B2',...,'B7', 'cobertura del suelo'). Ten en cuenta que la dimensión de las listas de números de punto flotante es [1] y el tipo es tf.float32:
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 este ejemplo ilustra la lectura de componentes escalares (es decir, shape=[1]).
Si exportas arrays 2D o 3D (p. ej., parches de imagen), debes especificar la
forma de tus parches en el momento del análisis, por ejemplo, shape=[16, 16] para un parche de pixeles de 16 × 16.
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, cada uno de los cuales contiene 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 es especificado por el usuario 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 componente es el ancho del parche × la altura. Las listas aplanadas 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 los bordes, los parches exportados pueden superponerse. Específicamente, puedes especificar un kernelSize que generará tarjetas del siguiente tamaño:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Cada tarjeta se superpone con las tarjetas adyacentes en [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, donde la dimensión de padding 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 formatOptions para una imagen exportada al formato TFRecord son los siguientes:
| Propiedad | Descripción | Tipo |
|---|---|---|
patchDimensions |
Dimensiones en mosaico sobre el área de exportación, que cubren cada píxel del cuadro de límite exactamente una vez (excepto cuando las dimensiones del parche no dividen de forma uniforme el cuadro de límite, en cuyo caso se descartarán las tarjetas de borde a lo largo de los bordes x/y más grandes). Las dimensiones deben ser superiores a 0. | Array<int>[2]. |
kernelSize |
Si se especifica, las tarjetas se almacenarán en búfer con las dimensiones del margen de forma positiva y negativa, lo que provocará 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. Predeterminado: 1 GiB |
defaultValue |
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 componente 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 componente (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 componente correspondiente de 3). La parte fraccionaria se descarta para las bandas de tipo de número entero y se ajusta al rango del tipo de banda. La configuración predeterminada es 0. | Int. Predeterminado: 0 |
tensorDepths |
Asignación de los nombres de las bandas del array de entrada a la profundidad de los tensores 3D que crean. Los arrays se truncarán o se rellenarán con valores predeterminados para adaptarse a la forma especificada. Para cada banda del array, debe tener una entrada correspondiente. | Array<int>[]. Opción predeterminada: [] |
sequenceData |
Si es verdadero, cada píxel se muestra como un SequenceExample que asigna bandas escalares al contexto y bandas de array a las secuencias del ejemplo. Los SequenceExamples se muestran en orden de filas de píxeles en cada parche y, luego, en orden de filas de 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 en 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 dentro de todas las bandas. Se permiten las bandas de array 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 esta tolerancia se descartarán en lugar de escribirse en los archivos. Si este campo se establece en cualquier valor que no sea 1, no se producirá el Sidecar JSON. El valor predeterminado es 1. | Es un argumento flotante. Predeterminado: 1 |
El archivo “mixer” de TFRecord
Cuando exportes a TFRecord, Earth Engine generará un contenedor lateral con tus archivos de TFRecord llamado “mixer”. Este es un archivo JSON simple que se usa para definir la disposición espacial de los parches (es decir, la georeferenciación). Este archivo es necesario para subir las predicciones realizadas en las imágenes, como se describe en la siguiente sección.
Cómo exportar 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 filas principales a una cantidad de archivos .tfrecord con cada banda su propia función (a menos que especifiques collapseBands). Cuando exportas a SequenceExamples, se exportará un SequenceExample por píxel, con esos SequenceExamples en orden de filas principales dentro de un parche y, luego, en orden de filas principales de parches en la región de exportación original (si tienes dudas, siempre asume que todo estará en orden de filas principales en algún momento).
Nota: Todas las bandas escalares de una imagen se empaquetarán en el contexto de un SequenceExample, mientras que las bandas del array se convertirán en los datos de secuencia reales.
Bandas de array
Las bandas de array se pueden exportar cuando se exporta una imagen al formato TFRecord. La exportación de bandas de array 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 o profundidades de las bandas del array, consulta collapseBands o tensorDepths en la tabla anterior. Nota: El uso de collapseBands y la exportación a SequenceExamples (por lo que se establece el parámetro sequenceData) hará que todas las bandas se reduzcan a una sola serie temporal por píxel.
Cómo subir TFRecords a Earth Engine
Puedes subir tablas (solo desde la línea de comandos) e imágenes a Earth Engine como archivos TFRecord. En el caso de 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 en imágenes exportadas, proporciona el mezclador cuando subas las predicciones (como archivos TFRecord) para obtener imágenes georeferenciadas. Ten en cuenta que se descartará la parte superpuesta de los parches (dimensión de padding en la Figura 1) para obtener una cobertura contigua de la región exportada. Las predicciones deben organizarse como una secuencia tf.train.Example del mismo número y orden que tus ejemplos de imágenes exportadas originalmente (incluso entre una cantidad arbitraria de archivos).