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

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

רישום של נכסי GeoTIFF (COG) שעברו אופטימיזציה לענן

‫Earth Engine תומך בנכסים שמגובים על ידי קובצי GeoTIFF שעברו אופטימיזציה לשימוש בענן (COG) ושמאוחסנים ב-Google Cloud Storage‏ (GCS).

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

דרישות מוקדמות והגדרת Cloud Storage

לפני שרושמים COG, צריך להגדיר את המשאבים של Google Cloud Storage בצורה נכונה.

1. מיקום הקטגוריה (דרישה מחמירה)

כדי ש-Earth Engine יוכל לגשת לקטגוריה של Cloud Storage, הקטגוריה חייבת להיות באחד מהאזורים או מהאזורים המרובים הבאים של מרכזי הנתונים:

האזור us (מספר אזורים)
כל אזור כפול בארה"ב שכולל את us-central1
האזור us-central1

אם הקטגוריה נמצאת במרכז נתונים אזורי אחר (כמו us-east4 או europe-west1), מערכת Earth Engine תדחה את בקשות הרישום והקריאה.

2. סוג האחסון והחיוב

מומלץ להשתמש בסוג האחסון Standard. ב-Standard Storage אין כללים לגבי משך אחסון מינימלי, וכך נמנעים קנסות חיוב על מחיקה מוקדמת אם מעדכנים או מחליפים קבצים זמניים.
לולאות חישוב ב-Earth Engine לא כרוכות בחיובים נוספים על אחזור נתונים מ-Cloud Storage, אבל גישה לרמות אחסון שאינן Standard Storage מכלי חיצוני (כמו תוכנת GIS למחשב) כרוכה בעלויות גבוהות של אחזור.
כדי להשתמש ב-GCS, צריך להפעיל את החיוב בפרויקט בענן ב-Google Cloud. כדי להתחיל, אפשר לעיין במדריך למתחילים ב-Google Cloud Storage.

שלב 1: הכנת עלויות המכר

קובצי ה-TIFF צריכים להיות מותאמים לענן. הקובץ בפורמט TIFF חייב להיות:

Tiled, עם מידות אריחים של: 256x256,‏ 512x512,‏ 1024x1024 או 2048x2048. כדי לקבל את הביצועים הכי טובים, מומלץ להשתמש בתמונה בגודל 512x512 או יותר.
מסודר כך שכל ספריות קובצי התמונות (IFD) נמצאות בהתחלה.
הכללת סקירות כלליות של חזקות של 2.
משתמשים ב-BAND interleave.

אפשר להשתמש ב-GDAL כדי להמיר את התמונות.

שימוש במנהל התקן GDAL COG (מומלץ 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 באמצעות ספריית הלקוח של Earth Engine ב-Python, כלי שורת הפקודה earthengine או Earth Engine API בארכיטקטורת REST, אתם צריכים להגדיר מניפסט להעלאת תמונות שמציין את יעד הנכס, מזהי URI של Google Cloud Storage ומטא-נתונים אופציונליים של שכבות נתונים.

דוגמה: COG יחיד שמגבה את כל הפסים אם ה-COG מכיל את כל הפסים (למשל, RGB), בקובץ המניפסט נדרש רק tileset אחד:

{
  "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 או Earth Engine REST API. בוחרים את השיטה שהכי מתאימה לתהליך העבודה שלכם.

ספריית לקוח Python

בסקריפט של Python או ב-notebook של Jupyter, משתמשים בספריית הלקוח של 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. 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 upload:

# 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

‫API בארכיטקטורת REST‏ (Python)

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

רישום סינכרוני: רישום COG הוא קריאה מהירה וסינכרונית ל-API, ולא משימת חישוב אסינכרונית באצווה. לכן, הוא לא יוצר משימת רקע בכרטיסייה משימות בכלי לעריכת קוד או במנהל המשימות באצווה. הקריאה ל-API נחסמת עד שאימות המטא-נתונים והוספה לאינדקס מסתיימים, ואז הנכס זמין באופן מיידי בכרטיסייה נכסים בכלי לעריכת קוד או באמצעות ee.data.getAsset().

הגבלות על מניפסטים של נכסי COG

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

קטגוריה אחת: כל מזהי ה-URI במניפסט חייבים להיות באותה קטגוריה ב-GCS.
מזהה URI אחד לכל מקור: כל ImageSource חייב להכיל בדיוק מזהה URI אחד. אי אפשר ליצור פסיפס של כמה קבצים יחד למקור אחד של קבוצת משבצות. כדי ליצור פסיפס של כמה סצנות COG, צריך לרשום כל COG כנכס ולשלב אותם ב-ee.ImageCollection באמצעות .mosaic().
No mask_bands: אין תמיכה ב-mask_bands ברמה העליונה. צריך להשתמש ב-missingData במניפסט או לוודא שלקובץ ה-TIFF יש ערך nodata פנימי.
‫No data_type in tileset: אל תציינו את data_type בקטע tilesets, כי הוא מזוהה באופן אוטומטי.
אין dimensions במקור: אל תציינו dimensions ב-ImageSource.
לא subdataset_prefix / subdataset_suffix.
No min_tile_area_ratio או skip_metadata_read.

שלב 4: הגדרת הרשאות (חשוב לשיתוף)

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

1. מתן הרשאות לקטגוריות GCS

שותפי העריכה צריכים הרשאות לקרוא את הקבצים מ-GCS.

ההרשאות שנדרשות:

‫storage.buckets.get (כדי לאחזר את המטא-נתונים והמיקום של הקטגוריה)
‫storage.objects.get (כדי לקרוא את נתוני הפיקסל)

אפשר להעניק את ההרשאות האלה באמצעות התפקידים הרגילים הבאים ב-Cloud Storage:

‫Storage Bucket Viewer (נותן את ההרשאה storage.buckets.get לקריאת המטא-נתונים והמיקום של הקטגוריה)
צפייה באובייקטים באחסון (נותן את ההרשאה storage.objects.get לקריאת נתוני פיקסלים)

שלבים להגדרה במסוף Google Cloud:

נכנסים לדף Cloud Storage Browser.
לוחצים על שם הקטגוריה.
לוחצים על הכרטיסייה הרשאות.
לוחצים על הענקת גישה.
מוסיפים את כתובות האימייל של השותפים לעריכה (או קבוצה ב-Google, או allUsers לגישה ציבורית).
מקצים את התפקידים צפייה בקטגוריית אחסון וצפייה באובייקט אחסון.
לוחצים על שמירה.

2. שיתוף הנכס ב-Earth Engine

שיתוף הנכס עצמו באמצעות כלי ניהול הנכסים או ה-CLI של Earth Engine. פרטים נוספים זמינים במדריך לניהול נכסים.

ניהול של יצירת אובייקטים

כשרושמים 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')

רישום של נכסי GeoTIFF (COG) שעברו אופטימיזציה לענן קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.