כלי שורת הפקודה

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

    earthengine

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

    earthengine command -h

בפעם הראשונה שמתקינים את ה-API בשפת Python, צריך להיכנס באמצעות הפקודה authenticate שמתוארת בהמשך. בקטעים הבאים מפורטות הפקודות הזמינות.

פרטי כניסה לחשבון שירות

כדי להשתמש ב-CLI עם פרטי הכניסה של חשבון שירות, משתמשים בדגל service_account_file כדי להפנות לקובץ JSON שמכיל את המפתח של חשבון השירות.

    earthengine --service_account_file=service_account_creds.json

שימוש ב-Colab

כלי שורת הפקודה של Earth Engine מותקן מראש ומוכן לשימוש ב-Google Colab.

אימות

צריך לבצע אימות בכל סשן חדש של Colab או אם פג התוקף של המכונה הווירטואלית בגלל חוסר פעילות (פרטי הכניסה לא נשמרים בין הסשנים).

מייבאים את ספריית הלקוח של Python וקוראים ל-ee.Authenticate() כדי להפעיל את תהליך האימות. פועלים לפי ההנחיות כדי להשלים את האימות. ברירת המחדל של auth_mode ב-Colab היא colab. אפשרויות אחרות מפורטות במדריך לאימות.

import ee
ee.Authenticate()

הרצת פקודות

כדי להריץ כלי שירות של שורת הפקודה, כמו ה-CLI של Earth Engine, צריך להוסיף סימן קריאה לפני הקריאות לפקודות.

!earthengine -h

הגדרת פרויקט בענן

משתמשים באפשרות --project כדי להגדיר פרויקט בענן לכל פקודת earthengine בנפרד.

!earthengine --project my-project <command>

לחלופין, אפשר להגדיר פרויקט ברירת מחדל שישמש את כל הקריאות ל-earthengine באמצעות הפקודה set_project. הפרויקט יתווסף לקובץ פרטי כניסה (‎~/.config/earthengine/credentials) וישמש לפקודות הבאות, אלא אם האפשרות --project תבטל אותו. מגדירים פרויקט כברירת מחדל לכל סשן חדש ב-Colab, או אם פג התוקף של המכונה הווירטואלית בגלל חוסר פעילות (פרטי הכניסה לא נשמרים בין הסשנים).

!earthengine set_project my-project

הפניה לפקודה

אימות

מאמת את כלי שורת הפקודה ואת ספריית הלקוח של Python ב-Earth Engine. דוגמה:

    earthengine authenticate

ב-Earth Engine משתמשים בפרוטוקול OAuth 2.0 לאימות לקוחות. הפקודה earthengine authenticate תנחה אתכם בתהליך האימות באמצעות דפדפן האינטרנט.

אם אתם משתמשים במצב ברירת המחדל של אימות gcloud, תצטרכו להתקין את gcloud. במדריך האימות תוכלו לקרוא על מצבי אימות אחרים שזמינים באמצעות הפרמטר auth_mode.

acl

מדפיסה או מעדכנת את רשימת בקרת הגישה (ACL) של נכס ב-Earth Engine. רשימת ה-ACL קובעת מי יכול לקרוא נכס או לכתוב בו. דוגמאות:

    earthengine acl get projects/my-project/assets/asset_id
    earthengine acl set public projects/my-project/assets/asset_id
    earthengine acl ch -u [e-mail]:R projects/my-project/assets/asset_id

פקודת המשנה get מדפיסה תיאור של רשימת ה-ACL בפורמט JSON. פקודת המשנה set מגדירה רשימת ACL שסופקה בקובץ באותו פורמט JSON. כדי להעתיק רשימת ACL מנכס אחד לנכסים אחרים, אפשר לשמור את הפלט מ-get ולספק אותו ל-set.

פקודת המשנה set מקבלת גם שני שמות מיוחדים של רשימות ACL:

• ‫private: הסרת ההרשאות מכולם חוץ מהבעלים.
• ‫public: נותן הרשאת קריאה לכל המשתמשים.

פקודת המשנה ch מאפשרת לבצע שינויים ספציפיים ב-ACL. כדי לתת הרשאת קריאה, מציינים את הערך -u [e-mail]:R. כדי לתת הרשאת כתיבה, מציינים את הערך -u [e-mail]:W. כדי להסיר הרשאות של משתמש, מציינים את הערך -d [e-mail]. אפשר להשתמש במזהה המשתמש המיוחד AllUsers כדי לתת הרשאת קריאה לכל המשתמשים או לבטל אותה. (שימו לב שביטול ההרשאות של AllUsers לא מבטל הרשאות נוספות שאולי הענקתם למשתמשים ספציפיים).

נכס

מדפיסה או מעדכנת מטא-נתונים שמשויכים לנכס ב-Earth Engine. דוגמאות:

    earthengine asset info projects/my-project/assets/asset_id
    earthengine asset set -p name=value projects/my-project/assets/asset_id
    earthengine asset setbands projects/my-project/assets/asset_id band1 band2

פקודת המשנה info מדפיסה מידע מפורט על הנכס, כולל המטא-נתונים שלו, בפורמט JSON. פקודת המשנה set מגדירה מאפייני מטא-נתונים ספציפיים בנכס. פקודת המשנה setbands מעדכנת את שמות הערוצים של נכס.

הערכים של מאפייני המטא-נתונים שאתם מגדירים יכולים להיות מספרים או מחרוזות. כשמגדירים שמות של מאפיינים באמצעות הדגל --property או -p, צריך להפריד בין שם המאפיין לבין הערך באמצעות סימן שוויון. סוג הנתונים מזוהה באופן אוטומטי, או שאפשר לציין אותו במפורש על ידי הוספת הקידומת (string),‏ (number) או (date) לשם המאפיין. לדוגמה, כך מגדירים מאפיין עם ערך מחרוזת "42":

    earthengine asset set -p '(string)name=42' projects/my-project/assets/asset_id

(המירכאות בדוגמה הזו מונעות מהמעטפת לפרש את הסוגריים. יכול להיות שהם נחוצים, בהתאם למעטפת ולפלטפורמה שלכם).

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

    earthengine asset set -p 'landcover_class_palette=ff0000,00ff00,0000ff' projects/my-project/assets/asset_id
    earthengine asset set -p 'landcover_class_values=1,2,3' projects/my-project/assets/asset_id

כדי למחוק מאפיין, מגדירים אותו כ-null בלי סוג:

    earthengine asset set -p name=null projects/my-project/assets/asset_id

מאפייני תאריך הם רק מספרים שמייצגים מספר אלפיות שנייה מאז ראשית זמן יוניקס (כלומר חצות ב-1 בינואר 1970). אפשר לציין אותם ישירות כמספר או באחד מהפורמטים הבאים:

    YYYY-MM-DD
    YYYY-MM-DDThh:mm:ss
    YYYY-MM-DDThh:mm:ss.f

אזור הזמן שמוגדר הוא UTC. אפשר להגדיר את מאפייני שעת ההתחלה ושעת הסיום המיוחדים באמצעות הדגלים --time_start ו---time_end:

    earthengine asset set --time_start 1978-10-15T12:34:56 projects/my-project/assets/asset_id

cp

העתקת נכס. דוגמה:

    earthengine cp projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

create

ליצור תיקיות חדשות ואוספי תמונות. דוגמה:

    earthengine create folder projects/my-project/assets/folder_id
    earthengine create collection projects/my-project/assets/collection_id

משתמשים בפקודת המשנה folder כדי ליצור תיקיות ובפקודת המשנה collection כדי ליצור אוספי תמונות. אפשר לציין את האפשרות -p כדי ליצור באופן רקורסיבי תיקיות הורה לפי הצורך. כברירת מחדל, לתיקיות ולתמונות שנוצרו לאחרונה יש רשימות ACL פרטיות.

ls

הצגת רשימה של התכנים בתיקייה אחת או יותר, או באוסף אחד או יותר. דוגמה:

    earthengine ls users/username

האפשרות -l מבקשת פורמט ארוך עם מידע נוסף על כל נכס (כרגע רק הסוג שלו). אפשר לציין את הפרמטר --max_items number (או בקיצור -m) כדי להגביל את מספר הפריטים מכל תיקייה או אוסף שאתם מציגים:

    earthengine ls -m 10 projects/my-project/assets/my_large_collection

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

מודל

כלי שמאפשר לבצע פעולות במודלים שנשמרו ב-TensorFlow.

model prepare

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

    earthengine model prepare my_source_dir my_dest_dir '{"Conv2D:0":"my_input_band"}' '{"Sigmoid:0":"my_output_band"}'

מידע נוסף על מודלים של פלטפורמת AI כאן אפשר לראות דוגמה מלאה.

mv

העברה או שינוי שם של נכס. דוגמה:

    earthengine mv projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

project_config

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

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

get

כדי לראות את הגדרות הפרויקט, משתמשים בפקודת המשנה get:

    earthengine alpha project_config get

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

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

בנוסף, אם יש לכם הרשאה לצפות בהגדרות של התוכנית, הפלט יכלול את הפרטים הבאים:

• ‫planMaxConcurrentExports, מספר שמציין את הכמות המקסימלית של משימות באצווה שיכולות לפעול במקביל בכל המשתמשים והפרויקטים שמשתמשים בחשבון לחיוב.

הוגדר

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

• ‫max_concurrent_exports, כדי לשלוט במקביליות המקסימלית של משימות באצווה בפרויקט
  • צריך את ההרשאות המתאימות

לדוגמה, כדי להגדיר פרויקט כך שרק 10 משימות יוכלו לפעול בו במקביל:

    earthengine alpha project_config set --max_concurrent_exports=10

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

מידע נוסף על מקביליות של משימות באצווה מופיע בדף המכסות של Earth Engine.

rm

מוחק נכס אחד או יותר. דוגמה:

    earthengine rm projects/my-project/assets/asset_id
    earthengine rm -r projects/my-project/assets/folder_id

אפשר להשתמש בדגל -r כדי למחוק את התוכן של תיקייה או אוסף באופן רקורסיבי. כדי למחוק כמה נכסים בבטחה, אתם יכולים להשתמש בדגל --dry_run כדי לוודא מה בדיוק יימחק, בלי למחוק שום דבר בפועל.

set_project

מגדיר את הפרויקט בענן של Google שדרכו מנותבות בקשות החישוב.

    earthengine set_project foo-project

צריך להריץ את הפקודה הזו לפני שמריצים פקודות שדורשות פונקציונליות של Cloud, למשל model.

משימה

מדפיסה מידע על משימות ארוכות או מנהלת אותן. דוגמאות:

    earthengine task list
    earthengine task list -l
    earthengine task info TASK_ID
    earthengine task cancel TASK_ID

פקודת המשנה list מציגה מידע בסיסי על המשימות ששלחתם לאחרונה. האפשרות -l מבקשת פורמט ארוך עם מידע נוסף על כל משימה. פקודת המשנה info מדפיסה מידע מפורט על משימות ספציפיות. פקודת המשנה cancel מבטלת משימה אחת או יותר שפועלות.

upload

העלאת תמונות או טבלאות מ-Google Cloud Storage ל-Earth Engine, או רישום של קובצי Cloud Optimized GeoTIFF‏ (COG) ב-Cloud Storage כנכסים שמגובים ב-COG (תמונות חיצוניות).

תמונה

כדי להעלות נכס תמונות באמצעות הגדרות ברירת המחדל:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id gs://bucket/image.tif

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

אפשר לציין את מדיניות הפחתת הפירמידה באמצעות הדגל --pyramiding_policy, שאפשר להגדיר לאחת מהאפשרויות הבאות: mean (ברירת המחדל), sample, mode, min או max. ההגדרה הזו קובעת איך Earth Engine יוצר את הפירמידה של גרסאות התמונה ברזולוציה נמוכה יותר:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --pyramiding_policy=sample gs://bucket/image.tif

אפשר להשתמש ב---last_band_alpha כדי לציין שהמסכה של התמונה צריכה להילקח מערוץ אלפא ברצועה האחרונה:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --last_band_alpha gs://bucket/image.tif

אפשר לציין ערך ללא נתונים באמצעות הדגל --nodata_value. הפעולה הזו תסתיר את כל הפיקסלים בתמונה עם הערך הזה:

    earthengine upload image --asset_id=users/myuser/asset --nodata_value=255 gs://bucket/image.tif

אפשר גם לציין מאפייני מטא-נתונים שיוגדרו בנכס באמצעות אותם דגלים שמתקבלים בפקודה asset set שמתוארת למעלה. האפשרויות מתוארות גם במדריך מניפסט תמונה.

שולחן

כדי להעלות קובץ Shapefile,‏ CSV או TFRecord מ-Google Cloud Storage לנכס טבלה ב-Earth Engine, אפשר להשתמש בכל אחת מהאפשרויות הבאות:

    earthengine upload table --asset_id=projects/my-project/assets/myUploadedShapefile gs://bucket/foo.shp
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedCSV gs://bucket/foo.csv
    earthengine upload table --asset_id=projects/my-project/assets/myUploadedTFRecord gs://bucket/foo.tfrecord

הערה: כשמעלים קובצי Shapefile, צריך לציין רק את הנתיב לקובץ .shp. הקבצים הקשורים .dbf,‏ .shx ו-.prj חייבים להיות באותו מיקום. לחלופין, אפשר לציין קובץ .zip שמכיל את הקבצים הנדרשים.

יש הרבה אפשרויות שקשורות לאופן שבו קובצי CSV ו-TFRecord מפורשים. כדי לראות את הרשימה המלאה של האפשרויות להעלאת טבלאות, אפשר לעיין במדריך Table Manifest או להריץ את הפקודה:

    earthengine upload table -h

external_image

כדי לרשום קובץ Cloud Optimized GeoTIFF‏ (COG) ב-Cloud Storage כנכס שמגובה ב-COG (נקרא תמונה חיצונית ב-API), מריצים את הפקודה upload external_image עם מניפסט:

earthengine upload external_image --manifest /tmp/foo.json

מוסיפים את --force כדי להחליף נכס קיים, למשל כדי להפנות אותו לגרסה חדשה של הקובץ שלו (ראו עדכון נכסים שמגובים ב-COG).

דוגמה למניפסט:

{
  "name": "projects/{project}/assets/cogdemo1",
  "tilesets": [
    { "id": "0", "sources": [{ "uris": ["gs://ee-docs-demos/COG_demo.tif"] }] }
  ],
  "properties": {
    "source": "https://code.earthengine.google.com/d541cf8b268b2f9d8f834c255698201d"
  },
  "startTime": "2016-01-01T00:00:00.000000000Z",
  "endTime": "2016-12-31T15:01:23.000000000Z"
}

לפרטים נוספים על יצירת המניפסט, קראו את המדריך לרישום COG ואת המדריך למניפסט של תמונות.