TFRecord ist ein Binärformat für die effiziente Codierung langer Sequenzen von tf.Example-Protos. TFRecord-Dateien können von TensorFlow ganz einfach über das Paket tf.data geladen werden, wie hier und hier beschrieben.
Auf dieser Seite wird beschrieben, wie Earth Engine zwischen ee.FeatureCollection oder ee.Image und dem TFRecord-Format konvertiert.
Daten nach TFRecord exportieren
Sie können Tabellen (ee.FeatureCollection) oder Bilder (ee.Image) in TFRecord-Dateien in Google Drive oder Cloud Storage exportieren. Die Konfiguration des Exports hängt davon ab, was Sie exportieren, wie unten beschrieben. Alle von Earth Engine nach TFRecord exportierten Zahlen werden in den Typ „float“ umgewandelt.
Tabellen exportieren
Beim Exportieren einer ee.FeatureCollection in eine TFRecord-Datei besteht eine 1:1-Entsprechung zwischen jeder ee.Feature in der Tabelle und jedem tf.train.Example (d.h. jedem Datensatz) in der TFRecord-Datei. Jedes Attribut des ee.Feature wird als tf.train.Feature mit einer Liste von Gleitkommazahlen codiert, die der im Attribut gespeicherten Zahl oder dem im Attribut gespeicherten ee.Array entsprechen. Wenn Sie eine Tabelle mit Arrays in den Attributen exportieren, müssen Sie TensorFlow die Form des Arrays beim Lesen mitteilen. Eine in eine TFRecord-Datei exportierte Tabelle wird immer mit dem GZIP-Komprimierungstyp komprimiert. Sie erhalten für jeden Export immer genau eine TFRecord-Datei.
Im folgenden Beispiel wird das Parsen von Daten aus einer exportierten Tabelle mit skalaren Attributen („B2“,..., „B7“, „landcover“) veranschaulicht. Die Dimension der Gleitkommalisten ist [1] und der Typ ist 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))
In diesem Beispiel wird das Lesen skalarer Features (d. h. shape=[1]) veranschaulicht. Wenn Sie 2D- oder 3D-Arrays (z. B. Bild-Patches) exportieren, geben Sie die Form der Patches beim Parsen an, z. B. shape=[16, 16] für einen Patch mit 16 × 16 Pixeln.
Images exportieren
Wenn Sie ein Bild exportieren, werden die Daten als Kanäle, Höhe, Breite (CHW) sortiert. Der Export kann in mehrere TFRecord-Dateien aufgeteilt werden, wobei jede Datei einen oder mehrere Patches der Größe patchSize enthält, die vom Nutzer im Export angegeben wird. Die Größe der Dateien in Byte wird vom Nutzer im Parameter maxFileSize angegeben.
Es gibt eine 1:1-Entsprechung zwischen jedem Patch und jedem tf.train.Example in der resultierenden TFRecord-Datei. Jedes Band des Bildes wird als separates tf.train.Feature in jedem tf.train.Example gespeichert, wobei die Länge der in jedem Feature gespeicherten Gleitkommaliste der Patchbreite * Höhe entspricht. Die vereinfachten Listen können in mehrere einzelne Pixel aufgeteilt werden, wie in diesem Beispiel gezeigt.
Oder die Form des exportierten Patches kann wie in diesem Beispiel wiederhergestellt werden.
Um Randeffekte zu reduzieren, können sich die exportierten Patches überlappen. Konkret können Sie einen kernelSize angeben, was zu Kacheln der folgenden Größe führt:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Jede Kachel überlappt benachbarte Kacheln um [kernelSize[0]/2, kernelSize[1]/2]. Daher enthält ein Kernel der Größe kernelSize, der auf einem Randpixel eines Patches der Größe patchSize zentriert ist, vollständig gültige Daten. Die räumliche Anordnung der Patches im Raum ist in Abbildung 1 dargestellt. Die Padding-Dimension entspricht dem Teil des Kernels, der das angrenzende Bild überlappt:
kernelSize/2.
formatOptions
Die Parameter patchSize, maxFileSize und kernelSize werden über ein formatOptions-Wörterbuch an den Aufruf ee.Export (JavaScript) oder ee.batch.Export (Python) übergeben. Die Schlüssel sind die Namen zusätzlicher Parameter, die an Export übergeben werden. Mögliche formatOptions für ein Bild, das im TFRecord-Format exportiert wurde:
| Attribut | Beschreibung | Typ |
|---|---|---|
patchDimensions |
Dimensionen, die über den Exportbereich gekachelt sind und jeden Pixel im Begrenzungsrahmen genau einmal abdecken (außer wenn die Patch-Dimensionen den Begrenzungsrahmen nicht gleichmäßig teilen, in diesem Fall werden Randkacheln entlang der größten x/y-Kanten weggelassen). Die Abmessungen müssen größer als 0 sein. | Array<int>[2]. |
kernelSize |
Wenn angegeben, werden die Kacheln sowohl positiv als auch negativ um die Randabmessungen gepuffert, was zu einer Überlappung zwischen benachbarten Patches führt. Wenn angegeben, müssen zwei Dimensionen angegeben werden (X und Y). | Array<int>[2]. Standard: [1, 1] |
compressed |
Wenn „true“, werden die .tfrecord-Dateien mit gzip komprimiert und das Suffix „.gz“ wird angehängt. | Boolescher Wert. Standardwert: true |
maxFileSize |
Maximale Größe in Byte für eine exportierte .tfrecord-Datei (vor der Komprimierung). Eine kleinere Dateigröße führt zu einer stärkeren Fragmentierung (und damit zu mehr Ausgabedateien). | Int. Standard: 1 GiB |
defaultValue |
Der Wert, der in jedem Band eines Pixels festgelegt ist, das teilweise oder vollständig maskiert ist, und der Wert, der für jeden Wert in einem 3D-Ausgabefeature festgelegt ist, das aus einem Arrayband erstellt wurde, wobei die Arraylänge am Quellpixel kleiner als die Tiefe des Featurewerts war (z.B. der Wert bei Index 3 eines Arraypixels der Länge 2 in einem Arrayband mit einer entsprechenden Featuretiefe von 3). Der Bruchteil wird für Bänder vom Typ „Ganzzahl“ verworfen und auf den Bereich des Bandtyps beschränkt. Die Standardeinstellung ist 0. | Int. Standardwert: 0 |
tensorDepths |
Zuordnung der Namen von Eingabearray-Bändern zur Tiefe der von ihnen erstellten 3D-Tensoren. Arrays werden gekürzt oder mit Standardwerten aufgefüllt, um der angegebenen Form zu entsprechen. Für jedes Arrayband muss ein entsprechender Eintrag vorhanden sein. | Array<int>[]. Standard: [] |
sequenceData |
Wenn „true“, wird jedes Pixel als SequenceExample ausgegeben, wobei skalare Bänder dem Kontext und Arraybänder den Sequenzen des Beispiels zugeordnet werden. Die SequenceExamples werden in zeilenweiser Reihenfolge der Pixel in jedem Patch und dann in zeilenweiser Reihenfolge der Bereichspatches in der Dateisequenz ausgegeben. | Boolescher Wert. Standardwert: false |
collapseBands |
Wenn „true“, werden alle Bänder zu einem einzigen 3D-Tensor kombiniert, der den Namen des ersten Bands im Bild annimmt. Alle Bänder werden in dieser Reihenfolge in Byte, Int64 und dann in Gleitkommazahlen umgewandelt, je nachdem, welcher Typ in dieser Sequenz in allen Bändern am weitesten hinten liegt. Arraybänder sind zulässig, solange tensor_depths angegeben ist. | Boolescher Wert. Standardwert: false |
maskedThreshold |
Maximal zulässiger Anteil maskierter Pixel in einem Patch. Patches, die dieses Kontingent überschreiten, werden verworfen, anstatt in Dateien geschrieben zu werden. Wenn dieses Feld auf einen anderen Wert als 1 festgelegt ist, wird die JSON-Sidecar-Datei nicht erstellt. Der Standardfaktor ist 1. | Gleitkommazahl. Standardeinstellung: 1 |
Die TFRecord-„Mixer“-Datei
Wenn Sie Daten nach TFRecord exportieren, generiert Earth Engine eine Sidecar-Datei mit Ihren TFRecord-Dateien, die als „Mixer“ bezeichnet wird. Dies ist eine einfache JSON-Datei, mit der die räumliche Anordnung der Patches (d.h. die Georeferenzierung) definiert wird. Diese Datei wird benötigt, um Vorhersagen hochzuladen, die für die Bilder getroffen wurden, wie im nächsten Abschnitt beschrieben.
Zeitreihe exportieren
Bildexporte in „Examples“ und „SequenceExamples“ werden unterstützt. Wenn Sie nach „Examples“ exportieren, wird die Exportregion in Patches aufgeteilt. Diese Patches werden in zeilenweiser Reihenfolge in eine bestimmte Anzahl von TFRecord-Dateien exportiert, wobei jedes Band ein eigenes Feature ist (es sei denn, Sie geben collapseBands an). Wenn Sie nach „SequenceExamples“ exportieren, wird ein SequenceExample pro Pixel exportiert. Diese SequenceExamples sind innerhalb eines Patches in zeilenweiser Reihenfolge und dann in zeilenweiser Reihenfolge der Patches in der ursprünglichen Exportregion angeordnet. Wenn Sie sich unsicher sind, gehen Sie immer davon aus, dass die Daten in irgendeiner Form in zeilenweiser Reihenfolge vorliegen.
Hinweis: Alle skalaren Bänder eines Bildes werden in den Kontext eines SequenceExample gepackt, während die Arraybänder zu den eigentlichen Sequenzdaten werden.
Array-Armbänder
Arraybänder können exportiert werden, wenn ein Bild im TFRecord-Format exportiert wird. Durch den Export von Arraybändern können die „FeatureLists“ von SequenceExamples gefüllt und 3D-Tensoren beim Export in reguläre Examples erstellt werden. Informationen dazu, wie die Längen/Tiefen von Arraybändern verwaltet werden, finden Sie in der Tabelle oben unter collapseBands und/oder tensorDepths. Hinweis: Wenn Sie collapseBands verwenden und nach SequenceExamples exportieren (also den Parameter sequenceData festlegen), werden alle Bänder zu einer einzigen Zeitreihe pro Pixel zusammengefasst.
TFRecords in die Earth Engine hochladen
Sie können Tabellen (nur Befehlszeile) und Bilder als TFRecord-Dateien in Earth Engine hochladen. Für Tabellen gilt die zuvor beschriebene 1:1-Beziehung in umgekehrter Richtung (d.h. tf.train.Example -> ee.Feature).
Bilder hochladen
Wenn Sie Vorhersagen für exportierte Bilder generieren, geben Sie den Mixer an, wenn Sie die Vorhersagen (als TFRecord-Dateien) hochladen, um georeferenzierte Bilder zu erhalten. Beachten Sie, dass der überlappende Teil der Patches (Padding-Dimension in Abbildung 1) verworfen wird, um eine zusammenhängende Abdeckung der exportierten Region zu erhalten. Die Vorhersagen sollten als tf.train.Example-Sequenz mit derselben Anzahl und Reihenfolge wie die ursprünglich exportierten Bildbeispiele angeordnet sein (auch zwischen einer beliebigen Anzahl von Dateien).