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

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

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

المتطلّبات الأساسية وإعداد مساحة التخزين في السحابة الإلكترونية

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

1. موقع الحزمة (شرط صارم)

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

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

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

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

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

الخطوة 1: إعداد تكلفة السلع المُباعة

يجب تحسين ملفات TIFF لتتوافق مع السحابة الإلكترونية. يجب أن يكون ملف TIFF على النحو التالي:

• مربّعات، بأبعاد مربّعات: 256x256 أو 512x512 أو 1024x1024 أو 2048x2048. ننصح باستخدام حجم 512×512 أو أكبر للحصول على أفضل أداء.
• يتم ترتيبها بحيث تكون جميع أدلة ملفات الصور (IFD) في البداية.
• تضمين نظرات عامة حول "قوة الرقم 2"
• استخدِم تداخل BAND.

يمكنك استخدام GDAL لتحويل صورك.

استخدام برنامج تشغيل COG في GDAL (يُنصح باستخدام 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 العادي:

أولاً، أنشئ نظرات عامة داخلية على قوة 2 (باستخدام 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

الخطوة 2: إنشاء ملف البيان

سواء سجّلت ملف COG باستخدام مكتبة برامج Python في Earth Engine أو أداة سطر الأوامر earthengine أو واجهة برمجة التطبيقات REST API في Earth Engine، عليك تحديد بيان تحميل الصور الذي يحدّد وجهة مادة العرض ومعرّفات الموارد المنتظمة (URI) في Google Cloud Storage والبيانات الوصفية الاختيارية للنطاق.

مثال: ملف COG واحد يضم جميع النطاقات إذا كان ملف COG يحتوي على جميع النطاقات (مثل الأحمر والأخضر والأزرق)، لا يتطلّب البيان سوى مجموعة مربعات واحدة:

{
  "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 }
  ]
}

الخطوة 3: إرسال طلب التسجيل

يمكنك إرسال البيان إلى 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. 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 هو طلب بيانات سريع ومتزامن من واجهة برمجة التطبيقات وليس مهمة حوسبة مجمّعة غير متزامنة، لا يتم إنشاء مهمة في الخلفية ضمن علامة التبويب المهام في "أداة تعديل الرموز" أو مدير المهام المجمّعة. يتم حظر طلب البيانات من واجهة برمجة التطبيقات إلى أن يكتمل التحقّق من صحة البيانات الوصفية وفهرستها، وبعد ذلك تصبح مادة العرض متاحة على الفور في علامة التبويب مواد العرض في "محرّر الرموز" أو باستخدام ee.data.getAsset().

قيود البيان لمواد عرض COG

عند إنشاء بيان لمواد العرض المستندة إلى COG، يُرجى مراعاة هذه القيود الصارمة (التي تختلف عن بيانات التحميل العادية):

• حزمة واحدة: يجب أن تكون جميع معرّفات الموارد المنتظمة (URI) في البيان ضمن حزمة GCS نفسها.
• معرّف موارد منتظم (URI) واحد لكل مصدر: يجب أن يحتوي كل ImageSource على معرّف موارد منتظم (URI) واحد بالضبط. لا يمكنك دمج ملفات متعددة معًا في مصدر مجموعة مربعات واحد. لإنشاء صورة مجمّعة من مشاهد COG متعددة، سجِّل كل مشهد COG كمادة عرض واجمعه معًا في ee.ImageCollection باستخدام .mosaic().
• لا 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

الخطوة 4: ضبط الأذونات (مهمة للمشاركة)

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

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

يجب أن يكون لدى المتعاونين أذونات لقراءة الملفات من GCS.

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

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

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

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

خطوات الإعداد في Google Cloud Console:

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

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

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

إدارة عمليات إنشاء العناصر

عند تسجيل ملف 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 في نصوص 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')