ابزار خط فرمان

ابزار earthengine یک برنامه کاربردی است که به شما امکان می دهد دارایی ها و وظایف Earth Engine را از خط فرمان مدیریت کنید. هنگامی که API پایتون را نصب می کنید، به طور خودکار نصب می شود. برای بررسی اینکه آیا ابزار نصب شده و به درستی کار می کند، موارد زیر را در خط فرمان تایپ کنید:

    earthengine

اگر ابزار به درستی نصب شده باشد، خلاصه‌ای از دستورات موجود را چاپ می‌کند. برای دریافت کمک در مورد یک دستور خاص، از:

    earthengine command -h

هنگامی که برای اولین بار API پایتون را نصب می کنید، باید با استفاده از دستور authenticate که در زیر توضیح داده شده است، وارد شوید. بخش های زیر دستورات موجود را با جزئیات بیشتری توضیح می دهند.

اعتبار حساب خدمات

برای استفاده از CLI با اعتبار یک حساب سرویس، از پرچم service_account_file استفاده کنید تا به فایل JSON حاوی کلید حساب سرویس اشاره کنید.

    earthengine --service_account_file=service_account_creds.json

استفاده در کولب

ابزار خط فرمان Earth Engine از پیش نصب شده و آماده استفاده در Google Colab است.

احراز هویت

برای هر جلسه جدید Colab یا اگر ماشین مجازی به دلیل عدم فعالیت منقضی می‌شود، احراز هویت کنید (اطلاعات اعتبار در تمام جلسات ذخیره نمی‌شوند).

کتابخانه کلاینت پایتون را وارد کنید و ee.Authenticate() را فراخوانی کنید تا جریان احراز هویت فعال شود. برای تکمیل احراز هویت، دستورات را دنبال کنید. حالت پیش‌فرض auth_mode در Colab colab است، برای سایر گزینه‌ها به راهنمای احراز هویت مراجعه کنید.

import ee
ee.Authenticate()

اجرای دستور

برای اجرای ابزارهای خط فرمان، مانند Earth Engine CLI، باید فراخوانی‌های فرمان را با علامت تعجب از قبل تنظیم کنید.

!earthengine -h

یک پروژه Cloud تنظیم کنید

از گزینه --project برای تنظیم پروژه Cloud برای هر فرمان earthengine جداگانه استفاده کنید.

!earthengine --project my-project <command>

همچنین، با استفاده از دستور set_project ، یک پروژه پیش‌فرض تنظیم کنید تا برای همه تماس‌های earthengine استفاده شود. پروژه به یک فایل اعتبارنامه (~/.config/earthengine/credentials) اضافه می شود و برای دستورات بعدی استفاده می شود، مگر اینکه توسط --project برای هر جلسه Colab جدید یا اگر ماشین مجازی به دلیل عدم فعالیت منقضی شود، یک پروژه پیش‌فرض تنظیم کنید (اطلاعات اعتبار در تمام جلسات ذخیره نمی‌شوند).

!earthengine set_project my-project

مرجع فرمان

احراز هویت

ابزار خط فرمان و کتابخانه کلاینت پایتون را در Earth Engine تأیید می کند. مثال:

    earthengine authenticate

Earth Engine از پروتکل OAuth 2.0 برای احراز هویت مشتریان استفاده می کند. دستور احراز هویت موتور خاکی شما را با استفاده از مرورگر وب خود از طریق فرآیند احراز هویت راهنمایی می کند.

اگر از حالت پیش فرض احراز هویت 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 username@gmail.com:R projects/my-project/assets/asset_id

دستور فرعی get شرح JSON از ACL را چاپ می کند. دستور فرعی set یک ACL ارائه شده در فایلی با همان فرمت JSON را تنظیم می کند. می توانید با ذخیره خروجی از get و ارائه آن برای set ، یک ACL را از یک دارایی به دیگری کپی کنید.

دستور فرعی set نیز دو نام ویژه ACL را می پذیرد:

  • private : مجوزها را از همه به جز مالک حذف می کند.
  • public : به همه کاربران اجازه خواندن می دهد.

دستور فرعی ch به شما امکان می دهد تغییرات فردی را در ACL ایجاد کنید. برای اعطای مجوز خواندن -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

ویژگی‌های تاریخ فقط اعدادی هستند که نشان‌دهنده تعدادی میلی‌ثانیه از زمان یونیکس ( یعنی نیمه‌شب ۱ ژانویه ۱۹۷۰) هستند و ممکن است مستقیماً به‌عنوان یک عدد یا در یکی از قالب‌های زیر مشخص شوند: 

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

در اینجا درباره مدل های پلتفرم هوش مصنوعی بیشتر بدانید. یک مثال کامل را اینجا ببینید.

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 می کند.

برای اطلاعات بیشتر در مورد موازی کاری دسته ای، به صفحه سهمیه های موتور زمین مراجعه کنید.

rm

یک یا چند دارایی را حذف می کند. مثال: 

    earthengine rm projects/my-project/assets/asset_id
    earthengine rm -r projects/my-project/assets/folder_id

می توانید از پرچم -r برای حذف محتویات یک پوشه یا مجموعه به صورت بازگشتی استفاده کنید. برای ایمنی هنگام حذف چندین دارایی، می‌توانید از پرچم --dry_run برای تأیید اینکه دقیقاً چه چیزی حذف می‌شود بدون حذف واقعی استفاده کنید.

مجموعه_پروژه

پروژه 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 شرح داده شده در بالا پذیرفته می‌شود، تعیین کنید. گزینه ها نیز در راهنمای 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 وجود دارد. با مراجعه به راهنمای Table Manifest یا با مراجعه به راهنمای جدول می توانید لیست کاملی از گزینه های آپلود جدول را مشاهده کنید: 

    earthengine upload table -h

خارجی_تصویر

برای ایجاد یک دارایی با پشتوانه یک تصویر خارجی، دستور 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 و راهنمای Image Manifest را ببینید.