Quickstart

Panduan ini menjelaskan cara memulai dengan cepat mengeluarkan kueri ke Earth Engine REST API dari Python menggunakan Google Colab. Konsep yang sama berlaku untuk mengakses API dari bahasa dan lingkungan lain.

Catatan: REST API berisi fitur baru dan lanjutan yang mungkin tidak cocok untuk semua pengguna. Jika Anda baru menggunakan Earth Engine, mulailah dengan panduan JavaScript.

Logo Colab Jalankan di Google Colab Logo GitHub Lihat sumber di GitHub

Sebelum memulai

Ikuti petunjuk berikut untuk:

Menyiapkan notebook Colab Anda

Jika Anda memulai panduan memulai ini dari awal, Anda dapat membuat notebook Colab baru dengan mengklik NEW NOTEBOOK dari halaman awal Colab dan memasukkan contoh kode di bawah ke dalam sel kode baru. Colab sudah menginstal Cloud SDK. Ini termasuk alat command line gcloud yang dapat Anda gunakan untuk mengelola layanan Cloud. Atau, jalankan notebook demo dari tombol di awal halaman ini.

Melakukan autentikasi ke Google Cloud

Hal pertama yang harus dilakukan adalah login agar Anda dapat membuat permintaan yang diautentikasi ke Google Cloud.

Di Colab, Anda dapat menjalankan:

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

(Atau jika Anda menjalankannya secara lokal, dari command line, dengan asumsi Anda telah menginstal Cloud SDK:)

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

Setujui opsi untuk login menggunakan akun pengguna Google Anda dan selesaikan proses login.

Mendapatkan file kunci pribadi untuk akun layanan Anda

Sebelum dapat menggunakan akun layanan untuk melakukan autentikasi, Anda harus mendownload file kunci pribadi. Untuk melakukannya di Colab, download ke VM notebook:

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}

Atau, dari command line:

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

Mengakses dan Menguji Kredensial Anda

Sekarang Anda siap mengirim kueri pertama ke Earth Engine API. Gunakan kunci pribadi untuk mendapatkan kredensial. Gunakan kredensial untuk membuat sesi yang diotorisasi guna membuat permintaan HTTP. Anda dapat memasukkan kode ini ke dalam sel kode baru di notebook Colab Anda. (Jika menggunakan command line, Anda harus memastikan bahwa library yang diperlukan telah diinstal).

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))

Jika semuanya dikonfigurasi dengan benar, menjalankan perintah ini akan menghasilkan output yang terlihat seperti:

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

Memilih Set Data

Anda dapat menelusuri dan menjelajahi set data yang tersedia menggunakan Editor Kode Earth Engine di code.earthengine.google.com. Mari kita cari beberapa data Sentinel 2. (Jika ini pertama kalinya Anda menggunakan Editor Kode, Anda akan diminta untuk memberikan otorisasi agar Editor Kode dapat mengakses Earth Engine atas nama Anda saat Anda login.) Di Editor Kode, telusuri "sentinel" di kotak penelusuran di bagian atas. Beberapa set data raster akan muncul:

Klik "Sentinel-2: MultiSpectral Instrument (MSI), Level-1C":

Halaman deskripsi set data seperti ini menyertakan informasi penting yang Anda perlukan untuk menggunakan set data apa pun di Earth Engine Public Data Catalog, termasuk deskripsi singkat set data, link ke penyedia data untuk mendapatkan detail tambahan, informasi tentang batasan penggunaan apa pun yang mungkin berlaku untuk set data, dan ID aset Earth Engine set data.

Dalam hal ini, kita melihat di sisi kanan jendela bahwa ini adalah aset koleksi gambar yang jalurnya adalah COPERNICUS/S2_HARMONIZED.

Membuat Kueri untuk Gambar Tertentu

Set data Sentinel-2 ini mencakup lebih dari dua juta gambar yang mencakup dunia dari tahun 2015 hingga saat ini. Mari kita buat kueri projects.assets.listImages terhadap koleksi gambar untuk menemukan beberapa data dari April 2017, dengan tutupan awan rendah yang mencakup titik tertentu di Mountain View, California.

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))

Skrip ini mengkueri koleksi untuk menemukan gambar yang cocok, mendekode respons JSON yang dihasilkan, dan mencetak ID aset serta tutupan awan untuk setiap aset gambar yang cocok. Output-nya akan terlihat seperti:

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

Tampaknya ada dua gambar di atas titik ini yang diambil pada bulan ini dan memiliki tutupan awan yang rendah.

Memeriksa Gambar Tertentu

Tampaknya salah satu gambar yang cocok pada dasarnya tidak memiliki tutupan awan. Mari kita pelajari lebih lanjut aset tersebut, yang ID-nya adalah COPERNICUS/S2_HARMONIZED/20170430T190351_20170430T190351_T10SEG. Perhatikan bahwa semua aset katalog publik termasuk dalam project earthengine-public. Berikut adalah cuplikan Python yang akan mengeluarkan kueri projects.assets.get untuk mengambil detail aset tertentu berdasarkan ID, mencetak band data yang tersedia, dan mencetak informasi yang lebih mendetail tentang band pertama:

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))

Output-nya akan terlihat seperti ini:

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"
}

Daftar band data sesuai dengan yang kita lihat sebelumnya dalam deskripsi set data. Kita dapat melihat bahwa set data ini memiliki data bilangan bulat 16-bit dalam sistem koordinat EPSG:32610, atau UTM Zone 10N. Band pertama ini memiliki ID B1 dan resolusi 60 meter per piksel. Origin gambar berada di posisi (499980,4200000) dalam sistem koordinat ini.

Nilai negatif affineTransform.scaleY menunjukkan bahwa titik asal berada di sudut barat laut gambar, seperti yang biasanya terjadi: peningkatan indeks piksel y sesuai dengan penurunan koordinat spasial y (menuju ke selatan).

Mengambil Nilai Piksel

Mari kita buat kueri projects.assets.getPixels untuk mengambil beberapa data dari band resolusi tinggi gambar ini. Halaman deskripsi set data menyatakan bahwa band B2, B3, B4, dan B8 memiliki resolusi 10 meter per piksel. Skrip ini mengambil ubin data berukuran 256x256 piksel di kiri atas dari keempat band tersebut. Memuat data dalam format NPY numpy memudahkan pendekodean respons menjadi array data 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)

Output-nya akan terlihat seperti ini:

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)]]

Untuk memilih kumpulan piksel yang berbeda dari gambar ini, cukup tentukan affineTransform yang sesuai. Ingat bahwa affineTransform ditentukan dalam sistem referensi koordinat spasial gambar; jika Anda ingin menyesuaikan lokasi titik asal dalam koordinat piksel, gunakan formula sederhana ini:

request_origin = image_origin + pixel_scale * offset_in_pixels

Membuat Gambar Thumbnail

Kita dapat menggunakan mekanisme serupa untuk membuat thumbnail RGB dari gambar ini. Alih-alih meminta data pada resolusi aslinya, kita akan menentukan wilayah dan dimensi gambar secara eksplisit. Untuk mendapatkan thumbnail dari seluruh gambar, kita dapat menggunakan geometri jejak gambar sebagai region permintaan. Terakhir, dengan menentukan band gambar merah, hijau, dan biru serta rentang nilai data yang sesuai, kita dapat memperoleh gambar thumbnail RGB yang menarik.

Dengan menggabungkan semuanya, cuplikan Python akan terlihat seperti ini (menggunakan widget tampilan gambar IPython Colab):

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)

Berikut adalah gambar thumbnail yang dihasilkan: