دارایی های موتور زمین با پشتوانه ابر GeoTiff

لوگوی کولابدر گوگل کولب اجرا کنید لوگوی گیت‌هابمشاهده منبع در گیت‌هاب

موتور زمین از دارایی‌هایی پشتیبانی می‌شود که توسط GeoTIFFهای بهینه‌شده ابری (COG) پشتیبانی می‌شوند. یکی از مزایای دارایی‌های پشتیبانی‌شده با COG این است که فیلدهای مکانی و فراداده‌ای تصویر در زمان ایجاد دارایی فهرست‌بندی می‌شوند و باعث می‌شوند تصویر در مجموعه‌ها عملکرد بهتری داشته باشد. عملکرد دارایی‌های پشتیبانی‌شده با COG در موارد استفاده معمول با دارایی‌های دریافتی قابل مقایسه است.

توجه داشته باشید که یک دارایی واحد می‌تواند توسط چندین COG پشتیبانی شود (برای مثال، می‌تواند یک COG در هر باند وجود داشته باشد). با این حال، استفاده از چندین کاشی COG برای یک باند واحد پشتیبانی نمی‌شود.

(به عنوان یک روش جایگزین، Earth Engine می‌تواند تصاویر را مستقیماً از COGها در Google Cloud Storage بارگذاری کند ( بیشتر بدانید ). با این حال، تصویری که از طریق ee.Image.loadGeoTIFF بارگذاری شده و به یک مجموعه تصویر اضافه می‌شود، برای عملیات فیلتر کردن روی مجموعه، نیاز به خواندن GeoTiff دارد.)

برای ایجاد یک دارایی تحت حمایت COG،

  1. فایل‌های COG خود را در یک سطل GCS قرار دهید (برای اطلاع از مناطق مجاز، به بخش «مکان» مراجعه کنید).
  2. نوشتن مانیفست آپلود تصویر
  3. برای ارسال دستور آپلود از ابزار خط فرمان earthengine استفاده کنید: 
earthengine upload external_image --manifest my_manifest.json

نمونه تصویر مانیفست با یک Tileset

ساده‌ترین ImageManifest ای است که فقط یک Tileset دارد. اگر هیچ باندی مشخص نشود، فایل حاصل شامل تمام باندهای GeoTIFF با نام باندهای کدگذاری شده در GeoTIFF خواهد بود (در این مورد، "vis-red"، "vis-green" و "vis-blue").

request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo1',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': [
        'gs://ee-docs-demos/COG_demo.tif'] } ] }
    ],
    'properties': {
      'version': '1.1'
    },
    'startTime': '2016-01-01T00:00:00.000000000Z',
    'endTime': '2016-12-31T15:01:23.000000000Z',
  },
}

pprint(request)

بیش از یک Tileset

می‌توان یک ImageManifest با بیش از یک Tileset مشخص کرد که در آن هر باند از تصویر حاصل توسط یکی از باندهای یک Tileset با استفاده از فیلدهای tilesetId و tilesetBandIndex پشتیبانی می‌شود. این در مواردی مفید است که باندهای مختلف وضوح یا انواع داده متفاوتی داشته باشند. باندها را می‌توان به هر ترتیبی از هر Tileset موجود فهرست کرد. در مثال زیر:

  • «b4b3b2.tif» مقیاس ۱۰ متر دارد، در حالی که «b5b6b7» مقیاس ۲۰ متر دارد.
  • ترتیب باند دارایی حاصل از COG های ورودی مخلوط شده است (مثلاً باند خروجی 0 از Tileset 0 است، در حالی که باند خروجی 1 از Tileset 1 است). 
request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo2',
    'uriPrefix': 'gs://ee-docs-demos/external_image_demo/',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': ['b4b3b2.tif'] } ] },
      { 'id': '1', 'sources': [ { 'uris': ['b5b6b7.tif'] } ] },
    ],
    'bands': [
      { 'id': 'red', 'tilesetId': '0', 'tilesetBandIndex': 0 },
      { 'id': 'rededge3', 'tilesetId': '1', 'tilesetBandIndex': 2 },
      { 'id': 'rededge2', 'tilesetId': '1', 'tilesetBandIndex': 1 },
      { 'id': 'green', 'tilesetId': '0', 'tilesetBandIndex': 1 },
      { 'id': 'blue', 'tilesetId': '1', 'tilesetBandIndex': 0 },
      { 'id': 'rededge1', 'tilesetId': '0', 'tilesetBandIndex': 2 },
    ],
  },
}

pprint(request)

جزئیات مربوط به دارایی‌های تحت حمایت COG

مکان

محل قرارگیری سطل ذخیره‌سازی ابری باید یکی از موارد زیر باشد:

  • چند منطقه‌ای ایالات متحده
  • هر منطقه دوگانه ایالات متحده که شامل US-CENTRAL1 باشد
  • منطقه ایالات متحده-مرکزی1

کلاس ذخیره‌سازی

کلاس ذخیره‌سازی سطل باید «ذخیره‌سازی استاندارد» باشد.

مجوزهای اشتراک گذاری

ACL های دارایی‌های Earth Engine با پشتیبانی COG و داده‌های زیربنایی به طور جداگانه مدیریت می‌شوند. هنگام اشتراک‌گذاری دارایی‌های با پشتیبانی COG با همکاران برای خواندن، مسئولیت مالک است که اطمینان حاصل کند که دسترسی خواندن هم به دارایی Earth Engine و هم به فایل‌های COG زیربنایی اعطا می‌شود.

۱. مجوزهای خواندن را به مخزن ذخیره‌سازی ابری گوگل اعطا کنید

برای اینکه همکاران بتوانند دارایی‌های پشتیبانی‌شده توسط COG را بخوانند، ابتدا باید به فایل‌های COG زیرین در مخزن ذخیره‌سازی ابری گوگل (Google Cloud Storage Bucket) دسترسی خواندن داشته باشند. بدون این مجوزها، Earth Engine قادر به بازیابی داده‌ها برای آنها نخواهد بود. اگر داده‌های موجود در Google Cloud Storage برای کاربر Earth Engine قابل مشاهده نباشد، Earth Engine خطایی به شکل "بارگذاری GeoTIFF در gs://my-bucket/my-object#123456 ناموفق بود" (که در آن 123456 نسل شیء است) را برمی‌گرداند.

به طور خاص، همکاران باید مجوزهای زیر را داشته باشند:

  • storage.buckets.get روی سطل (برای بازیابی ابرداده و مکان سطل، که به Earth Engine اجازه می‌دهد منبع دارایی را به درستی حل کند).
  • storage.objects.get روی سطل (برای خواندن داده‌های واقعی دارایی‌های پشتیبانی‌شده توسط COG).

این مجوزها به ترتیب توسط نقش‌های «Storage Legacy Bucket Reader» و «Storage Legacy Object Reader» و موارد دیگر ارائه می‌شوند.

برای اختصاص این نقش‌ها به همکاران:

  1. به صفحه مجوزهای سطل بروید: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. روی « اعطای دسترسی » کلیک کنید
  3. تمام مدیران (مثلاً کاربران، گروه‌ها، حساب‌های سرویس) که باید دسترسی خواندن به آنها اعطا شود را اضافه کنید.
  4. نقش‌های زیر را اختصاص دهید:
    • «Storage Legacy Bucket Reader» (مجوزهای خواندن storage.buckets.get و سایر مجوزهای خواندن در سطح bucket را فراهم می‌کند).
    • «خواننده شیء قدیمی حافظه» ( storage.objects.get را فراهم می‌کند).
    • (به عنوان یک راه حل جایگزین، می‌توانید یک نقش سفارشی جدید فقط با مجوزهای storage.buckets.get و storage.objects.get ایجاد کنید و آن را به نقش‌های دیگر اختصاص دهید.)
  5. ذخیره

۲. ابزار Earth Engine را برای مطالعه به اشتراک بگذارید

پس از اطمینان از اینکه همکارانتان مجوزهای لازم را روی سطل و اشیاء GCS زیربنایی دارند، باید خود دارایی Earth Engine را نیز به اشتراک بگذارید. برای اطلاعات بیشتر در مورد تنظیم مجوزهای دارایی Earth Engine، به راهنمای مدیریت دارایی Earth Engine مراجعه کنید.

نسل‌ها

وقتی یک دارایی با پشتیبانی COG ایجاد می‌شود، Earth Engine فراداده‌های TIFF های مشخص شده در مانیفست را می‌خواند و یک ورودی ذخیره دارایی ایجاد می‌کند. هر URI مرتبط با آن ورودی می‌تواند یک نسل داشته باشد. برای جزئیات بیشتر در مورد نسل‌ها، به اسناد نسخه‌بندی شیء مراجعه کنید. اگر یک نسل مشخص شده باشد، به عنوان مثال gs://foo/bar#123 ، Earth Engine آن URI را کلمه به کلمه ذخیره می‌کند. اگر یک نسل مشخص نشده باشد، Earth Engine آن URI را با نسل TIFF در زمان فراخوانی ImportExternalImage ذخیره می‌کند.

این بدان معناست که اگر هر TIFF حاوی یک فایل خارجی در GCS به‌روزرسانی شود (و در نتیجه نسل آن تغییر کند)، Earth Engine خطای "بارگذاری GeoTIFF در gs://my-bucket/my-object#123456 ناموفق بود" را برمی‌گرداند زیرا شیء مورد انتظار دیگر وجود ندارد (مگر اینکه سطل چندین نسخه شیء را فعال کند). این خط‌مشی برای همگام‌سازی فراداده‌های دارایی با فراداده‌های شیء طراحی شده است.

پیکربندی

از نظر نحوه پیکربندی COG، فایل TIFF باید:

  • کاشی‌کاری شده، که در آن ابعاد کاشی یکی از موارد زیر است:

    • ۲۵۶x۲۵۶
    • ۵۱۲x۵۱۲
    • ۱۰۲۴x۱۰۲۴
    • 2048x2048

  • طوری تنظیم شده که همه IFD ها در ابتدا قرار داشته باشند.

برای بهترین عملکرد:

  • از کاشی‌هایی با ابعاد ۵۱۲x۵۱۲ یا بالاتر استفاده کنید.
  • شامل قدرت ۲ مرور کلی باشد.

بسته به موارد استفاده مورد نظر شما، گزینه ایجاد «INTERLEAVE» ممکن است بر عملکرد تأثیر بگذارد. توصیه می‌کنیم در هر شرایطی از BAND interleave استفاده کنید.

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

دستور gdal_translate زیر، یک رستر را به یک GeoTIFF بهینه شده با ابر، فشرده شده با zstd و با لایه بندی باند تبدیل می‌کند که در Earth Engine عملکرد خوبی خواهد داشت:

gdal_translate in.tif out.tif \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=22 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS

می‌توان با تعیین یک پیش‌بینی‌کننده ( -co PREDICTOR=2 برای انواع داده صحیح و -co PREDICTOR=3 برای انواع داده اعشاری) حجم فایل خروجی را بیشتر کاهش داد.

برای کاربرانی که GDAL >= 3.11 دارند، درایور COG می‌تواند بدون نگرانی در مورد ایجاد و حفظ نمای کلی، فایل‌ها را تولید کند.

gdal_translate in.tif out.tif \
  -of COG \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=22 \
  -co PREDICTOR=2 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \

ایجاد دارایی‌های ابری با پشتیبانی GeoTiff با استفاده از REST API

توجه: REST API شامل ویژگی‌های جدید و پیشرفته‌ای است که ممکن است برای همه کاربران مناسب نباشد. اگر در Earth Engine تازه‌کار هستید، توصیه می‌کنیم با راهنمای جاوا اسکریپت شروع کنید.

برای ایجاد یک دارایی با پشتیبانی COG با استفاده از REST API، یک درخواست POST به نقطه پایانی Earth Engine ImportExternalImage ارسال کنید. همانطور که در ادامه نشان داده شده است، این درخواست باید برای ایجاد یک دارایی در پوشه کاربری شما مجاز باشد.

شروع یک جلسه مجاز

برای اینکه بتوانید یک دارایی Earth Engine را در پوشه کاربری خود ایجاد کنید، باید بتوانید هنگام ارسال درخواست، خودتان را احراز هویت کنید. می‌توانید از اعتبارنامه‌های تأییدکننده Earth Engine برای شروع یک AuthorizedSession استفاده کنید. سپس می‌توانید از AuthorizedSession برای ارسال درخواست‌ها به Earth Engine استفاده کنید.

import ee
import json
from pprint import pprint
from google.auth.transport.requests import AuthorizedSession

ee.Authenticate()  #  or !earthengine authenticate --auth_mode=gcloud

# Specify the cloud project you want associated with Earth Engine requests.
ee_project = 'your-project'

session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

درخواست بدنه

بدنه درخواست، نمونه‌ای از یک ImageManifest است. در اینجا مسیر COG به همراه سایر ویژگی‌های مفید مشخص شده است.

برای جزئیات بیشتر در مورد نحوه پیکربندی ImageManifest به این راهنما مراجعه کنید. می‌توان یک یا چند Tileset تعریف کرد که هر کدام یک یا چند باند را پشتیبانی کنند. برای ImportExternalImage ، حداکثر یک ImageSource به ازای هر Tileset پشتیبانی می‌شود.

برای جزئیات بیشتر در مورد صادرات COG به این سند مراجعه کنید.

درخواست را ارسال کنید

درخواست POST را به نقطه پایانی projects.images.importExternal در Earth Engine ارسال کنید.

url = f'https://earthengine.googleapis.com/v1alpha/projects/{ee_project}/image:importExternal'

response = session.post(
  url = url,
  data = json.dumps(request)
)

pprint(json.loads(response.content))