Quickstart

このガイドでは、Google Colab を使用して Python から Earth Engine REST API にクエリを発行する方法について説明します。同じコンセプトが、他の言語や環境から API にアクセスする場合にも適用されます。

注: REST API には、すべてのユーザーに適しているとは限らない新しい上級者向け機能が含まれています。Earth Engine を初めて使用する場合は、JavaScript ガイドから始めてください。

始める前に

こちらの手順に沿って、次の操作を行います。

  • Earth Engine へのアクセスを構成する
  • サービス アカウントを作成する

Colab ノートブックを設定する

このクイックスタートを最初から始める場合は、Colab のスタートページで [NEW NOTEBOOK] をクリックして新しい Colab ノートブックを作成し、以下のコードサンプルを新しいコードセルに入力します。Colab には Cloud SDK がすでにインストールされています。これには、Cloud サービスの管理に使用できる gcloud コマンドライン ツールが含まれています。または、このページの冒頭にあるボタンからデモ ノートブックを実行します。

Google Cloud に対して認証を行う

最初に行うことは、Google Cloud に認証済みのリクエストを送信できるようにログインすることです。

Colab では、次の操作を行うことができます。

PROJECT = 'my-project'
!gcloud auth login --project {PROJECT}

(ローカルで実行している場合は、Cloud SDK がインストールされていることを前提として、コマンドラインから実行します)。

PROJECT='my-project'
gcloud auth login --project $PROJECT

Google ユーザー アカウントを使用してログインするためのオプションを受け入れ、ログイン プロセスを完了します。

サービス アカウントの秘密鍵ファイルを取得する

サービス アカウントを使用して認証を行う前に、秘密鍵ファイルをダウンロードする必要があります。Colab でこれを行うには、ノートブック VM にダウンロードします。

SERVICE_ACCOUNT='foo-name@project-name.iam.gserviceaccount.com'
KEY = 'my-secret-key.json'
!gcloud iam service-accounts keys create {KEY} --iam-account {SERVICE_ACCOUNT}

または、コマンドラインから次のコマンドを実行します。

SERVICE_ACCOUNT='foo-name@project-name.iam.gserviceaccount.com'
KEY='my-secret-key.json'
gcloud iam service-accounts keys create $KEY --iam-account $SERVICE_ACCOUNT

認証情報へのアクセスとテスト

これで、Earth Engine API に最初のクエリを送信する準備が整いました。秘密鍵を使用して認証情報を取得します。認証情報を使用して、HTTP リクエストを行うための承認済みセッションを作成します。このコードは、Colab ノートブックの新しいコードセルに入力できます。(コマンドラインを使用している場合は、必要なライブラリがインストールされていることを確認する必要があります)。

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

credentials = service_account.Credentials.from_service_account_file(KEY)
scoped_credentials = credentials.with_scopes(
    ['https://www.googleapis.com/auth/cloud-platform'])

session = AuthorizedSession(scoped_credentials)

url = 'https://earthengine.googleapis.com/v1alpha/projects/earthengine-public/assets/LANDSAT'

response = session.get(url)

from pprint import pprint
import json
pprint(json.loads(response.content))

すべてが正しく構成されている場合、これを実行すると次のような出力が生成されます。

{'id': 'LANDSAT',
 'name': 'projects/earthengine-public/assets/LANDSAT',
 'type': 'FOLDER'}

データセットを選択する

利用可能なデータセットを検索して探索するには、code.earthengine.google.com の Earth Engine コードエディタを使用します。Sentinel 2 のデータを探してみましょう。(コードエディタを初めて使用する場合は、ログイン時に、ユーザーに代わって Earth Engine にアクセスすることを承認するよう求められます)。コードエディタで、上部の検索ボックスに「sentinel」と入力して検索します。複数のラスター データセットが表示されます。

[Sentinel-2: MultiSpectral Instrument (MSI), Level-1C] をクリックします。

このようなデータセットの説明ページには、Earth Engine 公開 Data Catalog のデータセットを使用するために必要な重要な情報が含まれています。たとえば、データセットの簡単な説明、詳細情報を取得するためのデータ プロバイダへのリンク、データセットに適用される可能性のある使用制限に関する情報、データセットの Earth Engine アセット ID などです。

この場合、ウィンドウの右側に、パスが COPERNICUS/S2_HARMONIZED の画像コレクション アセットであることが表示されます。

特定の画像をクエリする

この Sentinel-2 データセットには、2015 年から現在までの世界をカバーする 200 万枚以上の画像が含まれています。画像コレクションに対して projects.assets.listImages クエリを発行して、2017 年 4 月のデータのうち、カリフォルニア州マウンテンビューの特定の地点を含む、雲量の少ないデータを見つけてみましょう。

import urllib

coords = [-122.085, 37.422]

project = 'projects/earthengine-public'
asset_id = 'COPERNICUS/S2_HARMONIZED'
name = '{}/assets/{}'.format(project, asset_id)
url = 'https://earthengine.googleapis.com/v1alpha/{}:listImages?{}'.format(
  name, urllib.parse.urlencode({
    'startTime': '2017-04-01T00:00:00.000Z',
    'endTime': '2017-05-01T00:00:00.000Z',
    'region': '{"type":"Point", "coordinates":' + str(coords) + '}',
    'filter': 'CLOUDY_PIXEL_PERCENTAGE < 10',
}))

response = session.get(url)
content = response.content

for asset in json.loads(content)['images']:
    id = asset['id']
    cloud_cover = asset['properties']['CLOUDY_PIXEL_PERCENTAGE']
    print('%s : %s' % (id, cloud_cover))

このスクリプトは、一致する画像をコレクションにクエリし、結果の JSON レスポンスをデコードして、一致する各画像アセットのアセット ID と雲量を表示します。出力は次のようになります。

COPERNICUS/S2_HARMONIZED/20170420T184921_20170420T190203_T10SEG : 4.3166
COPERNICUS/S2_HARMONIZED/20170430T190351_20170430T190351_T10SEG : 0

この地点には、この月に撮影された雲量の少ない画像が 2 枚あることがわかります。

特定の画像を検査する

一致するものの 1 つは、雲量が実質的にゼロのようです。ID が COPERNICUS/S2_HARMONIZED/20170430T190351_20170430T190351_T10SEG のアセットを詳しく見てみましょう。すべての公開カタログ アセットは、プロジェクト earthengine-public に属しています。次の Python スニペットは、projects.assets.get クエリを発行して、特定のアセットの詳細を ID で取得し、使用可能なデータバンドを出力して、最初のバンドに関する詳細情報を出力します。

asset_id = 'COPERNICUS/S2_HARMONIZED/20170430T190351_20170430T190351_T10SEG'
name = '{}/assets/{}'.format(project, asset_id)
url = 'https://earthengine.googleapis.com/v1alpha/{}'.format(name)

response = session.get(url)
content = response.content

asset = json.loads(content)
print('Band Names: %s' % ','.join(band['id'] for band in asset['bands']))
print('First Band: %s' % json.dumps(asset['bands'][0], indent=2, sort_keys=True))

出力は次のようになります。

Band Names: B1,B2,B3,B4,B5,B6,B7,B8,B8A,B9,B10,B11,B12,QA10,QA20,QA60
First Band: {
  "dataType": {
    "precision": "INTEGER",
    "range": {
      "max": 65535
    }
  },
  "grid": {
    "affineTransform": {
      "scaleX": 60,
      "scaleY": -60,
      "translateX": 499980,
      "translateY": 4200000
    },
    "crsCode": "EPSG:32610",
    "dimensions": {
      "height": 1830,
      "width": 1830
    }
  },
  "id": "B1",
  "pyramidingPolicy": "MEAN"
}

データバンドのリストは、前述のデータセットの説明に記載されているものに対応しています。このデータセットには、EPSG:32610 座標系(UTM ゾーン 10N)の 16 ビット整数データが含まれていることがわかります。この最初のバンドの ID は B1 で、解像度は 1 ピクセルあたり 60 メートルです。画像の原点は、この座標系の位置(499980,4200000)にあります。

affineTransform.scaleY の負の値は、通常、原点が画像の北西の角にあることを示します。y ピクセル インデックスの増加は、y 空間座標の減少(南に向かう)に対応します。

ピクセル値を取得する

projects.assets.getPixels クエリを発行して、この画像の高解像度バンドからデータを取得してみましょう。データセットの説明ページによると、バンド B2、B3、B4、B8 の解像度は 1 ピクセルあたり 10 メートルです。このスクリプトは、これら 4 つのバンドから左上の 256x256 ピクセルのタイルデータを取得します。numpy NPY 形式でデータを読み込むと、レスポンスを Python データ配列に簡単にデコードできます。

import numpy
import io

name = '{}/assets/{}'.format(project, asset_id)
url = 'https://earthengine.googleapis.com/v1alpha/{}:getPixels'.format(name)
body = json.dumps({
    'fileFormat': 'NPY',
    'bandIds': ['B2', 'B3', 'B4', 'B8'],
    'grid': {
        'affineTransform': {
            'scaleX': 10,
            'scaleY': -10,
            'translateX': 499980,
            'translateY': 4200000,
        },
        'dimensions': {'width': 256, 'height': 256},
    },
})

pixels_response = session.post(url, body)
pixels_content = pixels_response.content

array = numpy.load(io.BytesIO(pixels_content))
print('Shape: %s' % (array.shape,))
print('Data:')
print(array)

出力は次のようになります。

Shape: (256, 256)
Data:
[[( 899, 586, 351, 189) ( 918, 630, 501, 248) (1013, 773, 654, 378) ...,
  (1014, 690, 419, 323) ( 942, 657, 424, 260) ( 987, 691, 431, 315)]
 [( 902, 630, 541, 227) (1059, 866, 719, 429) (1195, 922, 626, 539) ...,
  ( 978, 659, 404, 287) ( 954, 672, 426, 279) ( 990, 678, 397, 304)]
 [(1050, 855, 721, 419) (1257, 977, 635, 569) (1137, 770, 400, 435) ...,
  ( 972, 674, 421, 312) (1001, 688, 431, 311) (1004, 659, 378, 284)]
 ...,
 [( 969, 672, 375, 275) ( 927, 680, 478, 294) (1018, 724, 455, 353) ...,
  ( 924, 659, 375, 232) ( 921, 664, 438, 273) ( 966, 737, 521, 306)]
 [( 920, 645, 391, 248) ( 979, 728, 481, 327) ( 997, 708, 425, 324) ...,
  ( 927, 673, 387, 243) ( 927, 688, 459, 284) ( 962, 732, 509, 331)]
 [( 978, 723, 449, 330) (1005, 712, 446, 314) ( 946, 667, 393, 269) ...,
  ( 949, 692, 413, 271) ( 927, 689, 472, 285) ( 966, 742, 516, 331)]]

この画像から別のピクセルセットを選択するには、それに応じて affineTransform を指定します。affineTransform は画像の空間座標参照系で指定されることに注意してください。代わりにピクセル座標で原点の位置を調整する場合は、次の簡単な数式を使用します。

request_origin = image_origin + pixel_scale * offset_in_pixels

サムネイル画像の生成

同様のメカニズムを使用して、この画像の RGB サムネイルを生成できます。ネイティブ解像度でデータをリクエストする代わりに、リージョンと画像のサイズを明示的に指定します。画像全体のサムネイルを取得するには、リクエスト リージョンとして画像のフットプリント ジオメトリを使用します。最後に、赤、緑、青の画像バンドと適切な範囲のデータ値を指定することで、魅力的な RGB サムネイル画像を取得できます。

これらすべてをまとめると、Python スニペットは次のようになります(Colab IPython 画像表示ウィジェットを使用)。

url = 'https://earthengine.googleapis.com/v1alpha/{}:getPixels'.format(name)
body = json.dumps({
    'fileFormat': 'PNG',
    'bandIds': ['B4', 'B3', 'B2'],
    'region': asset['geometry'],
    'grid': {
        'dimensions': {'width': 256, 'height': 256},
    },
    'visualizationOptions': {
        'ranges': [{'min': 0, 'max': 3000}],
    },
})

image_response = session.post(url, body)
image_content = image_response.content

from IPython.display import Image
Image(image_content)

生成されたサムネイル画像は次のようになります。