Cloud Optimized GeoTIFF (COG) ऐसेट रजिस्टर करना

Earth Engine, Google Cloud Storage (GCS) में सेव किए गए, Cloud Optimized GeoTIFFs (COGs) की मदद से बनाए गए ऐसेट को सपोर्ट करता है.

COG की मदद से बनाए गए ऐसेट को रजिस्टर करने पर, Earth Engine, इमेज के स्पेस और मेटाडेटा फ़ील्ड को बनाते समय इंडेक्स करता है. इससे कलेक्शन में इस्तेमाल करने पर, इमेज की परफ़ॉर्मेंस बेहतर होती है . साथ ही, इसकी परफ़ॉर्मेंस, स्टैंडर्ड तरीके से इकट्ठा किए गए ऐसेट की परफ़ॉर्मेंस के बराबर होती है. ज़्यादा जानकारी के लिए, Cloud optimized 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 स्टोरेज में, कम से कम स्टोरेज की अवधि से जुड़े नियम लागू नहीं होते. इसलिए, अस्थायी फ़ाइलों को अपडेट या बदलने पर, उन्हें जल्द मिटाने पर लगने वाली बिलिंग पेनल्टी से बचा जा सकता है.
  • Earth Engine के कंप्यूटेशन लूप में, Cloud Storage से डेटा वापस पाने पर कोई सरचार्ज नहीं लगता. हालांकि, बाहरी टूल (जैसे, डेस्कटॉप जीआईएस सॉफ़्टवेयर) से, Standard स्टोरेज टियर के अलावा अन्य टियर को ऐक्सेस करने पर, डेटा वापस पाने के लिए ज़्यादा शुल्क लगता है.
  • GCS का इस्तेमाल करने के लिए, आपके Google Cloud प्रोजेक्ट पर बिलिंग की सुविधा चालू होनी चाहिए. शुरू करने के लिए, Google Cloud Storage का क्विकस्टार्ट देखें.

पहला चरण: अपने COG तैयार करना

आपकी TIFF फ़ाइलें, क्लाउड के लिए ऑप्टिमाइज़ की गई होनी चाहिए. TIFF इन शर्तों को पूरा करना चाहिए:

  • टाइल की गई हो. इसमें टाइल के डाइमेंशन: 256x256, 512x512, 1024x1024 या 2048x2048 होने चाहिए. बेहतर परफ़ॉर्मेंस के लिए, हमारा सुझाव है कि डाइमेंशन 512x512 या इससे ज़्यादा रखें.
  • इस तरह से व्यवस्थित की गई हो कि सभी इमेज फ़ाइल डायरेक्ट्री (आईएफ़डी) सबसे पहले दिखें.
  • इसमें, दो की पावर वाले ओवरव्यू शामिल हों.
  • BAND इंटरलीव का इस्तेमाल करें.

अपनी इमेज को बदलने के लिए, 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 ड्राइवर का इस्तेमाल करना:

सबसे पहले, दो की पावर वाले इंटरनल ओवरव्यू जनरेट करें. इसके लिए, 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

दूसरा चरण: मेनिफ़ेस्ट बनाना

Earth Engine Python क्लाइंट लाइब्रेरी, earthengine कमांड-लाइन टूल या Earth Engine REST API का इस्तेमाल करके, COG रजिस्टर किया जा सकता है. हालांकि, इसके लिए आपको इमेज अपलोड करने का मेनिफ़ेस्ट तय करना होगा. इसमें, ऐसेट की डेस्टिनेशन, Google Cloud Storage के यूआरआई, और बैंड का वैकल्पिक मेटाडेटा शामिल होना चाहिए.

उदाहरण: सभी बैंड को बैक अप करने वाला एक COG अगर आपके COG में सभी बैंड (जैसे, आरजीबी) शामिल हैं, तो मेनिफ़ेस्ट के लिए सिर्फ़ एक टाइलसेट की ज़रूरत होती है:

{
  "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 }
  ]
}

तीसरा चरण: रजिस्ट्रेशन का अनुरोध सबमिट करना

Earth Engine Python क्लाइंट लाइब्रेरी, earthengine कमांड-लाइन टूल या Earth Engine REST API का इस्तेमाल करके, अपना मेनिफ़ेस्ट Earth Engine को सबमिट किया जा सकता है. वह तरीका चुनें जो आपके वर्कफ़्लो के हिसाब से सबसे सही हो.

Python क्लाइंट लाइब्रेरी

Python स्क्रिप्ट या 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 अपलोड कमांड चलाएं:

# 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

REST API (Python)

क्लाइंट लाइब्रेरी के बिना, ऑटोमेटेड वर्कफ़्लो के लिए, Earth Engine REST API के एंडपॉइंट projects.image.importExternal पर सीधे तौर पर अनुमति वाला POST अनुरोध भेजें. यहां 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 ऐसेट के लिए मेनिफ़ेस्ट से जुड़ी पाबंदियां

COG की मदद से बनाए गए ऐसेट के लिए मेनिफ़ेस्ट बनाते समय, इन सख्त पाबंदियों का ध्यान रखें. ये पाबंदियां, स्टैंडर्ड तरीके से इकट्ठा किए गए ऐसेट के मेनिफ़ेस्ट से अलग होती हैं:

  • एक बकेट: मेनिफ़ेस्ट में मौजूद सभी यूआरआई, एक ही GCS बकेट में होने चाहिए.
  • हर सोर्स के लिए एक यूआरआई: हर ImageSource में सिर्फ़ एक यूआरआई होना चाहिए. एक से ज़्यादा फ़ाइलों को एक साथ जोड़कर, एक टाइलसेट सोर्स नहीं बनाया जा सकता. एक से ज़्यादा COG सीन को एक साथ जोड़ने के लिए, हर COG को एक ऐसेट के तौर पर रजिस्टर करें और .mosaic() का इस्तेमाल करके, उन्हें ee.ImageCollection में मिलाएं.
  • mask_bands नहीं: टॉप-लेवल mask_bands काम नहीं करता. मेनिफ़ेस्ट में missingData का इस्तेमाल करें या पक्का करें कि आपके TIFF में, nodata की इंटरनल वैल्यू हो.
  • टाइलसेट में data_type नहीं: tilesets सेक्शन में, data_type तय न करें. इसका पता अपने-आप लग जाता है.
  • सोर्स में dimensions नहीं: ImageSource में, dimensions तय न करें.
  • subdataset_prefix / subdataset_suffix नहीं.
  • min_tile_area_ratio या skip_metadata_read नहीं.

चौथा चरण: अनुमतियां कॉन्फ़िगर करना (शेयर करने के लिए ज़रूरी है)

Earth Engine के स्टैंडर्ड ऐसेट के उलट, COG का पिक्सल डेटा GCS में ही रहता है. COG की मदद से बनाए गए ऐसेट को दूसरों के साथ शेयर करते समय, आपको उन्हें Earth Engine ऐसेट और GCS फ़ाइलों, दोनों को पढ़ने का ऐक्सेस देना होगा.

1. GCS बकेट की अनुमतियां देना

साथ मिलकर काम करने वाले लोगों को, GCS से फ़ाइलें पढ़ने की अनुमतियां चाहिए.

ज़रूरी अनुमतियां:

  • storage.buckets.get (बकेट का मेटाडेटा और जगह की जानकारी वापस पाने के लिए)
  • storage.objects.get (पिक्सल डेटा पढ़ने के लिए)

Cloud Storage की इन स्टैंडर्ड भूमिकाओं का इस्तेमाल करके, ये अनुमतियां दी जा सकती हैं:

  • स्टोरेज बकेट व्यूअर (बकेट का मेटाडेटा और जगह की जानकारी पढ़ने के लिए, storage.buckets.get की अनुमति देता है)
  • स्टोरेज ऑब्जेक्ट व्यूअर (पिक्सल डेटा पढ़ने के लिए, storage.objects.get की अनुमति देता है)

Google Cloud Console में कॉन्फ़िगर करने के लिए, यह तरीका अपनाएं:

  1. Cloud Storage ब्राउज़र पर जाएं .
  2. अपनी बकेट के नाम पर क्लिक करें.
  3. अनुमतियां टैब चुनें.
  4. GRANT ACCESS पर क्लिक करें.
  5. साथ मिलकर काम करने वाले लोगों के ईमेल पते जोड़ें. इसके अलावा, सार्वजनिक ऐक्सेस के लिए, Google Group या allUsers जोड़ें.
  6. स्टोरेज बकेट व्यूअर और स्टोरेज ऑब्जेक्ट व्यूअर की भूमिकाएं असाइन करें.
  7. सेव करें पर क्लिक करें.

2. Earth Engine ऐसेट शेयर करना

Earth Engine Asset Manager या सीएलआई का इस्तेमाल करके, ऐसेट को शेयर करें. ज़्यादा जानकारी के लिए, ऐसेट मैनेजमेंट गाइड देखें.

ऑब्जेक्ट जनरेशन मैनेज करना

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')