במדריך הזה מוסבר איך להתחיל במהירות לשלוח שאילתות ל-Earth Engine API בארכיטקטורת REST מ-Python באמצעות Google Colab. אותם עקרונות חלים על גישה ל-API משפות וסביבות אחרות.
הערה: ה-API בארכיטקטורת REST כולל תכונות חדשות ותכונות מתקדמות שלא בהכרח מתאימות לכל המשתמשים. אם אתם משתמשים חדשים ב-Earth Engine, כדאי להתחיל עם המדריך ל-JavaScript.
לפני שמתחילים
פועלים לפי ההוראות האלה כדי:
הגדרת ה-Notebook ב-Colab
אם אתם מתחילים את המדריך המהיר הזה מאפס, אתם יכולים ליצור קובץ notebook חדש ב-Colab. כדי לעשות את זה, לוחצים על NEW NOTEBOOK בדף הפתיחה של Colab ומזינים את דוגמאות הקוד שבהמשך בתא קוד חדש. ב-Colab כבר מותקן Cloud SDK. הוא כולל את כלי שורת הפקודה gcloud, שבעזרתו אפשר לנהל את שירותי Cloud. לחלופין, אפשר להריץ את ה-notebook לדוגמה באמצעות הלחצן שבתחילת הדף הזה.
אימות ב-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, מורידים למכונה הווירטואלית של ה-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}
או משורת הפקודה:
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. אתם יכולים להזין את זה בתא קוד חדש ב-notebook של 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'}
בחירת קבוצת נתונים
אתם יכולים לחפש ולחקור את קבוצות הנתונים הזמינות באמצעות עורך הקוד של Earth Engine בכתובת code.earthengine.google.com. בואו נחפש נתונים של Sentinel 2. (אם זו הפעם הראשונה שאתם משתמשים בכלי לעריכת קוד, תתבקשו לאשר לו לגשת ל-Earth Engine בשמכם כשתתחברו). בעורך הקוד, מחפשים את המילה sentinel בתיבת החיפוש שבחלק העליון. מופיעות כמה קבוצות נתונים של רסטר:

לוחצים על "Sentinel-2: MultiSpectral Instrument (MSI), Level-1C":

דפים עם תיאור של קבוצת הנתונים, כמו הדף הזה, כוללים את המידע החיוני שאתם צריכים כדי להשתמש בכל קבוצת נתונים בקטלוג הנתונים הציבורי של Earth Engine, כולל תיאור קצר של קבוצת הנתונים, קישורים לספק הנתונים לקבלת פרטים נוספים, מידע על הגבלות שימוש שעשויות לחול על קבוצת הנתונים ומזהה הנכס של קבוצת הנתונים ב-Earth Engine.
במקרה הזה, בצד שמאל של החלון אפשר לראות שמדובר בנכס של אוסף תמונות שהנתיב שלו הוא COPERNICUS/S2_HARMONIZED.
שאילתה לגבי תמונות ספציפיות
מערך הנתונים הזה של Sentinel-2 כולל יותר משני מיליון תמונות שמכסות את העולם משנת 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"
}
רשימת רצועות הנתונים תואמת למה שראינו קודם בתיאור של מערך הנתונים. אפשר לראות שבקבוצת הנתונים הזו יש נתוני מספרים שלמים של 16 ביט במערכת הקואורדינטות EPSG:32610, או UTM Zone 10N. לרצועה הראשונה הזו יש את המזהה B1 ורזולוציה של 60 מטרים לפיקסל. מקור התמונה נמצא במיקום (499980,4200000) במערכת הקואורדינטות הזו.
הערך השלילי של affineTransform.scaleY מציין שנקודת המוצא נמצאת בפינה הצפון-מערבית של התמונה, כמו שבדרך כלל קורה: אינדקסים הולכים וגדלים של פיקסלים ב-y תואמים לקואורדינטות מרחביות הולכות וקטנות ב-y (לכיוון דרום).
אחזור ערכי פיקסלים
נשלח שאילתת projects.assets.getPixels כדי לאחזר נתונים מהרצועות ברזולוציה גבוהה של התמונה הזו. בדף התיאור של מערך הנתונים כתוב שהרזולוציה של שכבות הנתונים B2, B3, B4 ו-B8 היא 10 מטרים לפיקסל. הסקריפט הזה מאחזר את המשבצת של נתוני הפיקסלים בגודל 256x256 בפינה השמאלית העליונה מארבעת הפסים האלה. טעינת הנתונים בפורמט NPY של numpy מאפשרת לפענח בקלות את התשובה למערך נתונים של 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 ייראה כך (באמצעות הווידג'ט להצגת תמונות 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)
הנה התמונה הממוזערת שנוצרה:
הפעלה ב-Google Colab
הצגת קוד המקור ב-GitHub