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

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

    earthengine

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

    earthengine command -h

عند تثبيت Python API لأول مرة، عليك تسجيل الدخول باستخدام الأمر 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، عليك إضافة علامة تعجب قبل طلبات الأوامر.

!earthengine -h

إعداد مشروع على Cloud

استخدِم الخيار --project لضبط مشروع على Cloud لكل أمر individual 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 قائمة أذونات وصول مقدَّمة في ملف بتنسيق 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

ويُفترض أنّ المنطقة الزمنية هي التوقيت العالمي المنسّق. يمكنك ضبط سمتَي وقت البدء والانتهاء الخاصة باستخدام العلامتَين --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 لإنشاء مجلدات والد بشكل متكرّر حسب الحاجة. تحتوي المجلدات والصور التي تم إنشاؤها حديثًا على جداول تحكم بالوصول الخاصة بشكلٍ default.

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

يمكنك الاطّلاع على مزيد من المعلومات عن نماذج "منصّة الذكاء الاصطناعي" هنا. يمكنك الاطّلاع على مثال كامل هنا.

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