Earth Engine은 Google Cloud Storage (GCS)에 저장된 클라우드 최적화 GeoTIFF (COG)로 지원되는 애셋을 지원합니다.
COG 지원 애셋을 등록하면 Earth Engine은 생성 시 이미지의 공간 및 메타데이터 필드를 색인 생성합니다. 이렇게 하면 표준 수집 애셋과 비슷한 성능으로 컬렉션에서 이미지를 사용할 때 성능이 향상됩니다 (클라우드 최적화 GeoTIFF (COG) 개요 참고).
기본 요건 및 Cloud Storage 설정
COG를 등록하기 전에 Google Cloud Storage 리소스를 올바르게 설정해야 합니다.
1. 버킷 위치 (엄격한 요구사항)
Earth Engine이 Cloud Storage 버킷에 액세스하려면 버킷이 다음 데이터 센터 리전 또는 멀티 리전 중 하나에 있어야 합니다.
us멀티 리전us-central1을 포함하는 모든 미국 이중 리전us-central1리전
버킷이 다른 리전 데이터 센터 (예: us-east4 또는 europe-west1)에 배치되면 Earth Engine은 등록 및 읽기 요청을 거부합니다.
2. 스토리지 클래스 및 결제
- 표준 스토리지 클래스를 사용하는 것이 좋습니다. Standard Storage에는 최소 스토리지 기간 규칙이 없으므로 임시 파일을 업데이트하거나 교체하는 경우 조기 삭제 결제 페널티를 방지할 수 있습니다.
- Earth Engine 계산 루프에는 Cloud Storage 데이터 검색 추가 요금이 발생하지 않지만 외부 도구 (예: 데스크톱 GIS 소프트웨어)에서 비표준 스토리지 계층에 액세스하면 비용이 많이 드는 검색 수수료가 발생합니다.
- GCS를 사용하려면 Google Cloud 프로젝트에서 결제를 사용 설정해야 합니다. 시작하려면 Google Cloud Storage 빠른 시작 을 참고하세요.
1단계: COG 준비
TIFF 파일은 클라우드에 최적화되어야 합니다. TIFF는 다음을 충족 해야 합니다.
- 타일식, 타일 크기: 256x256, 512x512, 1024x1024 또는 2048x2048. 최상의 성능을 위해 512x512 이상을 사용하는 것이 좋습니다.
- 모든 이미지 파일 디렉터리 (IFD)가 시작 부분에 있도록 정렬됩니다.
- 2의 거듭제곱 개요를 포함합니다.
- BAND 인터리브를 사용합니다.
GDAL을 사용하여 이미지를 변환할 수 있습니다.
GDAL COG 드라이버 사용 (GDAL >= 3.1 권장):
gdal_translate in.tif out.tif \
-of COG \
-co BIGTIFF=YES \
-co OVERVIEWS=IGNORE_EXISTING \
-co COMPRESS=ZSTD \
-co LEVEL=16 \
-co BLOCKSIZE=512 \
-co INTERLEAVE=BAND \
-co NUM_THREADS=ALL_CPUS \
-co PREDICTOR=2 # 2 for integers, 3 for floating point
표준 GTiff 드라이버 사용:
먼저 내부 2의 거듭제곱 개요를 생성한 후 (gdal raster overview add
또는 gdaladdo 사용) 이미지와 개요를 타일식 COG 레이아웃에 복사합니다.
gdaladdo -r nearest in.tif 2 4 8 16 32 # or -r cubic for continuous/float data
gdal_translate in.tif out.tif \
-co BIGTIFF=YES \
-co COPY_SRC_OVERVIEWS=YES \
-co TILED=YES \
-co BLOCKXSIZE=512 \
-co BLOCKYSIZE=512 \
-co COMPRESS=ZSTD \
-co ZSTD_LEVEL=16 \
-co INTERLEAVE=BAND \
-co NUM_THREADS=ALL_CPUS \
-co PREDICTOR=2 # 2 for integers, 3 for floating point
2단계: 매니페스트 구성
Earth Engine Python 클라이언트 라이브러리, earthengine 명령줄 도구 또는 Earth Engine REST API를 사용하여 COG를 등록하는지 여부에 관계없이 애셋 대상, Google Cloud Storage URI, 선택적 밴드 메타데이터를 지정하는 이미지 업로드 매니페스트를 정의해야 합니다.
예: 모든 밴드를 지원하는 단일 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 }
]
}
3단계: 등록 요청 제출
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. Start the ingestion task (allow_overwrite=True corresponds to --force) result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) print(f"Asset registered: {result['name']}")
명령줄 도구
터미널에서 매니페스트를 파일 이름
manifest.json으로 저장하고 earthengine 업로드
명령어를 실행합니다.
# 1. Verify your environment is authenticated earthengine authenticate # 2. Submit the external image upload task earthengine --project your-project-id \ upload external_image \ --manifest manifest.json
REST API (Python)
클라이언트 라이브러리가 없는 자동화된 워크플로의 경우 승인된
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 등록은 픽셀 데이터를 복사하지 않으므로 이 작업은 일반적으로 몇 초 내에 완료됩니다.
COG 애셋의 매니페스트 제한사항
COG 지원 애셋의 매니페스트를 만들 때는 표준 수집 매니페스트와 다른 다음과 같은 엄격한 제한사항에 유의하세요.
- 단일 버킷: 매니페스트의 모든 URI는 동일한 GCS 버킷에 있어야 합니다.
- 소스당 하나의 URI: 각
ImageSource에는 정확히 하나의 URI가 포함되어야 합니다. 여러 파일을 단일 타일 세트 소스로 모자이크할 수 없습니다. 여러 COG 장면을 모자이크하려면 각 COG를 애셋으로 등록하고.mosaic()를 사용하여ee.ImageCollection으로 결합합니다. mask_bands없음: 최상위mask_bands는 지원되지 않습니다. 매니페스트에서missingData를 사용하거나 TIFF에 내부 nodata 값이 있는지 확인합니다.- 타일 세트에
data_type없음:tilesets섹션에서data_type을 지정하지 마세요. 자동으로 감지됩니다. - 소스에
dimensions없음:dimensions을(를)ImageSource에 지정하지 마세요. subdataset_prefix/subdataset_suffix없음.min_tile_area_ratio또는skip_metadata_read없음.
4단계: 권한 구성 (공유에 중요)
표준 Earth Engine 애셋과 달리 COG의 픽셀 데이터는 GCS에 남아 있습니다. COG 지원 애셋을 다른 사용자와 공유할 때는 Earth Engine 애셋과 GCS 파일 모두에 대한 읽기 액세스 권한을 부여해야 합니다.
1. GCS 버킷 권한 부여
공동작업자에게는 GCS에서 파일을 읽을 수 있는 권한이 필요합니다.
필수 권한:
storage.buckets.get(버킷 메타데이터 및 위치를 검색하기 위한 권한)storage.objects.get(픽셀 데이터를 읽기 위한 권한)
다음 표준 Cloud Storage 역할을 사용하여 이러한 권한을 부여할 수 있습니다.
- 스토리지 버킷 뷰어 (버킷 메타데이터 및 위치를 읽기 위한
storage.buckets.get제공) - 스토리지 객체 뷰어 (픽셀 데이터를 읽기 위한
storage.objects.get제공)
Google Cloud 콘솔에서 구성하는 단계:
- Cloud Storage 브라우저로 이동합니다. .
- 버킷 이름을 클릭합니다.
- 권한 탭을 선택합니다.
- 액세스 권한 부여 를 클릭합니다.
- 공동작업자의 이메일 주소 (또는 Google 그룹 또는 공개 액세스를 위한
allUsers)를 추가합니다. - 스토리지 버킷 뷰어 및 스토리지 객체 뷰어 역할을 할당합니다.
- 저장 을 클릭합니다.
2. Earth Engine 애셋 공유
Earth Engine 애셋 관리자 또는 CLI를 사용하여 애셋 자체를 공유합니다. 자세한 내용은 애셋 관리 가이드를 참고하세요.
객체 세대 관리
COG를 등록하면 Earth Engine은 GCS 객체의 특정 세대(버전)를 저장합니다. GCS에서 파일을 업데이트하면 세대가 변경됩니다.
- 기본적으로 Earth Engine은 애셋 로드에 실패하고 오류를 반환합니다.
Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation. - 이는 메타데이터 (예: 투영 또는 범위)가 기본 픽셀과 동기화되지 않도록 설계되었습니다.
권장사항: 기본 이미지 데이터를 업데이트해야 하는 경우 파일을 직접 덮어쓰는 대신 새 애셋 으로 등록하거나
--force플래그를 사용하여 업로드 명령어를 다시 실행합니다.earthengine --project your-project-id upload external_image --force --manifest manifest.json
등록된 애셋 사용
등록되면 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')