לקוח לעומת שרת

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

חשוב להבחין בין אובייקטים של Earth Engine לבין אובייקטים או פרימיטיבים אחרים של Python או אובייקט ב-JavaScript שעשויים להיות בקוד. אפשר לשנות אובייקטים בשרת על ידי שינוי אובייקטים של "שרת proxy" בצד הלקוח בסקריפט. אפשר לזהות אובייקט proxy לפי כל מה שמתחיל ב-ee. אובייקטי ה-proxy האלה של Earth Engine לא מכילים נתונים בפועל, והם רק נקודות אחיזה לאובייקטים בשרת. כדי להתחיל, נניח שיש לנו אובייקט מחרוזת בצד הלקוח (שהוא לא אובייקט proxy):

Code Editor (JavaScript)

var clientString = 'I am a String';
print(typeof clientString);  // string

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

client_string = 'I am a String'
print(type(client_string))  # str

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

Code Editor (JavaScript)

var serverString = ee.String('I am not a String!');
print(typeof serverString);  // object
print('Is this an EE object?',
    serverString instanceof ee.ComputedObject);  // true

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

server_string = ee.String('I am not a String!')
print(type(server_string))  # ee.ee_string.String
print(
    'Is this an EE object?', isinstance(server_string, ee.ee_string.String)
)  # True

בפלט, שימו לב שה-ee.String הוא object ולא string. באופן ספציפי יותר, זהו ee.computedObject, כלומר אובייקט proxy למשהו בשרת. אפשר לחשוב על ee.Thing כדרך להכניס משהו לקונטיינר כדי לשלוח אותו ל-Google. הלקוח לא יודע מה יש במאגר, אבל אתם יכולים לגלות מה יש בו על ידי הדפסה שלו:

Code Editor (JavaScript)

print(serverString);  // I am not a String

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

print(server_string.getInfo())  # I am not a String

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

Code Editor (JavaScript)

print(serverString.toString());  // ee.String("I am not a String!")

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

print(server_string)  # ee.String({"constantValue": "I am not a String!"})

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

Code Editor (JavaScript)

var someString = serverString.getInfo();
var strings = someString + '  Am I?';
print(strings);  // I am not a String!  Am I?

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

some_string = server_string.getInfo()
strings = some_string + '  Am I?'
print(strings)  # I am not a String!  Am I?

מעגלי

מכיוון שהלקוח לא יודע מה יש באובייקטים של ee.Thing בצד השרת, פעולות בצד הלקוח כמו תנאים ולולאות for לא פועלות איתם. לכן, וכדי להימנע מקריאות סינכרוניות ל-getInfo(), כדאי להשתמש בפונקציות של השרת ככל האפשר. לדוגמה, נניח שאתם רוצים ליצור רשימה בשתי דרכים:

לא מומלץ – לולאת for בצד הלקוח

Code Editor (JavaScript)

var clientList = [];
for(var i = 0; i < 8; i++) {
  clientList.push(i + 1);
}
print(clientList);

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

client_list = []
for i in range(8):
  client_list.append(i + 1)
print(client_list)

מומלץ – מיפוי בצד השרת

Code Editor (JavaScript)

var serverList = ee.List.sequence(0, 7);
serverList = serverList.map(function(n) {
  return ee.Number(n).add(1);
});
print(serverList);

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

server_list = ee.List.sequence(0, 7)
server_list = server_list.map(lambda n: ee.Number(n).add(1))
print(server_list.getInfo())

הדוגמה של המיפוי בצד השרת קצת טיפשית כי אפשר ליצור את אותה רשימה פשוט באמצעות ee.List.sequence(1, 8), אבל היא ממחישה כמה מושגים חשובים. המושג הראשון הוא map(), שפשוט מחיל את אותה פונקציה על כל הפריטים ברשימה. הפונקציה הזו מופעלת בשרת, ולכן פונקציות בצד הלקוח כמו getInfo() ו-print() לא יפעלו בפונקציה ממופה. לכן, צריך להחליף את הקוד i + 1 בקוד המקביל בצד השרת: ee.Number(n).add(1). חשוב לציין ש-n הוא אובייקט שקיים רק בשרת. מכיוון שהפונקציה לא יודעת את סוג הארגומנט שלה, צריך להמיר אותו ל-ee.Number.

(בקטע על פונקציות בצד הלקוח ובצד השרת מוסבר אילו פונקציות פועלות בצד הלקוח).

חשוב גם לציין שלפעמים פונקציונליות בצד הלקוח היא נוחה. לדוגמה, אפשר להשתמש בלולאת for הקודמת כדי ליצור רשימה ולעטוף אותה באובייקט בצד השרת:

Code Editor (JavaScript)

var toServerList = ee.List(clientList);

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

to_server_list = ee.List(client_list)

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

משפטי תנאי

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

Code Editor (JavaScript)

var myList = ee.List([1, 2, 3]);
var serverBoolean = myList.contains(5);
print(serverBoolean);  // false

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

my_list = ee.List([1, 2, 3])
server_boolean = my_list.contains(5)
print(server_boolean.getInfo())  # False

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

לא מומלץ – מותנה בצד הלקוח

Code Editor (JavaScript)

var clientConditional;
if (serverBoolean) {
  clientConditional = true;
} else {
  clientConditional = false;
}
print('Should be false:', clientConditional);  // True!

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

if server_boolean:
  client_conditional = True
else:
  client_conditional = False
print('Should be False:', client_conditional)  # True!

מומלץ – מותנה בצד השרת

Code Editor (JavaScript)

var serverConditional = ee.Algorithms.If(serverBoolean, 'True!', 'False!');
print('Should be false:', serverConditional);  // False!

הגדרה של Python

בדף סביבת Python מפורט מידע על API בשפת Python ועל השימוש ב-geemap לפיתוח אינטראקטיבי.

import ee
import geemap.core as geemap

Colab (Python)

server_conditional = ee.Algorithms.If(server_boolean, 'True!', 'False!')
print('Should be False:', server_conditional.getInfo())  # False!

פונקציות של לקוח ושרת

בקטעים הקודמים תיארנו כמה סיבות לכך שזה לא יעיל או לא הגיוני לשלב בין אובייקטים ופונקציות של לקוח ושל שרת. אילו אובייקטים ופונקציות הם בצד הלקוח ואילו בצד השרת? באופן כללי, כל מה שמאותחל בתור ee.Thing הוא אובייקט שרת, וכל שיטה באובייקט הזה, ee.Thing.method(), היא פונקציית שרת. אובייקטים ופונקציות שמופיעים במאמרי העזרה של Python או JavaScript הם בצד הלקוח. כמו שצוין קודם, אתם יכולים להשתמש בפונקציונליות בצד הלקוח כדי ליצור אובייקט, ואז לעטוף אותו על ידי הוספת האובייקט בצד הלקוח ל-constructor של Earth Engine, לדוגמה ee.String().