Earth Engine は、Google Cloud Storage（GCS）に保存されている Cloud Optimized GeoTIFF（COG）でバックアップされたアセットをサポートしています。
COG 対応アセットを登録すると、Earth Engine は作成時に画像の空間フィールドとメタデータ フィールドのインデックスを作成します。これにより、コレクションで使用した場合に、標準の取り込みアセットと同等のパフォーマンスが得られます（Cloud Optimized GeoTIFF（COG）の概要をご覧ください）。
前提条件と Cloud Storage の設定
COG を登録する前に、Google Cloud Storage リソースを正しく設定する必要があります。
1. バケットのロケーション（厳格な要件）
Earth Engine が Cloud Storage バケットにアクセスするには、バケットが次のいずれかのデータセンター リージョンまたはマルチリージョンに存在する必要があります。
usマルチリージョンus-central1を含む任意の米国デュアルリージョンus-central1リージョン
バケットが他のリージョン データセンター（us-east4 や europe-west1 など）に配置されている場合、Earth Engine は登録リクエストと読み取りリクエストを拒否します。
2. ストレージ クラスと課金
- Standard ストレージ クラスを使用することをおすすめします。Standard Storage には最小保存期間のルールがないため、一時ファイルを更新または置換しても、早期削除による課金ペナルティを回避できます。
- Earth Engine の計算ループでは Cloud Storage のデータ取得の追加料金は発生しませんが、外部ツール（デスクトップ GIS ソフトウェアなど）から Standard Storage 以外のストレージ ティアにアクセスすると、高額な取得料金が発生します。
- GCS を使用するには、Google Cloud プロジェクトで課金を有効にする必要があります。開始するには、Google Cloud Storage のクイックスタートをご覧ください。
ステップ 1: COG を準備する
TIFF ファイルはクラウド向けに最適化されている必要があります。TIFF は次の要件を満たしている必要があります。
- タイル形式。タイルサイズは 256x256、512x512、1024x1024、2048x2048。最適なパフォーマンスを得るには、512x512 以上のサイズをおすすめします。
- すべての画像ファイル ディレクトリ（IFD）が先頭に配置されるように構成されています。
- 2 の累乗の概要を含めます。
- BAND インターリーブを使用します。
GDAL を使用して画像を変換できます。
GDAL COG ドライバを使用する（GDAL 3.1 以上を推奨）:
gdal_translate in.tif out.tif \
-of COG \
-co BIGTIFF=YES \
-co OVERVIEWS=IGNORE_EXISTING \
-co COMPRESS=ZSTD \
-co LEVEL=16 \
-co BLOCKSIZE=512 \
-co INTERLEAVE=BAND \
-co NUM_THREADS=ALL_CPUS \
-co PREDICTOR=2 # 2 for integers, 3 for floating point
標準の GTiff ドライバを使用する:
まず、内部の 2 の累乗の概要を生成し（gdal raster overview add または gdaladdo を使用）、画像と概要をタイル状の COG レイアウトにコピーします。
gdaladdo -r nearest in.tif 2 4 8 16 32 # or -r cubic for continuous/float data
gdal_translate in.tif out.tif \
-co BIGTIFF=YES \
-co COPY_SRC_OVERVIEWS=YES \
-co TILED=YES \
-co BLOCKXSIZE=512 \
-co BLOCKYSIZE=512 \
-co COMPRESS=ZSTD \
-co ZSTD_LEVEL=16 \
-co INTERLEAVE=BAND \
-co NUM_THREADS=ALL_CPUS \
-co PREDICTOR=2 # 2 for integers, 3 for floating point
ステップ 2: マニフェストを作成する
Earth Engine Python クライアント ライブラリ、earthengine コマンドライン ツール、Earth Engine REST API のいずれを使用して COG を登録する場合でも、アセットの宛先、Google Cloud Storage URI、オプションのバンド メタデータを指定する画像アップロード マニフェストを定義する必要があります。
例: すべてのバンドをサポートする単一の COG COG にすべてのバンド（RGB など）が含まれている場合、マニフェストに必要なタイルセットは 1 つだけです。
{
"name": "projects/my-project/assets/my_cog_asset",
"tilesets": [
{
"id": "default_tileset",
"sources": [
{
"uris": [
"gs://google-sample-bucket/my_optimized_image.tif"
]
}
]
}
]
}
例: 複数の COG（バンドごとに 1 つ） 異なるバンドに個別のファイルがある場合（例: 赤、緑、青の個別のファイル）:
{
"name": "projects/my-project/assets/my_multi_band_cog",
"tilesets": [
{
"id": "red_tileset",
"sources": [ { "uris": [ "gs://google-sample-bucket/band_red.tif" ] } ]
},
{
"id": "green_tileset",
"sources": [ { "uris": [ "gs://google-sample-bucket/band_green.tif" ] } ]
}
],
"bands": [
{ "id": "R", "tilesetId": "red_tileset", "tilesetBandIndex": 0 },
{ "id": "G", "tilesetId": "green_tileset", "tilesetBandIndex": 0 }
]
}
ステップ 3: 登録リクエストを送信する
マニフェストを Earth Engine に送信するには、Earth Engine Python クライアント ライブラリ、earthengine コマンドライン ツール、または Earth Engine REST API を使用します。ワークフローに最適な方法を選択してください。
Python クライアント ライブラリ
Python スクリプトまたは Jupyter ノートブックで、プロジェクトを初期化した後に Earth Engine Python クライアント ライブラリ（ee.data）を使用します。
import ee # 1. Authenticate and initialize ee.Authenticate() ee.Initialize(project='your-project-id') # 2. Define the manifest as a Python dictionary manifest = { "name": "projects/your-project-id/assets/my_cog_asset", "tilesets": [ { "id": "default_tileset", "sources": [ { "uris": [ "gs://google-sample-bucket/my_optimized_image.tif" ] } ] } ] } # 3. Start the ingestion task (allow_overwrite=True corresponds to --force) result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) print(f"Asset registered: {result['name']}")
コマンドライン ツール
ターミナルで、マニフェストを manifest.json という名前のファイルに保存し、earthengine アップロード コマンドを実行します。
# 1. Verify your environment is authenticated earthengine authenticate # 2. Submit the external image upload task earthengine --project your-project-id \ upload external_image \ --manifest manifest.json
REST API（Python）
クライアント ライブラリを使用せずにワークフローを自動化するには、承認済みの POST リクエストを Earth Engine REST API エンドポイント
projects.image.importExternal に直接送信します（ここでは Python を使用して説明します）。
import json from pprint import pprint import ee from google.auth.transport.requests import AuthorizedSession # 1. Authenticate and start an authorized HTTP session ee.Authenticate() ee_project = 'your-project-id' session = AuthorizedSession( ee.data.get_persistent_credentials().with_quota_project(ee_project) ) # 2. Define the REST request body wrapping the manifest request = { 'imageManifest': { 'name': f'projects/{ee_project}/assets/my_cog_asset', 'tilesets': [ { 'id': 'default_tileset', 'sources': [ { 'uris': [ 'gs://google-sample-bucket/my_optimized_image.tif' ] } ] } ] } } # 3. Send the POST request url = ( 'https://earthengine.googleapis.com/v1alpha/' f'projects/{ee_project}/image:importExternal' ) response = session.post(url=url, data=json.dumps(request)) pprint(json.loads(response.content))
登録リクエストを送信すると、軽量のメタデータ インデックス登録オペレーションが開始されます。COG 登録ではピクセルデータがコピーされないため、通常はこのオペレーションは数秒で完了します。
COG アセットのマニフェストの制限
COG 対応アセットのマニフェストを作成する場合は、次の厳格な制限事項（標準の取り込みマニフェストとは異なります）に注意してください。
- 単一バケット: マニフェスト内のすべての URI は、同じ GCS バケットに存在する必要があります。
- ソースごとに 1 つの URI: 各
ImageSourceには、URI を 1 つだけ含める必要があります。複数のファイルを 1 つのタイルセット ソースにモザイク化することはできません。複数の COG シーンをモザイク化するには、各 COG をアセットとして登録し、.mosaic()を使用してee.ImageCollectionに結合します。 mask_bandsなし: 最上位のmask_bandsはサポートされていません。マニフェストでmissingDataを使用するか、TIFF に内部 nodata 値があることを確認します。- タイルセットに
data_typeがない:tilesetsセクションでdata_typeを指定しないでください。自動的に検出されます。 - ソースに
dimensionsがない:ImageSourceにdimensionsを指定しないでください。 subdataset_prefix/subdataset_suffixなし。min_tile_area_ratioまたはskip_metadata_readがありません。
ステップ 4: 権限を構成する（共有に不可欠）
標準の Earth Engine アセットとは異なり、COG のピクセルデータは GCS に残ります。COG を利用したアセットを他のユーザーと共有する場合は、Earth Engine アセットと GCS ファイルの両方に対する読み取りアクセス権を付与する必要があります。
1. GCS バケットの権限を付与する
共同編集者には、GCS からファイルを読み取る権限が必要です。
必要な権限:
storage.buckets.get（バケットのメタデータとロケーションを取得するため）storage.objects.get（ピクセルデータを読み取るため）
これらの権限は、次の標準の Cloud Storage ロールを使用して付与できます。
- ストレージ バケット閲覧者（バケットのメタデータとロケーションを読み取る
storage.buckets.getを提供します） - ストレージ オブジェクト閲覧者（ピクセルデータを読み取るための
storage.objects.getを提供）
Google Cloud コンソールで構成する手順:
- Cloud Storage の [ブラウザ] に移動します。
- バケット名をクリックします。
- [権限] タブを選択します。
- [アクセスを許可] をクリックします。
- 共同編集者のメールアドレス（または Google グループ、一般公開アクセスの場合は
allUsers）を追加します。 - Storage バケット閲覧者と Storage オブジェクト閲覧者のロールを割り当てます。
- [保存] をクリックします。
2. Earth Engine アセットを共有する
Earth Engine アセット マネージャーまたは CLI を使用して、アセット自体を共有します。詳細については、アセット管理ガイドをご覧ください。
オブジェクトの世代の管理
COG を登録すると、Earth Engine は GCS オブジェクトの特定の世代（バージョン）を保存します。GCS でファイルを更新すると、その世代が変更されます。
- デフォルトでは、Earth Engine はアセットの読み込みに失敗し、エラー
Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generationを返します。 - これは、メタデータ（投影やフットプリントなど）が基盤となるピクセルと同期しなくなるのを防ぐように設計されています。
ベスト プラクティス: 基盤となる画像データを更新する必要がある場合は、ファイルをその場で上書きするのではなく、新しいアセットとして登録するか、
--forceフラグを指定してアップロード コマンドを再実行します。earthengine --project your-project-id upload external_image --force --manifest manifest.json
登録済みのアセットを使用する
登録された COG ベースのアセットは、標準の取り込み済み画像アセットと同様に、Earth Engine スクリプトでアクセスされます。
JavaScript
var image = ee.Image('projects/your-project-id/assets/my_cog_asset');
Python
image = ee.Image('projects/your-project-id/assets/my_cog_asset')