TFRecord è un formato binario per la codifica efficiente di lunghe sequenze di proto tf.Example. I file TFRecord vengono caricati facilmente da TensorFlow tramite il pacchetto tf.data, come descritto qui e qui.
Questa pagina descrive come Earth Engine esegue la conversione tra ee.FeatureCollection
o ee.Image e il formato 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 convertiti in tipo con rappresentazione in virgola mobile.
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 viene codificata come tf.train.Feature con un elenco di valori float corrispondenti al numero o a ee.Array memorizzati 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. Per ogni esportazione viene sempre generato esattamente un file TFRecord.
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 valori float è [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 caratteristiche 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 16x16
pixel.
Esportazione delle immagini
Quando esporti un'immagine, i dati vengono ordinati in base a canali, altezza, larghezza (CHW). L'esportazione potrebbe essere suddivisa in più file TFRecord, ciascuno contenente una o più patch di dimensioni patchSize, specificate dall'utente nell'esportazione. Le dimensioni dei file in byte vengono 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 archiviata come tf.train.Feature separata in ogni tf.train.Example, dove la lunghezza dell'elenco di valori float archiviati in ogni caratteristica è la larghezza * l'altezza della patch. Gli elenchi bidimensionali 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 dei bordi, i patch esportati possono sovrapporsi. In particolare, puoi specificare un kernelSize che genererà riquadri di dimensioni:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Ogni riquadro si sovrappone ai riquadri adiacenti di [kernelSize[0]/2, kernelSize[1]/2]. Di conseguenza, un kernel di dimensioni kernelSize centrato su un pixel di bordo di una patch di dimensioni patchSize contiene dati completamente validi. La disposizione spaziale delle patch nello spazio è illustrata nella Figura 1, dove la dimensione di spaziatura interna 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 formatOptions per un'immagine esportata in formato TFRecord sono:
| Proprietà | Descrizione | Tipo |
|---|---|---|
patchDimensions |
Dimensioni affiancate sull'area di esportazione, che coprono ogni pixel nel riquadro di delimitazione esattamente una volta (tranne quando le dimensioni della patch non dividono in modo uniforme il riquadro di delimitazione, nel qual caso i riquadri dei bordi lungo i bordi x/y più grandi verranno eliminati). Le dimensioni devono essere maggiori di 0. | Array<int>[2]. |
kernelSize |
Se specificato, i riquadri verranno memorizzati nel buffer 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, di un file .tfrecord esportato (prima della compressione). Una dimensione del file più piccola comporterà uno sharding maggiore (e, di conseguenza, più file di output). | Int. 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 di una caratteristica 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 caratteristica (ovvero il valore all'indice 3 di un pixel di array di lunghezza 2 in una banda di array con una profondità della caratteristica corrispondente di 3). La parte frazionaria viene eliminata 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 restituito come SequenceExample che mappa le bande scalari al contesto e le bande di array alle sequenze dell'esempio. I SequenceExample vengono generati in ordine row-major dei pixel in ogni patch e poi in ordine row-major delle patch dell'area nella sequenza di file. | Booleano. Valore predefinito: false |
collapseBands |
Se il valore è true, tutte le bande verranno combinate in un unico tensore 3D, che assumerà il nome della prima banda nell'immagine. Tutte le bande vengono promosse a byte, int64 e poi float in questo ordine, a seconda del tipo più lontano in questa sequenza all'interno di tutte le bande. 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. Le patch che superano questa quota verranno eliminate anziché scritte nei file. Se questo campo è impostato su un valore diverso da 1, il file collaterale JSON non verrà generato. Il valore predefinito è 1. | Float. Valore predefinito: 1 |
Il file "mixer" TFRecord
Quando esporti in TFRecord, Earth Engine genera un file collaterale con i file TFRecord denominato "mixer". Si tratta di un semplice file JSON utilizzato per definire la disposizione spaziale delle patch (ovvero la georeferenziazione). Questo file è necessario per caricare le previsioni effettuate sulle immagini, come descritto nella sezione successiva.
Esportazione di 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 row-major in un certo numero di file .tfrecord, con ogni banda come caratteristica a sé stante (a meno che non specifichi collapseBands). Quando esporti in SequenceExamples, viene esportato un SequenceExample per pixel, con i SequenceExample in ordine row-major all'interno di una patch e poi in ordine row-major delle patch nella regione di esportazione originale (se hai dubbi, supponi sempre che gli elementi siano in ordine row-major in qualche modo).
Nota: le bande scalari di un'immagine verranno raggruppate nel contesto di un SequenceExample, mentre le bande di array diventeranno i dati di sequenza effettivi.
Cinturini Array
Le bande di array sono esportabili quando un'immagine viene esportata nel formato TFRecord. L'esportazione delle bande di array consente di compilare i "FeatureLists" di SequenceExamples e di creare tensori 3D durante l'esportazione in Examples normali. Per informazioni su come vengono gestite le lunghezze/profondità delle bande di array, consulta collapseBands e/o tensorDepths nella tabella riportata sopra. Nota: l'utilizzo di collapseBands
e l'esportazione in SequenceExamples (quindi l'impostazione del parametro sequenceData)
comporterà la compressione di tutte le bande in un'unica serie temporale per pixel.
Caricamento di TFRecord su Earth Engine
Puoi caricare tabelle (solo riga di comando) e immagini su Earth Engine come file TFRecord. Per le tabelle, la relazione 1:1 descritta in precedenza si applica nella direzione inversa (ovvero tf.train.Example -> ee.Feature).
Caricamento di immagini
Se generi previsioni su immagini esportate, fornisci il mixer quando carichi le previsioni (come file TFRecord) per ottenere immagini georeferenziate. Tieni presente che la parte sovrapposta delle patch (dimensione della spaziatura interna nella Figura 1) verrà ignorata per ottenere una copertura contigua della regione esportata. Le previsioni devono essere disposte come una sequenza tf.train.Example con lo stesso numero e lo stesso ordine degli esempi di immagini esportati originariamente (anche tra un numero arbitrario di file).