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

الأداة 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` التلقائي auth_mode في Colab هو colab، يمكنك الاطّلاع على دليل المصادقة للتعرّف على الخيارات الأخرى.

import ee
ee.Authenticate()

تنفيذ الأوامر

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

    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

(تمنع علامات التنصيص في هذا المثال الصدفة من تفسير الأقواس. وقد تكون ضرورية أو غير ضرورية، حسب الصدفة والنظام الأساسي.)

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

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

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

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

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

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

محدّدة

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

  • max_concurrent_exports، للتحكّم في الحد الأقصى للتوازي في المهام المجمّعة للمشروع
    • يتطلب الأذونات الصحيحة permissions

على سبيل المثال، لضبط مشروع بحيث لا يسمح مطلقًا بتشغيل أكثر من 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

هذا الأمر ضروري قبل تشغيل الأوامر التي تتطلب وظائف السحابة الإلكترونية ، مثل 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 الموضّح أعلاه. توضّح الخيارات أيضًا في الـ 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

هناك العديد من الخيارات المتعلقة بطريقة تفسير ملفات 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 ودليل بيان الصورة لمزيد من التفاصيل حول إنشاء البيان.