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 au 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
Lors de l'exportation d'un ee.FeatureCollection vers un fichier TFRecord, il existe une correspondance 1:1 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 à ee.Array stocké dans la propriété. Si vous exportez une table avec des tableaux dans les propriétés, vous devez indiquer à TensorFlow la forme du tableau lorsqu'il est lu. Une table exportée vers un fichier TFRecord est toujours compressée avec le type de compression GZIP. Vous obtenez toujours un seul 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 nombres à virgule flottante 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 caractéristiques scalaires (c'est-à-dire shape=[1]). Si vous exportez des tableaux 2D ou 3D (par exemple, des correctifs d'image), vous devez spécifier la forme de vos correctifs au moment de l'analyse, par exemple shape=[16, 16] pour un correctif de 16 x 16 pixels.
Exporter des images
Lorsque vous exportez une image, les données sont classé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, spécifiés par l'utilisateur dans l'exportation. La taille des fichiers en octets est spécifiée par l'utilisateur dans le paramètre maxFileSize.
Il existe une correspondance 1:1 entre chaque patch et chaque tf.train.Example dans le fichier TFRecord obtenu. Chaque bande de l'image est stockée sous la forme d'un tf.train.Feature distinct dans chaque tf.train.Example, où la longueur de la liste de nombres à virgule flottante stockée dans chaque caractéristique correspond à la largeur * hauteur du patch. Les listes aplaties peuvent être divisées en plusieurs pixels individuels, comme illustré dans cet exemple.
Vous pouvez également récupérer la forme du patch exporté, 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 qui générera des tuiles de taille :
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Chaque tuile chevauche les tuiles 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 correctifs dans l'espace est illustrée par la figure 1, où la dimension de marge intérieure 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 valeurs possibles de formatOptions pour une image exportée au format TFRecord sont les suivantes :
| Propriété | Description | Type |
|---|---|---|
patchDimensions |
Dimensions disposées en mosaïque sur la zone d'exportation, couvrant chaque pixel du cadre de délimitation exactement une fois (sauf si les dimensions du patch ne divisent pas uniformément le cadre de délimitation, auquel cas les tuiles de bordure le long des bords x/y les plus grands seront supprimées). Les dimensions doivent être supérieures à 0. | Array<int>[2]. |
kernelSize |
Si ce paramètre est spécifié, les tuiles seront mises en mémoire tampon par les dimensions de la marge, à la fois positivement et négativement, ce qui entraînera un chevauchement entre les correctifs voisins. Si spécifié, deux dimensions doivent être fournies (X et Y, respectivement). | Array<int>[2]. 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 partitionnement plus important (et donc plus de fichiers de sortie). | Int. Valeur par défaut : 1 Gio |
defaultValue |
Valeur définie dans chaque bande d'un pixel partiellement ou complètement masqué, et valeur définie à chaque valeur d'une caractéristique 3D de sortie créée à partir d'une bande de tableau où la longueur du tableau au niveau du pixel source était inférieure à la profondeur de la valeur de la caractéristique (par exemple, la valeur à l'index 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 du tableau d'entrée à la profondeur des tenseurs 3D qu'elles créent. Les tableaux seront tronqués ou complétés par des valeurs par défaut pour correspondre à la forme spécifiée. Chaque bande de tableau doit avoir une entrée correspondante. | Array<int>[]. Valeur par défaut : [] |
sequenceData |
Si la valeur est "true", chaque pixel est généré sous la forme d'un SequenceExample mappant les bandes scalaires au contexte et les bandes de tableau aux séquences de l'exemple. Les SequenceExamples sont générés dans l'ordre row-major des pixels de chaque patch, puis dans l'ordre row-major des patchs de zone de 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 Tensor 3D, qui prendra le nom de la première bande de l'image. Toutes les bandes sont promues en octets, en int64, puis en floats, dans cet ordre, en fonction du type le plus éloigné dans cette séquence au sein de 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 patch. Les correctifs qui dépassent cette limite seront supprimés plutôt qu'écrits dans des fichiers. Si ce champ est défini sur une valeur autre que 1, le side-car JSON ne sera pas produit. La valeur par défaut est 1. | Valeur float. Valeur par défaut : 1 |
Fichier "mixer" TFRecord
Lorsque vous exportez vers TFRecord, Earth Engine génère un fichier side-car avec vos fichiers TFRecord, appelé "mixer". Il s'agit d'un fichier JSON simple utilisé pour définir l'organisation spatiale des patchs (c'est-à-dire le géoréférencement). Ce fichier est nécessaire pour importer les prédictions effectuées sur l'imagerie, 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 Examples, la région d'exportation est découpée en patchs, qui sont exportés dans l'ordre des lignes vers un certain nombre de fichiers .tfrecord, chaque bande ayant sa propre caractéristique (sauf si vous spécifiez collapseBands). Lorsque vous exportez vers SequenceExamples, un SequenceExample par pixel est exporté, avec ces SequenceExamples dans l'ordre des lignes au sein d'un patch, puis dans l'ordre des lignes des patchs dans la région d'exportation d'origine (en cas de doute, supposez toujours que les éléments seront dans l'ordre des lignes d'une manière ou d'une autre).
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 sont exportables lorsqu'une image est exportée au format TFRecord. L'exportation de bandes de tableaux permet de remplir 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înent la réduction de toutes les bandes en une seule série temporelle par pixel.
Importer des TFRecord 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 1:1 décrite précédemment s'applique dans le sens inverse (c'est-à-dire 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 chevauchante des correctifs (dimension de marge intérieure dans la figure 1) sera supprimée pour obtenir une couverture contiguë de la région exportée. Les prédictions doivent être organisées sous la forme d'une séquence tf.train.Example du même nombre et du même ordre que les exemples d'images exportés à l'origine (même entre un nombre arbitraire de fichiers).