TFRecord는 긴 tf.Example 프로토 시퀀스를 효율적으로 인코딩하기 위한 바이너리 형식입니다. TFRecord 파일은 여기 및 여기에 설명된 대로 tf.data 패키지를 통해 TensorFlow에서 쉽게 로드됩니다.
이 페이지에서는 Earth Engine이 ee.FeatureCollection 또는 ee.Image과 TFRecord 형식 간에 변환하는 방법을 설명합니다.
TFRecord로 데이터 내보내기
테이블 (ee.FeatureCollection) 또는 이미지 (ee.Image)를 Google Drive 또는 Cloud Storage의 TFRecord 파일로 내보낼 수 있습니다. 내보내기 구성은 아래 설명된 대로 내보내는 항목에 따라 달라집니다. Earth Engine에서 TFRecord로 내보낸 모든 숫자는 강제로 float 유형으로 변환됩니다.
테이블 내보내기
ee.FeatureCollection를 TFRecord 파일로 내보낼 때 테이블의 각 ee.Feature와 TFRecord 파일의 각 tf.train.Example(즉, 각 레코드) 간에 1:1 대응이 있습니다. ee.Feature의 각 속성은 속성에 저장된 숫자 또는 ee.Array에 해당하는 부동 소수점 수 목록이 있는 tf.train.Feature로 인코딩됩니다. 속성에 배열이 있는 테이블을 내보내는 경우 읽을 때 배열의 형태를 TensorFlow에 알려야 합니다. TFRecord 파일로 내보낸 테이블은 항상 GZIP 압축 유형으로 압축됩니다. 내보내기마다 정확히 하나의 TFRecord 파일이 생성됩니다.
다음 예는 스칼라 속성('B2',…,'B7', 'landcover')의 내보낸 테이블에서 데이터를 파싱하는 방법을 보여줍니다. 부동 소수점 목록의 측정기준은 [1]이고 유형은 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))
이 예시에서는 스칼라 특성(즉, shape=[1])을 읽는 방법을 보여줍니다. 2D 또는 3D 배열(예: 이미지 패치)을 내보내는 경우 파싱 시 패치의 형태를 지정합니다(예: 16x16픽셀 패치의 경우 shape=[16, 16]).
이미지 내보내기
이미지를 내보낼 때 데이터는 채널, 높이, 너비 (CHW)로 정렬됩니다. 내보내기는 여러 TFRecord 파일로 분할될 수 있으며, 각 파일에는 내보내기에서 사용자가 지정한 크기 patchSize의 패치가 하나 이상 포함됩니다. 파일 크기(바이트)는 maxFileSize 매개변수에서 사용자가 지정합니다.
각 패치와 결과 TFRecord 파일의 각 tf.train.Example 사이에는 1:1 대응이 있습니다. 이미지의 각 대역은 각 tf.train.Example에서 별도의 tf.train.Feature로 저장됩니다. 여기서 각 특성에 저장된 부동 소수점 목록의 길이는 패치 너비 * 높이입니다. 평면화된 목록은 이 예와 같이 여러 개별 픽셀로 분할할 수 있습니다.
또는 내보낸 패치의 모양을 이 예시와 같이 복구할 수 있습니다.
에지 효과를 줄이기 위해 내보낸 패치가 겹칠 수 있습니다. 구체적으로는 kernelSize를 지정할 수 있으며, 이로 인해 다음과 같은 크기의 타일이 생성됩니다.
[patchSize[0] + kernelSize[0], patchSize[1] + kernelSize[1]]
각 타일은 인접한 타일과 [kernelSize[0]/2, kernelSize[1]/2]만큼 겹칩니다. 따라서 크기가 patchSize인 패치의 가장자리 픽셀을 중심으로 하는 크기가 kernelSize인 커널에는 완전히 유효한 데이터가 포함됩니다. 공간에서 패치의 공간적 배열은 그림 1에 나와 있습니다. 여기서 패딩 차원은 인접한 이미지와 겹치는 커널 부분에 해당합니다.
kernelSize/2입니다.
formatOptions
patchSize, maxFileSize, kernelSize 매개변수는 formatOptions 사전을 통해 ee.Export (JavaScript) 또는 ee.batch.Export(Python) 호출에 전달됩니다. 여기서 키는 Export에 전달되는 추가 매개변수의 이름입니다. TFRecord 형식으로 내보낸 이미지에 사용할 수 있는 formatOptions은 다음과 같습니다.
| 속성 | 설명 | 유형 |
|---|---|---|
patchDimensions |
내보내기 영역에 타일로 표시된 크기로, 경계 상자의 모든 픽셀을 정확히 한 번씩 포함합니다 (패치 크기가 경계 상자를 균등하게 나누지 않는 경우는 제외되며, 이 경우 가장 큰 x/y 가장자리를 따라 경계 타일이 삭제됨). 차원은 0보다 커야 합니다. | Array<int>[2]. |
kernelSize |
지정된 경우 타일은 여백 크기에 따라 양수 및 음수 방향으로 버퍼링되어 인접한 패치 간에 겹치게 됩니다. 지정된 경우 두 가지 측정기준 (각각 X 및 Y)을 제공해야 합니다. | Array<int>[2]. 기본값: [1, 1] |
compressed |
true인 경우 gzip으로 .tfrecord 파일을 압축하고 '.gz' 서픽스를 추가합니다. | 부울. 기본값: true |
maxFileSize |
내보낸 .tfrecord의 최대 크기 (바이트, 압축 전)입니다. 파일 크기가 작을수록 샤딩이 더 많아지므로 출력 파일이 더 많아집니다. | Int. 기본값: 1GiB |
defaultValue |
부분적으로 또는 완전히 마스킹된 픽셀의 각 밴드에 설정된 값과 소스 픽셀의 배열 길이가 특성 값의 깊이보다 작은 배열 밴드에서 생성된 출력 3D 특성의 각 값에 설정된 값입니다 (예: 해당 특성 깊이가 3인 배열 밴드에서 길이가 2인 배열 픽셀의 색인 3에 있는 값). 소수 부분은 정수 유형 밴드에서 삭제되고 밴드 유형의 범위로 고정됩니다. 기본값은 0입니다. | int. 기본값: 0 |
tensorDepths |
입력 배열 밴드의 이름에서 생성되는 3D 텐서의 깊이로의 매핑입니다. 배열은 지정된 형태에 맞게 잘리거나 기본값으로 채워집니다. 각 배열 대역에는 상응하는 항목이 있어야 합니다. | Array<int>[]. 기본값: [] |
sequenceData |
true인 경우 각 픽셀은 스칼라 밴드를 컨텍스트에 매핑하고 배열 밴드를 예시의 시퀀스에 매핑하는 SequenceExample로 출력됩니다. SequenceExamples는 각 패치의 픽셀 행 우선 순서로 출력된 다음 파일 시퀀스의 영역 패치 행 우선 순서로 출력됩니다. | 부울. 기본값: false |
collapseBands |
true인 경우 모든 밴드가 단일 3D 텐서로 결합되어 이미지의 첫 번째 밴드 이름을 사용합니다. 모든 밴드는 모든 밴드 내에서 해당 시퀀스에서 가장 먼 유형에 따라 바이트, int64, 부동 소수점 수 순서로 승격됩니다. tensor_depths가 지정된 경우 배열 밴드가 허용됩니다. | 부울. 기본값: false |
maskedThreshold |
패치에서 허용되는 마스크 처리된 픽셀의 최대 비율입니다. 이 허용량을 초과하는 패치는 파일에 기록되지 않고 삭제됩니다. 이 필드가 1이 아닌 값으로 설정되면 JSON 사이드카가 생성되지 않습니다. 기본값은 1입니다. | 부동 소수점 수. 기본값: 1 |
TFRecord '믹서' 파일
TFRecord로 내보내면 Earth Engine은 TFRecord 파일과 함께 '믹서'라는 사이드카를 생성합니다. 이는 패치의 공간 배열 (즉, 지리적 참조)을 정의하는 데 사용되는 간단한 JSON 파일입니다. 이 파일은 다음 섹션에 설명된 대로 이미지에 대한 예측을 업로드하는 데 필요합니다.
시계열 내보내기
Examples 및 SequenceExamples로의 이미지 내보내기가 지원됩니다. Examples로 내보내면 내보내기 영역이 패치로 분할되고 이러한 패치는 각 밴드가 자체 특성을 갖는 여러 .tfrecord 파일로 행 우선 순서로 내보내집니다(collapseBands를 지정하지 않는 한). SequenceExamples로 내보내면 픽셀당 SequenceExample이 내보내지며, 이러한 SequenceExamples는 패치 내에서 행 우선 순서로, 그런 다음 원래 내보내기 영역의 패치의 행 우선 순서로 내보내집니다(확실하지 않은 경우 항상 어떤 방식으로든 행 우선 순서로 진행된다고 가정하세요).
참고: 이미지의 모든 스칼라 밴드는 SequenceExample의 컨텍스트에 패킹되고 배열 밴드는 실제 시퀀스 데이터가 됩니다.
Array 밴드
이미지를 TFRecord 형식으로 내보낼 때 배열 밴드를 내보낼 수 있습니다. 배열 밴드를 내보내면 SequenceExamples의 'FeatureLists'를 채우고 일반 Examples로 내보낼 때 3D 텐서를 만들 수 있습니다. 배열 대역의 길이/깊이가 관리되는 방식에 관한 자세한 내용은 위 표의 collapseBands 또는 tensorDepths를 참고하세요. 참고: collapseBands를 사용하고 SequenceExamples로 내보내면 (따라서 sequenceData 매개변수 설정) 모든 밴드가 픽셀당 단일 시계열로 축소됩니다.
Earth Engine에 TFRecord 업로드
테이블 (명령줄만 해당)과 이미지를 TFRecord 파일로 Earth Engine에 업로드할 수 있습니다. 테이블의 경우 앞에서 설명한 1:1 관계가 역방향 (즉, tf.train.Example -> ee.Feature)으로 적용됩니다.
이미지 업로드 중
내보낸 이미지에서 예측을 생성하는 경우 예측을 업로드할 때 믹서를 제공하여 (TFRecord 파일로) 지리 참조 이미지를 가져옵니다. 패치의 겹치는 부분 (그림 1의 패딩 크기)은 삭제되어 내보낸 리전의 인접한 범위가 생성됩니다. 예측은 원래 내보낸 이미지 예시와 동일한 수와 순서의 tf.train.Example 시퀀스로 정렬되어야 합니다 (임의의 파일 수 사이에서도 마찬가지).