הודעה: כל הפרויקטים הלא מסחריים שנרשמו לשימוש ב-Earth Engine לפני 15 באפריל 2025 חייבים לעבור אימות של הזכאות לשימוש לא מסחרי כדי לשמור על הגישה ל-Earth Engine.

דף זה תורגם על ידי Cloud Translation API.

נכסי Earth Engine שמבוססים על קובצי GeoTiff ב-Cloud

הפעלה ב-Google Colab

הצגת המקור ב-GitHub

ב-Earth Engine יש תמיכה בנכסים שמגובים ב-Cloud Optimized GeoTIFFs‏ (COGs). יתרון של נכסים שמגובים ב-COG הוא ששדות המטא-נתונים והשדות המרחביים של התמונה יתווספו לאינדקס בזמן יצירת הנכס, וכך הביצועים של התמונה יהיו טובים יותר בקולקציות. הביצועים של נכסים שמגובים ב-COG דומים לאלה של נכסים שסוננו בתרחישי שימוש רגילים.

שימו לב שנכס אחד יכול להיות מגובה על ידי כמה COG (לדוגמה, יכול להיות COG אחד לכל תחנה). עם זאת, אין תמיכה בשימוש בכמה משבצות COG עבור תדר אחד.

(לחלופין, אפשר לטעון תמונות ישירות מ-COGs ב-Google Cloud Storage ב-Earth Engine (מידע נוסף). עם זאת, תמונה שנטענת דרך ee.Image.loadGeoTIFF ומתווספת לאוסף תמונות תחייב קריאה של קובץ GeoTiff לצורך פעולות סינון באוסף).

כדי ליצור נכס שמבוסס על עלות ייצור,

מעבירים את קובצי ה-COG לקטגוריה (bucket) ב-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 מ'.
סדר הפס של הנכס שנוצר הוא תערובת של COGs הקלט (למשל, פס הפלט 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

סוג אחסון (storage class)

סוג האחסון של הקטגוריה חייב להיות 'Standard storage'.

הרשאות לשיתוף

הרשאות ה-ACL של נכסי Earth Engine שמגובים ב-COG והנתונים שעליהם הם מבוססים מנוהלים בנפרד. כשמשתפים נכסים שמבוססים על קובצי COG עם שותפי עריכה לצורך קריאה, הבעלים אחראים לוודא שמוענקת הרשאת קריאה גם לנכס ב-Earth Engine וגם לקובצי ה-COG הבסיסיים.

1. הענקת הרשאות קריאה לקטגוריה ב-Google Cloud Storage

כדי ששותפי עריכה יוכלו לקרוא נכסים שמגובים ב-COG, קודם צריכה להיות להם הרשאת קריאה לקובצי ה-COG הבסיסיים בקטגוריה של Google Cloud Storage. בלי ההרשאות האלה, מערכת Earth Engine לא תוכל לאחזר את הנתונים שלהם. אם הנתונים ב-Google Cloud Storage לא גלויים למשתמש ב-Earth Engine, מערכת Earth Engine תחזיר הודעת שגיאה בפורמט 'Failed to load the GeoTIFF at 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.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 יאחסן את ה-URI הזה כפי שהוא. אם לא מציינים דור, ה-URI הזה יישמר ב-Earth Engine עם הדור של קובץ ה-TIFF בזמן הקריאה של ImportExternalImage.

המשמעות היא שאם קובץ TIFF שמכיל נכס חיצוני ב-GCS מתעדכן (וכך משתנה הדור שלו), מערכת Earth Engine תחזיר את השגיאה 'Failed to load the GeoTIFF at gs://my-bucket/my-object#123456' כי האובייקט הצפוי כבר לא קיים (אלא אם האפשרות להשתמש בכמה גרסאות של אובייקטים מופעלת בקטגוריה). המדיניות הזו נועדה לשמור על סנכרון בין המטא-נתונים של הנכס לבין המטא-נתונים של האובייקט.

תצורה

לגבי האופן שבו צריך להגדיר קובץ COG, קובץ ה-TIFF חייב:

בחלוקה לריבועים, כאשר מידות הריבועים הן:
- 256x256
- 512x512
- 1024x1024
- 2048x2048
מסודרים כך שכל ה-IFDs נמצאים בהתחלה.

כדי שהביצועים יהיו הכי טובים שאפשר:

מומלץ להשתמש בכרטיסי מידע בגודל 512x512 פיקסלים או יותר.
הוספת 2 סקירות כלליות.

בהתאם לתרחישי השימוש שלכם, אפשרות היצירה INTERLEAVE עשויה להשפיע על הביצועים. מומלץ להשתמש בשילוב BAND בכל הנסיבות.

בדף הזה מפורט מידע נוסף על הגדרה אופטימלית.

הפקודה הבאה של gdal_translate תמיר רסטר לקובץ GeoTIFF מותאם ל-Cloud, עם שכבות מרובות ורזולוציה משתנה (interleaved) ודחיסה של 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 כדי ליצור קבצים בלי לדאוג לגבי יצירת תצוגות מפורטות ושמירתן.

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 ב-Cloud באמצעות ה-API ל-REST

הערה: ממשק ה-API ל-REST מכיל תכונות חדשות ומתקדמות שיכול להיות שלא מתאימות לכל המשתמשים. אם זו הפעם הראשונה שאתם משתמשים ב-Earth Engine, מומלץ להתחיל עם המדריך ל-JavaScript.

כדי ליצור נכס שמבוסס על COG באמצעות ה-API ל-REST, שולחים בקשה מסוג 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. כאן מצוין הנתיב ל-COG, יחד עם מאפיינים שימושיים אחרים.

במדריך הזה מוסבר איך מגדירים ImageManifest. אפשר להגדיר Tileset אחד או יותר, כאשר כל אחד מהם תומך בלהקה אחת או יותר. בשביל ImportExternalImage, אפשר להשתמש ב-ImageSource אחד לכל היותר לכל Tileset.

במאמר הזה מוסבר איך מייצאים COGs.

שליחת הבקשה

שולחים את בקשת ה-POST לנקודת הקצה projects.images.importExternal של Earth Engine.

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 ב-Cloud קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

דוגמה למניפסט של תמונה עם Tileset אחד

יותר מ-Tileset