התקנת Python

תמיכה ב-Python

ספריית הלקוח של Earth Engine ל-Python תואמת לגרסאות Python שנתמכות ב-Google Cloud. התמיכה מתעדכנת מדי שנה בהתאם ללוח הזמנים של גרסאות Python (PEP 602, סטטוס הגרסאות של Python). שימוש בגרסאות Python לא נתמכות עלול לגרום לכשלים באימות, להתנהגות בלתי צפויה או לכשלים בפעולות מסוימות.

אפשרויות התקנה

אם אתם משתמשים ב-Google Colab, הגרסה העדכנית ביותר של ספריית הלקוח של Earth Engine ב-Python כבר הותקנה (דרך pip). כדי להתחיל לעבוד עם Earth Engine ו-Colab, תוכלו לנסות את מסמך ה-notebook הבא:

הלוגו של Colab הפעלה ב-Google Colab הלוגו של GitHub הצגת המקור ב-GitHub

אם אתם לא משתמשים ב-Colab, תוכלו להתקין ולעדכן את ספריית הלקוח של Earth Engine באופן ידני במערכת באמצעות conda (מומלץ) או pip:


מתקינים את ה-API בסביבת Python שרירותית באמצעות pip. במסוף או בשורת הפקודה:

pip install earthengine-api

אחרי ההתקנה, תוכלו לייבא, לאמת ולאתחל את Earth Engine API כפי שמתואר כאן.

עדכון ה-API:

pip install earthengine-api --upgrade

ייבוא חבילות

חבילת ה-API של Python נקראת ee. צריך לייבא אותו ולהפעיל אותו בכל סשן ובכל סקריפט חדשים ב-Python:

import ee

אימות והפעלה

לפני שמשתמשים בספריית הלקוח של Earth Engine ל-Python, צריך לבצע אימות ולהשתמש בפרטי הכניסה שהתקבלו כדי לאתחל את לקוח ה-Python. מריצים את הפקודה: 

ee.Authenticate()

כך תוכלו לבחור את מצב האימות המתאים ביותר לסביבה שלכם, ותתבקשו לאשר את הגישה לסקריפטים. כדי לבצע את האיפוס, צריך לציין פרויקט שבבעלותכם או שיש לכם הרשאות להשתמש בו. הפרויקט הזה ישמש להרצת כל הפעולות ב-Earth Engine: 

ee.Initialize(project='my-project')

במדריך לאימות מוסבר איך פותרים בעיות ומפורט מידע נוסף על מצבי אימות ופרויקטים ב-Cloud.

Hello world!‎

הנה סקריפט קצר לבדיקה שהכול מוכן לעבודה עם Earth Engine. 

import ee
ee.Authenticate()
ee.Initialize(project='my-project')
print(ee.String('Hello from the Earth Engine servers!').getInfo())

תחביר

גם ל-API של Python וגם ל-API של JavaScript יש גישה לאותה פונקציונליות בצד השרת, אבל ביטויים בצד הלקוח (מידע נוסף על לקוח לעומת שרת) יכולים להיות שונים בגלל הבדלים בסינטקס של השפות. בטבלה הבאה מפורטים ההבדלים הנפוצים בתחביר בין Python API לבין JavaScript API.

הבדלים נפוצים בתחביר בין JavaScript ל-Python
נכס JavaScript Python
הגדרת פונקציה 
function myFun(arg) {
  return arg;
}

var myFun = function(arg) {
  return arg;
};
 
def my_fun(arg):
  return arg
מיפוי פונקציות אנונימיות 
var foo = col.map(function(arg) {
  return arg;
});
 
foo = col.map(lambda arg: arg)
הגדרת משתנה 
var myVar = 'var';
 
my_var = 'var'
אופרטורים לוגיים 
var match = such.and(that);
var match = such.or(that);
var match = such.not(that);
 
match = such.And(that)
match = such.Or(that)
match = such.Not(that)
שרשרת שיטות עם כמה שורות 
var foo = my.really()
              .reallyLong()
              .methodChain();
 
foo = (my.really()
       .reallyLong()
       .methodChain())
מפתחות של מילון 
var dic = {'key': value};
var dic = {key: value};
 
dic = {'key': value}
גישה לאובייקט מילון 
var value = dic.key;
var value = dic['key'];
 
value = dic['key']
הגדרת ארגומנט של פונקציה 
// Positional arguments.
var foo = fun(argX, argY, argZ);
// Keyword arguments object.
var foo = fun({y: argY});
 
# Positional arguments.
foo = fun(arg_x, arg_y, arg_z)
# Keyword arguments dictionary.
foo = fun(**{'y': arg_y})
# Keyword arguments.
foo = fun(x=arg_x, z=arg_z)
בוליאני 
var t = true;
var f = false;
 
t = True
f = False
ערכי null 
var na = null;
 
na = None
תגובה 
//
 
#

אובייקטים מסוג תאריך

הגדרה של אובייקטי תאריך בצד הלקוח ושינוי שלהם באמצעות המודול datetime. מוסיפים את המודול לסקריפט:

import datetime

המרת ee.Date לתאריך מצד הלקוח:

ee_date = ee.Date('2020-01-01')
py_date = datetime.datetime.utcfromtimestamp(ee_date.getInfo()['value']/1000.0)

המרת תאריך בצד הלקוח ל-ee.Date:

py_date = datetime.datetime.utcnow()
ee_date = ee.Date(py_date)

מתבצע ייצוא נתונים

כדי לייצא נתונים באמצעות Python API, צריך להשתמש במודול ee.batch, שמספק ממשק לפונקציות Export. מעבירים את ארגומנטים הפרמטרים כמו שעושים ב-JavaScript API, תוך שמירה על ההבדלים שמפורטים בטבלת התחביר שלמעלה. כדי להתחיל משימות ייצוא, צריך להפעיל את השיטה start() במשימה מוגדרת. שולחים שאילתה לגבי סטטוס המשימה על ידי קריאה לשיטה status(). הדוגמה הבאה ממחישה ייצוא של אובייקט ee.Image.

יוצרים משימה לייצוא:

task = ee.batch.Export.image.toDrive(image=my_image,  # an ee.Image object.
                                     region=my_geometry,  # an ee.Geometry object.
                                     description='mock_export',
                                     folder='gdrive_folder',
                                     fileNamePrefix='mock_export',
                                     scale=1000,
                                     crs='EPSG:4326')

התחלת משימה של ייצוא:

task.start()

בודקים את סטטוס המשימה של הייצוא:

task.status()

התוצאה של task.status() היא מילון שמכיל מידע כמו המצב של המשימה והמזהה שלה. 

{
  'state': 'READY',
  'description': 'my_export_task',
  'creation_timestamp_ms': 1647567508236,
  'update_timestamp_ms': 1647567508236,
  'start_timestamp_ms': 0,
  'task_type': 'EXPORT_IMAGE',
  'id': '56TVJIZABUMTD5CJ5YHTMYK4',
  'name': 'projects/earthengine-legacy/operations/56TVJIZABUMTX5CJ5HHTMYK4'
}

אפשר לעקוב אחר ההתקדמות של המשימות באמצעות השדה state. בדף Processing Environments מופיעה רשימת הערכים של state ומידע נוסף על מחזור החיים של המשימות.

הדפסת אובייקטים

כשמדפיסים אובייקט של Earth Engine ב-Python, מודפסת הבקשה בסריאליזציה של האובייקט, ולא האובייקט עצמו. כדי להבין את הסיבה לכך, אפשר לעיין בדף לקוח לעומת שרת.

קוראים ל-getInfo() על אובייקטים של Earth Engine כדי לקבל את האובייקט הרצוי מהשרת ללקוח:

# Load a Landsat image.
img = ee.Image('LANDSAT/LT05/C02/T1_L2/LT05_034033_20000913')

# Print image object WITHOUT call to getInfo(); prints serialized request instructions.
print(img)

# Print image object WITH call to getInfo(); prints image metadata.
print(img.getInfo())
 שימו לב ש-getInfo() היא פעולה סינכרונית, כלומר ביצוע הביטויים שמגיעים אחרי הקריאה ל-getInfo() חסום עד שהתוצאה מוחזרת ללקוח. בנוסף, בקשות לנתונים רבים או לחישובים יקרים עלולות להחזיר שגיאה ו/או להיתקע. באופן כללי, השיטה המומלצת היא לייצא את התוצאות, ולאחר מכן לייבא אותן לסקריפט חדש לצורך ניתוח נוסף.

אובייקטים בממשק המשתמש

המודול ui של Earth Engine זמין רק דרך עורך הקוד של JavaScript API. שימוש בספריות של צד שלישי לרכיבי ממשק משתמש ב-Python. ספריות כמו geemap,‏ Folium ו-ipyleaflet מאפשרות להציג מפה אינטראקטיבית, ואפשר ליצור תרשימים באמצעות Matplotlib,‏ Altair או seaborn, בין היתר. ב notebook להגדרת Earth Engine ב-Colab מפורטות דוגמאות לשימוש ב-geemap וב-Matplotlib.

Python במדריך למפתחים

קוד Python כלול במדריך למפתחים של Earth Engine. כשהאפשרות זמינה, אפשר ללחוץ על הכרטיסייה 'Colab (Python)' בחלק העליון של בלוקים של קוד כדי להציג דוגמאות לקוד. דפי ההדרכה עשויים לכלול גם לחצנים בחלק העליון של הדף להפעלת הדף כ-notebook ב-Colab או להצגה ב-GitHub. דוגמאות לקוד Python מיועדות להרצה באמצעות Google Colab. הספרייה geemap מטפלת במפות אינטראקטיביות ובניתוח אובייקטים. גם ספריית הלקוח של Earth Engine ב-Python וגם geemap מותקנים מראש ב-Colab.

הגדרת Earth Engine

כדי להריץ קוד Python, צריך לייבא את ספריית Earth Engine, לבצע אימות ולהפעיל את הספרייה. הפקודות הבאות משמשות בדוגמאות (אפשרויות חלופיות מפורטות בדף אימות והפעלה).

import ee
ee.Authenticate()
ee.Initialize(project='my-project')

ניתוח אינטראקטיבי באמצעות geemap

הספרייה geemap משמשת להצגת משבצות מפה ולהדפסת ייצוגים עשירים של אובייקטים ב-Earth Engine. הספרייה תלויה בתכונות האלה, בהתאמה, ב-ipyleaflet וב-eerepr. הספרייה geemap והספריות התלויות בה מותקנות מראש ב-Google Colab. צריך לייבא אותה לכל סשן.

import geemap.core as geemap

אפשר להציג את סיווג הנתונים הגיאוגרפיים של Earth Engine, כמו ee.Image ו-ee.FeatureCollection, באמצעות האובייקט geemap.Map. קודם כול, מגדירים את אובייקט המפה. לאחר מכן, מוסיפים לו שכבות או משנים את אזור התצוגה שלו.

# Initialize a map object.
m = geemap.Map()

# Define an example image.
img = ee.Image.random()

# Add the image to the map.
m.add_layer(img, None, 'Random image')

# Display the map (you can call the object directly if it is the final line).
display(m)