การลงทะเบียนชิ้นงาน GeoTIFF (COG) ที่เพิ่มประสิทธิภาพสำหรับระบบคลาวด์

Earth Engine รองรับชิ้นงานที่สร้างขึ้นจาก Cloud Optimized GeoTIFF (COG) ซึ่งจัดเก็บไว้ใน Google Cloud Storage (GCS)

เมื่อลงทะเบียนชิ้นงานที่สร้างขึ้นจาก COG แล้ว Earth Engine จะจัดทำดัชนีช่องข้อมูลเชิงพื้นที่และข้อมูลเมตาของรูปภาพในเวลาที่สร้าง ซึ่งจะทำให้รูปภาพมีประสิทธิภาพ เมื่อใช้ในคอลเล็กชัน โดยมีประสิทธิภาพเทียบเท่ากับชิ้นงานที่นำเข้าตามมาตรฐาน (ดูภาพรวมของ Cloud Optimized GeoTIFF (COG))

ข้อกำหนดเบื้องต้นและการตั้งค่า Cloud Storage

ก่อนลงทะเบียน COG คุณต้องตั้งค่าทรัพยากร Google Cloud Storage อย่างถูกต้อง

1. ตำแหน่ง Bucket (ข้อกำหนดที่เข้มงวด)

Earth Engine จะเข้าถึง Bucket ของ Cloud Storage ได้ Bucket ต้อง อยู่ในภูมิภาคศูนย์ข้อมูลหรือหลายภูมิภาคต่อไปนี้

• หลายภูมิภาค us
• ภูมิภาคคู่ของสหรัฐอเมริกา ที่มี us-central1
• ภูมิภาค us-central1

หากวาง Bucket ไว้ในศูนย์ข้อมูลระดับภูมิภาคอื่นๆ (เช่น us-east4 หรือ europe-west1) Earth Engine จะปฏิเสธคำขอลงทะเบียนและอ่าน

2. คลาสพื้นที่เก็บข้อมูลและการเรียกเก็บเงิน

• เราขอแนะนำให้ใช้คลาสพื้นที่เก็บข้อมูลมาตรฐาน พื้นที่เก็บข้อมูลมาตรฐานไม่มีกฎระยะเวลาเก็บข้อมูลขั้นต่ำ ซึ่งจะป้องกันค่าปรับการเรียกเก็บเงินสำหรับการลบก่อนกำหนดหากคุณอัปเดตหรือแทนที่ไฟล์ชั่วคราว
• แม้ว่าลูปการคำนวณของ Earth Engine จะไม่มีค่าธรรมเนียมเพิ่มเติมสำหรับการดึงข้อมูล Cloud Storage แต่การเข้าถึงพื้นที่เก็บข้อมูลที่ไม่ใช่ระดับมาตรฐานจากเครื่องมือภายนอก (เช่น ซอฟต์แวร์ GIS บนเดสก์ท็อป) จะมีค่าธรรมเนียมการดึงข้อมูลที่มีราคาสูง
• คุณต้องเปิดใช้การเรียกเก็บเงินในโปรเจ็กต์ Google Cloud เพื่อใช้ GCS ดู เริ่มต้นใช้งาน Google Cloud Storage เพื่อเริ่มต้นใช้งาน

ขั้นตอนที่ 1: เตรียม COG

ไฟล์ TIFF ต้องได้รับการเพิ่มประสิทธิภาพสำหรับระบบคลาวด์ ไฟล์ TIFF ต้อง มีลักษณะดังนี้

• แบ่งเป็นส่วนๆ โดยมีขนาดส่วนดังนี้ 256x256, 512x512, 1024x1024 หรือ 2048x2048 เราขอแนะนำขนาด 512x512 ขึ้นไปเพื่อให้ได้ประสิทธิภาพสูงสุด
• จัดเรียงเพื่อให้ไดเรกทอรีไฟล์รูปภาพ (IFD) ทั้งหมดอยู่ที่จุดเริ่มต้น
• รวมภาพรวมที่เป็นกำลังของ 2
• ใช้การสอดแทรก 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 มาตรฐาน

ขั้นแรก ให้สร้างภาพรวมที่เป็นกำลังของ 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: สร้างไฟล์ Manifest

ไม่ว่าคุณจะลงทะเบียน COG โดยใช้ไลบรารีของไคลเอ็นต์ Python ของ Earth Engine, เครื่องมือบรรทัดคำสั่ง earthengine หรือ Earth Engine REST API คุณต้องกำหนดไฟล์ Manifest การอัปโหลดรูปภาพที่ระบุปลายทางของชิ้นงาน, URI ของ Google Cloud Storage และข้อมูลเมตาของแถบสีที่ไม่บังคับ

ตัวอย่าง: COG เดียวที่สร้างขึ้นจากแถบสีทั้งหมด หาก COG มีแถบสีทั้งหมด (เช่น RGB) ไฟล์ Manifest จะต้องมีชุดไทล์เพียงชุดเดียว

{
  "name": "projects/my-project/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

ตัวอย่าง: COG หลายรายการ (1 รายการต่อแถบสี) หากคุณมีไฟล์แยกต่างหากสำหรับแถบสีต่างๆ (เช่น แดง เขียว น้ำเงินในไฟล์แยกกัน)

{
  "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: ส่งคำขอลงทะเบียน

คุณสามารถส่งไฟล์ Manifest ไปยัง Earth Engine ได้โดยใช้ไลบรารีของไคลเอ็นต์ Python ของ Earth Engine, เครื่องมือบรรทัดคำสั่ง earthengine หรือ Earth Engine REST API เลือกวิธีที่เหมาะกับเวิร์กโฟลว์ของคุณมากที่สุด

ไลบรารีของไคลเอ็นต์ Python

ในสคริปต์ Python หรือสมุดบันทึก Jupyter ให้ใช้ไลบรารีของไคลเอ็นต์ Python ของ Earth Engine (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 ลงในไฟล์ที่ชื่อ 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 เป็นการเรียก API แบบซิงโครนัสที่รวดเร็ว ไม่ใช่การเรียกใช้การคำนวณแบบกลุ่มแบบอะซิงโครนัส จึงไม่ได้สร้างงานเบื้องหลังในแท็บ งาน ของตัวแก้ไขโค้ดหรือตัวจัดการงานแบบกลุ่ม การเรียก API จะบล็อกไว้จนกว่าการตรวจสอบข้อมูลเมตาและการจัดทำดัชนีจะ เสร็จสมบูรณ์ จากนั้นชิ้นงานจะพร้อมใช้งานทันทีในเครื่องมือแก้ไขโค้ด ชิ้นงาน แท็บหรือโดยใช้ ee.data.getAsset()

ข้อจำกัดของไฟล์ Manifest สำหรับชิ้นงาน COG

เมื่อสร้างไฟล์ Manifest สำหรับชิ้นงานที่สร้างขึ้นจาก COG โปรดทราบข้อจำกัดที่เข้มงวดต่อไปนี้ (ซึ่งแตกต่างจากไฟล์ Manifest การนำเข้าตามมาตรฐาน)

• Bucket เดียว: URI ทั้งหมดในไฟล์ Manifest ต้องอยู่ใน Bucket GCS เดียวกัน
• 1 URI ต่อแหล่งที่มา: ImageSource แต่ละรายการต้องมี URI เพียงรายการเดียว คุณไม่สามารถรวมไฟล์หลายไฟล์เข้าด้วยกันเป็นแหล่งที่มาของชุดไทล์เดียว หากต้องการรวมฉาก COG หลายฉาก ให้ลงทะเบียน COG แต่ละฉากเป็นชิ้นงาน แล้วรวมเข้าด้วยกันเป็น ee.ImageCollection โดยใช้ .mosaic()
• ไม่มี mask_bands: ระบบไม่รองรับ mask_bands ระดับบนสุด ใช้ missingData ในไฟล์ Manifest หรือตรวจสอบว่า TIFF มีค่า nodata ภายใน
• ไม่มี data_type ในชุดไทล์: อย่าระบุ data_type ในส่วน tilesets เนื่องจากระบบจะตรวจหาโดยอัตโนมัติ
• ไม่มี dimensions ในแหล่งที่มา: อย่าระบุ dimensions ใน ImageSource
• ไม่มี subdataset_prefix / subdataset_suffix
• ไม่มี min_tile_area_ratio หรือ skip_metadata_read

ขั้นตอนที่ 4: กำหนดค่าสิทธิ์ (สำคัญสำหรับการแชร์)

ข้อมูลพิกเซลของ COG จะยังคงอยู่ใน GCS ซึ่งแตกต่างจากชิ้นงาน Earth Engine มาตรฐาน เมื่อแชร์ชิ้นงานที่สร้างขึ้นจาก COG กับผู้อื่น คุณต้องให้สิทธิ์เข้าถึงแบบอ่านทั้งชิ้นงาน Earth Engine และไฟล์ GCS

1. ให้สิทธิ์ Bucket ของ GCS

ผู้ทำงานร่วมกันต้องมีสิทธิ์อ่านไฟล์จาก GCS

สิทธิ์ที่จำเป็นคือ

• storage.buckets.get (เพื่อดึงข้อมูลเมตาและตำแหน่งของ Bucket)
• storage.objects.get (เพื่ออ่านข้อมูลพิกเซล)

คุณสามารถให้สิทธิ์เหล่านี้ได้โดยใช้บทบาทมาตรฐานของ Cloud Storage ต่อไปนี้

• ผู้มีสิทธิ์ดู Bucket ของพื้นที่เก็บข้อมูล (ให้สิทธิ์ storage.buckets.get เพื่ออ่านข้อมูลเมตาและตำแหน่งของ Bucket)
• ผู้มีสิทธิ์ดูออบเจ็กต์พื้นที่เก็บข้อมูล (ให้สิทธิ์ storage.objects.get เพื่ออ่านข้อมูลพิกเซล)

ขั้นตอนการกำหนดค่าในคอนโซล Google Cloud

1. ไปที่ เบราว์เซอร์ Cloud Storage.
2. คลิกชื่อ Bucket
3. เลือกแท็บสิทธิ์
4. คลิกให้สิทธิ์เข้าถึง
5. เพิ่มอีเมลของผู้ทำงานร่วมกัน (หรือ Google Group หรือ allUsers สำหรับการเข้าถึงแบบสาธารณะ)
6. กำหนดบทบาทผู้มีสิทธิ์ดู Bucket ของพื้นที่เก็บข้อมูล และผู้มีสิทธิ์ดูออบเจ็กต์พื้นที่เก็บข้อมูล
7. คลิกบันทึก

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