Earth Engine תומך בנכסים שמגובים על ידי קובצי GeoTIFF שעברו אופטימיזציה לענן (COG) ומאוחסנים ב-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. ב-Standard Storage אין כללים לגבי משך אחסון מינימלי, וכך נמנעים קנסות חיוב על מחיקה מוקדמת אם מעדכנים או מחליפים קבצים זמניים.
- לולאות החישוב של Earth Engine לא כרוכות בתשלומים נוספים על אחזור נתונים מ-Cloud Storage, אבל גישה לשכבות אחסון שהן לא Standard Storage מכלים חיצוניים (כמו תוכנת GIS למחשב) כרוכה בעמלות אחזור גבוהות.
- כדי להשתמש ב-Cloud Storage, צריך להפעיל את החיוב בפרויקט ב-Google Cloud. כדי להתחיל, קראו את המדריך למתחילים של Cloud Storage.
הכנת נתוני עלות המכר (COGS)
Earth Engine קורא קובצי COG ישירות מ-Cloud Storage, ומאחזר רק את הכותרת ואת המשבצות שנדרשות לחישוב, כך שפריסת הקובץ חשובה. קובץ ה-TIFF חייב להיות:
- משבצות, עם מידות משבצת ריבועיות בחזקת 2, מ-16x16 עד 2048x2048. כדי לקבל את הביצועים הכי טובים, מומלץ להשתמש בגודל 512x512.
- מסודרים כך שכל ספריות קובצי התמונות (IFD) נמצאות בהתחלה.
- לכלול סקירות כלליות של חזקות של 2, אם יש כאלה. לא חובה להוסיף סקירות כלליות, אבל מומלץ להוסיף אותן לתמונות שגדולות ממשבצת אחת.
- השתמשו ב-BAND או ב-PIXEL interleave (ראו קבצים עם פס בודד לעומת קבצים עם כמה פסים כדי להבין את היתרונות והחסרונות).
כדי להמיר תמונה, משתמשים במנהל ההתקן 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
בגרסאות GDAL שקודמות ל-3.11, צריך להשמיט את INTERLEAVE=BAND.
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 באמצעות ספריית הלקוח של Earth Engine Python, כלי שורת הפקודה earthengine או API בארכיטקטורת REST של Earth Engine, אתם צריכים להגדיר מניפסט להעלאת תמונות שמציין את יעד הנכס, מזהי URI של Cloud Storage ומטא-נתונים אופציונליים של שכבות נתונים. ה-API וכלי שורת הפקודה מתייחסים לנכסים שמגובים ב-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 אחד. אי אפשר ליצור פסיפס של כמה קבצים יחד למקור אחד של קבוצת משבצות. כדי ליצור פסיפס מכמה סצנות 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.
שליחת בקשת הרישום
אתם יכולים לשלוח את המניפסט ל-Earth Engine באמצעות ספריית הלקוח של Earth Engine ב-Python, כלי שורת הפקודה earthengine או ה-API בארכיטקטורת REST של Earth Engine. בוחרים את השיטה שהכי מתאימה לתהליך העבודה שלכם.
ספריית לקוח Python
בסקריפט Python או ב-Jupyter Notebook, משתמשים בספריית הלקוח של Earth Engine ב-Python (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
API בארכיטקטורת REST
בתהליכי עבודה אוטומטיים בלי ספריית הלקוח, שולחים בקשת POST מורשית ישירות לנקודת הקצה של ה-API בארכיטקטורת REST של 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:
- נכנסים לדף Cloud Storage Browser.
- לוחצים על שם הקטגוריה.
- לוחצים על הכרטיסייה הרשאות.
- לוחצים על הענקת גישה.
- מוסיפים את כתובות האימייל של השותפים לעריכה (או קבוצה ב-Google, או
allUsersלגישה ציבורית). - מקצים את התפקידים Storage Bucket Viewer ו-Storage Object Viewer.
- לוחצים על שמירה.
שיתוף הנכס ב-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 - API בארכיטקטורת REST: כוללים את
"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 API: צריך למחוק כל נכס בנפרד, ואוסף חייב להיות ריק לפני שאפשר למחוק אותו. 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 בדף השאלות הנפוצות.