أداة سطر الأوامر

earthengine هي أداة مساعدة تتيح لك إدارة مواد عرض ومهام Earth Engine من سطر الأوامر. يتم تثبيته تلقائيًا عند تثبيت واجهة برمجة التطبيقات Python. للتحقّق مما إذا كانت الأداة مثبّتة وتعمل بشكل صحيح، اكتب ما يلي في سطر الأوامر:

    earthengine

في حال تثبيت الأداة بشكل صحيح، ستعرض ملخّصًا قصيرًا للأوامر المتاحة. للحصول على مساعدة بشأن أمر معيّن، استخدِم:

    earthengine command -h

عند تثبيت واجهة برمجة تطبيقات Python لأول مرة، عليك تسجيل الدخول باستخدام الأمر authenticate الموضّح أدناه. توضّح الأقسام التالية الأوامر المتاحة بمزيد من التفصيل.

بيانات اعتماد حساب الخدمة

لاستخدام واجهة سطر الأوامر مع بيانات اعتماد حساب خدمة، استخدِم العلامة 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 أو تعدّلها. تتحكّم قائمة التحكم في الوصول في المستخدمين الذين يمكنهم قراءة مادة عرض أو الكتابة إليها. أمثلة:

    earthengine acl get projects/my-project/assets/asset_id
    earthengine acl set public projects/my-project/assets/asset_id
    earthengine acl ch -u username@gmail.com:R projects/my-project/assets/asset_id

يطبع الأمر الفرعي get وصف JSON لقائمة التحكّم بالوصول. يضبط الأمر الفرعي set قائمة التحكّم بالوصول (ACL) المقدَّمة في ملف بالتنسيق نفسه JSON. يمكنك نسخ قائمة التحكّم بالوصول من مادة عرض إلى مواد عرض أخرى عن طريق حفظ الناتج من get وتقديمه إلى set.

يقبل الأمر الفرعي set أيضًا اسمَين خاصَّين لقائمة التحكّم بالوصول:

  • private: يزيل الأذونات من جميع المستخدمين باستثناء المالك.
  • public: يمنح إذن القراءة لجميع المستخدمين.

يتيح لك الأمر الفرعي ch إجراء تغييرات فردية على قائمة التحكّم بالوصول. لمنح إذن القراءة، حدِّد -u username@gmail.com:R، ولمنح إذن الكتابة، حدِّد -u username@gmail.com:W، ولإزالة أذونات المستخدم، حدِّد -d username@gmail.com. يمكن استخدام معرّف المستخدم الخاص 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

خصائص التاريخ هي مجرد أرقام تمثّل عدد المللي ثانية منذ بداية حقبة Unix (أي منتصف الليل في 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

إنشاء

إنشاء مجلدات ومجموعات صور جديدة مثال:

    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

تضبط هذه السمة قيم إعدادات المشروع. قبل استخدام هذا الأمر، تأكَّد من ضبط مشروع باستخدام set_project.

الحصول على

لعرض إعدادات مشروع، استخدِم الأمر الفرعي get:

    earthengine alpha project_config get

إذا كان لديك إذن بالاطّلاع على إعدادات مهمة الدفعات في المشروع، سيتضمّن الناتج ما يلي:

  • maxConcurrentExports: رقم يشير إلى الحد الأقصى لعدد مهام الدفعات التي يمكن تشغيلها بالتوازي لدى جميع المستخدمين للمشروع المحدّد. يتم ضبط هذا الحد تلقائيًا على الحد الأقصى المسموح به بموجب خطة الاشتراك في حساب الفوترة المرتبط.

بالإضافة إلى ذلك، إذا كان لديك إذن بالاطّلاع على إعدادات الخطة، سيتضمّن الناتج ما يلي:

  • ‫planMaxConcurrentExports: رقم يشير إلى الحد الأقصى لعدد مهام الدفعات التي يمكن تشغيلها بالتوازي على مستوى جميع المستخدمين والمشاريع التي تستخدم حساب الفوترة.

محدّدة

لتعديل إعدادات المشروع، استخدِم الأمر الفرعي set. يمكن ضبط الإعدادات التالية:

على سبيل المثال، لضبط مشروع بحيث لا يسمح مطلقًا بتنفيذ 10 مهام بالتوازي للمشروع المحدّد، اتّبِع الخطوات التالية:

    earthengine alpha project_config set --max_concurrent_exports=10

يعرض الناتج إعدادات المشروع المعدَّلة، وهي مطابقة لما تعرضه الدالة get.

لمزيد من المعلومات حول التوازي في مهام الدفعات، يُرجى الاطّلاع على صفحة حصص Earth Engine.

غرف

تحذف هذه الطريقة مادة عرض واحدة أو أكثر. مثال:

    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 مهمة واحدة أو أكثر قيد التشغيل.

تحميل

تحميل صور أو جداول من 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

تتوفّر العديد من الخيارات المتعلّقة بطريقة تفسير ملفات CSV وTFRecord. يمكنك الاطّلاع على قائمة كاملة بخيارات تحميل الجداول من خلال الانتقال إلى دليل بيان الجدول أو باستخدام:

    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 ودليل بيان الصور لمزيد من التفاصيل حول إنشاء البيان.