このページは Cloud Translation API によって翻訳されました。

TFRecord と Earth Engine

TFRecord は、長い tf.Example protos シーケンスを効率的にエンコードするためのバイナリ形式です。TFRecord ファイルは、こちらとこちらで説明されているように、tf.data パッケージを介して TensorFlow によって簡単に読み込まれます。このページでは、Earth Engine が ee.FeatureCollection または ee.Image と TFRecord 形式を変換する方法について説明します。

データを TFRecord にエクスポートする

テーブル（ee.FeatureCollection）または画像（ee.Image）を Google ドライブまたは 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 圧縮形式で圧縮されます。エクスポートごとに必ず 1 つの TFRecord ファイルが生成されます。

次の例は、スカラープロパティ（「B2」、「B3」、「B4」、「B5」、「B6」、「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 のパッチが 1 つ以上含まれています。ファイルのサイズ（バイト単位）は、ユーザーが 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 に示されています。ここで、パディングディメンションは、隣接する画像と重複するカーネルの部分に対応しています。

TFRecord 画像の図 — 図 1. イメージパッチのエクスポート方法。パディングディメンションは `kernelSize/2` です。

`formatOptions`

patchSize、maxFileSize、kernelSize パラメータは、formatOptions 辞書を介して ee.Export（JavaScript）または ee.batch.Export（Python）呼び出しに渡されます。キーは、Export に渡される追加パラメータの名前です。TFRecord 形式にエクスポートされた画像の formatOptions は次のとおりです。

プロパティ	説明	タイプ
`patchDimensions`	エクスポート領域にタイルを並べて、境界ボックス内のすべてのピクセルを 1 回ずつカバーします（パッチのサイズが境界ボックスを均等に分割しない場合を除きます。この場合、最大の x/y エッジに沿った境界タイルは破棄されます）。サイズは 0 より大きい値にする必要があります。	Array<int>[2]。
`kernelSize`	指定すると、タイルはマージンのサイズで正方向と負方向の両方でバッファリングされ、隣接するパッチが重なり合います。指定する場合は、2 つのディメンション（X と Y）を指定する必要があります。	Array<int>[2]。デフォルト: [1, 1]
`compressed`	true の場合、.tfrecord ファイルを gzip で圧縮し、「.gz」という接尾辞を追加します。	ブール値。デフォルト: true
`maxFileSize`	エクスポートされた .tfrecord の最大サイズ（圧縮前）。ファイルサイズが小さいほど、シャーディングが大きくなり（出力ファイルが増えます）。	Int。デフォルト: 1 GiB
`defaultValue`	部分的または完全にマスキングされたピクセルの各バンドに設定された値と、ソースピクセルの配列長が特徴値の深さ（対応する特徴深さが 3 の配列バンド内の長さ 2 の配列ピクセルのインデックス 3 の値）より小さい配列バンドから作成された出力 3D 特徴の各値に設定された値。整数型のバンドでは小数部分が破棄され、バンドタイプの範囲にクランプされます。デフォルトは 0 です。	整数。デフォルト: 0
`tensorDepths`	入力配列バンドの名前から、作成する 3D テンソルの深さへのマッピング。配列は、指定されたシェイプに合わせて切り捨てられるか、デフォルト値でパディングされます。配列バンドごとに、対応するエントリが必要です。	Array<int>[]。デフォルト: []
`sequenceData`	true の場合、各ピクセルは、スカラーバンドをコンテキストにマッピングし、配列バンドを例のシーケンスにマッピングする SequenceExample として出力されます。SequenceExamples は、各パッチのピクセルの行優先順序で出力され、次にファイルシーケンス内の領域パッチの行優先順序で出力されます。	ブール値。デフォルト: false
`collapseBands`	true の場合、すべてのバンドが 1 つの 3D テンソルに結合され、画像の最初のバンドの名前が付けられます。すべてのバンドは、すべてのバンド内のシーケンスで最も遠い型に応じて、バイト、int64、浮動小数点数に昇格されます。テンソル深度が指定されている限り、配列帯域は使用できます。	ブール値。デフォルト: false
`maskedThreshold`	パッチ内のマスクされたピクセルの最大許容割合。この許容量を超えるパッチは、ファイルに書き込まれるのではなく破棄されます。このフィールドが 1 以外に設定されている場合、JSON サイドカーは生成されません。デフォルトは 1 です。	浮動小数点数。デフォルト: 1

TFRecord の「ミキサー」ファイル

TFRecord にエクスポートすると、Earth Engine は「ミキサー」と呼ばれる TFRecord ファイルを含むサイドカーを生成します。これは、パッチの空間配置（ジオリファレンス）の定義に使用される単純な JSON ファイルです。このファイルは、次のセクションで説明するように、画像に基づいて作成された予測をアップロードするために必要です。

時系列のエクスポート

Examples と SequenceExamples の両方への画像のエクスポートがサポートされています。Examples にエクスポートする場合、エクスポート領域はパッチに分割され、これらのパッチは行優先で複数の .tfrecord ファイルにエクスポートされます。各バンドは独自の特徴を持ちます（collapseBands を指定しない限り）。SequenceExamples にエクスポートする場合は、ピクセルごとに SequenceExample がエクスポートされ、これらの SequenceExample はパッチ内で行優先で、元のエクスポート領域のパッチの行優先でエクスポートされます（不明な場合は、常に何らかの容量で行優先で処理されるものと想定してください）。注: 画像のすべてのスカラーバンドは SequenceExample のコンテキストにパックされますが、配列バンドは実際のシーケンスデータになります。

配列バンド

配列バンドは、画像が TFRecord 形式にエクスポートされたときにエクスポートできます。配列バンドのエクスポートは、SequenceExamples の「FeatureLists」に入力する手段と、通常の Examples にエクスポートするときに 3D テンソルを作成する手段を提供します。アレイバンドの長さ / 深さを管理する方法については、上の表の collapseBands または tensorDepths をご覧ください。注: collapseBands を使用して SequenceExamples にエクスポートすると（つまり、パラメータ sequenceData を設定すると）、すべてのバンドがピクセルごとに 1 つの時系列に集約されます。

TFRecords を Earth Engine にアップロードする

テーブル（コマンドラインのみ）と画像は、TFRecord ファイルとして Earth Engine にアップロードできます。テーブルの場合、前述の 1 対 1 の関係は逆方向（tf.train.Example -> ee.Feature）に適用されます。

画像のアップロード

エクスポートされた画像に対して予測を生成する場合、予測をアップロードするときにミキサーを指定して、地理参照付き画像を取得します（TFRecord ファイルとしてアップロードします）。パッチの重複部分（図 1 のパディングディメンション）は破棄され、エクスポートされた領域が連続してカバーされます。予測は、元のエクスポートされた画像サンプルと同じ数と順序の tf.train.Example シーケンスとして配置する必要があります（任意の数のファイル間であっても同様です）。

TFRecord と Earth Engine コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。