TFRecord to format binarny do wydajnego kodowania długich sekwencji protokołów tf.Example. Pliki TFRecord można łatwo wczytać do TensorFlow za pomocą pakietu tf.data, jak opisano tutaj i tutaj.
Na tej stronie opisujemy, jak Earth Engine konwertuje format ee.FeatureCollection lub ee.Image na format TFRecord.
Eksportowanie danych do TFRecord
Tabele (ee.FeatureCollection) lub obrazy (ee.Image) możesz eksportować do plików TFRecord na Dysku Google lub w Cloud Storage. Konfiguracja eksportu zależy od tego, co eksportujesz, jak opisano poniżej. Wszystkie liczby wyeksportowane z Earth Engine do TFRecord są wymuszane na typ float.
Eksportowanie tabel
Podczas eksportowania tabeli ee.FeatureCollection do pliku TFRecord istnieje odpowiedniość 1:1 między każdym elementem ee.Feature w tabeli i każdym elementem tf.train.Example (czyli każdym rekordem) w pliku TFRecord. Każda właściwość ee.Feature jest kodowana jako tf.train.Feature z listą liczb zmiennoprzecinkowych odpowiadających liczbie lub ee.Array przechowywanej we właściwości. Jeśli eksportujesz tabelę z tablicami we właściwościach, musisz poinformować TensorFlow o kształcie tablicy podczas jej odczytu. Tabela wyeksportowana do pliku TFRecord będzie zawsze skompresowana za pomocą kompresji GZIP. Zawsze otrzymujesz dokładnie 1 plik TFRecord na każdy eksport.
Poniższy przykład pokazuje, jak przeanalizować dane z wyeksportowanej tabeli właściwości skalarnych ('B2',...,'B7', 'landcover'). Zwróć uwagę, że wymiar list liczb zmiennoprzecinkowych to [1], a typ to 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))
Pamiętaj, że ten przykład ilustruje odczytywanie cech skalarnych (czyli shape=[1]). Jeśli eksportujesz tablice 2D lub 3D (np. fragmenty obrazu), musisz określić kształt fragmentów podczas analizy, np. shape=[16, 16] dla fragmentu 16 x 16 pikseli.
Eksportowanie obrazów
Podczas eksportowania obrazu dane są uporządkowane według kanałów, wysokości i szerokości (CHW). Eksport może zostać podzielony na kilka plików TFRecord, z których każdy zawiera co najmniej 1 fragment o rozmiarze patchSize, który jest określany przez użytkownika podczas eksportowania. Rozmiar plików w bajtach jest określany przez użytkownika w parametrze maxFileSize.
Istnieje odpowiedniość 1:1 między każdym fragmentem a każdym elementem tf.train.Example w wynikowym pliku TFRecord. Każde pasmo obrazu jest przechowywane jako osobny element tf.train.Feature w każdym elemencie tf.train.Example, gdzie długość listy zmiennoprzecinkowej przechowywanej w każdym elemencie to szerokość * wysokość fragmentu. Spłaszczone listy można podzielić na kilka pojedynczych pikseli, jak pokazano w tym przykładzie.
Możesz też przywrócić kształt wyeksportowanego fragmentu, jak w tym przykładzie.
Aby zmniejszyć efekty krawędzi, wyeksportowane fragmenty mogą się nakładać. Możesz określić kernelSize, co spowoduje, że kafelki będą miały rozmiar:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Każdy kafelek nakłada się na sąsiednie kafelki o [kernelSize[0]/2, kernelSize[1]/2]. W rezultacie jądro o rozmiarze kernelSize wyśrodkowane na pikselu krawędzi fragmentu o rozmiarze patchSize zawiera całkowicie prawidłowe dane. Układ przestrzenny fragmentów obrazu przedstawia rysunek 1, na którym wymiar dopełnienia odpowiada części jądra, która nakłada się na sąsiedni obraz:
kernelSize/2.
formatOptions
Parametry patchSize, maxFileSize i kernelSize są przekazywane do wywołania ee.Export (JavaScript) lub ee.batch.Export (Python) za pomocą słownika formatOptions, w którym klucze są nazwami dodatkowych parametrów przekazywanych do Export. Możliwe wartości formatOptions w przypadku obrazu wyeksportowanego do formatu TFRecord:
| Właściwość | Opis | Typ |
|---|---|---|
patchDimensions |
Wymiary są rozmieszczone na obszarze eksportu, pokrywając każdy piksel w ramce ograniczającej dokładnie raz (chyba że wymiary fragmentu nie dzielą równomiernie ramki ograniczającej, w którym to przypadku kafelki graniczne wzdłuż największych krawędzi x/y zostaną usunięte). Wymiary muszą być większe niż 0. | Array<int>[2]. |
kernelSize |
Jeśli ta opcja jest określona, kafelki będą buforowane przez wymiary marginesu zarówno dodatnio, jak i ujemnie, co spowoduje nakładanie się sąsiednich fragmentów. Jeśli podasz tę wartość, musisz podać 2 wymiary (odpowiednio X i Y). | Array<int>[2]. Domyślnie: [1, 1] |
compressed |
Jeśli ma wartość prawda, kompresuje pliki .tfrecord za pomocą gzip i dodaje sufiks „.gz” | Wartość logiczna. Wartość domyślna: true |
maxFileSize |
Maksymalny rozmiar (w bajtach) eksportowanego pliku .tfrecord (przed kompresją). Mniejszy rozmiar pliku spowoduje większe fragmentowanie (a tym samym więcej plików wyjściowych). | Liczba całkowita. Wartość domyślna: 1 GiB |
defaultValue |
Wartość ustawiona w każdym paśmie piksela, który jest częściowo lub całkowicie zamaskowany, oraz wartość ustawiona przy każdej wartości w wyjściowej cechy 3D utworzonej z pasma tablicy, w którym długość tablicy w pikselu źródłowym była mniejsza niż głębokość wartości cechy (np. wartość w indeksie 3 piksela tablicy o długości 2 w paśmie tablicy z odpowiadającą głębokością cechy 3). W przypadku pasm typu całkowitego część ułamkowa jest odrzucana i ograniczana do zakresu typu pasma. Domyślna wartość to 0. | Liczba całkowita. Wartość domyślna: 0 |
tensorDepths |
Mapowanie nazw pasm tablicy wejściowej na głębokość tworzonych przez nie tensorów 3D. Tablice zostaną obcięte lub uzupełnione wartościami domyślnymi, aby pasowały do określonego kształtu. Każdy pasmo tablicy musi mieć odpowiedni wpis. | Array<int>[]. Wartość domyślna: [] |
sequenceData |
Jeśli ma wartość prawda, każdy piksel jest zwracany jako SequenceExample, który mapuje pasma skalarne na kontekst, a pasma tablicy na sekwencje przykładu. Przykłady SequenceExample są generowane w kolejności wierszowej pikseli w każdym fragmencie, a następnie w kolejności wierszowej fragmentów obszaru w sekwencji plików. | Wartość logiczna. Domyślnie: false |
collapseBands |
Jeśli ma wartość „true”, wszystkie pasma zostaną połączone w jeden tensor 3D, który przyjmie nazwę pierwszego pasma na obrazie. Wszystkie pasma są promowane do bajtów, int64, a następnie float w tej kolejności, w zależności od typu, który znajduje się najdalej w tej sekwencji we wszystkich pasmach. Pasma tablicy są dozwolone, o ile określono tensor_depths. | Wartość logiczna. Domyślnie: false |
maskedThreshold |
Maksymalny dozwolony odsetek zamaskowanych pikseli we fragmencie. Poprawki, które przekraczają ten limit, zostaną usunięte, a nie zapisane w plikach. Jeśli to pole ma wartość inną niż 1, plik pomocniczy JSON nie zostanie wygenerowany. Domyślna wartość to 1. | Liczba zmiennoprzecinkowa. Domyślnie: 1 |
plik „miksera” TFRecord,
Gdy eksportujesz do TFRecord, Earth Engine wygeneruje plik pomocniczy z plikami TFRecord o nazwie „mixer”. Jest to prosty plik JSON używany do definiowania układu przestrzennego fragmentów (czyli georeferencji). Ten plik jest potrzebny do przesłania prognoz utworzonych na podstawie zdjęć, jak opisano w następnej sekcji.
Eksportowanie serii czasowych
Obsługiwany jest eksport obrazów zarówno do Examples, jak i SequenceExamples. Podczas eksportowania do Examples region eksportu jest dzielony na fragmenty, które są eksportowane w kolejności wierszowej do określonej liczby plików .tfrecord, przy czym każde pasmo ma własną cechę (chyba że określisz collapseBands). Podczas eksportowania do SequenceExamples eksportowany jest SequenceExample na piksel, przy czym te SequenceExamples są w kolejności wierszowej w obrębie fragmentu, a następnie w kolejności wierszowej fragmentów w pierwotnym regionie eksportu (jeśli nie masz pewności, zawsze zakładaj, że elementy będą w kolejności wierszowej).
Uwaga: wszystkie pasma skalarne obrazu zostaną spakowane w kontekście SequenceExample, a pasma tablicy staną się rzeczywistymi danymi sekwencji.
Paski Array
Pasma tablic można eksportować, gdy obraz jest eksportowany do formatu TFRecord. Eksportowanie pasm tablicy umożliwia wypełnianie „FeatureLists” w SequenceExamples i tworzenie trójwymiarowych tensorów podczas eksportowania do zwykłych Examples. Informacje o tym, jak zarządzane są długości/głębokości pasm tablic, znajdziesz w sekcji collapseBands lub tensorDepths w tabeli powyżej. Uwaga: użycie collapseBands i eksport do SequenceExamples (czyli ustawienie parametru sequenceData) spowoduje, że wszystkie pasma zostaną zwinięte do pojedynczego ciągu czasowego na piksel.
Przesyłanie plików TFRecord do Earth Engine
Do Earth Engine możesz przesyłać tabele (tylko w wierszu poleceń) i obrazy jako pliki TFRecord. W przypadku tabel relacja 1:1 opisana wcześniej obowiązuje w odwrotnym kierunku (czyli tf.train.Example -> ee.Feature).
Przesyłanie zdjęć
Jeśli generujesz prognozy na podstawie wyeksportowanych zdjęć, podaj mikser podczas przesyłania prognoz (jako pliki TFRecord), aby uzyskać zdjęcia z odniesieniami geograficznymi. Pamiętaj, że nakładające się części fragmentów (wymiar dopełnienia na rysunku 1) zostaną odrzucone, aby zapewnić ciągłe pokrycie eksportowanego regionu. Prognozy powinny być ułożone w sekwencję tf.train.Example o tej samej liczbie i kolejności co pierwotnie wyeksportowane przykłady obrazów (nawet w przypadku dowolnej liczby plików).