تسجيل مواد عرض GeoTIFF المحسّنة للسحابة الإلكترونية (COG)

يتيح Earth Engine استخدام مواد العرض المستندة إلى ملفات GeoTIFF المحسّنة للسحابة الإلكترونية (COGs) والمخزَّنة في Google Cloud Storage (GCS).

عند تسجيل مادة عرض مستندة إلى COG، يفهرس محرّك Earth Engine الحقول المكانية وحقول البيانات الوصفية للصورة في وقت الإنشاء. يؤدي ذلك إلى تحسين أداء الصورة عند استخدامها في المجموعات، مع أداء مماثل لملفات الوسائط العادية التي يتم نقلها (راجِع نظرة عامة على Cloud Optimized GeoTIFF (COG)‎).

يتناول هذا الدليل كيفية إعداد ملفاتك وكتابة البيان وإرسال طلب التسجيل وضبط الأذونات وتعديل مواد العرض المسجّلة أو حذفها.

قبل البدء

قبل تسجيل ملف COG، عليك إعداد موارد Cloud Storage بشكل صحيح.

الموقع الجغرافي للحزمة

لكي يتمكّن Earth Engine من الوصول إلى حزمة Cloud Storage، يجب أن تكون الحزمة موجودة في إحدى مناطق مراكز البيانات أو المناطق المتعدّدة التالية:

  • المنطقة المتعددة us
  • أي منطقة مزدوجة في الولايات المتحدة تتضمّن us-central1
  • منطقة us-central1

إذا تم وضع الحزمة في أي مركز بيانات إقليمي آخر (مثل us-east4 أو europe-west1)، سيرفض محرّك Earth Engine طلبات التسجيل والقراءة. يُرجى الاطّلاع على المواقع الجغرافية المتوافقة لحِزم Cloud Storage.

فئة التخزين والفوترة

  • ننصحك باستخدام فئة التخزين العادية. لا تتضمّن فئة Standard Storage أي قواعد للحد الأدنى لمدة التخزين، ما يمنع فرض غرامات على الفوترة بسبب الحذف المبكر في حال تعديل الملفات المؤقتة أو استبدالها.
  • على الرغم من أنّ عمليات تكرار الحوسبة في Earth Engine لا تفرض رسومًا إضافية على استرداد بيانات Cloud Storage، فإنّ الوصول إلى مستويات التخزين غير العادية من أدوات خارجية (مثل برامج نظم المعلومات الجغرافية على أجهزة الكمبيوتر المكتبي) يفرض رسومًا باهظة على استرداد البيانات.
  • يجب تفعيل الفوترة في مشروعك على Google Cloud لاستخدام Cloud Storage. يُرجى الاطّلاع على دليل البدء السريع في Cloud Storage للبدء.

إعداد تكلفة السلع المُباعة

يقرأ Earth Engine ملفات COG مباشرةً من Cloud Storage، ويجلب فقط العنوان والأقسام التي يحتاجها الحساب، لذا فإنّ تنسيق الملف مهم. يجب أن يكون ملف TIFF:

  • مربّعات، بأبعاد مربّعة من مضاعفات الرقم 2، من 16×16 إلى 2048×2048. ننصحك باستخدام حجم 512×512 للحصول على أفضل أداء.
  • يجب ترتيبها بحيث تكون جميع أدلة ملفات الصور (IFD) في البداية.
  • تضمين النبذات التي تستخدم قوى العدد 2، إن وُجدت لا تكون النظرات العامة مطلوبة، ولكن يُنصح بها للصور الأكبر من مربّع واحد.
  • استخدِم التداخل BAND أو PIXEL (راجِع الملفات ذات النطاق الواحد مقابل الملفات المتعددة النطاقات للمفاضلة بينهما).

لتحويل صورة، استخدِم برنامج تشغيل COG من GDAL الذي ينتج التنسيق المطلوب (التقسيم إلى مربعات والنظرات العامة وموضع العنوان) في خطوة واحدة. أضِف OVERVIEW_RESAMPLING=NEAREST للبيانات الفئوية، والقيمة التلقائية هي CUBIC. للاطّلاع على الاقتراحات المتعلّقة بالضغط والنظرة العامة والتنسيق، يُرجى مراجعة أفضل الممارسات لإعداد ملفات COG الخارجية.

GDAL 3.11+ CLI

gdal raster convert in.tif out.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co OVERVIEWS=IGNORE_EXISTING \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

Classic CLI

يجب حذف INTERLEAVE=BAND في إصدارات GDAL الأقدم من 3.11.

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

إنشاء ملف البيان

سواء سجّلت ملف COG باستخدام مكتبة برامج Python في Earth Engine أو أداة سطر الأوامر earthengine أو واجهة برمجة التطبيقات REST API في Earth Engine، عليك تحديد بيان تحميل الصور الذي يحدّد وجهة مادة العرض وعناوين URI في Cloud Storage والبيانات الوصفية الاختيارية للنطاق. تشير واجهة برمجة التطبيقات وأداة سطر الأوامر إلى مواد العرض المستندة إلى COG على أنّها صور خارجية (ee.data.startExternalImageIngestion() وearthengine upload external_image وprojects.image.importExternal).

مثال: ملف 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 }
  ]
}

قيود البيان

تتضمّن ملفات البيان لمواد العرض المستندة إلى COG قيودًا لا تنطبق على ملفات بيان التحميل العادية:

  • حزمة واحدة: يجب أن تكون جميع معرّفات الموارد المنتظمة (URI) في البيان ضمن حزمة Cloud Storage نفسها.
  • معرّف موارد منتظم (URI) واحد لكل مصدر: يجب أن يحتوي كل ImageSource على معرّف موارد منتظم (URI) واحد بالضبط. لا يمكنك دمج ملفات متعددة معًا في مصدر مجموعة مربعات واحد. To mosaic multiple COG scenes, register each COG as an asset and combine them into an ee.ImageCollection using .mosaic().
  • No mask_bands: حقل mask_bands ذو المستوى الأعلى غير متاح. استخدِم missingData في ملف البيان أو تأكَّد من أنّ ملف TIFF يتضمّن قيمة nodata داخلية.
  • عدم تضمين data_type في مجموعة المربّعات: لا تحدِّد data_type في قسم tilesets، لأنّه يتم رصده تلقائيًا.
  • عدم توفّر السمة dimensions في المصدر: لا تحدِّد السمة dimensions في ImageSource.
  • No subdataset_prefix / subdataset_suffix.
  • لا يُسمح باستخدام min_tile_area_ratio أو skip_metadata_read.

إرسال طلب التسجيل

يمكنك إرسال البيان إلى Earth Engine باستخدام مكتبة برامج Python في Earth Engine أو أداة سطر الأوامر earthengine أو واجهة برمجة تطبيقات REST في Earth Engine. اختَر الطريقة التي تناسب سير عملك على أفضل نحو.

مكتبة برامج Python

في نص برمجي بلغة Python أو دفتر ملاحظات Jupyter، استخدِم مكتبة برامج Python في Earth Engine (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. Register the asset
result = ee.data.startExternalImageIngestion(manifest)
print(f"Asset registered: {result['name']}")

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

في الوحدة الطرفية، احفظ ملف البيان في ملف باسم manifest.json وشغِّل أمر التحميل earthengine:

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Register the asset
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

REST API

بالنسبة إلى مهام سير العمل المبرمَجة بدون مكتبة العميل، أرسِل طلبًا معتمَدًا POST مباشرةً إلى نقطة نهاية REST API في Earth Engine 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 لا تنسخ بيانات وحدات البكسل، تكتمل هذه العملية عادةً في غضون ثوانٍ.

ضبط الأذونات

على عكس مواد عرض Earth Engine العادية، تبقى بيانات وحدات البكسل في COG في Cloud Storage. عند مشاركة مادة عرض مستندة إلى COG مع الآخرين، يجب منحهم إذن القراءة لكل من مادة عرض Earth Engine وملفات Cloud Storage.

منح أذونات حزمة Cloud Storage

يحتاج المتعاونون إلى أذونات لقراءة الملفات من Cloud Storage.

الأذونات المطلوبة:

  • storage.buckets.get (لاسترداد البيانات الوصفية والموقع الجغرافي للحزمة)
  • storage.objects.get (لقراءة بيانات البكسل)

يمكنك منح هذه الأذونات باستخدام أدوار Cloud Storage العادية التالية:

  • Storage Bucket Viewer (يوفّر الإذن storage.buckets.get لقراءة البيانات الوصفية والموقع الجغرافي للحزمة)
  • عارض عنصر التخزين (يوفّر storage.objects.get لقراءة بيانات وحدات البكسل)

خطوات الضبط في Google Cloud Console:

  1. انتقِل إلى متصفّح Cloud Storage.
  2. انقر على اسم الحزمة.
  3. انقر على علامة التبويب الأذونات.
  4. انقر على منح إذن الوصول.
  5. أضِف عناوين البريد الإلكتروني للمتعاونين (أو "مجموعة Google" أو allUsers للوصول العلني).
  6. امنح الدورَين عارض حزمة التخزين وعارض عنصر التخزين.
  7. انقر على حفظ.

مشاركة مادة عرض Earth Engine

مشاركة مادة العرض نفسها باستخدام "مدير مواد العرض" في Earth Engine أو واجهة سطر الأوامر (CLI) يُرجى الاطّلاع على دليل إدارة مواد العرض لمزيد من التفاصيل.

تعديل مواد العرض المستندة إلى COG واستبدالها وحذفها

مادة العرض المستندة إلى COG هي مؤشر إلى إصدار معيّن من ملف في Cloud Storage، بالإضافة إلى البيانات الوصفية (البصمة والإسقاط والنطاقات وتخطيط النظرة العامة) التي فهرسها محرّك Earth Engine عند تسجيلها. يثبّت Earth Engine إصدار الملف كي لا تختلف هذه البيانات الوصفية عن وحدات البكسل، وهذا ما يجعل تعديل مواد العرض المستندة إلى COG مختلفًا عن تعديل مواد العرض العادية.

أجيال العناصر

عند تسجيل ملف COG، يسجّل محرّك Earth Engine جيل عنصر Cloud Storage (رقم إصداره) إلى جانب معرّف الموارد المنتظم (URI). يمكنك الاطّلاع على الجيل المثبَّت في البيانات الوصفية لمادة العرض، ويظهر كلاحقة #<generation> في عنوان URI:

Python

asset = ee.data.getAsset('projects/your-project-id/assets/my_cog_asset')
print(asset['tilesets'][0]['sources'][0]['uris'])
# ['gs://google-sample-bucket/my_optimized_image.tif#1750427474244728']

يمكنك أيضًا تثبيت إصدار معيّن بنفسك من خلال تضمين اللاحقة #<generation> في معرّف الموارد المنتظم (URI) للبيان عند تسجيل مادة العرض (أو إعادة تسجيلها). بدون هذه السياسة، يقرأ Earth Engine العنصر الحالي ويثبّت أي إصدار يعثر عليه. يُعدّ التثبيت الصريح مفيدًا للعودة إلى إصدار سابق احتفظ به حزمة مع إصدار الكائن.

إذا استبدلت الملف في Cloud Storage، سيحصل على جيل جديد، وإذا حذفته، سيختفي الجيل المثبَّت. في كلتا الحالتين، يتعذّر قراءة وحدات بكسل مادة العرض، ما لم يتم الاحتفاظ بالجيل القديم من خلال تحديد إصدارات العناصر في الحزمة، وفي هذه الحالة تواصل منصة Earth Engine قراءة وحدات البكسل القديمة. تستمر عمليات البيانات الوصفية التي تستخدم السجلّ المفهرَس (مثل ee.data.getAsset() وbandNames() وفلترة المجموعات) في العمل في كلتا الحالتين.

تعديل مادة عرض بعد تغيير ملفها

لتوجيه مادة عرض حالية إلى نسخة جديدة من ملفها، أعِد تسجيلها باستخدام اسم مادة العرض نفسه مع تفعيل خيار الاستبدال. يعيد محرّك Earth Engine قراءة عنوان GeoTIFF، ويعيد فهرسة البيانات الوصفية، ويثبّت الجيل الجديد، في طلب متزامن واحد. يتم الاحتفاظ بأذونات مادة العرض الحالية، ولكن يتم الحصول على خصائصها ونطاقها الزمني وأسماء النطاقات من البيان الجديد، لذا يجب تضمين أي شيء سبق لك ضبطه باستخدام ee.data.updateAsset().

  • ‫Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • سطر الأوامر: earthengine upload external_image --force --manifest manifest.json
  • ‫REST API: يجب تضمين "overwrite": true كحقل عالي المستوى إلى جانب "imageManifest" في projects.image.importExternal نص الطلب.

ليس عليك حذف مادة العرض أولاً، لأنّ حذفها يؤدي إلى نتائج عكسية: تفقد مادة العرض المستقلة أذوناتها، وتختفي الصورة في المجموعة لفترة وجيزة من المجموعة. يُرجى العِلم أنّ ee.data.updateAsset() (projects.assets.patch) يمكنه فقط تغيير السمات والنطاق الزمني وأسماء النطاقات، ولا يمكنه تغيير الملف الذي تشير إليه مادة العرض.

مراحل نشاط مستقلة

تتم إدارة مواد عرض Earth Engine وعناصر Cloud Storage بشكل منفصل:

  • يؤدي حذف مادة عرض Earth Engine (earthengine rm أو ee.data.deleteAsset()) إلى إزالة سجلّ مادة العرض فقط. لن يتم إجراء أي تغييرات على ملفاتك في Cloud Storage.
  • لا يؤدي حذف الملف في Cloud Storage إلى إزالة مادة العرض، بل تظلّ تظهر في القوائم وفي مجموعتها (راجِع إنشاء العناصر).

العمل مع مجموعات كبيرة

لا تتوفّر ميزة الحذف المجمّع أو المتكرّر في واجهة برمجة تطبيقات Earth Engine، إذ يجب حذف كل مادة عرض على حدة، ويجب أن تكون المجموعة فارغة قبل حذفها. يتولّى earthengine rm -r هذه المهمة نيابةً عنك، ولكنه يحذف الصور واحدة تلو الأخرى، لذا قد تستغرق إزالة مجموعة تحتوي على عشرات الآلاف من الصور ساعات.

  • لاستبدال صور مجموعة، يمكنك استبدالها بدلاً من حذفها. أعِد تسجيل كل صورة حسب الاسم مع تفعيل خيار الاستبدال (انظر أعلاه). يتطلب هذا الإجراء طلبًا واحدًا لكل صورة بدلاً من طلبَين، ويحافظ على ملء المجموعة طوال الوقت، ويتجنّب حذف المجموعة نفسها وإعادة إنشائها، حيث يتم الاحتفاظ بأذوناتها. احذف فقط الصور التي ليست في المجموعة الجديدة.
  • لحذف العديد من مواد العرض، يمكنك تنفيذ ذلك بالتوازي من خلال نص برمجي. أدرِج مواد العرض التي تتضمّن ee.data.listAssets() (باستخدام طريقة العرض BASIC التي تعرض الأسماء والأنواع فقط بدلاً من البيانات الوصفية الكاملة لكل صورة) واحذفها من مجموعة سلاسل محادثات صغيرة. تتشارك طلبات مواد العرض حدود المعدّل على مستوى المشروع، لذا يجب إبقاء التزامن متواضعًا (حوالي 10 عمال) والسماح لعمليات إعادة المحاولة المضمّنة في مكتبة العميل بالتعامل مع أي استجابات 429 Too Many Requests:

    Python

    import concurrent.futures
    import ee
    
    ee.Initialize(project='your-project-id')
    collection = 'projects/your-project-id/assets/my_collection'
    
    listing = ee.data.listAssets({'parent': collection, 'view': 'BASIC'})
    asset_ids = [a['name'] for a in listing['assets']]
    
    def delete(asset_id):
      try:
        ee.data.deleteAsset(asset_id)
      except ee.EEException as e:
        return f'{asset_id}: {e}'
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
      failures = [f for f in executor.map(delete, asset_ids) if f]
    
    if failures:
      print('\n'.join(failures))
    else:
      ee.data.deleteAsset(collection)
    

    لا يتم حذف المجموعة إلا إذا تم حذف كل صورة، لذا فإن الفشل الجزئي يتركها في مكانها لإعادة تشغيلها.

    ينطبق النمط نفسه على تسجيل صور متعددة: استبدِل ee.data.deleteAsset(asset_id) في المساعد بـ ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) وحدِّد موقعه في قائمة ملفات البيان. يؤدي تمرير allow_overwrite=True حتى في التشغيل الأول إلى جعل الدفعة آمنة لإعادة التشغيل بعد فشل جزئي، لأنّ أي مادة عرض تم إنشاؤها مسبقًا يتم استبدالها بدلاً من التسبب في حدوث خطأ.

استخدام مواد العرض المسجَّلة

بعد التسجيل، يتم الوصول إلى مادة عرض مستندة إلى COG في نصوص 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')

للحصول على إجابات عن الأسئلة الشائعة حول الأذونات وتعديل الملفات وإدارة المجموعات الكبيرة، يُرجى الاطّلاع على قسم COG في الأسئلة الشائعة.