이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Cloud GeoTiff 기반 Earth Engine 애셋

Earth Engine은 클라우드 최적화 GeoTIFF (COG)를 기반으로 하는 애셋을 지원합니다. COG 지원 확장 소재의 장점은 확장 소재 생성 시 이미지의 공간 및 메타데이터 필드가 색인이 생성되므로 컬렉션에서 이미지의 성능이 향상된다는 점입니다. COG 지원 애셋의 실적은 일반적인 사용 사례에서 처리된 애셋의 실적과 비슷합니다.

단일 확장 소재가 여러 COG의 지원을 받을 수 있습니다 (예: 밴드당 COG가 하나 있을 수 있음). 단, 단일 밴드에 여러 COG 타일을 사용하는 것은 지원되지 않습니다.

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

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

COG 파일을 GCS 버킷에 배치합니다 (허용되는 리전은 아래 참고).
이미지 업로드 매니페스트 작성
earthengine 명령줄 유틸리티를 사용하여 업로드 명령어를 전송합니다.

earthengine upload external_image --manifest my_manifest.json

`Tileset`가 하나 있는 샘플 이미지 매니페스트

가장 단순한 ImageManifest는 단일 Tileset가 있는 ImageManifest입니다. 지정된 밴드가 없으면 결과 애셋에는 GeoTIFF에 인코딩된 밴드 이름 (이 경우 'vis-red', 'vis-green', 'vis-blue')이 포함된 GeoTIFF의 모든 밴드가 포함됩니다.

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` 2개 이상

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 리전

스토리지 클래스

버킷의 스토리지 클래스는 '표준 스토리지'여야 합니다.

공유 권한

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 지원 애셋 데이터 읽기)

이러한 권한은 기타 역할 중 'Storage Legacy Bucket Reader' 및 'Storage Legacy Object Reader'에 의해 제공됩니다.

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

버킷 권한 페이지로 이동합니다. 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의 메타데이터를 읽고 애셋 스토어 항목을 만듭니다. 해당 항목과 연결된 각 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 압축, 클라우드 최적화 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 지원 애셋을 만들려면 Earth Engine ImportExternalImage 엔드포인트에 POST 요청을 보냅니다. 다음과 같이 이 요청이 승인되어야 사용자 폴더에 저작물을 만들 수 있습니다.

승인된 세션 시작

사용자 폴더에 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를 하나 이상 정의할 수 있습니다. ImportExternalImage의 경우 Tileset당 최대 1개의 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))

Cloud GeoTiff 기반 Earth Engine 애셋 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Tileset가 하나 있는 샘플 이미지 매니페스트

Tileset 2개 이상