ক্লাউড অপ্টিমাইজ করা GeoTIFF (COG) অ্যাসেট রেজিস্টার করা

Earth Engine-এ Cloud Optimized GeoTIFFs (COGs) দ্বারা ব্যাক-আপ নেওয়া অ্যাসেট কাজ করে যা Google Cloud Storage (GCS)-এ স্টোর করা থাকে।

আপনি COG-ব্যাকড অ্যাসেট রেজিস্টার করলে, Earth Engine তৈরির সময় ছবির স্পেশিয়াল ও মেটাডেটা ফিল্ড ইন্ডেক্স করে। এর ফলে, সংগ্রহে ব্যবহার করা হলে ছবিটি ভালো পারফর্ম করে। এটি সাধারণ ইনজেস্ট করা অ্যাসেটের মতো পারফর্ম করে (ক্লাউড অপ্টিমাইজ করা GeoTIFF (COG) ওভারভিউ দেখুন)।

পূর্বশর্ত ও ক্লাউড স্টোরেজ সেট-আপ

COG রেজিস্টার করার আগে, আপনাকে অবশ্যই Google Cloud Storage রিসোর্স সঠিকভাবে সেট-আপ করতে হবে।

১. বাকেট লোকেশন (কঠোরভাবে প্রয়োজনীয়)

Earth Engine যাতে আপনার Cloud Storage বাকেট অ্যাক্সেস করতে পারে, তার জন্য বাকেটটি অবশ্যই নিম্নলিখিত ডেটা সেন্টার অঞ্চল বা মাল্টি-অঞ্চলের মধ্যে কোনও একটিতে অবস্থিত হতে হবে:

  • us মাল্টি-রিজিয়ন
  • us-central1 অন্তর্ভুক্ত আছে এমন যেকোনও মার্কিন যুক্তরাষ্ট্রের ডুয়াল-রিজিয়ন
  • us-central1 অঞ্চল

আপনার বাকেট অন্য কোনও আঞ্চলিক ডেটা সেন্টারে (যেমন us-east4 বা europe-west1) থাকলে, Earth Engine রেজিস্ট্রেশন ও পড়ার অনুরোধ বাতিল করে দেবে।

২. স্টোরেজ ক্লাস ও বিলিং

  • আমরা স্ট্যান্ডার্ড স্টোরেজ ক্লাস ব্যবহার করার সাজেশন দিই। স্ট্যান্ডার্ড স্টোরেজের ক্ষেত্রে ন্যূনতম স্টোরেজ মেয়াদের কোনও নিয়ম নেই, তাই আপনি অস্থায়ী ফাইল আপডেট বা পরিবর্তন করলে আগেভাগে মুছে দেওয়ার জন্য বিলিং সংক্রান্ত জরিমানা এড়াতে পারবেন।
  • Earth Engine কম্পিউটেশন লুপের জন্য Cloud Storage ডেটা রিট্রিভাল সারচার্জ না লাগলেও, এক্সটার্নাল টুল (যেমন, ডেস্কটপ GIS সফ্টওয়্যার) থেকে নন-স্ট্যান্ডার্ড স্টোরেজ টিয়ার অ্যাক্সেস করলে, রিট্রিভাল ফি বাবদ অনেক খরচ হয়।
  • GCS ব্যবহার করতে হলে আপনার Google Cloud প্রোজেক্টে বিলিং চালু থাকতে হবে। শুরু করতে Google Cloud Storage কুইকস্টার্ট দেখুন।

ধাপ ১: আপনার COG প্রস্তুত করুন

আপনার TIFF ফাইল ক্লাউডের জন্য অপ্টিমাইজ করা থাকতে হবে। TIFF ফাইল অবশ্যই:

  • টাইল করা, যার টাইল ডাইমেনশন: ২৫৬x২৫৬, ৫১২x৫১২, ১০২৪x১০২৪, অথবা ২০৪৮x২০৪৮। সেরা পারফর্ম্যান্সের জন্য আমরা ৫১২x৫১২ বা তার বেশি সাইজের ছবি ব্যবহার করার সাজেশন দিই।
  • এমনভাবে সাজানো হয়েছে যাতে সব ইমেজ ফাইল ডিরেক্টরি (IFD) শুরুতে থাকে।
  • ২-এর ঘাত সম্পর্কিত ওভারভিউ অন্তর্ভুক্ত করুন।
  • 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 URI এবং ঐচ্ছিক ব্যান্ড মেটাডেটা নির্দিষ্ট করে একটি ইমেজ আপলোড ম্যানিফেস্ট সংজ্ঞায়িত করতে হবে।

উদাহরণ: সব ব্যান্ড ব্যাক-আপ করা একটি 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 }
  ]
}

ধাপ ৩: রেজিস্ট্রেশনের অনুরোধ জমা দিন

আপনি 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)

ক্লায়েন্ট লাইব্রেরি ছাড়া অটোমেটিক ওয়ার্কফ্লোয়ের জন্য, অনুমোদিত POST অনুরোধ সরাসরি Earth Engine REST API এন্ডপয়েন্টে পাঠান 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 অ্যাসেটের জন্য ম্যানিফেস্ট সংক্রান্ত বিধিনিষেধ

COG-ব্যাকড অ্যাসেটের জন্য ম্যানিফেস্ট তৈরি করার সময়, এইসব কঠোর বিধিনিষেধ (যা স্ট্যান্ডার্ড ইনজেশন ম্যানিফেস্ট থেকে আলাদা) মনে রাখবেন:

  • সিঙ্গেল বাকেট: ম্যানিফেস্টের সব URI একই GCS বাকেটে থাকতে হবে।
  • প্রতি সোর্সে একটি URI: প্রতিটি ImageSource-এ ঠিক একটি URI থাকতে হবে। আপনি একাধিক ফাইল একসাথে মোজাইক করে একটি টাইলসেট সোর্স তৈরি করতে পারবেন না। একাধিক 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 ফাইল, উভয় ক্ষেত্রেই রিড অ্যাক্সেস দিতে হবে।

১. GCS বাকেট সংক্রান্ত অনুমতি দিন

GCS থেকে ফাইল পড়ার জন্য সহযোগীদের অনুমতি প্রয়োজন।

প্রয়োজনীয় অনুমতি:

  • storage.buckets.get (বাকেট মেটাডেটা ও লোকেশন পেতে)
  • storage.objects.get (পিক্সেল ডেটা পড়ার জন্য)

আপনি নিম্নলিখিত স্ট্যান্ডার্ড Cloud Storage ভূমিকা ব্যবহার করে এইসব অনুমতি দিতে পারবেন:

  • স্টোরেজ বাকেট ভিউয়ার (storage.buckets.get বাকেট মেটাডেটা ও লোকেশন পড়ার সুবিধা দেয়)
  • Storage Object Viewer (পিক্সেল ডেটা পড়ার জন্য storage.objects.get প্রদান করে)

Google Cloud Console-এ কনফিগার করার ধাপ:

  1. Cloud Storage ব্রাউজার-এ যান।
  2. আপনার বাকেটের নামে ক্লিক করুন।
  3. অনুমতি ট্যাব বেছে নিন।
  4. অ্যাক্সেস দিন বিকল্পে ক্লিক করুন।
  5. আপনার কোলাবরেটরদের ইমেল আইডি (বা Google গ্রুপ, অথবা allUsers সর্বজনীন অ্যাক্সেসের জন্য) যোগ করুন।
  6. Storage Bucket Viewer এবং Storage Object Viewer ভূমিকা অ্যাসাইন করুন।
  7. সেভ করুন বিকল্পে ক্লিক করুন।

২. Earth Engine অ্যাসেট শেয়ার করুন

Earth Engine অ্যাসেট ম্যানেজার বা CLI ব্যবহার করে অ্যাসেট শেয়ার করুন। আরও বিবরণের জন্য অ্যাসেট ম্যানেজমেন্ট গাইড দেখুন।

অবজেক্ট জেনারেশন ম্যানেজ করা

আপনি 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 স্ক্রিপ্টে ঠিক অন্যান্য সাধারণ ইনজেস্ট করা ইমেজ অ্যাসেটের মতোই অ্যাক্সেস করা হয়:

জাভাস্ক্রিপ্ট

var image = ee.Image('projects/your-project-id/assets/my_cog_asset');

Python

image = ee.Image('projects/your-project-id/assets/my_cog_asset')