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

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

    earthengine

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

    earthengine command -h

בפעם הראשונה שמתקינים את Python API צריך להיכנס באמצעות הפקודה 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

הגדרת פרויקט ב-Cloud

משתמשים באפשרות --project כדי להגדיר פרויקט ב-Cloud לכל פקודה בנפרד של 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 של רשימת ה-ACL. פקודת המשנה 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 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 Cloud שדרכו מנותבות בקשות לחישוב.

    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 שמתוארת למעלה. האפשרויות מתוארות גם במדריך Image Manifest.

שולחן

כדי להעלות קובץ 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.