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

הכלי 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()

ביצוע פקודות

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

!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 מדפיסה תיאור JSON של רשימת בקרת הגישה. פקודת המשנה set מגדירה רשימת ACL שמופיעה בקובץ בפורמט JSON. אפשר להעתיק רשימת בקרת גישה מנכס אחד לנכסים אחרים על ידי שמירת הפלט מ-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

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

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

    earthengine asset set -p '(string)name=42' 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 Platform דוגמה מלאה

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, או יצירת נכסים שמגובים בתמונות חיצוניות.

תמונה

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

    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

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

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

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

{
  "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"
}

לפרטים נוספים על יצירת המניפסט, אפשר לעיין במדריך בנושא Cloud GeoTIFF ובמדריך בנושא Image Manifest.