TFRecord
è un formato binario per la codifica efficiente di sequenze lunghe di
protos
tf.Example. I file TFRecord vengono caricati facilmente da TensorFlow tramite il
tf.data pacchetto come descritto
qui e
qui.
Questa pagina descrive come Earth Engine esegue la conversione tra i formati ee.FeatureCollection
o ee.Image e TFRecord.
Esportazione dei dati in TFRecord
Puoi esportare tabelle (ee.FeatureCollection) o immagini (ee.Image)
in file TFRecord in Google Drive o Cloud Storage. La configurazione dell'esportazione dipende da ciò che stai esportando, come descritto di seguito. Tutti i numeri esportati da Earth Engine in
TFRecord vengono forzati in tipo float.
Esportazione delle tabelle
Quando esporti un ee.FeatureCollection in un file TFRecord, esiste una corrispondenza 1:1 tra ogni
ee.Feature
nella tabella e ogni
tf.train.Example
(ovvero ogni record) nel file TFRecord. Ogni proprietà di ee.Feature è codificata come tf.train.Feature con un elenco di valori float corrispondenti al numero o al ee.Array memorizzato nella proprietà. Se esporti una tabella con array nelle proprietà, devi indicare a TensorFlow
la forma dell'array quando viene letto. Una tabella esportata in un file TFRecord verrà sempre
compressa con il tipo di compressione GZIP. Viene sempre generato esattamente un file TFRecord per ogni esportazione.
L'esempio seguente mostra l'analisi dei dati di una tabella esportata di proprietà scalari
('B2',...,'B7', 'landcover'). Tieni presente che la dimensione degli elenchi di numeri in virgola mobile è
[1] e il tipo è 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))
Tieni presente che questo esempio illustra la lettura di elementi scalari (ovvero shape=[1]).
Se esporti array 2D o 3D (ad es. patch di immagini), devi specificare la forma delle patch al momento dell'analisi, ad esempio shape=[16, 16] per una patch di 16 x 16 pixel.
Esportazione di immagini
Quando esporti un'immagine, i dati vengono ordinati come canali, altezza e larghezza (CHW). L'esportazione può essere suddivisa in più file TFRecord, ciascuno contenente uno o più patch di dimensioni patchSize, specificate dall'utente nell'esportazione. Le
dimensioni dei file in byte sono specificate dall'utente nel parametro maxFileSize.
Esiste una corrispondenza 1:1 tra ogni patch e ogni
tf.train.Example
nel file TFRecord risultante. Ogni banda dell'immagine viene memorizzata come tf.train.Feature distinta in ogni tf.train.Example, dove la lunghezza dell'elenco di valori float memorizzato in ogni elemento è la larghezza della patch * altezza. Gli elenchi appiattiti possono essere suddivisi in
più singoli pixel come mostrato in
questo esempio.
In alternativa, la forma della patch esportata può essere recuperata come in
questo esempio.
Per ridurre gli effetti di confine, i patch esportati possono sovrapporsi. Nello specifico, puoi
specificare un kernelSize che avrà come risultato riquadri delle seguenti dimensioni:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Ogni riquadro si sovrappone ai riquadri adiacenti per [kernelSize[0]/2, kernelSize[1]/2]. Di conseguenza, un nucleo di dimensione kernelSize centrato su un pixel di bordo di una patch di dimensione patchSize contiene dati completamente validi. La disposizione spaziale delle patch nello spazio è illustrata nella Figura 1, dove la dimensione Padding corrisponde alla parte del kernel che si sovrappone all'immagine adiacente:
kernelSize/2.
formatOptions
I parametri patchSize, maxFileSize e kernelSize
vengono passati alla chiamata ee.Export (JavaScript) o ee.batch.Export
(Python) tramite un dizionario formatOptions, in cui le chiavi sono i nomi
dei parametri aggiuntivi passati a Export. I possibili valori di formatOptions
per un'immagine esportata in formato TFRecord sono:
| Proprietà | Descrizione | Tipo |
|---|---|---|
patchDimensions |
Dimensioni suddivise in riquadri nell'area di esportazione, che coprono ogni pixel della casella delimitante esattamente una volta (tranne nel caso in cui le dimensioni della patch non dividano uniformemente la casella delimitante, nel qual caso i riquadri di confine lungo i bordi x/y maggiori verranno eliminati). Le dimensioni devono essere maggiori di 0. | Array<int>[2]. |
kernelSize |
Se specificato, i riquadri verranno memorizzati nella memoria intermedia in base alle dimensioni del margine sia in positivo che in negativo, con conseguente sovrapposizione tra le patch adiacenti. Se specificato, devono essere fornite due dimensioni (rispettivamente X e Y). | Array<int>[2]. Valore predefinito: [1, 1] |
compressed |
Se true, comprime i file .tfrecord con gzip e aggiunge il suffisso ".gz" | Booleano. Valore predefinito: true |
maxFileSize |
Dimensione massima, in byte, per un file .tfrecord esportato (prima della compressione). Un file di dimensioni inferiori comporta un maggiore suddivisione (e, di conseguenza, più file di output). | Valore predefinito: 1 GiB |
defaultValue |
Il valore impostato in ogni banda di un pixel parzialmente o completamente mascherato e il valore impostato in ogni valore in una funzionalità 3D di output creata da una banda di array in cui la lunghezza dell'array nel pixel di origine era inferiore alla profondità del valore della funzionalità (ad es. il valore all'indice 3 di un pixel di array di lunghezza 2 in una banda di array con una profondità della funzionalità corrispondente di 3). La parte frazionaria viene ignorata per le bande di tipo intero e limitata all'intervallo del tipo di banda. Il valore predefinito è 0. | Int. Valore predefinito: 0 |
tensorDepths |
Mappatura dai nomi delle bande dell'array di input alla profondità dei tensori 3D che creano. Gli array verranno troncati o riempiti con valori predefiniti per adattarsi alla forma specificata. Per ogni banda dell'array deve essere presente una voce corrispondente. | Array<int>[]. Valore predefinito: [] |
sequenceData |
Se true, ogni pixel viene visualizzato come SequenceExample che mappa le bande scalari al contesto e le bande di array alle sequenze dell'esempio. Gli SequenceExamples vengono visualizzati nell'ordine di righe principali dei pixel in ogni patch e poi nell'ordine di righe principali delle patch di area nella sequenza di file. | Booleano. Valore predefinito: false |
collapseBands |
Se il valore è true, tutte le bande verranno combinate in un unico tensore 3D, assumendo il nome della prima banda nell'immagine. Tutti i gruppi vengono promossi a byte, int64 e poi a valori float in questo ordine, a seconda del tipo più lontano nella sequenza all'interno di tutti i gruppi. Le bande di array sono consentite purché sia specificato tensor_depths. | Booleano. Valore predefinito: false |
maskedThreshold |
Proporzione massima consentita di pixel mascherati in una patch. I patch che superano questo limite verranno eliminati anziché essere scritti nei file. Se questo campo è impostato su un valore diverso da 1, il sidecar JSON non verrà prodotto. Il valore predefinito è 1. | Galleggia. Valore predefinito: 1 |
Il file "mixer" TFRecord
Quando esporti in TFRecord, Earth Engine genera un file aggiuntivo con i file TFRecord chiamato "mixer". Si tratta di un semplice file JSON utilizzato per definire la disposizione spaziale delle patch (ovvero il georeferenziamento). Questo file è necessario per caricare le previsioni effettuate sulle immagini come descritto nella sezione successiva.
Esportazione delle serie temporali
Sono supportate le esportazioni di immagini sia in Examples che in SequenceExamples. Quando esporti in Examples, la regione di esportazione viene suddivisa in patch che vengono esportate in ordine crescente di riga in un numero di file .tfrecord con ogni banda con la propria funzionalità (a meno che non specifichi collapseBands). Quando esporti in SequenceExamples, viene esportato un SequenceExample per pixel, con questi SequenceExamples in ordine crescente di riga all'interno di una patch e poi in ordine crescente di riga delle patch nella regione di esportazione originale (in caso di dubbi, presupponi sempre che le cose siano in ordine crescente di riga in qualche modo).
Nota: eventuali bande scalari di un'immagine verranno impacchettate nel contesto di un SequenceExample, mentre le bande di array diventeranno i dati effettivi della sequenza.
Cinturini Array
Le bande di array sono esportabili quando un'immagine viene esportata in formato TFRecord. L'esportazione delle bande di array fornisce un mezzo per compilare le "FeatureList" di SequenceExamples e un modo per creare tensori 3D durante l'esportazione in Examples normali. Per informazioni su come vengono gestite le lunghezze/le profondità delle bande dell'array, consulta collapseBands e/o tensorDepths nella tabella precedente. Nota: l'utilizzo di collapseBands
ed esportazione in SequenceExamples (quindi l'impostazione del parametro sequenceData) fará
collassare tutte le bande in una singola serie temporale per pixel.
Caricamento di TFRecords in Earth Engine
Puoi caricare tabelle (solo riga di comando) e immagini
in Earth Engine come file TFRecord. Per le tabelle, la relazione 1:1
descritta in precedenza si applica in direzione opposta (ovvero tf.train.Example -> ee.Feature).
Caricamento di immagini
Se generi previsioni sulle immagini esportate, fornisci il mixer quando carichi le
previsioni (come file TFRecord) per ottenere immagini georeferenziate. Tieni presente che la parte in sovrapposizione
dei patch (dimensione Spaziatura nella Figura 1) verrà ignorata per ottenere
una copertura contigua della regione esportata. Le previsioni devono essere organizzate come
tf.train.Example sequenza dello stesso numero e ordine degli esempi di immagini
esportati in origine (anche tra un numero arbitrario di file).