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

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

הפעלה ב-Google Colab

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

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

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

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

כדי ליצור נכס מגובה COG,

ממקמים את קובצי ה-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 זמין. בדוגמה הבאה:

הקובץ 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)

פרטים על נכסים מגובים ב-COG

מיקום

המיקום של קטגוריית Cloud Storage צריך להיות אחד מהבאים:

ארה"ב במספר אזורים
כל אזור כפול בארה"ב שכולל את US-CENTRAL1
האזור US-CENTRAL1

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

סוג האחסון (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 ב-bucket (כדי לקרוא את נתוני הנכסים שגובו על ידי COG).

ההרשאות האלה ניתנות על ידי התפקידים Storage Legacy Bucket Reader ו-Storage Legacy Object Reader, בין היתר.

כדי להקצות את התפקידים האלה למשתפי פעולה:

עוברים לדף ההרשאות של הקטגוריה: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
לוחצים על מתן גישה.
מוסיפים את כל החשבונות הראשיים (למשל, משתמשים, קבוצות, חשבונות שירות) שצריכה להיות להם הרשאת קריאה.
מקצים את התפקידים הבאים:
- ‫Storage Legacy Bucket Reader (מספק storage.buckets.get והרשאות קריאה אחרות ברמת הקטגוריה).
- ‫Storage Legacy Object Reader (מספק 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 הזה בדיוק כמו שהוא. אם לא מציינים דור, Earth Engine ישמור את ה-URI עם הדור של קובץ ה-TIFF בזמן הקריאה ל-ImportExternalImage.

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

הגדרות אישיות

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

בפורמט tiled, שבו המידות של ה-tile הן:
- 256x256
- ‫512x512
- ‫1024x1024
- ‫2048x2048
הסדר הוא כזה שכל ה-IFD נמצאים בהתחלה.

כדי לקבל את הביצועים הטובים ביותר:

השתמשו במידות של כרטיסי מידע של 512x512 או יותר.
הכללת סקירות כלליות של חזקות של 2.

בהתאם לתרחישי השימוש המיועדים, אפשרות היצירה INTERLEAVE עשויה להשפיע על הביצועים. מומלץ להשתמש ב-BAND 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

אפשר להקטין עוד יותר את גודל קובץ הפלט על ידי הגדרת predictor (-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 \

יצירת נכסים מסוג Cloud GeoTiff-Backed Assets באמצעות 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.

פרטים על ייצוא של COG מופיעים במסמך הזה.

שליחת הבקשה

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

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

יותר מ-Tileset