ประกาศ: โปรเจ็กต์ที่ไม่ใช่เชิงพาณิชย์ทั้งหมดที่ลงทะเบียนเพื่อใช้ Earth Engine ก่อนวันที่ 15 เมษายน 2025 ต้องยืนยันการมีสิทธิ์ที่ไม่ใช่เชิงพาณิชย์เพื่อรักษาสิทธิ์เข้าถึง Earth Engine

หน้านี้ได้รับการแปลโดย Cloud Translation API

เนื้อหา Earth Engine ที่เก็บไว้ในระบบคลาวด์ซึ่งอิงตาม GeoTIFF

เรียกใช้ใน Google Colab

ดูซอร์สโค้ดใน GitHub

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

โปรดทราบว่าชิ้นงานเดียวอาจมี COG หลายรายการ (เช่น อาจมี COG 1 รายการต่อกลุ่ม) แต่ระบบไม่รองรับการใช้ไทล์ COG หลายรายการสำหรับย่านความถี่เดียว

(หรือ Earth Engine จะโหลดภาพจาก COG ใน Google Cloud Storage โดยตรงก็ได้ (ดูข้อมูลเพิ่มเติม)) อย่างไรก็ตาม รูปภาพที่โหลดผ่าน ee.Image.loadGeoTIFF และเพิ่มลงในคอลเล็กชันรูปภาพจะต้องมีการอ่าน GeoTiff สำหรับการดำเนินการกรองในคอลเล็กชัน)

วิธีสร้างชิ้นงานที่อิงตาม COG

วางไฟล์ COG ไว้ในที่เก็บข้อมูล GCS (ดูภูมิภาคที่อนุญาตด้านล่าง)
เขียนไฟล์ Manifest สำหรับการอัปโหลดรูปภาพ
ใช้ยูทิลิตีบรรทัดคำสั่ง earthengine เพื่อส่งคำสั่งอัปโหลด

earthengine upload external_image --manifest my_manifest.json

ไฟล์ Manifest รูปภาพตัวอย่างที่มี `Tileset` รายการเดียว

ImageManifest ที่ง่ายที่สุดคือ ImageManifest ที่มี Tileset รายการเดียว หากไม่ได้ระบุแถบ ชิ้นงานที่ได้จะมีแถบทั้งหมดของ GeoTIFF พร้อมชื่อแถบที่เข้ารหัสไว้ใน GeoTIFF (ในกรณีนี้คือ "vis-red", "vis-green" และ "vis-blue")

request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo1',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': ['gs://ee-docs-demos/COG_demo.tif'] } ] }
    ],
    'properties': {
      'version': '1.1'
    },
    'startTime': '2016-01-01T00:00:00.000000000Z',
    'endTime': '2016-12-31T15:01:23.000000000Z',
  },
}

pprint(request)

`Tileset` มากกว่า 1 รายการ

คุณสามารถระบุ ImageManifest ที่มี Tileset มากกว่า 1 รายการได้ โดยแต่ละย่านของเนื้อหาที่ได้จะอิงตามย่านใดย่านหนึ่งของ Tileset โดยใช้ช่อง tilesetId และ tilesetBandIndex ซึ่งมีประโยชน์ในกรณีที่แถบต่างๆ มีความละเอียดหรือประเภทข้อมูลต่างกัน คุณจัดเรียงวงดนตรีในลำดับใดก็ได้จาก Tileset ที่มีอยู่ ในตัวอย่างด้านล่าง

"b4b3b2.tif" มีมาตราส่วน 10 ม. ส่วน "b5b6b7" มีมาตราส่วน 20 ม.
ลําดับของแถบของชิ้นงานที่ได้จะผสมจาก COG อินพุต (เช่น แถบเอาต์พุต 0 มาจาก Tileset 0 ส่วนแถบเอาต์พุต 1 มาจาก Tileset 1)

request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo2',
    'uriPrefix': 'gs://ee-docs-demos/external_image_demo/',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': ['b4b3b2.tif'] } ] },
      { 'id': '1', 'sources': [ { 'uris': ['b5b6b7.tif'] } ] },
    ],
    'bands': [
      { 'id': 'red', 'tilesetId': '0', 'tilesetBandIndex': 0 },
      { 'id': 'rededge3', 'tilesetId': '1', 'tilesetBandIndex': 2 },
      { 'id': 'rededge2', 'tilesetId': '1', 'tilesetBandIndex': 1 },
      { 'id': 'green', 'tilesetId': '0', 'tilesetBandIndex': 1 },
      { 'id': 'blue', 'tilesetId': '1', 'tilesetBandIndex': 0 },
      { 'id': 'rededge1', 'tilesetId': '0', 'tilesetBandIndex': 2 },
    ],
  },
}

pprint(request)

รายละเอียดเกี่ยวกับเนื้อหาที่รองรับ COG

ตำแหน่ง

ตำแหน่งที่เก็บข้อมูล Cloud Storage ต้องเป็นอย่างใดอย่างหนึ่งต่อไปนี้

หลายภูมิภาคในสหรัฐอเมริกา
ภูมิภาคคู่ในสหรัฐอเมริกาที่มี US-CENTRAL1
ภูมิภาค US-CENTRAL1

คลาสพื้นที่เก็บข้อมูล

คลาสพื้นที่เก็บข้อมูลของที่เก็บข้อมูลต้องเป็น "พื้นที่เก็บข้อมูลมาตรฐาน"

สิทธิ์ในการแชร์

ระบบจะจัดการ ACL ของเนื้อหา Earth Engine ที่สำรองข้อมูลโดย COG และข้อมูลที่เกี่ยวข้องแยกกัน เมื่อแชร์เนื้อหาที่สำรองข้อมูล COG กับผู้ทำงานร่วมกันเพื่ออ่าน เจ้าของมีหน้าที่รับผิดชอบในการให้สิทธิ์การอ่านทั้งเนื้อหา Earth Engine และไฟล์ COG ที่เกี่ยวข้อง

1. ให้สิทธิ์ที่เก็บข้อมูล Google Cloud Storage สำหรับการอ่าน

ผู้ทำงานร่วมกันต้องได้รับสิทธิ์การอ่านไฟล์ COG ที่เกี่ยวข้องในที่เก็บข้อมูล Google Cloud Storage ก่อนจึงจะอ่านเนื้อหาที่สำรองข้อมูลด้วย COG ได้ หากไม่มีสิทธิ์เหล่านี้ Earth Engine จะดึงข้อมูลให้ผู้ใช้ไม่ได้ หากผู้ใช้ Earth Engine ไม่เห็นข้อมูลใน Google Cloud Storage แสดงว่า Earth Engine จะแสดงข้อผิดพลาดในรูปแบบ "โหลด GeoTIFF ที่ gs://my-bucket/my-object#123456 ไม่สำเร็จ" (โดยที่ 123456 คือการสร้างออบเจ็กต์)

กล่าวโดยละเอียดคือ ผู้ทำงานร่วมกันต้องมีสิทธิ์ต่อไปนี้

storage.buckets.get ในที่เก็บข้อมูล (เพื่อดึงข้อมูลเมตาและตำแหน่งของที่เก็บข้อมูล ซึ่งช่วยให้ Earth Engine แก้ปัญหาแหล่งที่มาของชิ้นงานได้อย่างถูกต้อง)
storage.objects.get ในที่เก็บข้อมูล (เพื่ออ่านข้อมูลเนื้อหาจริงที่สำรองข้อมูลโดย COG)

สิทธิ์เหล่านี้มาจากบทบาท "ผู้อ่านที่เก็บข้อมูลเดิมของ Storage" และ "ผู้อ่านออบเจ็กต์เดิมของ Storage" ตามลำดับและบทบาทอื่นๆ

วิธีมอบหมายบทบาทเหล่านี้ให้กับผู้ทำงานร่วมกัน

ไปที่หน้าสิทธิ์ของที่เก็บข้อมูล โดยทำดังนี้ https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
คลิก "ให้สิทธิ์เข้าถึง"
เพิ่มผู้ใช้หลักทั้งหมด (เช่น ผู้ใช้ กลุ่ม บัญชีบริการ) ที่ได้รับสิทธิ์การอ่าน
มอบหมายบทบาทต่อไปนี้
- "Storage Legacy Bucket Reader" (ให้สิทธิ์ storage.buckets.get และสิทธิ์การอ่านระดับที่เก็บข้อมูลอื่นๆ)
- "Storage Legacy Object Reader" (ระบุ storage.objects.get)
- (หรือจะสร้างบทบาทที่กําหนดเองใหม่ที่มีสิทธิ์ storage.buckets.get และ storage.objects.get เท่านั้นแล้วมอบหมายบทบาทนั้นก็ได้)
บันทึก

2. แชร์เนื้อหา Earth Engine เพื่ออ่าน

หลังจากตรวจสอบว่าผู้ทำงานร่วมกันมีสิทธิ์ที่จำเป็นในที่เก็บข้อมูล GCS และออบเจ็กต์ที่เกี่ยวข้องแล้ว คุณต้องแชร์ชิ้นงาน Earth Engine ด้วย ดูข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่าสิทธิ์เนื้อหา Earth Engine ได้ที่คู่มือการจัดการเนื้อหา Earth Engine

เจเนอเรชัน

เมื่อสร้างเนื้อหาที่สำรองข้อมูลด้วย COG แล้ว Earth Engine จะอ่านข้อมูลเมตาของ TIFF ที่ระบุไว้ในไฟล์ Manifest และสร้างรายการใน Store ของเนื้อหา URI แต่ละรายการที่เชื่อมโยงกับรายการนั้นๆ อาจมีรุ่น ดูรายละเอียดเกี่ยวกับการสร้างได้จากเอกสารเกี่ยวกับการกำหนดเวอร์ชันออบเจ็กต์ หากระบุรุ่น เช่น gs://foo/bar#123 Earth Engine จะจัดเก็บ URI นั้นตามตัวอักษร หากไม่ได้ระบุรุ่น Earth Engine จะจัดเก็บ URI นั้นพร้อมกับรุ่น TIFF ณ เวลาที่มีการเรียกImportExternalImage

ซึ่งหมายความว่าหาก TIFF ที่ประกอบด้วยชิ้นงานภายนอกใน GCS ได้รับการอัปเดต (จึงเปลี่ยนรุ่น) Earth Engine จะแสดงข้อผิดพลาด "โหลด GeoTIFF ที่ gs://my-bucket/my-object#123456 ไม่สำเร็จ" เนื่องจากไม่มีออบเจ็กต์ที่คาดไว้อีกต่อไป (เว้นแต่ที่เก็บข้อมูลจะเปิดใช้ออบเจ็กต์หลายเวอร์ชัน) นโยบายนี้ออกแบบมาเพื่อให้ข้อมูลเมตาของเนื้อหาซิงค์กับข้อมูลเมตาของออบเจ็กต์

การกำหนดค่า

ในแง่ของวิธีกำหนดค่า COG ไฟล์ TIFF จะต้องมีลักษณะดังนี้

เรียงต่อกัน โดยขนาดของชิ้นส่วนแผนที่จะเป็นค่าใดค่าหนึ่งต่อไปนี้
- 256x256
- 512x512
- 1024x1024
- 2048x2048
จัดเรียงเพื่อให้ IFD ทั้งหมดอยู่ในช่วงต้น

วิธีใช้เพื่อประสิทธิภาพที่ดีที่สุด

ใช้ขนาดไทล์ 512x512 ขึ้นไป
รวมภาพรวม 2 รายการ

ตัวเลือกการสร้าง'INTERLEAVE' อาจส่งผลต่อประสิทธิภาพ ทั้งนี้ขึ้นอยู่กับกรณีการใช้งานที่ต้องการ เราขอแนะนำให้ใช้การซ้อน BAND ในทุกกรณี

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการกําหนดค่าแบบเพิ่มประสิทธิภาพได้ในหน้านี้

คำสั่ง gdal_translate ต่อไปนี้จะแปลงแรสเตอร์เป็น GeoTIFF ที่เพิ่มประสิทธิภาพสำหรับระบบคลาวด์ซึ่งมีการบีบอัด zstd และมีการแทรกแถบสี ซึ่งจะทำงานได้ดีใน Earth Engine

gdal_translate in.tif out.tif \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=22 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS

คุณอาจลดขนาดไฟล์เอาต์พุตได้อีกโดยระบุตัวทำนาย (-co PREDICTOR=2 สำหรับประเภทข้อมูลจำนวนเต็มและ -co PREDICTOR=3 สำหรับประเภทข้อมูลทศนิยม)

สําหรับผู้ใช้ที่มี GDAL >= 3.11 ไดรฟ์ COG จะสร้างไฟล์ได้โดยไม่ต้องกังวลเกี่ยวกับการสร้างและเก็บรักษาภาพรวม

gdal_translate in.tif out.tif \
  -of COG \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=22 \
  -co PREDICTOR=2 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \

การสร้างชิ้นงานที่ฝังข้อมูล GeoTIFF ของ Cloud โดยใช้ REST API

หมายเหตุ: REST API มีฟีเจอร์ใหม่และขั้นสูงที่อาจไม่เหมาะกับผู้ใช้บางราย หากคุณเพิ่งเริ่มใช้ Earth Engine เราขอแนะนําให้เริ่มต้นด้วยคู่มือ JavaScript

หากต้องการสร้างชิ้นงานที่สำรองข้อมูลด้วย COG โดยใช้ REST API ให้ส่งPOSTคำขอไปยังImportExternalImage ปลายทางของ Earth Engine ดังที่แสดงต่อไปนี้ คําขอนี้ต้องได้รับอนุญาตจึงจะสร้างชิ้นงานในโฟลเดอร์ผู้ใช้ได้

เริ่มเซสชันที่ได้รับอนุญาต

หากต้องการสร้างชิ้นงาน Earth Engine ในโฟลเดอร์ผู้ใช้ คุณต้องตรวจสอบสิทธิ์เป็นตนเองได้เมื่อส่งคำขอ คุณสามารถใช้ข้อมูลเข้าสู่ระบบจากโปรแกรมตรวจสอบสิทธิ์ของ Earth Engine เพื่อเริ่มAuthorizedSession จากนั้นจะใช้ AuthorizedSession เพื่อส่งคำขอไปยัง Earth Engine ได้

import ee
import json
from pprint import pprint
from google.auth.transport.requests import AuthorizedSession

ee.Authenticate()  #  or !earthengine authenticate --auth_mode=gcloud

# Specify the cloud project you want associated with Earth Engine requests.
ee_project = 'your-project'

session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

เนื้อความของคำขอ

เนื้อหาของคำขอคืออินสแตนซ์ของ ImageManifest ในส่วนนี้จะมีการระบุเส้นทางไปยัง COG พร้อมกับพร็อพเพอร์ตี้อื่นๆ ที่มีประโยชน์

ดูรายละเอียดเกี่ยวกับวิธีกําหนดค่า ImageManifest ได้ในคู่มือนี้ คุณกำหนด Tileset ได้อย่างน้อย 1 รายการ โดยแต่ละรายการจะมีแบนด์สนับสนุนอย่างน้อย 1 แบนด์ สำหรับ ImportExternalImage ระบบจะรองรับ ImageSource สูงสุด 1 รายการต่อ Tileset

ดูรายละเอียดการส่งออกต้นทุนรวมในการรับชมได้ที่เอกสารนี้

ส่งคำขอ

ส่งคำขอ POST ไปยังปลายทาง projects.images.importExternal ของ Earth Engine

url = f'https://earthengine.googleapis.com/v1alpha/projects/{ee_project}/image:importExternal'

response = session.post(
  url = url,
  data = json.dumps(request)
)

pprint(json.loads(response.content))

ไฟล์ Manifest รูปภาพตัวอย่างที่มี Tileset รายการเดียว

Tileset มากกว่า 1 รายการ