Cloud Optimized GeoTIFF(COG) 애셋 등록

Earth Engine은 Google Cloud Storage (GCS)에 저장된 Cloud Optimized GeoTIFF (COG)에서 지원하는 애셋을 지원합니다.

COG 지원 애셋을 등록하면 Earth Engine은 생성 시 이미지의 공간 및 메타데이터 필드를 색인화합니다. 이렇게 하면 컬렉션에서 사용할 때 이미지가 표준 수집 애셋과 비슷한 성능을 발휘합니다(Cloud Optimized GeoTIFF(COG) 개요 참고).

이 가이드에서는 파일 준비, 매니페스트 작성, 등록 요청 제출, 권한 구성, 등록된 애셋 업데이트 또는 삭제를 다룹니다.

시작하기 전에

COG를 등록하기 전에 Cloud Storage 리소스를 올바르게 설정해야 합니다.

버킷 위치

Earth Engine이 Cloud Storage 버킷에 액세스하려면 버킷이 다음 데이터 센터 리전 또는 멀티 리전 중 하나에 있어야 합니다.

  • us 멀티 리전
  • us-central1를 포함하는 모든 미국 이중 리전
  • us-central1 리전

버킷이 다른 리전 데이터 센터 (예: us-east4 또는 europe-west1)에 배치된 경우 Earth Engine은 등록 및 읽기 요청을 거부합니다. 지원되는 Cloud Storage 버킷 위치를 참조하세요.

스토리지 클래스 및 결제

  • 표준 스토리지 클래스를 사용하는 것이 좋습니다. Standard Storage에는 최소 스토리지 기간 규칙이 없으므로 임시 파일을 업데이트하거나 교체할 때 조기 삭제 청구 페널티가 방지됩니다.
  • Earth Engine 연산 루프에는 Cloud Storage 데이터 검색 부가금이 발생하지 않지만 외부 도구 (예: 데스크톱 GIS 소프트웨어)에서 Standard Storage가 아닌 스토리지 등급에 액세스하면 비용이 많이 드는 검색 수수료가 발생합니다.
  • Cloud Storage를 사용하려면 Google Cloud 프로젝트에서 결제를 사용 설정해야 합니다. 시작하려면 Cloud Storage 빠른 시작을 참조하세요.

COG 준비

Earth Engine은 Cloud Storage에서 직접 COG를 읽고 계산에 필요한 헤더와 타일만 가져오므로 파일 레이아웃이 중요합니다. TIFF는 다음과 같아야 합니다.

  • 타일: 16x16에서 2048x2048까지의 정사각형 2의 거듭제곱 타일 크기입니다. 최상의 성능을 위해 512x512를 사용하는 것이 좋습니다.
  • 모든 이미지 파일 디렉터리 (IFD)가 시작 부분에 오도록 정렬됩니다.
  • 2의 거듭제곱 개요가 있는 경우 포함합니다. 개요는 필수가 아니지만 단일 타일보다 큰 이미지에 권장됩니다.
  • BAND 또는 PIXEL 인터리브를 사용합니다 (장단점은 단일 대역 파일과 다중 대역 파일 비교 참조).

이미지를 변환하려면 GDAL의 COG 드라이버를 사용합니다. 이 드라이버는 한 단계로 필요한 레이아웃 (타일링, 개요, 헤더 배치)을 생성합니다. 범주형 데이터에 OVERVIEW_RESAMPLING=NEAREST를 추가합니다. 기본값은 CUBIC입니다. 압축, 개요, 레이아웃 권장사항은 외부 COG 준비 권장사항을 참조하세요.

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

기존 CLI

3.11 이전 GDAL 버전에서는 INTERLEAVE=BAND를 생략합니다.

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

매니페스트 구성

Earth Engine Python 클라이언트 라이브러리, earthengine 명령줄 도구 또는 Earth Engine REST API를 사용하여 COG를 등록하는지 여부에 관계없이 애셋 대상, Cloud Storage URI, 선택적 밴드 메타데이터를 지정하는 이미지 업로드 매니페스트를 정의해야 합니다. API 및 명령줄 도구는 COG 지원 애셋을 외부 이미지(ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal)라고 합니다.

예: 모든 대역을 지원하는 단일 COG COG에 모든 대역(예: RGB)이 포함된 경우 매니페스트에는 단일 타일 세트만 필요합니다.

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

예시: 여러 COG(대역당 하나) 대역마다 별도의 파일이 있는 경우(예: 빨간색, 녹색, 파란색이 별도의 파일에 있는 경우) 다음 안내를 따르세요.

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

매니페스트 제한사항

COG 지원 애셋의 매니페스트에는 표준 처리 매니페스트에 적용되지 않는 제한사항이 있습니다.

  • 단일 버킷: 매니페스트의 모든 URI는 동일한 Cloud Storage 버킷에 있어야 합니다.
  • 소스당 URI 1개: 각 ImageSource에는 URI가 정확히 1개 포함되어야 합니다. 여러 파일을 단일 타일셋 소스로 모자이크할 수 없습니다. 여러 COG 장면을 모자이크하려면 각 COG를 애셋으로 등록하고 .mosaic()를 사용하여 ee.ImageCollection로 결합합니다.
  • mask_bands 없음: 최상위 mask_bands 필드는 지원되지 않습니다. 매니페스트에서 missingData를 사용하거나 TIFF에 내부 nodata 값이 있는지 확인합니다.
  • 타일 세트에 data_type 없음: tilesets 섹션에 data_type를 지정하지 마세요. 자동으로 감지됩니다.
  • 소스에 dimensions 없음: ImageSource에 dimensions를 지정하지 마세요.
  • subdataset_prefix/subdataset_suffix 없음
  • min_tile_area_ratio 또는 skip_metadata_read 없음.

등록 요청 제출

Earth Engine Python 클라이언트 라이브러리, earthengine 명령줄 도구 또는 Earth Engine REST API를 사용하여 Earth Engine에 매니페스트를 제출할 수 있습니다. 워크플로에 가장 적합한 방법을 선택하세요.

Python 클라이언트 라이브러리

Python 스크립트 또는 Jupyter 노트북에서 프로젝트를 초기화한 후 Earth Engine Python 클라이언트 라이브러리(ee.data)를 사용합니다.

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']}")

명령줄 도구

터미널에서 매니페스트를 manifest.json이라는 파일에 저장하고 earthengine 업로드 명령어를 실행합니다.

# 1. Verify your environment is authenticated
earthengine authenticate

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

REST API

클라이언트 라이브러리가 없는 자동화된 워크플로의 경우 승인된 POST 요청을 Earth Engine REST API 엔드포인트 projects.image.importExternal에 직접 전송합니다(여기서는 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))

등록 요청이 제출되면 경량 메타데이터 색인 생성 작업이 시작됩니다. COG 등록은 픽셀 데이터를 복사하지 않으므로 이 작업은 일반적으로 몇 초 내에 완료됩니다.

권한 구성

표준 Earth Engine 애셋과 달리 COG의 픽셀 데이터는 Cloud Storage에 남아 있습니다. COG 지원 애셋을 다른 사용자와 공유할 때는 Earth Engine 애셋과 Cloud Storage 파일 모두에 대한 읽기 액세스 권한을 부여해야 합니다.

Cloud Storage 버킷 권한 부여

공동작업자에게는 Cloud Storage에서 파일을 읽을 수 있는 권한이 필요합니다.

필수 권한:

  • storage.buckets.get (버킷 메타데이터 및 위치 검색)
  • storage.objects.get (픽셀 데이터 읽기)

다음 표준 Cloud Storage 역할을 사용하여 이러한 권한을 부여할 수 있습니다.

  • 스토리지 버킷 뷰어 (버킷 메타데이터 및 위치를 읽을 수 있는 storage.buckets.get 제공)
  • 스토리지 객체 뷰어 (픽셀 데이터를 읽을 수 있는 storage.objects.get 제공)

Google Cloud 콘솔에서 구성하는 단계:

  1. Cloud Storage 브라우저로 이동합니다.
  2. 버킷 이름을 클릭합니다.
  3. 권한 탭을 선택합니다.
  4. 액세스 권한 부여를 클릭합니다.
  5. 공동작업자의 이메일 주소 (또는 Google 그룹스, 공개 액세스의 경우 allUsers)를 추가합니다.
  6. 스토리지 버킷 뷰어 및 스토리지 객체 뷰어 역할을 할당합니다.
  7. 저장을 클릭합니다.

Earth Engine 애셋 공유

Earth Engine 애셋 관리자 또는 CLI를 사용하여 애셋 자체를 공유합니다. 자세한 내용은 저작물 관리 가이드를 참고하세요.

COG 지원 애셋 업데이트, 교체, 삭제

COG 지원 애셋은 Cloud Storage에 있는 특정 버전의 파일에 대한 포인터와 등록 시 Earth Engine에서 색인을 생성한 메타데이터 (풋프린트, 투영, 밴드, 개요 레이아웃)입니다. Earth Engine은 이 메타데이터가 픽셀과 동기화되지 않도록 파일 버전을 고정합니다. 이로 인해 COG 지원 애셋 업데이트가 표준 애셋 업데이트와 다릅니다.

객체 생성

COG를 등록하면 Earth Engine은 URI와 함께 Cloud Storage 객체의 세대(버전 번호)를 기록합니다. 애셋의 메타데이터에서 고정된 생성을 확인할 수 있습니다. URI에 #<generation> 서픽스로 표시됩니다.

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

애셋을 등록 (또는 재등록)할 때 매니페스트 URI에 #<generation> 서픽스를 포함하여 특정 버전을 직접 고정할 수도 있습니다. 이 옵션이 없으면 Earth Engine은 현재 객체를 읽고 찾은 세대를 고정합니다. 명시적으로 고정하는 것은 객체 버전 관리가 있는 버킷이 보관한 이전 버전으로 롤백하는 데 유용합니다.

Cloud Storage에서 파일을 덮어쓰면 새 세대가 생성되고, 삭제하면 고정된 세대가 사라집니다. 어느 경우든 버킷의 객체 버전 관리가 이전 세대를 유지하지 않는 한 애셋의 픽셀을 읽지 못합니다. 이 경우 Earth Engine은 이전 픽셀을 계속 읽습니다. 색인이 생성된 레코드를 사용하는 메타데이터 작업 (예: ee.data.getAsset(), bandNames(), 컬렉션 필터링)은 어느 쪽이든 계속 작동합니다.

파일을 변경한 후 애셋 업데이트

기존 애셋을 새 버전의 파일로 가리키려면 동일한 애셋 이름으로 다시 등록하고 덮어쓰기를 사용 설정합니다. Earth Engine은 단일 동기 호출에서 GeoTIFF 헤더를 다시 읽고, 메타데이터의 색인을 다시 생성하고, 새 세대를 고정합니다. 애셋의 기존 권한은 유지되지만 속성, 기간, 밴드 이름은 새 매니페스트에서 가져오므로 이전에 ee.data.updateAsset()로 설정한 모든 항목을 포함합니다.

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • 명령줄: earthengine upload external_image --force --manifest manifest.json
  • REST API: projects.image.importExternal 요청 본문에 "imageManifest"와 함께 "overwrite": true를 최상위 필드로 포함합니다.

애셋을 먼저 삭제할 필요가 없으며 삭제하면 역효과가 발생합니다. 독립형 애셋은 권한을 잃고 컬렉션의 이미지는 컬렉션에서 잠시 사라집니다. ee.data.updateAsset()(projects.assets.patch)는 속성, 기간, 대역 이름만 변경할 수 있으며 애셋이 가리키는 파일은 변경할 수 없습니다.

독립적인 수명 주기

Earth Engine 애셋과 Cloud Storage 객체는 별도로 관리됩니다.

  • Earth Engine 애셋 (earthengine rm 또는 ee.data.deleteAsset())을 삭제하면 애셋 레코드만 삭제됩니다. Cloud Storage의 파일은 그대로 유지됩니다.
  • Cloud Storage에서 파일을 삭제해도 애셋은 삭제되지 않으며 목록과 컬렉션에 계속 표시됩니다(객체 세대 참조).

대규모 컬렉션 작업

Earth Engine API에는 일괄 삭제 또는 재귀 삭제가 없습니다. 각 애셋은 개별적으로 삭제해야 하며 컬렉션은 비어 있어야 삭제할 수 있습니다. earthengine rm -r는 이 작업을 자동으로 처리하지만 삭제를 한 번에 하나씩 실행하므로 수만 개의 이미지가 있는 컬렉션을 삭제하는 데 몇 시간이 걸릴 수 있습니다.

  • 컬렉션의 이미지를 바꾸려면 삭제하지 말고 덮어쓰세요. 덮어쓰기를 사용 설정한 상태에서 각 이미지를 이름으로 다시 등록합니다 (위 참고). 이렇게 하면 이미지당 요청이 2개가 아닌 1개만 필요하고, 컬렉션이 계속 채워진 상태로 유지되며, 권한이 있는 컬렉션 자체를 삭제하고 다시 만들지 않아도 됩니다. 새 세트에 없는 이미지만 삭제합니다.
  • 여러 애셋을 삭제하려면 스크립트에서 병렬화합니다. ee.data.listAssets()를 사용하여 애셋을 나열하고(모든 이미지의 전체 메타데이터가 아닌 이름과 유형만 반환하는 BASIC 뷰 사용) 작은 스레드 풀에서 삭제합니다. 애셋 요청은 프로젝트 전체 비율 제한을 공유하므로 동시 실행을 적당히 유지하고 (약 10명의 작업자) 클라이언트 라이브러리의 기본 제공 재시도가 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)
    

    모든 이미지가 삭제된 경우에만 컬렉션이 삭제되므로 부분적으로 실패하면 다시 실행할 수 있도록 그대로 유지됩니다.

    여러 이미지를 등록할 때도 동일한 패턴이 적용됩니다. 도우미의 ee.data.deleteAsset(asset_id)를 ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)로 바꾸고 매니페스트 목록에 매핑합니다. 첫 번째 실행에서도 allow_overwrite=True를 전달하면 이미 생성된 애셋이 오류를 일으키는 대신 대체되므로 부분 실패 후 일괄 작업을 안전하게 다시 실행할 수 있습니다.

등록된 애셋 사용

등록되면 COG 지원 애셋은 표준 수집 이미지 애셋과 마찬가지로 Earth Engine 스크립트에서 액세스됩니다.

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

권한, 파일 업데이트, 대규모 컬렉션 관리에 관한 일반적인 질문과 답변은 FAQ의 COG 섹션을 참조하세요.