Cloud Optimized GeoTIFF(COG)アセットを登録する

Earth Engine は、Google Cloud Storage(GCS)に保存されている Cloud Optimized GeoTIFF(COG)を基盤とするアセットをサポートしています。

COG を基盤とするアセットを登録すると、Earth Engine は作成時に画像の空間フィールドとメタデータ フィールドにインデックスを付けます。これにより、コレクションで使用する場合に、標準の取り込みアセットに匹敵するパフォーマンスが得られます(Cloud Optimized GeoTIFF(COG)の概要をご覧ください)。

このガイドでは、ファイルの準備、マニフェストの作成、登録リクエストの送信、権限の構成、登録済みアセットの更新または削除について説明します。

始める前に

COG を登録する前に、Cloud Storage リソースを正しく設定する必要があります。

バケットのロケーション

Earth Engine が Cloud Storage バケットにアクセスするには、バケットが次のいずれかのデータセンター リージョンまたはマルチリージョンに存在する必要があります。

  • us マルチリージョン
  • us-central1 を含む任意の米国のデュアルリージョン
  • us-central1 リージョン

バケットが他のリージョン データセンター(us-east4 や europe-west1 など)に配置されている場合、Earth Engine は登録リクエストと読み取りリクエストを拒否します。サポートされている Cloud Storage バケットのロケーションをご覧ください。

ストレージ クラスと課金

  • Standard ストレージ クラスを使用することをおすすめします。Standard Storage には最小保存期間のルールがないため、一時ファイルを更新または置換しても、早期削除の課金ペナルティは発生しません。
  • Earth Engine の計算ループでは Cloud Storage のデータ取得の追加料金は発生しませんが、外部ツール(デスクトップ GIS ソフトウェアなど)から Standard Storage 以外のストレージ ティアにアクセスすると、高額な取得料金が発生します。
  • Cloud Storage を使用するには、Google Cloud プロジェクトで課金を有効にする必要があります。開始するには、Cloud Storage クイックスタートをご覧ください。

COG を準備する

Earth Engine は Cloud Storage から COG を直接読み取り、計算に必要なヘッダーとタイルのみを取得するため、ファイル レイアウトが重要になります。TIFF は次の要件を満たす必要があります。

  • タイル。16x16 から 2048x2048 までの 2 の累乗の正方形のタイルサイズ。最適なパフォーマンスを得るには、512x512 をおすすめします。
  • すべての画像ファイル ディレクトリ(IFD)が先頭に配置されるように配置されています。
  • 2 の累乗の概要がある場合は、それを含めます。オーバービューは必須ではありませんが、1 つのタイルよりも大きい画像にはオーバービューを使用することをおすすめします。
  • BAND または PIXEL インターリーブを使用します(トレードオフについては、シングルバンド ファイルとマルチバンド ファイルをご覧ください)。

画像を変換するには、GDAL の COG ドライバを使用します。このドライバは、必要なレイアウト(タイリング、概要、ヘッダーの配置)を 1 ステップで生成します。カテゴリデータに OVERVIEW_RESAMPLING=NEAREST を追加します。デフォルトは CUBIC です。圧縮、概要、レイアウトに関する推奨事項については、外部 COG の準備に関するベスト プラクティスをご覧ください。

GDAL 3.11 以降の CLI

gdal raster convert in.tif out.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co OVERVIEWS=IGNORE_EXISTING \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

従来の CLI

3.11 より前の GDAL バージョンでは INTERLEAVE=BAND を省略します。

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

マニフェストを作成する

Earth Engine Python クライアント ライブラリ、earthengine コマンドライン ツール、Earth Engine REST API のいずれを使用して COG を登録する場合でも、アセットの宛先、Cloud Storage URI、オプションのバンド メタデータを指定する画像アップロード マニフェストを定義する必要があります。API とコマンドラインツールは、COG がバックアップするアセットを外部イメージ(ee.data.startExternalImageIngestion()、earthengine upload external_image、projects.image.importExternal)と参照します。

例: すべてのバンドをサポートする単一の 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 }
  ]
}

マニフェストの制限

COG を基盤とするアセットのマニフェストには、標準の取り込みマニフェストには適用されない制限があります。

  • 単一のバケット: マニフェスト内のすべての URI は、同じ Cloud Storage バケットに存在する必要があります。
  • ソースごとに 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。

登録リクエストを送信する

マニフェストを 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. Register the asset
result = ee.data.startExternalImageIngestion(manifest)
print(f"Asset registered: {result['name']}")

コマンドライン ツール

ターミナルで、マニフェストを manifest.json という名前のファイルに保存し、earthengine アップロード コマンドを実行します。

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Register the asset
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

REST API

クライアント ライブラリを使用しない自動ワークフローの場合は、承認済みの 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 登録ではピクセルデータがコピーされないため、通常、このオペレーションは数秒で完了します。

権限を構成する

標準の Earth Engine アセットとは異なり、COG のピクセルデータは Cloud Storage に残ります。COG を利用したアセットを他のユーザーと共有する場合は、Earth Engine アセットと Cloud Storage ファイルの両方に対する読み取りアクセス権を付与する必要があります。

Cloud Storage バケットの権限を付与する

共同編集者には、Cloud Storage からファイルを読み取る権限が必要です。

必要な権限:

  • storage.buckets.get(バケットのメタデータとロケーションを取得するため)
  • storage.objects.get(ピクセルデータを読み取るため)

これらの権限を付与するには、次の標準の Cloud Storage ロールを使用します。

  • Storage バケット閲覧者(バケットのメタデータとロケーションを読み取る storage.buckets.get を提供)
  • ストレージ オブジェクト閲覧者(ピクセルデータを読み取るための storage.objects.get を提供)

Google Cloud コンソールで構成する手順:

  1. Cloud Storage の [ブラウザ] に移動します。
  2. バケット名をクリックします。
  3. [権限] タブを選択します。
  4. [アクセスを許可] をクリックします。
  5. 共同編集者のメールアドレス(または Google グループ、一般公開アクセスの場合は allUsers)を追加します。
  6. Storage バケット閲覧者と Storage オブジェクト閲覧者のロールを割り当てます。
  7. [保存] をクリックします。

Earth Engine アセットを共有する

Earth Engine アセット マネージャーまたは CLI を使用して、アセット自体を共有します。詳しくは、アセット管理ガイドをご覧ください。

COG を基盤とするアセットの更新、置換、削除

COG を基盤とするアセットは、Cloud Storage 内の特定のバージョンのファイルへのポインタと、登録時に Earth Engine がインデックスに登録したメタデータ(フットプリント、投影、バンド、概要レイアウト)です。Earth Engine はファイル バージョンを固定して、このメタデータがピクセルと同期しなくなるのを防ぎます。これにより、COG を基盤とするアセットの更新は、標準アセットの更新とは異なります。

オブジェクトの世代

COG を登録すると、Earth Engine は Cloud Storage オブジェクトの世代(バージョン番号)を URI とともに記録します。固定された世代は、アセットのメタデータで確認できます。URI の #<generation> 接尾辞として表示されます。

Python

asset = ee.data.getAsset('projects/your-project-id/assets/my_cog_asset')
print(asset['tilesets'][0]['sources'][0]['uris'])
# ['gs://google-sample-bucket/my_optimized_image.tif#1750427474244728']

アセットを登録(または再登録)するときに、マニフェスト URI に #<generation> 接尾辞を含めることで、特定のバージョンを自分で固定することもできます。指定しない場合、Earth Engine は現在のオブジェクトを読み取り、見つかった世代を固定します。明示的に固定すると、オブジェクトのバージョニングが有効なバケットに保持されている以前のバージョンにロールバックする場合に便利です。

Cloud Storage でファイルを上書きすると、新しい世代が作成されます。削除すると、固定された世代はなくなります。どちらの場合も、バケットのオブジェクトのバージョニングで古い世代が保持されていない限り、アセットのピクセルの読み取りは失敗します。古い世代が保持されている場合、Earth Engine は古いピクセルを読み取り続けます。インデックス付きレコードを使用するメタデータ オペレーション(ee.data.getAsset()、bandNames()、コレクション フィルタリングなど)は、どちらの方法でも機能します。

ファイルを変更した後にアセットを更新する

既存のアセットを新しいバージョンのファイルにポイントするには、同じアセット名で再登録し、上書きを有効にします。Earth Engine は、1 回の同期呼び出しで GeoTIFF ヘッダーを再読み取りし、メタデータを再インデックス化して、新しい世代を固定します。アセットの既存の権限は保持されますが、プロパティ、期間、バンド名は新しいマニフェストから取得されるため、以前に ee.data.updateAsset() で設定した内容が含まれます。

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • コマンドライン: earthengine upload external_image --force --manifest manifest.json
  • REST API: projects.image.importExternal リクエスト本文の "imageManifest" とともに、"overwrite": true を最上位フィールドとして含めます。

最初にアセットを削除する必要はありません。削除すると、スタンドアロン アセットの権限が失われ、コレクション内の画像がコレクションから一時的に消えるため、逆効果になります。ee.data.updateAsset()(projects.assets.patch)で変更できるのは、プロパティ、期間、バンド名のみです。アセットが参照するファイルは変更できません。

独立したライフサイクル

Earth Engine アセットと Cloud Storage オブジェクトは別々に管理されます。

  • Earth Engine アセット(earthengine rm または ee.data.deleteAsset())を削除すると、アセットレコードのみが削除されます。Cloud Storage 内のファイルは変更されません。
  • Cloud Storage でファイルを削除しても、アセットは削除されません。アセットは引き続きリスティングとコレクションに表示されます(オブジェクトの世代をご覧ください)。

大規模なコレクションを操作する

Earth Engine API にはバッチ削除や再帰削除はありません。各アセットを個別に削除する必要があります。また、コレクションを削除するには、コレクションを空にする必要があります。earthengine rm -r はこの処理を自動的に行いますが、削除は 1 つずつ行われるため、数万枚の画像を含むコレクションを削除するには数時間かかることがあります。

  • コレクションの画像を置き換えるには、削除するのではなく上書きします。 上書きを有効にして、各イメージを名前で再登録します(上記参照)。これにより、2 つではなく 1 つの画像につき 1 つのリクエストが必要になり、コレクション全体が常に保持され、権限が設定されているコレクション自体の削除と再作成を回避できます。新しいセットに含まれていないイメージのみを削除します。
  • 多くのアセットを削除するには、スクリプトから並列化します。ee.data.listAssets() を使用してアセットを一覧表示し(BASIC ビューを使用。すべてのイメージの完全なメタデータではなく、名前とタイプのみを返します)、小さなスレッドプールから削除します。アセット リクエストはプロジェクト全体でレート制限を共有するため、同時実行数を控えめ(約 10 ワーカー)に保ち、クライアント ライブラリの組み込みの再試行で 429 Too Many Requests レスポンスを処理できるようにします。

    Python

    import concurrent.futures
    import ee
    
    ee.Initialize(project='your-project-id')
    collection = 'projects/your-project-id/assets/my_collection'
    
    listing = ee.data.listAssets({'parent': collection, 'view': 'BASIC'})
    asset_ids = [a['name'] for a in listing['assets']]
    
    def delete(asset_id):
      try:
        ee.data.deleteAsset(asset_id)
      except ee.EEException as e:
        return f'{asset_id}: {e}'
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
      failures = [f for f in executor.map(delete, asset_ids) if f]
    
    if failures:
      print('\n'.join(failures))
    else:
      ee.data.deleteAsset(collection)
    

    コレクションは、すべての画像が削除された場合にのみ削除されます。そのため、部分的な失敗が発生した場合は、再実行のためにコレクションがそのまま残ります。

    同じパターンが、多くのイメージの登録に適用されます。ヘルパーの ee.data.deleteAsset(asset_id) を ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) に置き換え、マニフェストのリストにマッピングします。最初の実行でも allow_overwrite=True を渡すと、部分的な失敗の後にバッチを安全に再実行できます。これは、すでに作成されているアセットがエラーの原因となるのではなく、置き換えられるためです。

登録済みのアセットを使用する

登録が完了すると、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')

権限、ファイルの更新、大規模なコレクションの管理に関するよくある質問とその回答については、よくある質問の COG セクションをご覧ください。