TFRecord to format binarny do wydajnego kodowania długich sekwencji protosów tf.Example. Pliki TFRecord są łatwo wczytywane przez TensorFlow za pomocą pakietu tf.data, jak opisano tutaj i tutaj.
Na tej stronie opisano, jak Earth Engine konwertuje dane z formatu ee.FeatureCollection
lub ee.Image na format TFRecord.
Eksportowanie danych do formatu TFRecord
Możesz wyeksportować tabele (ee.FeatureCollection) lub obrazy (ee.Image) do plików TFRecord na Dysku Google lub w Cloud Storage. Konfiguracja eksportu zależy od tego, co eksportujesz. Wszystkie liczby eksportowane z Earth Engine do formatu TFRecord są przymusowo zamieniane na typ float.
Eksportowanie tabel
Podczas eksportowania pliku ee.FeatureCollection do pliku TFRecord występuje dokładne powiązanie każdego elementu ee.Feature w tabeli z 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.Featurez listą wartości zmiennoprzecinkowych odpowiadających liczbie lub ee.Array przechowywanej we właściwości. Jeśli eksportujesz tabelę z tablicami w właściwościach, musisz podać TensorFlow kształt tablicy podczas jej odczytu. Tabela wyeksportowana do pliku TFRecord będzie zawsze skompresowana za pomocą typu kompresji GZIP. W przypadku każdego eksportu zawsze otrzymujesz dokładnie 1 plik TFRecord.
Ten przykład pokazuje parsowanie danych z wyeksportowanej tabeli właściwości skalarnych ('B2',...,'B7', 'landcover'). Zwróć uwagę, że wymiar listy typów float 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 podać kształt fragmentów w momencie ich analizowania, np. shape=[16, 16] dla fragmentu 16 × 16 pikseli.
Eksportowanie obrazów
Podczas eksportowania obrazu dane są sortowane według kanałów, wysokości i szerokości (CHW). Eksport może być podzielony na kilka plików TFRecord, z których każdy zawiera co najmniej 1 łatkę o rozmiarze patchSize, który jest określony przez użytkownika podczas eksportu. Rozmiar plików w bajtach jest określony przez użytkownika w parametrze maxFileSize.
Każda poprawka i każdy elementtf.train.Example w wygenerowanym pliku TFRecord są ze sobą powiązane w sposób jeden do jednego. Każdy pasek obrazu jest przechowywany jako osobny element tf.train.Feature w każdym tf.train.Example, gdzie długość listy liczb zmiennoprzecinkowych przechowywanej w każdej funkcji to szerokość i wysokość plakietki. Spłaszczone listy można podzielić na wiele pikseli, jak pokazano w tym przykładzie.
Możesz też odzyskać kształt wyeksportowanego pakietu, jak w tym przykładzie.
Aby ograniczyć efekt krawędzi, wyeksportowane łaty mogą się na siebie nakładać. Możesz w szczególności określić kernelSize, co spowoduje, że kafelki będą miały rozmiar:
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
Każdy kafelek zachodzi na sąsiednie o [kernelSize[0]/2, kernelSize[1]/2]. W efekcie kernel o rozmiarze kernelSize, którego środek znajduje się na krawędzi piksela w patchu o rozmiarze patchSize, zawiera całkowicie prawidłowe dane. Układ przestrzenny łat w przestrzeni ilustruje rysunek 1, gdzie wymiar wypełnienia odpowiada części rdzenia, 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, gdzie kluczami są nazwy dodatkowych parametrów przekazywanych do Export. Możliwe formatOptions
dla obrazu wyeksportowanego do formatu TFRecord:
| Właściwość | Opis | Typ |
|---|---|---|
patchDimensions |
Wymiary pokrywają się z obszarem eksportu, obejmując dokładnie raz każdy piksel w ograniczonym obszarze (z wyjątkiem sytuacji, gdy wymiary fragmentu nie dzielą równo ograniczonego obszaru. W takim przypadku krawędzie obszaru granicznego wzdłuż największej krawędzi x/y zostaną pominięte). Wymiary muszą być większe niż 0. | Tablica<int>[2]. |
kernelSize |
Jeśli to pole jest określone, płytki będą buforowane z marginesami zarówno dodatnimi, jak i ujemnymi, co spowoduje nakładanie się sąsiednich obszarów. Jeśli jest podany, musisz podać 2 wymiary (odpowiednio X i Y). | Tablica<int>[2]. Wartość domyślna: [1, 1] |
compressed |
Jeśli to pole ma wartość prawda, pliki .tfrecord są kompresowane za pomocą gzip i dodawane jest do nich rozszerzenie „.gz”. | Wartość logiczna. Wartość domyślna: true. |
maxFileSize |
Maksymalny rozmiar (w bajtach) wyeksportowanego pliku .tfrecord (przed kompresją). Mniejszy rozmiar pliku spowoduje większą segmentację (a co za tym idzie, więcej plików wyjściowych). | Int. Domyślnie: 1 GiB |
defaultValue |
Wartość ustawiona w każdej pasmie piksela, który jest częściowo lub całkowicie zamaskowany, oraz wartość ustawiona w każdej wartości w cechu wyjściowym 3D utworzonym z pasma tablicy, w którym długość tablicy w źródłowym pikselu była mniejsza niż głębia wartości cechy (np. wartość w indeksie 3 piksela tablicy o długości 2 w pasmie tablicy z odpowiadającą głębią cechy 3). Część ułamkowa jest pomijana w przypadku pasm typu liczba całkowita, a w przypadku pasm typu zakres jest ograniczana do zakresu typu. Domyślna wartość to 0. | Int. Domyślnie: 0 |
tensorDepths |
Mapowanie nazw pasm wejściowego tabli na głębokość tworzonych przez nie tensorów 3D. Tablice zostaną obcięte lub wypełnione wartościami domyślnymi, aby pasowały do określonego kształtu. W przypadku każdego pasma tablicy musi być odpowiedni wpis. | Tablica<int>[]. Wartość domyślna: [] |
sequenceData |
Jeśli ma wartość true, każdy piksel jest generowany jako przykład sekwencji, który mapuje pasma skalarne na kontekst oraz pasma tablic na sekwencje przykładu. Przykłady sekwencji są wyświetlane w kolejności wierszy pikseli w każdym pliku, a następnie w kolejności wierszy obszarów w sekwencji plików. | Wartość logiczna. Wartość domyślna: false |
collapseBands |
Jeśli ma wartość „true” (prawda), wszystkie pasma zostaną połączone w jeden tensor 3D, który będzie miał nazwę pierwszego pasma na obrazie. Wszystkie pasma są promowane do bajtów, int64, a następnie do zmiennych typu float w tej kolejności w zależności od typu najdalszego w sekwencji we wszystkich pasmach. Pasma tablicy są dozwolone, o ile podano parametr tensor_depths. | Wartość logiczna. Wartość domyślna: false |
maskedThreshold |
Maksymalny dopuszczalny udział zamaskowanych pikseli w łacie. Aktualizacje, które przekraczają ten limit, zostaną odrzucone, a nie zapisane w plikach. Jeśli to pole jest ustawione na wartość inną niż 1, plik JSON sidecar nie zostanie wygenerowany. Domyślna wartość to 1. | Liczba zmiennoprzecinkowa. Wartość domyślna: 1. |
Plik „mixer” w formacie TFRecord
Podczas eksportowania do formatu TFRecord Earth Engine wygeneruje plik pomocniczy z plikami TFRecord, zwany „mixerem”. Jest to prosty plik JSON służący do definiowania rozmieszczenia przestrzennego fragmentów (tj. georeferencowania). Ten plik jest potrzebny do przesłania prognoz wykonanych na podstawie obrazów zgodnie z opisem w następnej sekcji.
Eksportowanie serii czasowych
Obsługiwane są eksporty obrazów do Examples i SequenceExamples. Podczas eksportu do Examples region eksportu jest dzielony na fragmenty, a te fragmenty są eksportowane w kolejności wierszy do określonej liczby plików .tfrecord z osobnymi cechami dla każdego pasma (chyba że określisz opcję collapseBands). Podczas eksportu do SequenceExamples dla każdego piksela będzie eksportowany pojedynczy przykład sekwencji, a te przykłady sekwencji będą uporządkowane w kolejności wierszy w danym fragmencie, a następnie w kolejności wierszy w pierwotnym regionie eksportu (jeśli nie masz pewności, zawsze zakładaj, że elementy będą uporządkowane w kolejności wierszy).
Uwaga: wszystkie skalarne pasma obrazu zostaną spakowane w kontekście przykładu sekwencji, a pasma tablic staną się rzeczywistymi danymi sekwencji.
Opaski Array
Pasma tablic można eksportować, gdy obraz jest eksportowany do formatu TFRecord. Eksportowanie pasm tablic umożliwia wypełnianie list cech w przypadku przykładów sekwencji oraz tworzenie tensorów 3D podczas eksportowania do zwykłych przykładów. Informacje o zarządzaniu długością/głębią pasm macierzy znajdziesz w sekcji collapseBands lub tensorDepths w tabeli powyżej. Uwaga: użycie parametru collapseBands i eksport do SequenceExamples (czyli ustawienie parametru sequenceData) spowoduje złożenie wszystkich pasm w jedną serię czasową na piksel.
Przesyłanie plików TFRecords 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 ma zastosowanie w odwrotnym kierunku (czyli tf.train.Example -> ee.Feature).
Przesyłanie zdjęć
Jeśli prognozy są generowane na podstawie wyeksportowanych obrazów, podczas przesyłania prognoz (jako plików TFRecord) podaj dane do miksera, aby uzyskać obrazy z georeferencjacją. Pamiętaj, że nakładająca się część łat (wymiar wypełnienia w Rysunku 1) zostanie odrzucona, aby uzyskać ciągłe pokrycie eksportowanego regionu. Prognozy powinny być uporządkowane w ciągu tf.train.Example o tej samej liczbie i tej samej kolejności co pierwotnie wyeksportowane przykładowe obrazy (nawet w przypadku dowolnej liczby plików).