Cloud GeoTiff 기반 Earth Engine 애셋

Colab 로고 Google Colab에서 실행 GitHub 로고 GitHub에서 소스 보기

Earth Engine은 Cloud Optimized GeoTIFF (COG)로 지원되는 애셋을 지원합니다. COG로 지원되는 애셋의 장점은 애셋 생성 시 이미지의 공간 및 메타데이터 필드가 색인되어 컬렉션에서 이미지의 성능이 향상된다는 것입니다. COG로 지원되는 애셋의 성능은 일반적인 사용 사례에서 수집된 애셋의 성능과 비슷합니다.

단일 애셋은 여러 COG로 지원될 수 있습니다 (예: 밴드당 하나의 COG가 있을 수 있음). 하지만 단일 밴드에 여러 COG 타일을 사용하는 것은 지원되지 않습니다.

(또는 Earth Engine은 Google Cloud Storage의 COG에서 이미지를 직접 로드할 수 있습니다 (자세히 알아보기). 하지만 ee.Image.loadGeoTIFF를 통해 로드되고 이미지 컬렉션에 추가된 이미지는 컬렉션의 필터링 작업을 위해 GeoTiff를 읽어야 합니다.)

COG로 지원되는 애셋을 만들려면 다음 단계를 따르세요.

  1. COG 파일을 GCS 버킷에 넣습니다 (허용되는 리전은 위치 참고).
  2. 이미지 업로드 매니페스트 작성
  3. earthengine 명령줄 유틸리티를 사용하여 업로드 명령어를 보냅니다.
earthengine upload external_image --manifest my_manifest.json

Tileset이 하나인 샘플 이미지 매니페스트

가장 간단한 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이 두 개 이상인 경우

tilesetId 및 tilesetBandIndex 필드를 사용하여 결과 애셋의 각 밴드가 Tileset의 밴드 중 하나로 지원되는 Tileset이 두 개 이상인 ImageManifest를 지정할 수 있습니다. 이는 밴드마다 해상도 또는 데이터 유형이 다른 경우에 유용합니다. 밴드는 사용 가능한 Tileset에서 임의의 순서로 나열할 수 있습니다. 아래 예시를 참조하세요.

  • 'b4b3b2.tif'의 축척은 10m이고 'b5b6b7'의 축척은 20m입니다.
  • 결과 애셋의 밴드 순서는 입력 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

스토리지 클래스

버킷의 스토리지 클래스는 "Standard Storage"여야 합니다.

공유 권한

COG로 지원되는 Earth Engine 애셋과 기본 데이터의 ACL은 별도로 관리됩니다. 읽기 위해 공동작업자와 COG로 지원되는 애셋을 공유할 때 Earth Engine 애셋과 기본 COG 파일 모두에 읽기 액세스 권한을 부여하는 것은 소유자의 책임입니다.

1. 읽기용 Google Cloud Storage 버킷 권한 부여

공동작업자가 COG로 지원되는 애셋을 읽으려면 먼저 Google Cloud Storage 버킷의 기본 COG 파일에 대한 읽기 액세스 권한이 있어야 합니다. 이러한 권한이 없으면 Earth Engine에서 공동작업자를 위한 데이터를 가져올 수 없습니다. Google Cloud Storage의 데이터가 Earth Engine 사용자에게 표시되지 않으면 Earth Engine에서 'gs://my-bucket/my-object#123456에서 GeoTIFF를 로드하지 못했습니다' 형식의 오류를 반환합니다(여기서 123456은 객체의 생성입니다).

특히 공동작업자에게는 다음 권한이 있어야 합니다.

  • 버킷에 대한 storage.buckets.get (버킷 메타데이터 및 위치를 가져와 Earth Engine에서 애셋의 소스를 올바르게 확인할 수 있도록 함)
  • 버킷에 대한 storage.objects.get (실제 COG로 지원되는 애셋 데이터 읽기)

이러한 권한은 다른 권한 중에서 각각 '스토리지 기존 버킷 리더' 및 '스토리지 기존 객체 리더' 역할에서 제공됩니다.

공동작업자에게 이러한 역할을 할당하려면 다음 단계를 따르세요.

  1. 버킷 권한 페이지로 이동합니다. https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. "액세스 권한 부여"를 클릭합니다.
  3. 읽기 액세스 권한을 부여해야 하는 모든 주 구성원 (예: 사용자, 그룹, 서비스 계정)을 추가합니다.
  4. 다음 역할을 할당합니다.
    • "스토리지 기존 버킷 리더" (storage.buckets.get 및 기타 버킷 수준 읽기 권한 제공)
    • "스토리지 기존 객체 리더" (storage.objects.get 제공)
    • (또는 storage.buckets.get 및 storage.objects.get 권한만 있는 새 커스텀 역할을 만들어 할당할 수 있습니다.)
  5. 저장

2. 읽기용 Earth Engine 애셋 공유

공동작업자에게 기본 GCS 버킷 및 객체에 대한 필요한 권한이 있는지 확인한 후에는 Earth Engine 애셋 자체도 공유해야 합니다. Earth Engine 애셋 권한 설정에 대한 자세한 내용은 Earth Engine 애셋 관리 가이드를 참고하세요.

세대

COG로 지원되는 애셋이 생성되면 Earth Engine은 매니페스트에 지정된 TIFF의 메타데이터를 읽고 애셋 저장소 항목을 만듭니다. 해당 항목과 연결된 각 URI에는 생성이 있을 수 있습니다. 생성에 대한 자세한 내용은 객체 버전 관리 문서를 참고하세요. 생성이 지정된 경우(예: gs://foo/bar#123) Earth Engine은 해당 URI를 그대로 저장합니다. 생성이 지정되지 않은 경우 Earth Engine은 ImportExternalImage가 호출될 때 TIFF의 생성으로 해당 URI를 저장합니다.

즉, GCS의 외부 애셋을 구성하는 TIFF가 업데이트되어 생성이 변경되면 버킷에서 여러 객체 버전을 사용 설정하지 않는 한 예상 객체가 더 이상 존재하지 않으므로 Earth Engine에서 'gs://my-bucket/my-object#123456에서 GeoTIFF를 로드하지 못했습니다' 오류를 반환합니다. 이 정책은 애셋의 메타데이터를 객체의 메타데이터와 동기화하도록 설계되었습니다.

구성

COG를 구성하는 방법과 관련하여 TIFF는 다음을 충족해야 합니다.

  • 타일 크기가 다음 중 하나인 타일 형식이어야 합니다.

    • 256x256
    • 512x512
    • 1024x1024
    • 2048x2048

  • 모든 IFD가 시작 부분에 있도록 정렬되어야 합니다.

최상의 성능을 위해 다음을 수행하세요.

  • 타일 크기를 512x512 이상으로 사용합니다.
  • 2의 거듭제곱 개요를 포함합니다.

의도한 사용 사례에 따라 'INTERLEAVE' 생성 옵션이 성능에 영향을 미칠 수 있습니다. 모든 상황에서 BAND 인터리브를 사용하는 것이 좋습니다.

최적화된 구성에 대한 자세한 내용은 이 페이지를 참고하세요.

다음 gdal_translate 명령어는 Earth Engine에서 잘 작동하는 밴드 인터리브, zstd 압축, Cloud Optimized GeoTIFF로 래스터를 변환합니다.

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 \

REST API를 사용하여 Cloud GeoTiff로 지원되는 애셋 만들기

참고: REST API에는 일부 사용자에게 적합하지 않을 수 있는 새로운 고급 기능이 포함되어 있습니다. Earth Engine을 처음 사용하는 경우 JavaScript 가이드로 시작하는 것이 좋습니다.

REST API를 사용하여 COG로 지원되는 애셋을 만들려면 POST 요청을 Earth Engine ImportExternalImage 엔드포인트에 보냅니다. 다음과 같이 이 요청은 사용자 폴더에 애셋을 만들 수 있도록 승인되어야 합니다.

승인된 세션 시작

사용자 폴더에서 Earth Engine 애셋을 만들려면 요청을 할 때 본인으로 인증할 수 있어야 합니다. Earth Engine 인증 도구의 사용자 인증 정보를 사용하여 `AuthorizedSession`을 시작할 수 있습니다. 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을 정의할 수 있습니다. ImportExternalImage의 경우 Tileset당 최대 하나의 ImageSource가 지원됩니다.

COG 내보내기에 대한 자세한 내용은 이 문서 를 참고하세요.

요청 전송

Earth Engine projects.images.importExternal 엔드포인트에 POST 요청을 보냅니다.

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