Earth Engine برای محافظت از منابع محاسباتی مشترک و تضمین عملکرد قابل اعتماد برای همه، سطوح سهمیه‌بندی غیرتجاری را معرفی کرده است. پروژه‌های غیرتجاری به طور پیش‌فرض از سطح Community استفاده می‌کنند، اگرچه می‌توانید سطح یک پروژه را در هر زمان تغییر دهید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

ثبت دارایی‌های GeoTIFF بهینه‌سازی‌شده ابری (COG)

Earth Engine از دارایی‌های پشتیبانی‌شده توسط Cloud Optimized GeoTIFFs (COGs) ذخیره‌شده در Google Cloud Storage (GCS) پشتیبانی می‌کند.

وقتی دارایی COG-backed را ثبت می‌کنید، Earth Engine فیلدهای فضایی و فراداده تصویر را در زمان ایجاد نمایه می‌کند. این کار باعث می‌شود تصویر هنگام استفاده در مجموعه‌ها عملکرد خوبی داشته باشد و عملکرد آن با دارایی‌های استاندارد واردشده قابل‌مقایسه باشد (به نمای کلی GeoTIFF بهینه‌شده ابری (COG) مراجعه کنید).

پیش‌نیازها و راه‌اندازی Cloud Storage

قبل‌از ثبت COG، باید منابع Google Cloud Storage خود را به‌درستی راه‌اندازی کنید.

۱. مکان دسته‌بندی (الزام اکید)

برای اینکه Earth Engine به سطل Cloud Storage شما دسترسی داشته باشد، سطل باید در یکی از مناطق یا مناطق چندگانه مرکز داده زیر قرار داشته باشد:

چندمنطقه‌ای us
هر منطقه دوگانه ایالات متحده که شامل us-central1 باشد
منطقه us-central1

اگر محفظه‌تان در هر مرکز داده منطقه‌ای دیگری قرار گیرد (مثلاً us-east4 یا europe-west1)، Earth Engine درخواست‌های ثبت و خواندن را رد خواهد کرد.

۲. طبقه فضای ذخیره‌سازی و صورت‌حساب

توصیه می‌کنیم از کلاس ذخیره‌سازی استاندارد استفاده کنید. فضای ذخیره‌سازی استاندارد هیچ قانون حداقل مدت ذخیره‌سازی ندارد، که درصورت به‌روزرسانی یا جایگزینی فایل‌های موقت، از جریمه‌های صورت‌حساب حذف زودهنگام جلوگیری می‌کند.
اگرچه حلقه‌های محاسباتی Earth Engine هزینه‌های اضافی برای بازیابی داده‌های Cloud Storage را دربرنمی‌گیرد، دسترسی به سطوح ذخیره‌سازی غیر استاندارد از ابزارهای خارجی (مانند نرم‌افزار GIS رومیزی) هزینه‌های بازیابی پرهزینه‌ای را دربرمی‌گیرد.
برای استفاده از GCS، باید صورت‌حساب را در پروژه Google Cloud خود فعال کرده باشید. برای شروع، شروع سریع Google Cloud Storage را ببینید.

مرحله ۱: آماده کردن COG

فایل‌های TIFF شما باید برای فضای ابری بهینه‌سازی شده باشد. TIFF باید:

کاشی‌کاری‌شده، با ابعاد کاشی: ۲۵۶x۲۵۶،‏ ۵۱۲x۵۱۲،‏ ۱۰۲۴x۱۰۲۴، یا ۲۰۴۸x۲۰۴۸. برای بهترین عملکرد، ۵۱۲×۵۱۲ یا بالاتر را توصیه می‌کنیم.
به‌گونه‌ای چیده شده‌اند که همه «فهرست‌های فایل تصویری» (IFD) در ابتدا قرار دارند.
نماهای کلی توان ۲ را اضافه کنید.
از درهم‌گذاری BAND استفاده کنید.

می‌توانید از GDAL برای تبدیل تصاویرتان استفاده کنید.

بااستفاده از GDAL COG Driver (GDAL >= 3.1 توصیه می‌شود):

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

بااستفاده از درایور GTiff استاندارد:

ابتدا، نمای کلی داخلی توان ۲ را تولید کنید (بااستفاده از gdal raster overview add یا gdaladdo)، سپس تصویر و نماهای کلی را در چیدمان COG کاشی‌کاری‌شده کپی کنید:

gdaladdo -r nearest in.tif 2 4 8 16 32  # or -r cubic for continuous/float data

gdal_translate in.tif out.tif \
  -co BIGTIFF=YES \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=16 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

مرحله ۲: ساختن مانیفست

چه COG را بااستفاده از کتابخانه مشتری Python در Earth Engine، ابزار خط فرمان earthengine، یا Earth Engine REST API ثبت کنید، باید مانیفست بارگذاری تصویری را تعریف کنید که مقصد دارایی، نشانی‌های وب Google Cloud Storage، و فراداده‌های اختیاری باند را مشخص می‌کند.

مثال: COG تکی که از همه باندها پشتیبانی می‌کند اگر COG شما حاوی همه باندها (مثلاً RGB) باشد، مانیفست فقط به یک مجموعه کاشی نیاز دارد:

{
  "name": "projects/my-project/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

مثال: چند COG (یکی برای هر باند) اگر فایل‌های جداگانه‌ای برای باندهای مختلف دارید (مثلاً قرمز، سبز، آبی در فایل‌های جداگانه):

{
  "name": "projects/my-project/assets/my_multi_band_cog",
  "tilesets": [
    {
      "id": "red_tileset",
      "sources": [ { "uris": [ "gs://google-sample-bucket/band_red.tif" ] } ]
    },
    {
      "id": "green_tileset",
      "sources": [ { "uris": [ "gs://google-sample-bucket/band_green.tif" ] } ]
    }
  ],
  "bands": [
    { "id": "R", "tilesetId": "red_tileset", "tilesetBandIndex": 0 },
    { "id": "G", "tilesetId": "green_tileset", "tilesetBandIndex": 0 }
  ]
}

مرحله ۳: ارسال درخواست ثبت

می‌توانید مانیفست خود را بااستفاده از کتابخانه مشتری Earth Engine Python، ابزار خط فرمان earthengine، یا Earth Engine REST API به Earth Engine ارسال کنید. روشی را انتخاب کنید که بهترین تناسب را با گردش کارتان دارد.

کتابخانه کارخواه Python

در اسکریپت Python یا دفترچه Jupyter، پس‌از مقداردهی اولیه پروژه، از کتابخانه کارخواه Earth Engine Python (ee.data) استفاده کنید:

import ee

# 1. Authenticate and initialize
ee.Authenticate()
ee.Initialize(project='your-project-id')

# 2. Define the manifest as a Python dictionary
manifest = {
  "name": "projects/your-project-id/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

# 3. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
print(f"Asset registered: {result['name']}")

رابط خط فرمان

در پایانه، مانیفست را در فایلی به‌نام manifest.json ذخیره کنید و فرمان بارگذاری earthengine را اجرا کنید: :

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Submit the external image upload task
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

REST API (Python)

برای گردش‌های کاری خودکار بدون کتابخانه کارخواه، یک درخواست مجاز POST را مستقیماً به نقطه پایانی Earth Engine REST API ارسال کنید projects.image.importExternal (در اینجا بااستفاده از Python نشان داده شده است):

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

# 1. Authenticate and start an authorized HTTP session
ee.Authenticate()
ee_project = 'your-project-id'
session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

# 2. Define the REST request body wrapping the manifest
request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/my_cog_asset',
    'tilesets': [
      {
        'id': 'default_tileset',
        'sources': [
          {
            'uris': [
              'gs://google-sample-bucket/my_optimized_image.tif'
            ]
          }
        ]
      }
    ]
  }
}

# 3. Send the POST request
url = (
    'https://earthengine.googleapis.com/v1alpha/'
    f'projects/{ee_project}/image:importExternal'
)
response = session.post(url=url, data=json.dumps(request))
pprint(json.loads(response.content))

پس‌از ارسال، درخواست ثبت‌نام یک عملیات فهرست‌بندی فراداده سبک را آغاز می‌کند. چون ثبت COG داده‌های پیکسل را کپی نمی‌کند، این عملیات معمولاً ظرف چند ثانیه تکمیل می‌شود.

ثبت هم‌زمان: چون ثبت COG یک فراخوانی API هم‌زمان و سریع است و نه یک کار محاسباتی دسته‌ای ناهم‌زمان، تکلیف پس‌زمینه‌ای در برگه تکالیف «ویرایشگر کد» یا مدیر تکلیف دسته‌ای ایجاد نمی‌کند. تماس API تا زمانی که درستی‌سنجی و نمایه‌گذاری فراداده تکمیل شود مسدود می‌شود، پس‌از آن دارایی بلافاصله در برگه دارایی‌ها «ویرایشگر کد» یا بااستفاده از ee.data.getAsset() دردسترس قرار می‌گیرد.

محدودیت‌های مانیفست برای دارایی‌های COG

هنگام ایجاد مانیفست برای دارایی‌های COG-backed، به این محدودیت‌های سخت‌گیرانه توجه کنید (که با مانیفست‌های استاندارد دریافت متفاوت است):

یک سطل: همه شناسه‌های منبع یکسان در مانیفست باید در یک سطل GCS قرار داشته باشند.
یک شناسه منبع یکسان برای هر منبع: هر ImageSource باید دقیقاً یک شناسه منبع یکسان داشته باشد. نمی‌توانید چند فایل را باهم در یک منبع مجموعه کاشی موزاییک کنید. برای موزاییک کردن چند صحنه COG، هر COG را به‌عنوان دارایی ثبت کنید و آن‌ها را بااستفاده از .mosaic() در یک ee.ImageCollection ترکیب کنید.
نه mask_bands: از mask_bands سطح بالا پشتیبانی نمی‌شود. از missingData در مانیفست استفاده کنید یا مطمئن شوید که TIFF شما مقدار داخلی nodata دارد.
data_type در مجموعه کاشی وجود ندارد: data_type را در بخش tilesets مشخص نکنید؛ به‌طور خودکار شناسایی می‌شود.
dimensions در منبع وجود ندارد: dimensions را در ImageSource مشخص نکنید.
subdataset_prefix / subdataset_suffix وجود ندارد.
min_tile_area_ratio یا skip_metadata_read وجود ندارد.

مرحله ۴: پیکربندی اجازه‌ها (بسیار مهم برای هم‌رسانی)

برخلاف دارایی‌های استاندارد Earth Engine، داده‌های پیکسل COG در GCS باقی می‌ماند. هنگام هم‌رسانی دارایی COG-backed با دیگران، باید به آن‌ها اجازه خواندن هم برای دارایی Earth Engine و هم برای فایل‌های GCS بدهید.

۱. اعطای اجازه‌های سطل GCS

مشارکت‌کنندگان برای خواندن فایل‌ها از GCS به اجازه نیاز دارند.

اجازه‌های لازم:

storage.buckets.get (برای بازیابی فراداده و مکان دسته)
storage.objects.get (برای خواندن داده‌های پیکسل)

می‌توانید این اجازه‌ها را بااستفاده از نقش‌های استاندارد Cloud Storage زیر اعطا کنید:

Storage Bucket Viewer (storage.buckets.get را برای خواندن فراداده و مکان فضای ذخیره‌سازی ارائه می‌دهد)
Storage Object Viewer (storage.objects.get را برای خواندن داده‌های پیکسل ارائه می‌دهد)

مراحل پیکربندی در Google Cloud Console:

به مرورگر Cloud Storage بروید.
روی نام دسته‌بندی خود کلیک کنید.
برگه اجازه‌ها را انتخاب کنید.
روی اجازه دسترسی دادن کلیک کنید.
نشانی ایمیل همکارانتان (یا «گروه Google»، یا allUsers برای دسترسی عمومی) را اضافه کنید.
نقش‌های مشاهده‌گر دسته فضای ذخیره‌سازی و مشاهده‌گر شیء فضای ذخیره‌سازی را واگذار کنید.
روی ذخیره کلیک کنید.

۲. هم‌رسانی دارایی Earth Engine

خود دارایی را بااستفاده از «مدیر دارایی Earth Engine» یا CLI هم‌رسانی کنید. برای جزئیات، راهنمای مدیریت دارایی را ببینید.

مدیریت تولید اشیاء

وقتی COG را ثبت می‌کنید، Earth Engine نسل (نسخه) خاصی از شی GCS را ذخیره می‌کند. اگر فایل را در GCS به‌روز کنید، نسل آن تغییر می‌کند.

به‌طور پیش‌فرض، Earth Engine نمی‌تواند دارایی را بار کند و خطایی برمی‌گرداند: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
این کار برای جلوگیری از ناهماهنگ شدن فراداده (مانند طرح‌ریزی یا ردپا) با پیکسل‌های زیرین طراحی شده است.
روال مطلوب: اگر نیاز دارید داده‌های تصویر زیرین را به‌روز کنید، آن را به‌عنوان دارایی جدید ثبت کنید یا فرمان بارگذاری را با پرچم --force دوباره اجرا کنید، به‌جای اینکه فایل‌ها را در جای خود رونویسی کنید:
```
earthengine --project your-project-id upload external_image --force --manifest manifest.json
```

استفاده از دارایی‌های ثبت‌شده

پس‌از ثبت، به دارایی COG-backed در اسکریپت‌های Earth Engine دسترسی پیدا می‌کنید، درست مانند هر دارایی تصویر استاندارد واردشده:

JavaScript

var image = ee.Image('projects/your-project-id/assets/my_cog_asset');

Python

image = ee.Image('projects/your-project-id/assets/my_cog_asset')

ثبت دارایی‌های GeoTIFF بهینه‌سازی‌شده ابری (COG) با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.