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로 내보낸 모든 숫자는 부동 소수점 유형으로 강제 변환됩니다.
테이블 내보내기
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보다 커야 합니다. | 배열<int>[2]. |
kernelSize |
지정된 경우 타일이 여백 크기로 양수 및 음수 방향으로 버퍼링되어 인접한 패치가 겹쳐집니다. 지정된 경우 두 가지 크기 (각각 X 및 Y)를 제공해야 합니다. | 배열<int>[2]. 기본값: [1, 1] |
compressed |
true인 경우 .tfrecord 파일을 gzip으로 압축하고 '.gz' 접미사를 추가합니다. | 부울. 기본값: true |
maxFileSize |
내보낸 .tfrecord의 최대 크기 (압축 전, 바이트)입니다. 파일 크기가 작을수록 샤딩이 더 많이 이루어지므로 출력 파일이 더 많아집니다. | 정수. 기본값: 1GiB |
defaultValue |
부분적으로 또는 완전히 마스킹된 픽셀의 각 밴드에 설정된 값과 소스 픽셀의 배열 길이가 특성 값의 깊이보다 작은 배열 밴드에서 만들어진 출력 3D 지형지물의 각 값에 설정된 값 (예: 상응하는 지형지물 깊이가 3인 배열 밴드에서 길이가 2인 배열 픽셀의 색인 3의 값) 소수 부분은 정수 유형 대역의 경우 삭제되고 대역 유형의 범위에 고정됩니다. 기본값은 0입니다. | 정수. 기본값: 0 |
tensorDepths |
입력 배열 밴드의 이름을 생성하는 3D 텐서의 깊이에 매핑합니다. 배열은 지정된 도형에 맞게 잘리거나 기본값으로 채워집니다. 배열 밴드마다 이에 상응하는 항목이 있어야 합니다. | 배열<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가 내보내지며, 이러한 SequenceExample는 패치 내에서 행 우선 순서로, 그런 다음 원래 내보내기 영역의 패치 행 우선 순서로 내보내집니다(확실하지 않은 경우 항상 모든 항목이 행 우선 순서로 되어 있다고 가정).
참고: 이미지의 모든 스칼라 밴드는 SequenceExample의 컨텍스트에 패킹되지만 배열 밴드는 실제 시퀀스 데이터가 됩니다.
배열 밴드
이미지를 TFRecord 형식으로 내보낼 때 배열 밴드를 내보낼 수 있습니다. 배열 밴드 내보내기는 SequenceExamples의 'FeatureLists'를 채우는 수단과 일반 예시로 내보낼 때 3D 텐서를 만드는 방법을 제공합니다. 배열 밴드의 길이/깊이가 관리되는 방식에 관한 자세한 내용은 위 표의 collapseBands 또는 tensorDepths를 참고하세요. 참고: collapseBands를 사용하고 SequenceExamples로 내보내면 (즉, sequenceData 매개변수를 설정) 모든 밴드가 픽셀당 단일 시계열로 축소됩니다.
Earth Engine에 TFRecords 업로드
테이블 (명령줄만 해당)과 이미지를 TFRecord 파일로 Earth Engine에 업로드할 수 있습니다. 테이블의 경우 앞서 설명한 1:1 관계가 역방향으로 적용됩니다 (예: tf.train.Example -> ee.Feature).
이미지 업로드 중
내보낸 이미지에서 예측을 생성하는 경우 예측을 TFRecord 파일로 업로드할 때 믹서를 제공하여 지리적 참조 이미지를 가져옵니다. 패치의 겹치는 부분 (그림 1의 패딩 크기)은 삭제되므로 내보낸 영역이 연속적으로 적용됩니다. 예측은 원래 내보낸 이미지 예시와 동일한 수와 순서의 tf.train.Example 시퀀스로 정렬되어야 합니다 (임의 개수의 파일 간에 있더라도).