Đăng ký thành phần GeoTIFF được tối ưu hoá cho đám mây (COG)

Earth Engine hỗ trợ các thành phần được hỗ trợ bởi GeoTIFF được tối ưu hoá cho đám mây (COG) được lưu trữ trong Google Cloud Storage (GCS).

Khi bạn đăng ký một thành phần dựa trên COG, Earth Engine sẽ lập chỉ mục các trường không gian và siêu dữ liệu của hình ảnh tại thời điểm tạo. Điều này giúp hình ảnh hoạt động hiệu quả khi được dùng trong các tập hợp, với hiệu suất tương đương với các thành phần được nhập chuẩn (xem phần Tổng quan về GeoTIFF được tối ưu hoá cho đám mây (COG)).

Hướng dẫn này trình bày cách chuẩn bị tệp, viết tệp kê khai, gửi yêu cầu đăng ký, định cấu hình quyền và cập nhật hoặc xoá tài sản đã đăng ký.

Trước khi bắt đầu

Trước khi đăng ký COG, bạn phải thiết lập đúng cách các tài nguyên Cloud Storage.

Vị trí bộ chứa

Để Earth Engine truy cập vào bộ chứa Cloud Storage của bạn, bộ chứa đó phải nằm ở một trong những khu vực hoặc nhiều khu vực trung tâm dữ liệu sau:

  • Đa vùng us
  • Bất kỳ vùng kép nào ở Hoa Kỳ có chứa us-central1
  • Khu vực us-central1

Nếu bộ chứa của bạn được đặt ở bất kỳ trung tâm dữ liệu khu vực nào khác (chẳng hạn như us-east4 hoặc europe-west1), thì Earth Engine sẽ từ chối yêu cầu đăng ký và đọc. Xem các vị trí được hỗ trợ của bộ chứa Cloud Storage.

Lớp lưu trữ và việc thanh toán

  • Bạn nên sử dụng lớp lưu trữ Standard. Bộ nhớ tiêu chuẩn không có quy tắc về thời gian lưu trữ tối thiểu, giúp tránh bị phạt phí xoá sớm nếu bạn cập nhật hoặc thay thế các tệp tạm thời.
  • Mặc dù các vòng lặp tính toán của Earth Engine không phát sinh phụ phí truy xuất dữ liệu của Cloud Storage, nhưng việc truy cập vào các cấp bộ nhớ không phải là bộ nhớ Tiêu chuẩn từ các công cụ bên ngoài (chẳng hạn như phần mềm GIS dành cho máy tính) sẽ phát sinh phí truy xuất tốn kém.
  • Bạn phải bật tính năng thanh toán trong dự án Google Cloud để sử dụng Cloud Storage. Hãy xem phần bắt đầu nhanh về Cloud Storage để bắt đầu.

Chuẩn bị COG

Earth Engine đọc COG trực tiếp từ Cloud Storage, chỉ tìm nạp tiêu đề và các ô mà một phép tính cần, vì vậy, bố cục tệp rất quan trọng. Tệp TIFF phải:

  • Xếp kề, với kích thước ô vuông luỹ thừa của 2 từ 16x16 đến 2048x2048. Bạn nên dùng kích thước 512x512 để có hiệu suất tốt nhất.
  • Được sắp xếp sao cho tất cả Thư mục tệp hình ảnh (IFD) đều nằm ở đầu.
  • Bao gồm thông tin tổng quan về luỹ thừa của 2 (nếu có). Bạn không bắt buộc phải có thông tin tổng quan, nhưng nên có thông tin này đối với hình ảnh lớn hơn một ô.
  • Sử dụng xen kẽ BAND hoặc PIXEL (xem tệp đơn băng tần so với tệp đa băng tần để biết các điểm đánh đổi).

Để chuyển đổi hình ảnh, hãy sử dụng trình điều khiển COG của GDAL. Trình điều khiển này sẽ tạo bố cục bắt buộc (vị trí xếp kề, tổng quan và tiêu đề) trong một bước. Thêm OVERVIEW_RESAMPLING=NEAREST cho dữ liệu phân loại; giá trị mặc định là CUBIC. Để biết các đề xuất về việc nén, tổng quan và bố cục, hãy xem các phương pháp hay nhất để chuẩn bị COG bên ngoài.

GDAL 3.11+ CLI

gdal raster convert in.tif out.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co OVERVIEWS=IGNORE_EXISTING \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

Classic CLI

Bỏ qua INTERLEAVE=BAND trên các phiên bản GDAL cũ hơn 3.11.

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

Tạo tệp kê khai

Cho dù bạn đăng ký COG bằng thư viện ứng dụng Python của Earth Engine, công cụ dòng lệnh earthengine hay API REST của Earth Engine, bạn đều phải xác định tệp kê khai tải lên hình ảnh, trong đó chỉ định đích đến của thành phần, URI Cloud Storage và siêu dữ liệu dải tần (không bắt buộc). API và công cụ dòng lệnh gọi các thành phần dựa trên COG là hình ảnh bên ngoài (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal).

Ví dụ: Một COG hỗ trợ tất cả các dải Nếu COG của bạn chứa tất cả các dải (ví dụ: RGB), thì tệp kê khai chỉ cần một tập hợp ô:

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

Ví dụ: Nhiều COG (mỗi dải một COG) Nếu bạn có các tệp riêng biệt cho các dải khác nhau (ví dụ: đỏ, lục và lam trong các tệp riêng biệt):

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

Quy tắc hạn chế trong tệp kê khai

Tệp kê khai cho các thành phần được COG hỗ trợ có những quy định hạn chế không áp dụng cho tệp kê khai nhập dữ liệu chuẩn:

  • Một bộ chứa: Tất cả URI trong tệp kê khai phải nằm trong cùng một bộ chứa Cloud Storage.
  • Một URI cho mỗi nguồn: Mỗi ImageSource phải chứa đúng một URI. Bạn không thể ghép nhiều tệp thành một nguồn nhóm ô duy nhất. Để ghép nhiều cảnh COG, hãy đăng ký từng COG dưới dạng một thành phần rồi kết hợp chúng thành một ee.ImageCollection bằng .mosaic().
  • Không mask_bands: Trường mask_bands cấp cao nhất không được hỗ trợ. Sử dụng missingData trong tệp kê khai hoặc đảm bảo TIFF của bạn có giá trị nodata nội bộ.
  • Không có data_type trong nhóm thẻ thông tin: Đừng chỉ định data_type trong phần tilesets; phần này được phát hiện tự động.
  • Không có dimensions trong nguồn: Đừng chỉ định dimensions trong ImageSource.
  • Không subdataset_prefix / subdataset_suffix.
  • Không có min_tile_area_ratio hoặc skip_metadata_read.

Gửi yêu cầu đăng ký

Bạn có thể gửi tệp kê khai đến Earth Engine bằng thư viện ứng dụng Python của Earth Engine, công cụ dòng lệnh earthengine hoặc API REST của Earth Engine. Hãy chọn phương thức phù hợp nhất với quy trình làm việc của bạn.

Thư viện ứng dụng Python

Trong tập lệnh Python hoặc sổ tay Jupyter, hãy sử dụng thư viện ứng dụng Python của Earth Engine (ee.data) sau khi khởi chạy dự án:

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. Register the asset
result = ee.data.startExternalImageIngestion(manifest)
print(f"Asset registered: {result['name']}")

Công cụ dòng lệnh

Trong cửa sổ dòng lệnh, hãy lưu tệp kê khai vào một tệp có tên là manifest.json rồi chạy lệnh tải lên earthengine:

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Register the asset
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

API REST

Đối với quy trình công việc tự động không có thư viện ứng dụng, hãy gửi trực tiếp một yêu cầu POST được uỷ quyền đến điểm cuối của Earth Engine API REST projects.image.importExternal (được minh hoạ tại đây bằng 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))

Sau khi được gửi, yêu cầu đăng ký sẽ bắt đầu một thao tác lập chỉ mục siêu dữ liệu đơn giản. Vì quá trình đăng ký COG không sao chép dữ liệu pixel, nên thao tác này thường hoàn tất trong vài giây.

Định cấu hình quyền

Không giống như các thành phần Earth Engine tiêu chuẩn, dữ liệu pixel của COG vẫn nằm trong Cloud Storage. Khi chia sẻ tài sản dựa trên COG với người khác, bạn phải cấp cho họ quyền đọc cả tài sản Earth Engine và tệp Cloud Storage.

Cấp quyền cho bộ chứa Cloud Storage

Cộng tác viên cần có quyền đọc tệp trong Cloud Storage.

Các quyền bắt buộc:

  • storage.buckets.get (để truy xuất siêu dữ liệu và vị trí của bộ chứa)
  • storage.objects.get (để đọc dữ liệu pixel)

Bạn có thể cấp các quyền này bằng cách sử dụng các vai trò Cloud Storage tiêu chuẩn sau:

  • Storage Bucket Viewer (cung cấp storage.buckets.get để đọc siêu dữ liệu và vị trí của bộ chứa)
  • Storage Object Viewer (Người xem đối tượng lưu trữ) (cung cấp storage.objects.get để đọc dữ liệu pixel)

Các bước định cấu hình trong Google Cloud Console:

  1. Chuyển đến Trình duyệt Cloud Storage.
  2. Nhấp vào tên bộ chứa của bạn.
  3. Chọn thẻ Quyền.
  4. Nhấp vào CẤP QUYỀN TRUY CẬP.
  5. Thêm địa chỉ email của cộng tác viên (hoặc một nhóm trên Google Groups, hoặc allUsers để cấp quyền truy cập công khai).
  6. Chỉ định vai trò Storage Bucket Viewer (Người xem bộ chứa lưu trữ) và Storage Object Viewer (Người xem đối tượng lưu trữ).
  7. Nhấp vào Lưu.

Chia sẻ tài sản Earth Engine

Chia sẻ chính tài sản đó bằng Trình quản lý tài sản Earth Engine hoặc CLI. Hãy xem Hướng dẫn quản lý tài sản để biết thông tin chi tiết.

Cập nhật, thay thế và xoá các thành phần do COG hỗ trợ

Thành phần dựa trên COG là một con trỏ đến một phiên bản cụ thể của tệp trong Cloud Storage, cộng với siêu dữ liệu (dấu vết, phép chiếu, dải và bố cục tổng quan) mà Earth Engine đã lập chỉ mục khi bạn đăng ký. Earth Engine ghim phiên bản tệp để siêu dữ liệu này không bị lệch khỏi các pixel. Đây là điểm khác biệt giữa việc cập nhật tài sản dựa trên COG và cập nhật tài sản tiêu chuẩn.

Thế hệ đối tượng

Khi bạn đăng ký COG, Earth Engine sẽ ghi lại thế hệ (số phiên bản) của đối tượng Cloud Storage cùng với URI. Bạn có thể xem thế hệ được ghim trong siêu dữ liệu của tài sản; thế hệ này xuất hiện dưới dạng hậu tố #<generation> trên URI:

Python

asset = ee.data.getAsset('projects/your-project-id/assets/my_cog_asset')
print(asset['tilesets'][0]['sources'][0]['uris'])
# ['gs://google-sample-bucket/my_optimized_image.tif#1750427474244728']

Bạn cũng có thể tự ghim một phiên bản cụ thể bằng cách thêm hậu tố #<generation> vào URI tệp kê khai khi đăng ký (hoặc đăng ký lại) thành phần. Nếu không, Earth Engine sẽ đọc đối tượng hiện tại và ghim bất kỳ thế hệ nào mà nó tìm thấy. Việc ghim rõ ràng sẽ hữu ích khi khôi phục về phiên bản cũ hơn mà một bộ chứa có tính năng tạo phiên bản đối tượng đã giữ lại.

Nếu bạn ghi đè tệp trong Cloud Storage, tệp đó sẽ có một thế hệ mới và nếu bạn xoá tệp, thế hệ được ghim sẽ biến mất. Dù bằng cách nào, việc đọc pixel của thành phần cũng sẽ không thành công, trừ phi tính năng tạo phiên bản đối tượng trên bộ chứa giữ lại thế hệ cũ. Trong trường hợp đó, Earth Engine sẽ tiếp tục đọc các pixel cũ. Các thao tác siêu dữ liệu sử dụng bản ghi được lập chỉ mục (chẳng hạn như ee.data.getAsset(), bandNames() và lọc tập hợp) vẫn hoạt động bình thường.

Cập nhật tài sản sau khi thay đổi tệp của tài sản đó

Để trỏ một thành phần hiện có đến phiên bản mới của tệp, hãy đăng ký lại thành phần đó bằng cùng tên thành phần và bật chế độ ghi đè. Earth Engine đọc lại tiêu đề GeoTIFF, lập chỉ mục lại siêu dữ liệu và ghim thế hệ mới trong một lệnh gọi đồng bộ duy nhất. Các quyền hiện có của thành phần được giữ nguyên, nhưng các thuộc tính, phạm vi thời gian và tên dải tần của thành phần đó sẽ được lấy từ tệp kê khai mới, vì vậy, hãy thêm mọi thông tin bạn đã đặt trước đó bằng ee.data.updateAsset().

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Dòng lệnh: earthengine upload external_image --force --manifest manifest.json
  • API REST: thêm "overwrite": true làm trường cấp cao nhất cùng với "imageManifest" trong nội dung yêu cầu projects.image.importExternal.

Bạn không cần phải xoá thành phần trước và việc xoá thành phần sẽ phản tác dụng: một thành phần độc lập sẽ mất quyền và một hình ảnh trong bộ sưu tập sẽ biến mất khỏi bộ sưu tập trong thời gian ngắn. Xin lưu ý rằng ee.data.updateAsset() (projects.assets.patch) chỉ có thể thay đổi các thuộc tính, phạm vi thời gian và tên dải tần; chứ không thể thay đổi tệp mà một thành phần trỏ đến.

Vòng đời độc lập

Tài sản Earth Engine và đối tượng Cloud Storage được quản lý riêng biệt:

  • Khi bạn xoá tài sản Earth Engine (earthengine rm hoặc ee.data.deleteAsset()), chỉ có bản ghi tài sản bị xoá. Các tệp của bạn trong Cloud Storage vẫn được giữ nguyên.
  • Việc xoá tệp trong Cloud Storage không xoá thành phần; thành phần đó vẫn xuất hiện trong trang thông tin và trong bộ sưu tập của thành phần (xem phần thế hệ đối tượng).

Làm việc với các tập hợp lớn

Không có tính năng xoá theo lô hoặc xoá đệ quy trong API Earth Engine: mỗi thành phần phải được xoá riêng lẻ và một tập hợp phải trống thì mới có thể xoá. earthengine rm -r sẽ xử lý việc này cho bạn nhưng sẽ xoá từng mục một, vì vậy, một bộ sưu tập có hàng chục nghìn hình ảnh có thể mất hàng giờ để xoá.

  • Để thay thế hình ảnh của một bộ sưu tập, hãy ghi đè thay vì xoá. Đăng ký lại từng hình ảnh theo tên và bật chế độ ghi đè (xem ở trên). Cách này chỉ cần một yêu cầu cho mỗi hình ảnh thay vì hai yêu cầu, giúp bộ sưu tập luôn có dữ liệu và tránh việc xoá rồi tạo lại chính bộ sưu tập đó (nơi lưu trữ các quyền của bộ sưu tập). Chỉ xoá những hình ảnh không có trong nhóm mới.
  • Để xoá nhiều thành phần, hãy thực hiện song song bằng một tập lệnh. Liệt kê các thành phần bằng ee.data.listAssets() (sử dụng chế độ xem BASIC, chỉ trả về tên và loại thay vì siêu dữ liệu đầy đủ cho mọi hình ảnh) và xoá các thành phần đó khỏi một nhóm luồng nhỏ. Yêu cầu về thành phần chia sẻ giới hạn số lượng yêu cầu trên toàn dự án, vì vậy, hãy giữ cho tính đồng thời ở mức vừa phải (khoảng 10 worker) và để các lần thử lại tích hợp sẵn của thư viện ứng dụng xử lý mọi phản hồi 429 Too Many Requests:

    Python

    import concurrent.futures
    import ee
    
    ee.Initialize(project='your-project-id')
    collection = 'projects/your-project-id/assets/my_collection'
    
    listing = ee.data.listAssets({'parent': collection, 'view': 'BASIC'})
    asset_ids = [a['name'] for a in listing['assets']]
    
    def delete(asset_id):
      try:
        ee.data.deleteAsset(asset_id)
      except ee.EEException as e:
        return f'{asset_id}: {e}'
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
      failures = [f for f in executor.map(delete, asset_ids) if f]
    
    if failures:
      print('\n'.join(failures))
    else:
      ee.data.deleteAsset(collection)
    

    Bộ sưu tập chỉ bị xoá nếu mọi hình ảnh đều bị xoá, vì vậy, nếu không xoá được một phần thì bộ sưu tập sẽ được giữ nguyên để chạy lại.

    Mẫu tương tự áp dụng cho việc đăng ký nhiều hình ảnh: thay thế ee.data.deleteAsset(asset_id) trong trình trợ giúp bằng ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) và liên kết mẫu đó với danh sách tệp kê khai của bạn. Việc truyền allow_overwrite=True ngay cả trong lần chạy đầu tiên giúp lô an toàn để chạy lại sau khi không thành công một phần, vì mọi thành phần đã được tạo đều được thay thế thay vì gây ra lỗi.

Sử dụng tài sản đã đăng ký

Sau khi đăng ký, bạn có thể truy cập vào một thành phần được COG hỗ trợ trong tập lệnh Earth Engine giống như bất kỳ thành phần hình ảnh chuẩn nào được nhập:

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

Để biết câu trả lời cho các câu hỏi thường gặp về quyền, cách cập nhật tệp và quản lý các tập hợp lớn, hãy xem phần COG trong Câu hỏi thường gặp.