TFRecord est un format binaire permettant d'encoder efficacement de longues séquences de protos tf.Example. Les fichiers TFRecord sont facilement chargés par TensorFlow via le package tf.data, comme décrit ici et ici.
Cette page décrit comment Earth Engine convertit les formats ee.FeatureCollection ou ee.Image en format TFRecord.
Exporter des données vers TFRecord
Vous pouvez exporter des tables (ee.FeatureCollection) ou des images (ee.Image) vers des fichiers TFRecord dans Google Drive ou Cloud Storage. La configuration de l'exportation dépend de ce que vous exportez, comme décrit ci-dessous. Tous les nombres exportés d'Earth Engine vers TFRecord sont convertis en type float.
Exporter des tables
Lorsque vous exportez un ee.FeatureCollection vers un fichier TFRecord, il existe une correspondance individuelle entre chaque ee.Feature de la table et chaque tf.train.Example (c'est-à-dire chaque enregistrement) du fichier TFRecord. Chaque propriété de ee.Feature est encodée en tant que tf.train.Feature avec une liste de nombres à virgule flottante correspondant au nombre ou au ee.Array stocké dans la propriété. Si vous exportez un tableau avec des tableaux dans les propriétés, vous devez indiquer à TensorFlow la forme du tableau lors de sa lecture. Une table exportée vers un fichier TFRecord est toujours compressée avec le type de compression GZIP. Vous obtenez toujours exactement un fichier TFRecord pour chaque exportation.
L'exemple suivant montre comment analyser les données d'une table exportée de propriétés scalaires ("B2",...,"B7", "landcover"). Notez que la dimension des listes de flottants est [1] et que le type est 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))
Notez que cet exemple illustre la lecture de fonctionnalités scalaires (c'est-à-dire shape=[1]). Si vous exportez des tableaux 2D ou 3D (par exemple, des patches d'image), vous devez spécifier la forme de vos patches au moment de l'analyse, par exemple shape=[16, 16] pour un patch de 16 x 16 pixels.
Exporter des images
Lorsque vous exportez une image, les données sont triées par canaux, hauteur et largeur (CHW). L'exportation peut être divisée en plusieurs fichiers TFRecord, chacun contenant un ou plusieurs correctifs de taille patchSize, qui est spécifié par l'utilisateur lors de l'exportation. La taille des fichiers en octets est spécifiée par l'utilisateur dans le paramètre maxFileSize.
Il existe une correspondance un à un entre chaque correctif et chaque tf.train.Example dans le fichier TFRecord généré. Chaque bande de l'image est stockée en tant que tf.train.Feature distincte dans chaque tf.train.Example, où la longueur de la liste de flottants stockée dans chaque élément géographique correspond à la largeur du patch * hauteur. Les listes aplaties peuvent être divisées en plusieurs pixels individuels, comme illustré dans cet exemple.
La forme du correctif exporté peut également être récupérée, comme dans cet exemple.
Pour réduire les effets de bord, les correctifs exportés peuvent se chevaucher. Plus précisément, vous pouvez spécifier un kernelSize, ce qui entraînera des cartes de taille:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Chaque carte chevauche les cartes adjacentes de [kernelSize[0]/2, kernelSize[1]/2]. Par conséquent, un noyau de taille kernelSize centré sur un pixel de bord d'un patch de taille patchSize contient des données entièrement valides. La disposition spatiale des patches dans l'espace est illustrée par la figure 1, où la dimension de remplissage correspond à la partie du noyau qui chevauche l'image adjacente:
kernelSize/2.
formatOptions
Les paramètres patchSize, maxFileSize et kernelSize sont transmis à l'appel ee.Export (JavaScript) ou ee.batch.Export (Python) via un dictionnaire formatOptions, où les clés sont les noms des paramètres supplémentaires transmis à Export. Les formatOptions possibles pour une image exportée au format TFRecord sont les suivantes:
| Propriété | Description | Type |
|---|---|---|
patchDimensions |
Dimensions en tuiles sur la zone d'exportation, couvrant chaque pixel du cadre de délimitation exactement une fois (sauf lorsque les dimensions de la correction ne divisent pas uniformément le cadre de délimitation, auquel cas les tuiles de bordure le long des bords x/y les plus importants seront supprimées). Les dimensions doivent être supérieures à 0. | Array<int>[2]. |
kernelSize |
Si elles sont spécifiées, les tuiles seront mises en mémoire tampon par les dimensions de marge à la fois positivement et négativement, ce qui entraînera un chevauchement entre les patches voisins. Si elles sont spécifiées, deux dimensions doivent être fournies (X et Y, respectivement). | Array<int>[2]. Valeur par défaut: [1, 1] |
compressed |
Si la valeur est "true", compresse les fichiers .tfrecord avec gzip et ajoute le suffixe ".gz". | Valeur booléenne. Valeur par défaut: true |
maxFileSize |
Taille maximale, en octets, d'un fichier .tfrecord exporté (avant compression). Une taille de fichier plus petite entraîne un fractionnement plus important (et donc un plus grand nombre de fichiers de sortie). | Int. Par défaut: 1 Gio |
defaultValue |
Valeur définie dans chaque bande d'un pixel masqué partiellement ou complètement, et valeur définie à chaque valeur dans une caractéristique 3D de sortie créée à partir d'une bande de tableau dont la longueur du tableau au pixel source était inférieure à la profondeur de la valeur de la caractéristique (c'est-à-dire la valeur à l'indice 3 d'un pixel de tableau de longueur 2 dans une bande de tableau avec une profondeur de caractéristique correspondante de 3). La partie fractionnaire est supprimée pour les bandes de type entier et limitée à la plage du type de bande. La valeur par défaut est 0. | Int. Valeur par défaut: 0 |
tensorDepths |
Mappage des noms des bandes de tableaux d'entrée à la profondeur des tenseurs 3D qu'ils créent. Les tableaux seront tronqués ou complétés par des valeurs par défaut pour s'adapter à la forme spécifiée. Pour chaque bande de tableau, une entrée correspondante doit être définie. | Array<int>[]. Valeur par défaut: [] |
sequenceData |
Si la valeur est "true", chaque pixel est affiché sous la forme d'un exemple de séquence mappant les bandes scalaires au contexte et les bandes de tableaux aux séquences de l'exemple. Les exemples de séquence sont affichés dans l'ordre des pixels par ligne dans chaque patch, puis par ordre des patches de zone par ligne dans la séquence de fichiers. | Valeur booléenne. Valeur par défaut : false |
collapseBands |
Si la valeur est "true", toutes les bandes seront combinées en un seul tenseur 3D, qui prendra le nom de la première bande de l'image. Toutes les bandes sont promues en octets, en int64, puis en flottants dans cet ordre en fonction du type le plus éloigné de cette séquence dans toutes les bandes. Les bandes de tableaux sont autorisées tant que tensor_depths est spécifié. | Valeur booléenne. Valeur par défaut : false |
maskedThreshold |
Proportion maximale autorisée de pixels masqués dans un correctif. Les correctifs qui dépassent cette tolérance seront supprimés plutôt que d'être écrits dans des fichiers. Si ce champ est défini sur une valeur autre que 1, le sidecar JSON ne sera pas généré. La valeur par défaut est 1. | Valeur float. Valeur par défaut : 1 |
Fichier "mélangeur" TFRecord
Lorsque vous exportez au format TFRecord, Earth Engine génère un sidecar avec vos fichiers TFRecord appelé "mélangeur". Il s'agit d'un fichier JSON simple utilisé pour définir l'arrangement spatial des parcelles (géoréférencement, par exemple). Ce fichier est nécessaire pour importer les prédictions effectuées sur les images, comme décrit dans la section suivante.
Exporter des séries temporelles
Les exportations d'images vers Examples et SequenceExamples sont acceptées. Lorsque vous exportez vers des exemples, la région d'exportation est découpée en patches, qui sont exportés dans l'ordre des lignes dans un certain nombre de fichiers .tfrecord, chaque bande ayant sa propre fonctionnalité (sauf si vous spécifiez collapseBands). Lorsque vous exportez vers des séquences d'exemples, un exemple de séquence par pixel est exporté, avec ces exemples de séquences dans l'ordre des lignes dans un patch, puis dans l'ordre des lignes des patches dans la région d'exportation d'origine (en cas de doute, partez toujours du principe que les éléments seront dans l'ordre des lignes dans une certaine mesure).
Remarque: toutes les bandes scalaires d'une image seront empaquetées dans le contexte d'un SequenceExample, tandis que les bandes de tableau deviendront les données de séquence réelles.
Bracelets Array
Les bandes de tableaux peuvent être exportées lorsqu'une image est exportée au format TFRecord. L'exportation des bandes de tableaux permet de renseigner les "FeatureLists" de SequenceExamples et de créer des tenseurs 3D lors de l'exportation vers des exemples standards. Pour en savoir plus sur la gestion des longueurs/profondeurs des bandes de tableaux, consultez collapseBands et/ou tensorDepths dans le tableau ci-dessus. Remarque: L'utilisation de collapseBands et l'exportation vers SequenceExamples (en définissant le paramètre sequenceData) entraîneront le regroupement de toutes les bandes en une seule série temporelle par pixel.
Importer des TFRecords dans Earth Engine
Vous pouvez importer des tables (ligne de commande uniquement) et des images dans Earth Engine en tant que fichiers TFRecord. Pour les tables, la relation individuelle décrite précédemment s'applique dans le sens inverse (tf.train.Example -> ee.Feature).
Importation d'images
Si vous générez des prédictions sur des images exportées, fournissez le mélangeur lorsque vous importez les prédictions (sous forme de fichiers TFRecord) pour obtenir des images géoréférencées. Notez que la partie des correctifs qui se chevauchent (dimension "Padding" dans la figure 1) sera supprimée pour obtenir une couverture continue de la région exportée. Les prédictions doivent être organisées en séquence tf.train.Example du même nombre et de la même manière que les exemples d'images exportés à l'origine (même entre un nombre arbitraire de fichiers).