إشعار: يجب إثبات أهلية جميع المشاريع غير التجارية المسجّلة لاستخدام Earth Engine قبل 15 أبريل 2025 من أجل الحفاظ على إمكانية الوصول إلى Earth Engine.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

مواد عرض Earth Engine المستندة إلى ملفات GeoTiff في السحابة الإلكترونية

التشغيل في Google Colab

عرض المصدر على GitHub

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

يُرجى العلم أنّه يمكن الاحتفاظ بنسخة احتياطية من مادة عرض واحدة باستخدام مجموعات COG متعددة (على سبيل المثال، يمكن أن يكون هناك مجموعة COG واحدة لكل نطاق). ومع ذلك، لا يمكن استخدام العديد من شرائح COG لفرقة واحدة.

(بدلاً من ذلك، يمكن لخدمة Earth Engine تحميل الصور مباشرةً من مجموعات COG في Google Cloud Storage (مزيد من المعلومات). ومع ذلك، فإنّ الصورة التي يتم تحميلها من خلال ee.Image.loadGeoTIFF وإضافتها إلى مجموعة صور تتطلّب قراءة ملف GeoTiff لإجراء عمليات الفلترة على المجموعة.)

لإنشاء مادة عرض مستندة إلى تكلفة الاكتساب، اتّبِع الخطوات التالية:

ضَع ملفات 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 بأي ترتيب من أي 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)

تفاصيل عن مواد العرض المستندة إلى تكلفة الاكتساب

الموقع الجغرافي

يجب أن يكون موقع حزمة Cloud Storage واحدًا مما يلي:

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

فئة التخزين

يجب أن تكون class storage لملف التخزين "مساحة تخزين عادية".

أذونات المشاركة

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

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

لكي يتمكّن المتعاونون من قراءة مواد العرض المستندة إلى COG، يجب أن يكون لديهم أولاً إذن بالقراءة في ملفات COG الأساسية في حزمة Google Cloud Storage. بدون هذين الإذنَين، لن تتمكّن أداة Earth Engine من استرداد البيانات لهم. إذا كانت data في Google Cloud Storage غير مرئية لمستخدم Earth Engine، سيعرض Earth Engine خطأً من النوع "تعذّر تحميل ملف GeoTIFF في gs://my-bucket/my-object#123456" (حيث يكون 123456 هو الجيل للعنصر).

على وجه التحديد، يجب أن يحصل المتعاونون على الأذونات التالية:

storage.buckets.get على الحزمة (لاسترداد البيانات الوصفية للحزمة وموقعها الجغرافي، السماح لخدمة Earth Engine بتحديد مصدر مادة العرض بشكل صحيح).
storage.objects.get في الحزمة (لقراءة بيانات مواد العرض الفعلية المستندة إلى COG)

يتم توفير هذه الأذونات من خلال الدورَين "قارئ حِزم التخزين القديمة" و"قارئ عناصر التخزين القديمة" على التوالي، بالإضافة إلى أدوار أخرى.

لإسناد هذه الأدوار إلى المتعاونين:

انتقِل إلى صفحة أذونات الحزمة: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
انقر على منح الإذن بالوصول.
أضِف جميع الجهات الرئيسية (مثل المستخدمين والمجموعات وحسابات الخدمة) التي يجب منحهم إذن الوصول للقراءة.
حدِّد الأدوار التالية:
- "Storage Legacy Bucket Reader" (يمنح storage.buckets.get و أذونات قراءة أخرى على مستوى الحزمة)
- ‫"قارئ عناصر التخزين القديمة" (يوفّر 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 عنوان URL هذا حرفيًا. في حال عدم تحديد عملية إنشاء، سَتخزِّن Earth Engine معرّف الموارد المنتظم (URI) هذا مع إنشاء ملف TIFF في وقت استدعاء ImportExternalImage.

وهذا يعني أنّه في حال تعديل أي ملف TIFF يتضمّن مادة عرض خارجية في GCS (وبالتالي تغيير جيله)، ستُظهر Earth Engine الخطأ "تعذّر تحميل ملف GeoTIFF في gs://my-bucket/my-object#123456" لأنّ الكائن المتوقع لم يعُد موجودًا (ما لم تفعِّل الحزمة إصدارات متعددة من الكائن). تم تصميم هذه السياسة لمزامنة البيانات الوصفية لمادة العرض مع البيانات الوصفية للعنصر.

الإعداد

في ما يتعلّق بطريقة ضبط COG، يجب أن يكون ملف TIFF:

مربّعات متداخلة، حيث تكون سمات المربّعات على النحو التالي:
- ‫256×256
- ‫512×512
- ‫1024x1024
- ‫2048×2048
تم ترتيبها بحيث تكون جميع عناوين IP للأجهزة في البداية.

للحصول على أفضل أداء:

استخدِم أبعاد مربّعات الصور التي تبلغ 512×512 أو أعلى.
استخدِم ميزتَي النظرة العامة.

استنادًا إلى حالات الاستخدام المقصودة، قد يؤثر خيار الإنشاء '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 driver إنشاء ملفات بدون القلق بشأن إنشاء النظرة العامة والحفاظ عليها.

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، ننصحك بالبدء بقراءة دليل JavaScript.

لإنشاء مادة عرض مستندة إلى COG باستخدام واجهة برمجة التطبيقات REST API، قدِّم طلب POST إلى نقطة نهاية ImportExternalImage Earth Engine. كما هو موضّح في ما يلي، يجب أن يكون هذا الطلب مفوَّضًا لإنشاء مادة عرض في مجلد المستخدم.

بدء جلسة مفوَّضة

لكي تتمكّن من إنشاء مادة عرض في 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. يتمّ تحديد المسار إلى مركز الجاذبية هنا، بالإضافة إلى خصائص مفيدة أخرى.

اطّلِع على هذا الدليل للاطّلاع على مزيد من التفاصيل حول كيفية ضبط ImageManifest. من الممكن تحديد Tileset واحد أو أكثر مع كل مجموعة نطاقات واحدة أو أكثر. بالنسبة إلى ImportExternalImage، يمكن استخدام ImageSource واحد كحد أقصى لكل Tileset.

اطّلِع على هذا المستند لمعرفة تفاصيل عن تصدير تكلفة الإجراء.

إرسال الطلب

أرسِل طلب 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))

مواد عرض Earth Engine المستندة إلى ملفات GeoTiff في السحابة الإلكترونية تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

نموذج بيان صور يتضمّن Tileset واحدًا

أكثر من Tileset