Thông báo: Tất cả dự án phi thương mại đã đăng ký sử dụng Earth Engine trước ngày 15 tháng 4 năm 2025 phải xác minh điều kiện sử dụng phi thương mại để duy trì quyền truy cập vào Earth Engine.

Trang này được dịch bởi Cloud Translation API.

Tài sản Earth Engine dựa trên GeoTiff trên đám mây

Chạy trong Google Colab

Xem mã nguồn trên GitHub

Earth Engine hỗ trợ các thành phần được hỗ trợ bởi GeoTIFF được tối ưu hoá trên đám mây (COG). Một lợi thế của các thành phần được hỗ trợ COG là các trường siêu dữ liệu và không gian của hình ảnh sẽ được lập chỉ mục tại thời điểm tạo thành phần, giúp hình ảnh hoạt động hiệu quả hơn trong các bộ sưu tập. Hiệu suất của các thành phần được COG hỗ trợ tương đương với hiệu suất của các thành phần được nhập trong các trường hợp sử dụng thông thường.

Xin lưu ý rằng một thành phần có thể được nhiều COG hỗ trợ (ví dụ: có thể có một COG cho mỗi băng tần). Tuy nhiên, bạn không được sử dụng nhiều thẻ thông tin COG cho một băng tần.

(Ngoài ra, Earth Engine có thể trực tiếp tải hình ảnh từ COG trong Google Cloud Storage (tìm hiểu thêm). Tuy nhiên, hình ảnh được tải thông qua ee.Image.loadGeoTIFF và thêm vào một bộ sưu tập hình ảnh sẽ yêu cầu đọc GeoTiff để lọc các thao tác trên bộ sưu tập.)

Để tạo một thành phần được COG hỗ trợ,

Đặt các tệp COG vào một bộ chứa GCS (xem bên dưới để biết các khu vực được phép).
Viết tệp kê khai tải hình ảnh lên
Sử dụng tiện ích dòng lệnh earthengine để gửi lệnh tải lên:

earthengine upload external_image --manifest my_manifest.json

Tệp kê khai hình ảnh mẫu có một `Tileset`

ImageManifest đơn giản nhất là một ImageManifest có một Tileset. Nếu không chỉ định băng nào, tài sản thu được sẽ chứa tất cả các băng của GeoTIFF với tên băng được mã hoá trong GeoTIFF (trong trường hợp này là "vis-red", "vis-green" và "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)

Nhiều `Tileset`

Bạn có thể chỉ định ImageManifest với nhiều Tileset, trong đó mỗi dải của thành phần kết quả được hỗ trợ bởi một trong các dải của Tileset bằng cách sử dụng các trường tilesetId và tilesetBandIndex. Điều này rất hữu ích trong trường hợp các băng tần có độ phân giải hoặc loại dữ liệu khác nhau. Bạn có thể liệt kê các ban nhạc theo thứ tự bất kỳ từ Tileset bất kỳ. Trong ví dụ dưới đây:

"b4b3b2.tif" có tỷ lệ 10 m, trong khi "b5b6b7" có tỷ lệ 20 m.
Thứ tự băng tần của thành phần kết quả được kết hợp từ các COG đầu vào (ví dụ: băng tần đầu ra 0 là từ Tileset 0, trong khi băng tần đầu ra 1 là từ 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)

Thông tin chi tiết về các tài sản được COG hỗ trợ

Vị trí

Vị trí bộ chứa Cloud Storage phải là một trong những vị trí sau:

Nhiều khu vực ở Hoa Kỳ
Mọi khu vực kép ở Hoa Kỳ bao gồm cả US-CENTRAL1
Khu vực US-CENTRAL1

Lớp bộ nhớ

Lớp bộ nhớ của bộ chứa phải là "Bộ nhớ chuẩn".

Quyền chia sẻ

Các ACL của tài sản Earth Engine được COG hỗ trợ và dữ liệu cơ bản được quản lý riêng biệt. Khi chia sẻ tài sản được hỗ trợ COG với cộng tác viên để đọc, chủ sở hữu có trách nhiệm đảm bảo rằng quyền đọc được cấp cho cả tài sản Earth Engine và các tệp COG cơ bản.

1. Cấp quyền đọc cho bộ chứa Google Cloud Storage

Để cộng tác viên có thể đọc các thành phần được COG hỗ trợ, trước tiên, họ phải có quyền đọc vào các tệp COG cơ bản trong bộ chứa Google Cloud Storage. Nếu không có các quyền này, Earth Engine sẽ không thể truy xuất dữ liệu cho các lớp phủ đó. Nếu người dùng Earth Engine không thấy dữ liệu trong Google Cloud Storage, thì Earth Engine sẽ trả về lỗi ở dạng "Không tải được GeoTIFF tại gs://my-bucket/my-object#123456" (trong đó 123456 là phiên bản của đối tượng).

Cụ thể, cộng tác viên phải có các quyền sau:

storage.buckets.get trên bộ chứa (để truy xuất siêu dữ liệu và vị trí của bộ chứa, cho phép Earth Engine phân giải đúng nguồn của tài sản).
storage.objects.get trên bộ chứa (để đọc dữ liệu tài sản thực tế được COG hỗ trợ).

Các quyền này được cung cấp bởi các vai trò "Storage Legacy Bucket Reader" (Trình đọc bộ chứa cũ của Bộ nhớ) và "Storage Legacy Object Reader" (Trình đọc đối tượng cũ của Bộ nhớ) và các vai trò khác.

Cách chỉ định các vai trò này cho cộng tác viên:

Chuyển đến trang quyền đối với bộ chứa: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
Nhấp vào "CẤP QUAN QUYỀN TRUY CẬP"
Thêm tất cả các thực thể chính (ví dụ: người dùng, nhóm, tài khoản dịch vụ) sẽ được cấp quyền đọc.
Chỉ định các vai trò sau:
- "Trình đọc bộ chứa cũ của bộ nhớ" (cung cấp storage.buckets.get và các quyền đọc cấp bộ chứa khác).
- "Storage Legacy Object Reader" (Cung cấp storage.objects.get).
- (Ngoài ra, bạn có thể tạo một vai trò tuỳ chỉnh mới chỉ với các quyền storage.buckets.get và storage.objects.get rồi chỉ định vai trò đó.)
Lưu

2. Chia sẻ tài sản Earth Engine để đọc

Sau khi đảm bảo cộng tác viên của bạn có các quyền cần thiết trên bộ chứa và đối tượng GCS cơ bản, bạn cũng phải chia sẻ chính tài sản Earth Engine. Để biết thêm thông tin về cách thiết lập quyền đối với tài sản Earth Engine, hãy tham khảo hướng dẫn quản lý tài sản Earth Engine.

Thế hệ

Khi một thành phần được hỗ trợ COG được tạo, Earth Engine sẽ đọc siêu dữ liệu của TIFF được chỉ định trong tệp kê khai và tạo một mục trong kho tài sản. Mỗi URI liên kết với mục đó có thể có một thế hệ. Xem tài liệu về việc tạo phiên bản đối tượng để biết thông tin chi tiết về các thế hệ. Nếu bạn chỉ định một thế hệ, chẳng hạn như gs://foo/bar#123, Earth Engine sẽ lưu trữ nguyên văn URI đó. Nếu bạn không chỉ định một phiên bản, Earth Engine sẽ lưu trữ URI đó cùng với phiên bản TIFF tại thời điểm gọi ImportExternalImage.

Điều đó có nghĩa là nếu bất kỳ TIFF nào bao gồm một thành phần bên ngoài trong GCS được cập nhật (do đó thay đổi quá trình tạo), Earth Engine sẽ trả về lỗi "Không tải được GeoTIFF tại gs://my-bucket/my-object#123456" vì đối tượng dự kiến không còn tồn tại (trừ khi bộ chứa cho phép nhiều phiên bản đối tượng). Chính sách này được thiết kế để đồng bộ hoá siêu dữ liệu của thành phần với siêu dữ liệu của đối tượng.

Cấu hình

Về cách định cấu hình COG, TIFF PHẢI:

Thẻ thông tin xếp kề, trong đó kích thước thẻ thông tin là:
- 256x256
- 512x512
- 1024x1024
- 2048x2048
Sắp xếp để tất cả IFD đều ở đầu.

Để có hiệu suất tốt nhất:

Sử dụng kích thước thẻ thông tin từ 512x512 trở lên.
Bao gồm thông tin tổng quan về sức mạnh của 2.

Tuỳ thuộc vào trường hợp sử dụng dự kiến, tuỳ chọn tạo "INTERLEAVE" có thể ảnh hưởng đến hiệu suất. Bạn nên sử dụng tính năng xen kẽ BAND trong mọi trường hợp.

Hãy xem trang này để biết thêm thông tin chi tiết về cấu hình được tối ưu hoá.

Lệnh gdal_translate sau đây sẽ chuyển đổi một ảnh quét thành một GeoTIFF được tối ưu hoá cho đám mây, được nén zstd, được xếp kề theo băng sẽ hoạt động tốt trong 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

Bạn có thể giảm thêm kích thước tệp đầu ra bằng cách chỉ định một trình dự đoán (-co PREDICTOR=2 cho các loại dữ liệu số nguyên và -co PREDICTOR=3 cho các loại dữ liệu dấu phẩy động).

Đối với người dùng có GDAL >= 3.11, trình điều khiển COG có thể tạo các tệp mà không phải lo lắng về việc tạo và lưu giữ thông tin tổng quan.

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 \

Tạo thành phần dựa trên GeoTiff trên đám mây bằng API REST

Lưu ý: API REST chứa các tính năng mới và nâng cao có thể không phù hợp với mọi người dùng. Nếu mới sử dụng Earth Engine, bạn nên bắt đầu bằng hướng dẫn về JavaScript.

Để tạo một thành phần được COG hỗ trợ bằng API REST, hãy tạo một yêu cầu POST đến điểm cuối Earth Engine ImportExternalImage. Như minh hoạ sau, yêu cầu này phải được uỷ quyền để tạo một thành phần trong thư mục người dùng.

Bắt đầu một phiên được uỷ quyền

Để có thể tạo một tài sản Earth Engine trong thư mục người dùng, bạn cần xác thực chính mình khi đưa ra yêu cầu. Bạn có thể sử dụng thông tin xác thực từ trình xác thực Earth Engine để bắt đầu một AuthorizedSession. Sau đó, bạn có thể sử dụng AuthorizedSession để gửi yêu cầu đến 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)
)

Nội dung yêu cầu

Nội dung yêu cầu là một thực thể của ImageManifest. Đây là nơi chỉ định đường dẫn đến COG, cùng với các thuộc tính hữu ích khác.

Hãy xem hướng dẫn này để biết thông tin chi tiết về cách định cấu hình ImageManifest. Bạn có thể xác định một hoặc nhiều Tileset, trong đó mỗi Tileset hỗ trợ một hoặc nhiều dải tần. Đối với ImportExternalImage, mỗi Tileset chỉ hỗ trợ tối đa một ImageSource.

Hãy xem tài liệu này để biết thông tin chi tiết về cách xuất COG.

Gửi yêu cầu

Tạo yêu cầu POST đến điểm cuối Earth Engine projects.images.importExternal.

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

Tài sản Earth Engine dựa trên GeoTiff trên đám mây Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Tệp kê khai hình ảnh mẫu có một Tileset

Nhiều Tileset