اطلاعیه : همه پروژه‌های غیرتجاری ثبت‌شده برای استفاده از Earth Engine قبل از ۱۵ آوریل ۲۰۲۵ باید واجد شرایط بودن غیرتجاری برای حفظ دسترسی Earth Engine را تأیید کنند .

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

در Google Colab اجرا شود

مشاهده منبع در GitHub

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

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

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

برای ایجاد یک دارایی با پشتوانه COG،

فایل های COG خود را در یک سطل GCS قرار دهید (برای مناطق مجاز به زیر مراجعه کنید).
یک مانیفست آپلود تصویر بنویسید
از ابزار خط فرمان 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» دارای مقیاس 10 متری است، در حالی که «b5b6b7» دارای مقیاس 20 متری است.
ترتیب باند دارایی حاصل از 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 باشد
منطقه US-CENTRAL1

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

کلاس ذخیره سازی سطل باید "Standard storage" باشد.

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

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

1. به Google Cloud Storage مجوز برای خواندن اعطا کنید

برای اینکه همکاران بتوانند دارایی های پشتیبانی شده COG را بخوانند، ابتدا باید به فایل های COG زیربنایی در سطل فضای ذخیره سازی ابری Google دسترسی خواندن داشته باشند. بدون این مجوزها، 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" و سایر موارد ارائه می‌شوند.

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

به صفحه مجوز سطل بروید: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
روی " GRANT ACCESS " کلیک کنید
همه اصلی‌ها (به عنوان مثال، کاربران، گروه‌ها، حساب‌های سرویس) را که باید به آنها دسترسی خواندن داده شود، اضافه کنید.
نقش های زیر را تعیین کنید:
- "Storage Legacy Bucket Reader" ( storage.buckets.get و سایر مجوزهای خواندن در سطح سطل را ارائه می دهد).
- "Storage Legacy Object Reader" ( storage.objects.get را ارائه می دهد).
- (در عوض، می توانید یک نقش سفارشی جدید فقط با مجوزهای storage.buckets.get و storage.objects.get ایجاد کنید و آن را اختصاص دهید.)
ذخیره کنید

2. دارایی 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 باید به صورت زیر باشد:

کاشی کاری شده، که در آن ابعاد کاشی عبارتند از:
- 256x256
- 512x512
- 1024x1024
- 2048x2048
طوری تنظیم شده است که تمام IFD ها در ابتدا باشند.

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

از ابعاد کاشی 512x512 یا بالاتر استفاده کنید.
شامل قدرت 2 نمای کلی.

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

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

دستور gdal_translate زیر یک شطرنجی را به یک GeoTIFF بهینه سازی شده ابری، فشرده شده با نوار، تبدیل می کند که عملکرد خوبی در 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 \

ایجاد دارایی های Cloud GeoTiff-Backed با استفاده از REST API

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

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

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

برای اینکه بتوانید یک دارایی Earth Engine را در پوشه کاربری خود ایجاد کنید، باید بتوانید در هنگام ارسال درخواست، به عنوان خودتان احراز هویت کنید. برای شروع یک AuthorizedSession می توانید از اعتبارنامه های Earth Engine Authenticator استفاده کنید. سپس می توانید از 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 را به Earth Engine projects.images.importExternal پایان دهید.

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))

دارایی های موتور زمین با پشتوانه ابر GeoTiff با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

بیش از یک Tileset