Quickstart

इस गाइड में बताया गया है कि Google Colab का इस्तेमाल करके, Python से Earth Engine REST API को क्वेरी भेजने की सुविधा को तुरंत कैसे शुरू किया जा सकता है. अन्य भाषाओं और एनवायरमेंट से एपीआई को ऐक्सेस करने पर भी यही सिद्धांत लागू होते हैं.

ध्यान दें: REST API में नई और ऐडवांस सुविधाएं शामिल हैं. ऐसा हो सकता है कि ये सुविधाएं सभी उपयोगकर्ताओं के लिए सही न हों. अगर Earth Engine आपके लिए नया है, तो कृपया JavaScript गाइड से शुरुआत करें.

शुरू करने से पहले

इन निर्देशों का पालन करके:

Colab notebook सेट अप करना

अगर आपको इस क्विकस्टार्ट को शुरू से शुरू करना है, तो Colab के स्टार्ट पेज पर जाकर, NEW NOTEBOOK पर क्लिक करके नई Colab notebook बनाई जा सकती है. इसके बाद, नीचे दिए गए कोड सैंपल को नए कोड सेल में डालें. Colab में Cloud SDK पहले से इंस्टॉल होता है. इसमें gcloud कमांड-लाइन टूल शामिल है. इसका इस्तेमाल करके, Cloud की सेवाओं को मैनेज किया जा सकता है. इसके अलावा, इस पेज की शुरुआत में मौजूद बटन से डेमो नोटबुक चलाएं.

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 में ऐसा करने के लिए, नोटबुक वीएम में डाउनलोड करें:

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 को पहली क्वेरी भेजी जा सकती है. क्रेडेंशियल पाने के लिए, निजी पासकोड का इस्तेमाल करें. एचटीटीपी अनुरोध करने के लिए, क्रेडेंशियल का इस्तेमाल करके अनुमति वाला सेशन बनाएं. इसे अपनी Colab notebook के नए कोड सेल में डाला जा सकता है. (अगर कमांड लाइन का इस्तेमाल किया जा रहा है, तो आपको यह पक्का करना होगा कि ज़रूरी लाइब्रेरी इंस्टॉल की गई हों).

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 के सार्वजनिक डेटा कैटलॉग में मौजूद किसी भी डेटासेट को इस्तेमाल करने के लिए ज़रूरी जानकारी शामिल होती है. जैसे, डेटासेट की खास जानकारी, ज़्यादा जानकारी पाने के लिए डेटा उपलब्ध करवाने वाली कंपनी के लिंक, डेटासेट के इस्तेमाल पर लागू होने वाली पाबंदियों की जानकारी, और डेटासेट का Earth Engine ऐसेट का आईडी.

इस मामले में, हमें विंडो की दाईं ओर दिखता है कि यह एक इमेज कलेक्शन ऐसेट है, जिसका पाथ COPERNICUS/S2_HARMONIZED है.

खास इमेज के लिए क्वेरी

इस Sentinel-2 डेटासेट में, 20 लाख से ज़्यादा इमेज शामिल हैं. इनमें 2015 से लेकर अब तक की दुनिया भर की इमेज शामिल हैं. आइए, इमेज कलेक्शन के लिए projects.assets.listImages क्वेरी जारी करें. इससे अप्रैल 2017 का कुछ डेटा मिलेगा. इसमें कम क्लाउड कवर वाला डेटा शामिल होगा. इसमें कैलिफ़ोर्निया के माउंटेन व्यू का एक खास पॉइंट शामिल होगा.

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 रिस्पॉन्स को डिकोड करती है. इसके बाद, मिलती-जुलती हर इमेज ऐसेट के लिए, ऐसेट का आईडी और क्लाउड कवर को प्रिंट करती है. आउटपुट कुछ ऐसा दिखना चाहिए:

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

इस जगह की दो इमेज मौजूद हैं, जो इस महीने ली गई थीं. इनमें बादलों की वजह से जगह साफ़ तौर पर नहीं दिख रही है.

किसी खास इमेज की जांच करना

ऐसा लगता है कि मैच होने वाली किसी एक इमेज में, बादलों की मौजूदगी बिलकुल नहीं है. आइए, उस एसेट के बारे में ज़्यादा जानें जिसका आईडी COPERNICUS/S2_HARMONIZED/20170430T190351_20170430T190351_T10SEG है. ध्यान दें कि सभी सार्वजनिक कैटलॉग ऐसेट, प्रोजेक्ट earthengine-public से जुड़ी हैं. यहां Python स्निपेट दिया गया है, जो आईडी के हिसाब से किसी खास ऐसेट की जानकारी फ़ेच करने के लिए, projects.assets.get क्वेरी जारी करेगा. साथ ही, उपलब्ध डेटा बैंड को प्रिंट करेगा और पहले बैंड के बारे में ज़्यादा जानकारी प्रिंट करेगा:

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 कोऑर्डिनेट सिस्टम या यूटीएम ज़ोन 10N में 16-बिट इंटीजर डेटा है. इस पहले बैंड का आईडी B1 है और इसका रिज़ॉल्यूशन 60 मीटर प्रति पिक्सल है. इस कोऑर्डिनेट सिस्टम में, इमेज का ऑरिजिन (499980,4200000) पोज़िशन पर है.

affineTransform.scaleY की नेगेटिव वैल्यू से पता चलता है कि ओरिजन, इमेज के उत्तर-पश्चिम कोने में है. आम तौर पर ऐसा ही होता है: y पिक्सल इंडेक्स बढ़ने का मतलब है कि y स्पेशल कोऑर्डिनेट कम हो रहे हैं (दक्षिण की ओर बढ़ रहे हैं).

पिक्सल वैल्यू फ़ेच की जा रही हैं

इस इमेज के हाई रिज़ॉल्यूशन वाले बैंड से कुछ डेटा फ़ेच करने के लिए, projects.assets.getPixels क्वेरी जारी करें. डेटासेट की जानकारी वाले पेज पर बताया गया है कि बैंड B2, B3, B4, और B8 का रिज़ॉल्यूशन 10 मीटर प्रति पिक्सल है. यह स्क्रिप्ट, उन चार बैंड से डेटा की सबसे ऊपर बाईं ओर मौजूद 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

थंबनेल इमेज जनरेट करना

इस इमेज का आरजीबी थंबनेल जनरेट करने के लिए, हम इसी तरह के तरीके का इस्तेमाल कर सकते हैं. हम डेटा को उसके नेटिव रिज़ॉल्यूशन में अनुरोध करने के बजाय, साफ़ तौर पर किसी इलाके और इमेज के डाइमेंशन की जानकारी देंगे. पूरी इमेज का थंबनेल पाने के लिए, इमेज के फ़ुटप्रिंट ज्यामिति का इस्तेमाल, अनुरोध किए गए इलाके के तौर पर किया जा सकता है. आखिर में, लाल, हरे, और नीले रंग के इमेज बैंड और डेटा वैल्यू की सही रेंज तय करके, हम एक आकर्षक आरजीबी थंबनेल इमेज पा सकते हैं.

इन सभी को एक साथ जोड़ने पर, 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)

यहां थंबनेल इमेज दी गई है: