TFRecord ist ein Binärformat, mit dem sich lange Sequenzen von tf.Example-Protos effizient codieren lassen. TFRecord-Dateien können von TensorFlow über das tf.data-Paket ganz einfach 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 in TFRecord exportieren
Sie können Tabellen (ee.FeatureCollection) oder Bilder (ee.Image) als TFRecord-Dateien in Google Drive oder Cloud Storage exportieren. Die Konfiguration des Exports hängt davon ab, was Sie exportieren, wie unten beschrieben. Alle Zahlen, die aus Earth Engine in TFRecord exportiert werden, werden in den Typ „float“ umgewandelt.
Tabellen exportieren
Beim Exportieren einer ee.FeatureCollection in eine TFRecord-Datei besteht eine 1:1-Beziehung zwischen jedem ee.Feature in der Tabelle und jedem tf.train.Example (d.h. jedem Datensatz) in der TFRecord-Datei. Jede Property der ee.Feature wird als tf.train.Feature mit einer Liste von Gleitkommazahlen codiert, die der in der Property gespeicherten Zahl oder ee.Array entspricht. Wenn Sie eine Tabelle mit Arrays in den Eigenschaften exportieren, müssen Sie TensorFlow beim Lesen die Form des Arrays mitteilen. Eine Tabelle, die in eine TFRecord-Datei exportiert wird, wird immer mit dem GZIP-Komprimierungstyp komprimiert. Für jeden Export erhalten Sie immer genau eine TFRecord-Datei.
Im folgenden Beispiel wird gezeigt, wie Daten aus einer exportierten Tabelle mit skalaren Eigenschaften ('B2',…,'B7', 'landcover') geparst werden. Die Dimension der Gleitkommalisten ist [1] und der Typ 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))
In diesem Beispiel wird das Lesen skalarer Features (d. h. shape=[1]) veranschaulicht. Beim Exportieren von 2D- oder 3D-Arrays (z. B. Bild-Patches) geben Sie die Form der Patches beim Parsen an, z. B. shape=[16, 16] für einen Patch mit 16 × 16 Pixeln.
Bilder exportieren
Beim Exportieren eines Bildes werden die Daten nach Kanälen, Höhe und 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.
Zwischen jedem Patch und jedem tf.train.Example in der resultierenden TFRecord-Datei besteht eine 1:1-Beziehung. Jeder Band des Bildes wird in jedem tf.train.Example als separate tf.train.Feature gespeichert. Die Länge der in jedem Feature gespeicherten Gleitkommaliste entspricht der Breite × Höhe des Patches. Die flachen Listen können in mehrere einzelne Pixel aufgeteilt werden, wie in diesem Beispiel gezeigt.
Alternativ kann die Form des exportierten Patches wie in diesem Beispiel wiederhergestellt werden.
Um Kanteneffekte zu reduzieren, können sich die exportierten Patches überschneiden. Sie können kernelSize angeben, was zu folgenden Kacheln führt:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Jede Kachel überlappt sich mit benachbarten 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 benachbarte Bild überlappt:
kernelSize/2.
formatOptions
Die Parameter patchSize, maxFileSize und kernelSize werden über ein formatOptions-Wörterbuch an den ee.Export- (JavaScript) oder ee.batch.Export-Aufruf (Python) übergeben. Die Schlüssel sind die Namen der zusätzlichen Parameter, die an Export übergeben werden. Mögliche formatOptions für ein in das TFRecord-Format exportiertes Bild sind:
| Attribut | Beschreibung | Typ |
|---|---|---|
patchDimensions |
Die Abmessungen werden über den Exportbereich gelegt und decken jedes Pixel im Begrenzungsrahmen genau einmal ab. Dies gilt nicht, wenn die Patchabmessungen den Begrenzungsrahmen nicht gleichmäßig teilen. In diesem Fall werden Randkacheln entlang der größten X‑/Y‑Achsen entfernt. Die Abmessungen müssen > 0 sein. | Array<int>[2]. |
kernelSize |
Wenn Sie diese Option angeben, werden die Kacheln sowohl positiv als auch negativ durch die Ränder begrenzt, was zu Überschneidungen zwischen benachbarten Patches führt. Falls angegeben, müssen zwei Dimensionen (X und Y) angegeben werden. | Array<int>[2]. Standard: [1, 1] |
compressed |
Wenn „wahr“ ist, werden die .tfrecord-Dateien mit gzip komprimiert und das Suffix „.gz“ angehängt. | Boolescher Wert. Standardeinstellung: true |
maxFileSize |
Maximale Größe in Byte für eine exportierte .tfrecord-Datei (vor der Komprimierung). Eine kleinere Dateigröße führt zu einem größeren Sharding (und damit zu mehr Ausgabedateien). | Int. Standard: 1 GiB |
defaultValue |
Der Wert, der in jedem Band eines teilweise oder vollständig maskierten Pixels festgelegt ist, und der Wert, der für jeden Wert in einem Ausgabe-3D-Element festgelegt ist, das aus einem Arrayband erstellt wurde, bei dem die Arraylänge am Quellpixel kleiner als die Tiefe des Featurewerts war (d.h. der Wert bei Index 3 eines Array-Pixels mit einer Länge von 2 in einem Arrayband mit einer entsprechenden Featuretiefe von 3). Der Bruchteil wird bei Bändern vom Typ „Ganzzahl“ ignoriert und auf den Bereich des Bändertyps begrenzt. Die Standardeinstellung ist 0. | Ganzzahl. Standard: 0 |
tensorDepths |
Zuordnung der Namen der Eingabearray-Bänder zur Tiefe der von ihnen erstellten 3D-Tensoren. Arrays werden abgeschnitten oder mit Standardwerten aufgefüllt, um der angegebenen Form zu entsprechen. Für jedes Arrayband muss es einen entsprechenden Eintrag geben. | Array<int>[]. Standard: [] |
sequenceData |
Wenn „true“ festgelegt ist, wird jedes Pixel als SequenceExample ausgegeben, wobei Skalarbänder dem Kontext und Arraybänder den Sequenzen des Beispiels zugeordnet werden. Die SequenceExamples werden in Zeilenvorrang-Reihenfolge der Pixel in jedem Patch und dann in Zeilenvorrang-Reihenfolge der Gebiets-Patches in der Dateisequenz ausgegeben. | Boolescher Wert. Standardwert: false |
collapseBands |
Wenn diese Option aktiviert ist, werden alle Bänder zu einem einzigen 3D-Tensor kombiniert, der den Namen des ersten Bandes im Bild übernimmt. Alle Bänder werden in Bytes, int64s und dann in dieser Reihenfolge in Floats umgewandelt, je nach dem Typ, der in dieser Sequenz innerhalb aller Bänder am weitesten entfernt ist. Arrays sind zulässig, solange „tensor_depths“ angegeben ist. | Boolescher Wert. Standardwert: false |
maskedThreshold |
Der maximal zulässige Anteil an maskierten Pixeln in einem Patch. Patches, die diese Obergrenze überschreiten, werden verworfen und nicht in Dateien geschrieben. Wenn dieses Feld auf einen anderen Wert als „1“ festgelegt ist, wird das JSON-Sidecar nicht erstellt. Der Standardfaktor ist 1. | Gleitkommazahl. Standardeinstellung: 1 |
Die TFRecord-Datei „mixer“
Wenn Sie in 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 ist zum Hochladen von Vorhersagen erforderlich, die auf den Bildern erstellt wurden, wie im nächsten Abschnitt beschrieben.
Zeitreihen exportieren
Bildexporte in „Beispiele“ und „Sequenzbeispiele“ werden unterstützt. Wenn Sie in „Examples“ exportieren, wird die Exportregion in Patches geschnitten und diese Patches werden in zeilenreihenfolge in eine Reihe von .tfrecord-Dateien exportiert, wobei jeder Band ein eigenes Feature hat (es sei denn, Sie geben collapseBands an). Wenn Sie in „SequenceExamples“ exportieren, wird ein SequenceExample pro Pixel exportiert. Diese SequenceExamples werden innerhalb eines Patches in zeilenreihenfolge und dann in zeilenreihenfolge der Patches in der ursprünglichen Exportregion exportiert. Wenn Sie sich nicht sicher sind, gehen Sie immer davon aus, dass die Daten in irgendeiner Form in zeilenreihenfolge vorliegen.
Hinweis: Alle Skalarbänder eines Bildes werden in den Kontext eines SequenceExample-Objekts verpackt, während die Arraybänder zu den tatsächlichen Sequenzdaten werden.
Array-Armbänder
Arraybänder können exportiert werden, wenn ein Bild in das TFRecord-Format exportiert wird. Der Export von Arrays ermöglicht es, die „FeatureLists“ von SequenceExamples zu füllen und 3D-Tensoren beim Exportieren in reguläre Examples zu erstellen. Informationen zum Verwalten der Längen/Tiefe der Arraybänder finden Sie in der Tabelle oben unter collapseBands und/oder tensorDepths. Hinweis: Wenn Sie collapseBands verwenden und in SequenceExamples exportieren (also den Parameter sequenceData festlegen), werden alle Bänder zu einer einzelnen Zeitreihe pro Pixel zusammengefasst.
TFRecords in Earth Engine hochladen
Sie können Tabellen (nur über die Befehlszeile) und Bilder als TFRecord-Dateien in Earth Engine hochladen. Bei Tabellen gilt die zuvor beschriebene 1:1-Beziehung in umgekehrter Richtung (d.h. tf.train.Example -> ee.Feature).
Bilder hochladen
Wenn Sie Vorhersagen auf exportierten Bildern generieren, geben Sie den Mixer an, wenn Sie die Vorhersagen (als TFRecord-Dateien) hochladen, um georeferenzierte Bilder zu erhalten. Hinweis: Der sich überschneidende Teil der Patches (Abstand in Abbildung 1) wird verworfen, um eine zusammenhängende Abdeckung der exportierten Region zu erzielen. 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).