若要使用 Microsoft Planetary Computer Pro 數據瀏覽器或 Tiler API 來進行地理空間數據的可視化，您必須為您的 STAC（時空資產目錄）集合定義渲染配置。 渲染配置指定如何合併、處理及設置 STAC 項目內的數據資產，以建立地圖磚塊。
本指南會逐步引導您完成建立轉譯組態的程式，從瞭解必要條件到設定進階選項。 行星計算機專業版的轉譯功能是以開放原始碼 TiTiler 項目為基礎。
先決條件
設定轉譯之前，請確定下列必要條件步驟已完成：
- STAC 集合存在： 您在 行星電腦專業版中建立了 STAC 集合。
- 數據擷取： 您已 新增包含您要在集合中可視化的地理空間數據資產的 STAC 項目。
-
item_assets在集合中定義： 您的 STAC 集合的 JSON 定義 必須 包含定義完善的item_assets區段。 這些屬性會通知渲染引擎有關集合中項目共享的數據資產（及其屬性，例如數據類型或波段）。 渲染組態會參考這裡定義的資產鍵值。
建置渲染配置的流程
| 步驟 | 標題 | 說明 |
|---|---|---|
| 1 |
在集合 JSON 中定義item_assets |
首先，您必須確保您的 STAC 集合 JSON 包含定義完善的 item_assets 區段，以描述專案內的一般資產。 |
| 2 | 瞭解您的數據和視覺效果目標 | 接下來，決定您正在使用的數據類型，並決定您希望其以可視化方式顯示的方式（單一波段色彩圖、多波段 RGB）。 |
| 3 | 建構渲染設定物件 | 現在，建立基本的 JSON 結構，以包含一個或多個資源管理器 UI 的渲染組態。 |
| 4 |
options定義字串 - 核心參數 |
設定字串內 options 的基本 TiTiler 參數，以選取正確的資產或頻帶，並套用基本樣式，例如色彩圖或重新調整。 |
| 5 |
新增進階 options 參數（視需要） |
或者，使用 options 字串新增運算式、演算法、色彩更正或自定義色彩圖等進階 TiTiler 功能，以增強視覺效果。 |
| 6 | 將轉譯組態新增至您的集合 | 最後，使用 Web 介面或 API，將您建立的轉譯組態清單套用至 STAC 集合。 |
步驟 1：在集合 JSON 中定義item_assets
集合 JSON 中的item_assets字段對於轉譯很重要，因為它提供描述集合專案內所含資產的架構。 此架構可讓轉譯引擎和 Explorer Web 應用程式了解視覺效果的可用數據，而不需要檢查個別專案。 它會聲明資產的鍵（名稱），例如image、red、NIR或elevation，其會參考您的渲染配置。 此外，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 或 Web 介面來更新集合定義。
步驟 2：瞭解您的數據和視覺效果目標
在建置組態之前，請先決定您要如何將數據可視化：
| 數據類型 | 說明 | 範例 | 視覺效果目標 |
|---|---|---|---|
| Single-Band 數據 | 每個圖元都有一個值。 | 海拔， 溫度， 土地覆蓋分類， 計算索引 | 使用 colormap 將這些單一值對應至色彩範圍或離散色彩。 |
| 多頻數據 | 每個像素的數據有多個頻帶。 | RGB 衛星影像，多重光譜數據 | 結合三個特定波段來代表輸出影像的紅色、綠色和藍色通道。 |
| 衍生數據（表達式） | 從一或多個頻帶/資產計算新值。 | 來自紅色和 NIR 頻帶的 NDVI | 定義數學表達式，並將結果可視化（單一波段使用色彩圖或直接顯示多波段）。 |
| 衍生資料（演算法） | 計算跨像素的新值。 | Hillshade 顯示海拔數據的輪廓 | 使用數學 演算法 將數據轉換成視覺效果。 |
| 資料立方體 (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：Explorer UI 中顯示的顯示名稱。 -
description：提供更多內容的選擇性文字。 -
type：通常是"raster-tile"。 -
options：包含 URL 查詢參數的字串（由key=value配對，並以&分隔），這些參數控制 TiTiler 渲染引擎。 這是大部分自定義發生的地方。 -
minZoom：選擇性整數，指定此圖層可見的最小地圖縮放層級。 有助於利用高解析度數據來提升效能管理效率。
使用相同的結構，可以有多個相同數據的轉譯組態，以便以多種方式將數據可視化。
步驟 4：定義 options 字串 - 核心參數
字串 options 是轉譯組態的核心。 它會使用 key=value&key=value 格式。 以下是最常見的參數：
1.識別資產/波段
| 參數 | 說明 | 用例 | 範例 |
|---|---|---|---|
assets={asset_key} |
指定要使用的資產，其中 {asset_key} 符合集合 item_assets中定義的索引鍵。 |
使用單一資產的單頻渲染 | assets=elevation |
| 使用三個獨立單帶資產進行三頻段轉譯（順序決定 R、G、B） | assets=B04&assets=B03&assets=B02 |
||
| 使用單一多頻資產進行轉譯 |
assets=image （常搭配 asset_bidx使用） |
||
asset_bidx={asset_key}\|{band_index1},{band_index2},... |
從單一由指定的多頻資產中選取特定的頻帶索引。 頻帶索引通常是以 1 為基礎。 |
三波段 RGB 來自資產image的波段1、2、3 |
assets=image&asset_bidx=image\|1,2,3 |
三波段 由資產的波段 4、1、2 組成的假彩色紅外（NIR、紅色、綠色）image |
assets=image&asset_bidx=image\|4,1,2 |
||
| 單波段轉譯僅使用資產的第 4 頻帶 | assets=image&asset_bidx=image\|4 |
2.設定 Single-Band 數據的樣式
| 參數 | 說明 | 範例 |
|---|---|---|
colormap_name={name} |
套用預先定義的命名色彩映射。 常見範例：viridis、、plasmagray、 rdylgn。 請參閱可用的帶名稱的顏色映射。 |
assets=elevation&colormap_name=viridis |
rescale={min_val},{max_val} |
延展或壓縮數據值，以符合色彩地圖的完整範圍。 超出此範圍的值會限制為最小值/最大色彩。 | 從 100 m 到 1500 m 跨完整色彩地圖對應高度值： 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、terrainrgb、normalizedIndex |
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 / 三頻輸出）
| 參數 | 說明 | 格式 | 範例 |
|---|---|---|---|
color_formula={formula_string} |
套用色彩調整 | 空白分隔的字串，具有 Gamma、飽和度和/或 Sigmoidal 調整 | 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 集合：
使用 Web 介面：
- 在 Planetary Computer Pro 入口網站中瀏覽至您的集合。
- 選取 [ 組態] 按鈕。
- 移至 渲染 索引標籤。
- 將您的 JSON 清單貼到編輯器中，或使用 UI 字段來建置它。
- 儲存變更。
如需設定集合的詳細資訊，請參閱 使用 Web 介面設定集合。
使用 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 生物質的變化：
{
"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. Three-Band 自然色彩（RGB）來自獨立的資產：
{
"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. 單一影像中的 Three-Band False Color （近紅外，紅色，綠色）頻段：
{
"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. Hillshade 演算法：
{
"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日期詳細數據，請參閱 TiTiler 檔 ）：
| 參數 | 類型 | 說明 | 範例使用方式 |
|---|---|---|---|
assets |
字符串 | 來自 item_assets的資產金鑰。 針對多個資產重複使用相同的鍵。 |
assets=B04&assets=B03&assets=B02 |
expression |
字符串 | 使用資產索引鍵的數學表達式。 | expression=(B08-B04)/(B08+B04) |
asset_bidx |
字符串 | 多頻資產的頻帶索引。 格式：{asset_key}|{idx1},{idx2},... |
asset_bidx=image|4,1,2 |
asset_as_band |
布爾 (bool) | 將expression中的資產視為單一波段。 當表達式使用多個資產時必需。 |
asset_as_band=true |
colormap_name |
字符串 | 預先定義的 TiTiler 顏色映射名稱。 | colormap_name=viridis |
colormap |
字符串 | 定義自訂色彩地圖的 URL 編碼 JSON。 | colormap=%7B%221%22%3A%5B...%5D%7D |
rescale |
字符串 | 用於數據縮放的逗號分隔最小值和最大值。 | rescale=0,3000 |
color_formula |
字符串 | 以空格分隔的顏色校正公式（Gamma、飽和度、Sigmoidal）。 | 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 |
字符串 | TiTiler 處理演算法的名稱。 | algorithm=hillshade |
algorithm_params |
字符串 | 具有演算法參數的 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 |
字符串 | NetCDF 資料的變數名稱。 | subdataset_name=temperature |
datetime |
字符串 | 在 NetCDF 中選取時間片段用的 ISO 8601 時間戳記。 | datetime=2023-10-26T12:00:00Z |
resampling |
字符串 | 重新取樣方法 （nearest， bilinear）。 |
resampling=nearest |