Microsoft Planetary Computer Pro 데이터 탐색기 또는 Tiler API를 사용하여 지리 공간적 데이터를 시각화하려면 STAC(SpatioTemporal Asset Catalog) 컬렉션에 대한 렌더링 구성 을 정의해야 합니다. 렌더링 구성은 STAC 항목 내의 데이터 자산을 결합, 처리 및 스타일 지정하여 지도 타일을 만드는 방법을 지정합니다.
이 가이드에서는 필수 구성 요소 이해에서 고급 옵션 구성에 이르기까지 렌더링 구성을 만드는 프로세스를 안내합니다. Planetary Computer Pro의 렌더링 기능은 오픈 소스 TiTiler 프로젝트를 기반으로 합니다.
필수 조건
렌더링을 구성하기 전에 다음 필수 구성 요소 단계가 완료되었는지 확인합니다.
- STAC 컬렉션이 있습니다.Planetary Computer Pro에서 STAC 컬렉션을 만들었습니다.
- 수집된 데이터: 컬렉션에 시각화하려는 지리 공간적 데이터 자산이 포함된 STAC 항목을 추가 했습니다.
-
item_assets컬렉션에 정의됨: STAC 컬렉션의 JSON 정의에는 잘 정의된 섹션이 포함되어item_assets. 이러한 속성은 컬렉션의 항목에서 사용할 수 있는 공통 데이터 자산(및 데이터 형식 또는 밴드와 같은 속성)에 대해 렌더링 엔진에 알립니다. 렌더링 구성은 여기에 정의된 자산 키를 참조합니다.
렌더링 구성을 빌드하는 프로세스
| 단계 | 제목 | 설명 |
|---|---|---|
| 1 |
컬렉션 JSON에서 정의 item_assets |
먼저 STAC 컬렉션 JSON에 항목 내의 공통 자산을 설명하는 잘 정의된 item_assets 섹션이 포함되어 있는지 확인해야 합니다. |
| 2 | 데이터 및 시각화 목표 이해 | 다음으로, 작업 중인 데이터 형식을 결정하고 시각적으로 표시할 방법을 결정합니다(단일 밴드 colormap, 다중 밴드 RGB). |
| 3 | Render Configuration 개체를 구성 | 이제 탐색기 UI에 대해 하나 이상의 렌더링 구성을 포함하는 기본 JSON 구조를 만듭니다. |
| 4 |
options 문자열 정의 - 핵심 매개 변수 |
문자열 내에서 필수 TiTiler 매개 변수를 options 구성하여 올바른 자산 또는 밴드를 선택하고 색맵 또는 크기 조정과 같은 기본 스타일을 적용합니다. |
| 5 |
고급 options 매개 변수 추가(필요에 따라) |
옵션으로, options 문자열을 사용하여 식, 알고리즘, 색 보정, 사용자 지정 색맵과 같은 고급 TiTiler 기능을 추가하여 시각화를 향상시킬 수 있습니다. |
| 6 | 컬렉션에 렌더링 구성 추가 | 마지막으로, 웹 인터페이스 또는 API를 사용하여 만든 렌더링 구성 목록을 STAC 컬렉션에 적용합니다. |
1단계: 컬렉션 JSON에서 정의 item_assets
컬렉션 JSON의 item_assets 필드는 컬렉션의 항목에 포함된 자산을 설명하는 스키마를 제공하므로 렌더링에 필수적입니다. 이 스키마를 사용하면 렌더링 엔진과 탐색기 웹 애플리케이션이 개별 항목을 검사하지 않고 시각화에 사용할 수 있는 데이터를 이해할 수 있습니다. 렌더링 구성을 참조하는 자산imageredNIRelevation의 키(이름)를 선언합니다. 또한 item_assets 다중 밴드 자산과 같은 eo:bands 메타데이터를 포함할 수 있으므로 렌더링을 위해 특정 밴드를 선택할 수 있습니다. 탐색기는 이 정보를 사용하여 메뉴를 채우고 전체 데이터 구조를 이해합니다.
4대역 NAIP 자산의 예 item_assets :
{
"item_assets": {
"image": {
"type": "image/tiff; application=geotiff; profile=cloud-optimized",
"roles": [
"data"
],
"title": "RGBIR COG tile",
"eo:bands": [
{
"name": "Red",
"common_name": "red",
"description": "Red band, 610-680 nm"
},
{
"name": "Green",
"common_name": "green",
"description": "Green band, 510-600 nm"
},
{
"name": "Blue",
"common_name": "blue",
"description": "Blue band, 420-530 nm"
},
{
"name": "NIR",
"common_name": "nir",
"description": "Near-infrared band, 830-920 nm"
}
]
}
},
// ... other collection properties ...
}
자세한 item_assets내용은 STAC 개요의 항목 자산 섹션을 참조하세요. 또한 공식 STAC 항목 자산 확장 사양을 참조하세요.
계속하기 전에 STAC 컬렉션 JSON에 이 섹션이 포함되어 있는지 확인합니다. API 또는 웹 인터페이스를 통해 컬렉션 정의를 업데이트할 수 있습니다.
2단계: 데이터 및 시각화 목표 이해
구성을 빌드하기 전에 데이터를 시각화하는 방법을 결정합니다.
| 데이터 형식 | 설명 | 예시 | 시각화 목표 |
|---|---|---|---|
| Single-Band 데이터 | 각 픽셀에는 하나의 값이 있습니다. | 고도, 온도, 토지 커버 분류, 계산 인덱스 | 색맵을 사용하여 이러한 단일 값을 색 범위 또는 불연속 색에 매핑합니다. |
| 다중 밴드 데이터 | 데이터에는 픽셀당 여러 대역이 있습니다. | RGB 위성 이미지, 다중 스펙트럼 데이터 | 출력 이미지의 빨강, 녹색 및 파랑 채널을 나타내려면 세 개의 특정 밴드를 결합합니다. |
| 파생 데이터(식) | 하나 이상의 밴드/자산에서 새 값을 계산합니다. | 빨간색 및 NIR 대역의 NDVI | 수학적 표현식을 정의하여 결과를 시각화합니다. 결과는 colormap을 사용한 단일 대역 방식이나 다중 대역 형태로 직접 시각화할 수 있습니다. |
| 파생 데이터(알고리즘) | 픽셀에서 새 값을 계산합니다. | 힐스하드는 상승 데이터의 윤곽을 보여줍니다. | 수학 알고리즘 을 사용하여 데이터를 시각화로 변환합니다. |
| 데이터 큐브(GRIB/NetCDF) | 여러 변수 및 차원이 있는 GRIB 또는 NetCDF 형식으로 저장된 데이터입니다. | 시간, 압력 수준 | 2D 시각화를 위해 특정 변수를 선택하고, 필요에 따라 다른 차원(예: 시간)을 통해 슬라이스를 고릅니다. |
3단계: 렌더링 구성 개체 생성
렌더링 구성은 JSON 개체 목록(또는 API를 사용하는 경우 Python 사전)으로 정의됩니다. 목록의 각 개체는 탐색기 드롭다운에 표시되는 하나의 시각화 옵션을 나타냅니다.
기본 구조:
[
{
"id": "unique-render-id",
"name": "Human-Readable Name for UI",
"description": "Optional: More details about this render.",
"type": "raster-tile", // Usually "raster-tile"
"options": "key1=value1&key2=value2...", // The core TiTiler parameters
"minZoom": 8 // Optional: Minimum map zoom level to display this layer
},
{
// ... another render configuration object ...
}
]
-
id: 컬렉션 내에서 이 렌더링 옵션에 대해 컴퓨터에서 읽을 수 있는 고유한 식별자입니다. -
name: 탐색기 UI에 표시된 표시 이름입니다. -
description: 더 많은 컨텍스트를 제공하는 선택적 텍스트입니다. -
type: 일반적으로"raster-tile". -
options: TiTiler 렌더링 엔진을 제어하는 URL 쿼리 매개 변수(key=value쌍으로&구분)를 포함하는 문자열입니다. 대부분의 사용자 지정이 발생하는 위치입니다. -
minZoom: 이 계층이 표시되는 최소 지도 확대/축소 수준을 지정하는 선택적 정수입니다. 고해상도 데이터를 사용하여 성능을 관리하는 데 유용합니다.
동일한 구조를 사용하면 데이터를 여러 가지 방법으로 시각화할 수 있도록 동일한 데이터에 대해 여러 렌더링 구성을 사용할 수 있습니다.
4단계: 문자열 정의 options - 핵심 매개 변수
문자열은 options 렌더링 구성의 핵심입니다. 형식을 key=value&key=value 사용합니다. 가장 일반적인 매개 변수는 다음과 같습니다.
1. 자산/밴드 식별
| 매개 변수 | 설명 | 사용 사례 | 예시 |
|---|---|---|---|
assets={asset_key} |
사용할 자산을 지정합니다. 여기서 {asset_key} 컬렉션 item_assets에 정의된 키와 일치합니다. |
하나의 자산을 사용하여 단일 밴드 렌더링 | assets=elevation |
| 세 개의 단일 밴드 자산을 각기 사용하는 3대역 렌더링(순서에 따라 R, G, B가 결정됨) | assets=B04&assets=B03&assets=B02 |
||
| 단일 다중 밴드 자산을 사용하여 렌더링 |
assets=image(asset_bidx와 함께 자주 사용됨) |
||
asset_bidx={asset_key}\|{band_index1},{band_index2},... |
에 지정된 단일 다중 밴드 자산 assets 특정 밴드 인덱스를 선택합니다. 대역 인덱스는 일반적으로 1 기반입니다. |
삼중 대역 자산의 밴드 1, 2, 3에서 추출한 RGB image |
assets=image&asset_bidx=image\|1,2,3 |
3대역 자산의 밴드 4, 1, 2의 가색 적외선(NIR, 빨강, 녹색) image |
assets=image&asset_bidx=image\|4,1,2 |
||
단일 밴드 렌더링은 자산의 4번 밴드만 사용합니다image |
assets=image&asset_bidx=image\|4 |
2. Single-Band 데이터 스타일 지정
| 매개 변수 | 설명 | 예시 |
|---|---|---|
colormap_name={name} |
미리 정의된 명명된 colormap을 적용합니다. 일반적인 예: viridis, plasma, grayrdylgn. 사용 가능한 명명된 색맵을 참조하세요. |
assets=elevation&colormap_name=viridis |
rescale={min_val},{max_val} |
데이터 값을 늘이거나 압축하여 색맵의 전체 범위에 맞습니다. 이 범위를 벗어난 값은 최소/최대 색으로 고정됩니다. | 전체 색맵에서 100m에서 1500m까지의 고도 값을 매핑합니다. assets=elevation&colormap_name=viridis&rescale=100,1500 |
3. RGB(멀티 밴드) 데이터 스타일 지정
| 매개 변수 | 설명 | 예시 |
|---|---|---|
| RGB 밴드 주문 | RGB 밴드는 assets (개별 자산의 경우) 또는 asset_bidx (자산 내의 밴드)의 순서에 의해 암시적으로 정의됩니다. |
자산/밴드 식별 테이블의 예제를 참조하세요. |
rescale={min_val},{max_val} |
(선택 사항) R, G, B 대역의 입력 값을 0-255 표시 범위에 매핑하기 전에 크기를 조정하는 데 사용할 수 있습니다. 원본 데이터가 아직 8비트가 아닌 경우 유용합니다. | assets=B04&assets=B03&assets=B02&rescale=0,3000 |
color_formula={formula_string} |
(선택 사항) 색 보정 수식을 적용합니다. | 다음 섹션에서 고급 옵션을 참조하세요. |
5단계: 고급 options 매개 변수 추가(필요에 따라)
TiTiler는 기본 사항 외에도 문자열을 통해 많은 고급 매개 변수를 options 제공합니다.
1. 표현
| 매개 변수 | 설명 | 서식/값 | 예시 |
|---|---|---|---|
expression={formula} |
자산 키를 변수로 사용하여 수학 수식 정의 | 표준 연산자(+, -, *, /) 및 괄호 |
expression=(B08-B04)/(B08+B04) |
asset_as_band=true |
식에서 여러 단일 밴드 자산을 사용하는 경우 필요 |
true 또는 false |
expression=(B08-B04)/(B08+B04)&asset_as_band=true |
기타 세부 정보:
- 단일 밴드 결과 예제:
expression=(B08-B04)/(B08+B04)&asset_as_band=true&colormap_name=rdylgn&rescale=-1,1 - 다중 밴드 식은 세미콜론을 사용합니다.
expression=B04*1.5;B03*1.1;B02*1.3&asset_as_band=true -
expression을 사용할 때 일반적으로는assets이나asset_bidx이 필요하지 않습니다.
2. 알고리즘
| 매개 변수 | 설명 | 서식/값 | 예시 |
|---|---|---|---|
algorithm={name} |
미리 정의된 픽셀 처리 알고리즘 적용 |
hillshade, contours, terrarium, terrainrgbnormalizedIndex |
algorithm=hillshade |
algorithm_params={json_string} |
알고리즘에 대한 매개 변수(URL로 인코딩된 JSON) | 알고리즘에 따라 다름 | algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D |
buffer={integer} |
타일 주위에 픽셀 버퍼 추가(알고리즘에 자주 필요) | 정수 값 | buffer=3 |
전체 예제:assets=elevation&algorithm=hillshade&colormap_name=gray&buffer=3&algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D
특정 알고리즘에 대한 자세한 내용은 TiTiler 알고리즘 설명서 및 Mapbox 알고리즘을 참조하세요.
3. 색 보정(RGB/3대역 출력용)
| 매개 변수 | 설명 | 포맷 | 예시 |
|---|---|---|---|
color_formula={formula_string} |
색 조정 적용 | 감마, 채도 및/또는 시그모이드 조정을 사용하여 공백으로 구분된 문자열 | color_formula=Gamma RGB 2.5 Saturation 1.4 Sigmoidal RGB 15 0.35 |
서식 세부 정보:
-
Gamma {BANDS} {VALUE}- 밝기 조정 -
Saturation {PROPORTION}- 색 강도 조정 -
Sigmoidal {BANDS} {CONTRAST} {BIAS}- 대비 조정
색 보정에 대한 자세한 내용은 TiTiler 설명서를 참조하세요.
4. 사용자 지정 색상 지도(단일 밴드 출력용)
| 매개 변수 | 설명 | 포맷 | 예시 |
|---|---|---|---|
colormap={json_string} |
사용자 지정 색맵 정의 | URL로 인코딩된 JSON 매핑 데이터 값을 RGBA 목록에 매핑 [R,G,B,Alpha] |
colormap={\"1\":[54,124,20,255],\"2\":[28,67,0,255],\"3\":[94, 91, 32, 255],\"4\":[234, 99, 32, 255],\"5\":[237, 232, 60, 255],\"6\":[236, 31, 175, 255],\"7\":[19, 0,239, 255], \"8\":[209, 3, 0, 255]} |
다음으로 디코딩하는 예제: 값 1을 진한 녹색으로, 2에서 매우 진한 녹색으로, 3을 올리브 그린에, 4에서 오렌지-레드로, 5에서 노랑으로, 6에서 분홍색/마젠타로, 7에서 파랑 바이올렛으로, 8에서 빨강으로 매핑합니다.
5. 데이터 처리
| 매개 변수 | 설명 | 예시 |
|---|---|---|
nodata={value} |
투명하게 만들 픽셀 값 지정 |
nodata=0 또는 nodata=-9999 또는 nodata=nan |
unscale={true\|false} |
GeoTIFF 메타데이터에서 배율/오프셋 적용 | unscale=true |
6. 성능/타일링 동작
| 매개 변수 | 설명 | 포맷 | 예시 |
|---|---|---|---|
maxItemsPerTile={integer} |
타일당 STAC 항목 수 제한 | 정수 | maxItemsPerTile=20 |
skipcovered={true\|false} |
다른 사용자가 다루는 항목 건너뛰기 |
true 또는 false |
skipcovered=true |
exitwhenfull={true\|false} |
타일이 완전히 적용되는 경우 처리 중지 |
true 또는 false |
exitwhenfull=true |
time_limit={seconds} |
타일을 렌더링하는 최대 시간 | 정수(초) | time_limit=10 |
7. 데이터 큐브 매개 변수(GRIB/NetCDF)
| 매개 변수 | 데이터 형식 | 설명 | 예시 |
|---|---|---|---|
subdataset_bands={band_index} |
GRIB | 특정 메시지/밴드 선택 | assets=grib_data&subdataset_bands=1&colormap_name=jet&rescale=273,300 |
subdataset_name={variable_name} |
NetCDF | 시각화할 변수 선택 | assets=netcdf_data&subdataset_name=temperature |
datetime={timestamp} |
NetCDF | 시간 조각 선택(ISO 8601) | datetime=2023-10-26T12:00:00Z |
전체 NetCDF 예제:assets=netcdf_data&subdataset_name=temperature&datetime=2023-10-26T12:00:00Z&colormap_name=viridis&rescale=0,30
6단계: 컬렉션에 렌더링 구성 추가
렌더링 구성 목록(하나 이상의 JSON 개체)을 구성한 후 STAC 컬렉션에 추가합니다.
웹 인터페이스 사용:
- Planetary Computer Pro 포털에서 컬렉션으로 이동합니다.
- 구성 단추를 선택합니다.
- 렌더링 탭으로 이동합니다.
- JSON 목록을 편집기에 붙여넣거나 UI 필드를 사용하여 작성합니다.
- 변경 내용을 저장합니다.
컬렉션 구성에 대한 자세한 내용은 웹 인터페이스를 사용하여 컬렉션 구성을 참조하세요.
API 사용:
컬렉션의 렌더링 옵션 엔드포인트에 대한 HTTP POST 요청을 사용합니다.
import requests
import json
import azure.identity
geocatalog_url = <your geocatalog url>
collection_id = <your collection id>
credential = azure.identity.AzureCliCredential()
token = credential.get_token("https://geocatalog.spatio.azure.com")
headers = {
"Authorization": f"Bearer {token.token}"
}
response = requests.post(
f"{geocatalog_url}/stac/collections/{collection_id}/configurations/render-options",
json=render_config, # Your list of render config dicts
headers=headers,
params={"api-version": "2025-04-30-preview"} # Use the appropriate API version
)
if response.status_code == 200:
print("Render configuration updated successfully.")
print(response.json())
else:
print(f"Error updating render configuration: {response.status_code}")
print(response.text)
STAC 컬렉션 API 사용에 대한 자세한 내용은 STAC 컬렉션 만들기(API 예제)를 참조하세요.
예시
다음은 문자열 및 전체 렌더링 구성 개체의 options 다양한 예입니다.
1. Single-Band 색맵 및 크기 조정을 사용하여 Biomass 변경:
{
"id": "biomass-change",
"name": "Biomass Change from prior year (tonnes)",
"description": "Annual estimates of changes (gains and losses) in aboveground woody biomass.",
"type": "raster-tile",
"options": 'assets=biomass_change_wm&colormap_name=spectral&rescale=-5000,5000',
"minZoom": 2
}
2. 별도의 자산에서 가져온 자연색 (RGB) Three-Band:
{
"id": "natural-color",
"name": "Natural color",
"description": "True color composite of visible bands (B04, B03, B02)",
"type": "raster-tile",
"options": "assets=B04&assets=B03&assets=B02&nodata=0&color_formula=Gamma RGB 3.2 Saturation 0.8 Sigmoidal RGB 25 0.35",
"minZoom": 9
}
3. 단일 자산 내의 밴드에서 False Color(NIR, R, G)를 Three-Band.
{
"id": "color-infrared",
"name": "Color infrared",
"description": "Highlights healthy (red) and unhealthy (blue/gray) vegetation.",
"type": "raster-tile",
"options": "assets=image&asset_bidx=image|4,1,2&color_formula=Sigmoidal RGB 15 0.35",
"minZoom": 12
}
4. NDVI 계산 사용 식:
{
"id": "normalized-difference-veg-inde",
"name": "Normalized Difference Veg. Index (NDVI)",
"description": "Normalized Difference Vegetation Index (B08-B04)/(B08+B04), darker green indicates healthier vegetation.",
"type": "raster-tile",
"options": "nodata=0&expression=(B08-B04)/(B08+B04)&rescale=-1,1&colormap_name=rdylgn&asset_as_band=true",
"minZoom": 9
}
5. 힐스하드 알고리즘:
{
"id": "hillshade",
"name": "Hillshade",
"description": "Terrain visualization based on elevation.",
"type": "raster-tile",
"options": "assets=data&colormap_name=gray&algorithm=hillshade&buffer=3&algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D",
"minZoom": 7
}
6. NetCDF 온도 시각화:
{
"id": "pr-1950-07-07",
"name": "Precipitation (1950-07-07)",
"description": "Precipitation from NetCDF data.",
"type": "raster-tile",
"options": "assets=cmip&rescale=0,0.01&colormap_name=viridis&subdataset_name=pr&datetime=1950-07-07T00:00:00",
"minZoom": 4
}
참조: 모든 options 매개 변수
문자열은 options 다음 키-값 쌍을 허용합니다(가장 up-to-date 세부 정보는 TiTiler 설명서 참조).
| 매개 변수 | 유형 | 설명 | 사용 예시 |
|---|---|---|---|
assets |
str(str) |
item_assets의 자산 키 여러 자산에 대해 키를 반복합니다. |
assets=B04&assets=B03&assets=B02 |
expression |
str(str) | 자산 키를 사용하는 수학 식입니다. | expression=(B08-B04)/(B08+B04) |
asset_bidx |
str(str) | 다중 대역 자산에 대한 밴드 인덱스입니다. 형식: {asset_key}|{idx1},{idx2},... |
asset_bidx=image|4,1,2 |
asset_as_band |
bool | 자산을 expression에서 단일 대역으로 취급합니다. 식에서 여러 자산을 사용하는 경우에 필요합니다. |
asset_as_band=true |
colormap_name |
str(str) | 미리 정의된 TiTiler 색맵 이름입니다. | colormap_name=viridis |
colormap |
str(str) | 사용자 지정 색맵을 정의하는 URL로 인코딩된 JSON입니다. | colormap=%7B%221%22%3A%5B...%5D%7D |
rescale |
str(str) | 데이터 크기 조정을 위한 쉼표로 구분된 최소 최대값입니다. | rescale=0,3000 |
color_formula |
str(str) | 공백으로 구분된 색 보정 수식(감마, 채도, 시그모이드). | color_formula=Gamma RGB 2.2 Saturation 1.1 |
nodata |
str/float/int | 데이터 없음(투명)으로 처리할 픽셀 값입니다. |
nodata=0 또는 nodata=-9999.0 또는 nodata=nan |
unscale |
bool | GeoTIFF 메타데이터에서 배율/오프셋을 적용합니다. | unscale=true |
algorithm |
str(str) | TiTiler 처리 알고리즘의 이름입니다. | algorithm=hillshade |
algorithm_params |
str(str) | 알고리즘에 대한 매개 변수를 사용하여 URL로 인코딩된 JSON 문자열입니다. | algorithm_params=%7B%22azimuth%22%3A315%7D |
buffer |
떠다니다 | 타일 주위의 픽셀 버퍼(알고리즘에 자주 필요). | buffer=3 |
maxItemsPerTile |
정수 (int) | 타일당 처리할 최대 STAC 항목입니다. | maxItemsPerTile=20 |
skipcovered |
bool | 다른 항목에 의해 완전히 가려진 항목을 건너뜁니다. | skipcovered=true |
exitwhenfull |
bool | 완전히 덮인 타일의 처리를 중지합니다. | exitwhenfull=true |
time_limit |
정수 (int) | 타일당 최대 처리 시간(초)입니다. | time_limit=10 |
subdataset_bands |
정수 (int) | GRIB 데이터에 대한 대역/메시지 인덱스입니다. | subdataset_bands=1 |
subdataset_name |
str(str) | NetCDF 데이터의 변수 이름입니다. | subdataset_name=temperature |
datetime |
str(str) | NetCDF에서 시간 조각을 선택하기 위한 ISO 8601 타임스탬프입니다. | datetime=2023-10-26T12:00:00Z |
resampling |
str(str) | 재샘플링 메서드(nearest, bilinear). |
resampling=nearest |