Microsoft Planetary Computer Pro データ エクスプローラーまたは Tiler API を使用して地理空間データを視覚化するには、SpatioTemporal Asset Catalog (STAC) コレクションごとに 1 つ以上の レンダリング構成 を定義する必要があります。 レンダリング構成では、STAC 項目内のデータ資産を結合、処理、およびスタイル設定してマップ タイルを作成する方法を指定します。
このガイドでは、前提条件の理解から高度なオプションの構成まで、レンダリング構成を作成するプロセスについて説明します。 プラネタリー コンピューター プロのレンダリング機能は、オープンソースの TiTiler プロジェクトに基づいて構築されています。
Prerequisites
レンダリングを構成する前に、次の前提条件の手順が完了していることを確認します。
- STAC コレクションが存在します。プラネタリー・コンピューター・プロで STAC コレクションを作成しました。
- 取り込まれたデータ: 視覚化する地理空間データ資産を含む STAC 項目 をコレクションに追加しました。
レンダリング構成をビルドするプロセス
| Step | Title | Description |
|---|---|---|
| 1 |
コレクション JSON で item_assets を定義する |
まず、STAC コレクション JSON に、項目内の一般的な資産について説明する明確に定義された item_assets セクションが含まれていることを確認する必要があります。 |
| 2 | データと視覚化の目標を理解する | 次に、使用しているデータの種類を決定し、視覚的に表示する方法 (シングルバンド カラーマップ、マルチバンド RGB) を決定します。 |
| 3 | Render Configuration オブジェクトを構築する | 次に、エクスプローラー UI の 1 つ以上のレンダリング構成を保持する基本的な JSON 構造を作成します。 |
| 4 |
options文字列の定義 - コア パラメーター |
options文字列内で重要な TiTiler パラメーターを構成して、適切なアセットまたはバンドを選択し、カラーマップや再スケーリングなどの基本的なスタイルを適用します。 |
| 5 |
高度な options パラメーターを追加する (必要に応じて) |
必要に応じて、 options 文字列を使用して、式、アルゴリズム、色補正、カスタム カラーマップなどの高度な TiTiler 機能を追加して、視覚化を強化します。 |
| 6 | レンダー構成をコレクションに追加する | 最後に、作成したレンダリング構成リストを、Web インターフェイスまたは API を使用して STAC コレクションに適用します。 |
手順 1: コレクション JSON で item_assets を定義する
コレクション JSON の item_assets フィールドは、コレクションの項目に含まれる資産の統合された説明を提供するため、レンダリングに不可欠です。 レンダリング エンジンとエクスプローラー Web アプリケーションは、item_assets フィールドを使用して、個々の項目を検査せずに視覚化に使用できるデータを理解します。
image、red、NIR、elevationなど、アセットのキー (名前) が宣言され、レンダリング構成によって参照されます。 さらに、item_assetsには、マルチバンド アセットの eo:bands などの STAC 拡張メタデータを含めることができるため、レンダリング用の特定のバンドの選択が容易になります。 エクスプローラーでは、この情報を使用してメニューを設定し、全体的なデータ構造を理解します。
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: データと視覚化の目標を理解する
構成を構築する前に、データを視覚化する方法を決定します。
| データ型 | Description | Example | 視覚化の目標 |
|---|---|---|---|
| シングルバンドデータ | 各ピクセルには 1 つの値があります。 | 標高、温度、土地被覆分類、計算インデックス | カラーマップを使用して、これらの単一の値を色の範囲または不連続の色に マップします。 |
| マルチバンド データ | データには、ピクセルごとに複数のバンドがあります。 | RGB 衛星画像、マルチスペクトル データ | 3 つの特定のバンドを組み合わせて、出力画像の赤、緑、青のチャンネルを表します。 |
| 派生データ (式) | 1 つ以上のバンド/アセットから新しい値を計算します。 | 赤色帯および近赤外 (NIR) 帯からの正規化差植生指数 (NDVI) | 数式を定義し、結果を視覚化します (カラーマップまたはマルチバンドを直接使用した単一バンド)。 |
| 派生データ (アルゴリズム) | ピクセル間で新しい値を計算します。 | 標高データの輪郭を示すヒルシェード | 数学的 アルゴリズム を使用して、データを視覚化に変換します。 |
| データ キューブ (GRIB/NetCDF) | 複数の変数とディメンションを持つ GRIB 形式または NetCDF 形式で格納されたデータ。 | 時間、圧力レベル | 特定の変数を選択し、2D 視覚化のために他のディメンション (時間など) をスライスする可能性があります。 |
手順 3: レンダー構成オブジェクトを構築する
レンダリング構成は、JSON オブジェクト (または API を使用する場合は Python ディクショナリ) の一覧として定義されます。 一覧内の各オブジェクトは、[ エクスプローラー] ドロップダウンに表示される 1 つの視覚化オプションを表します。
基本構造:
[
{
"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. アセット/バンドの識別
| Parameter | Description | 使用事例 | Example |
|---|---|---|---|
assets={asset_key} |
使用する資産を指定します。ここで、 {asset_key} はコレクションの item_assetsで定義されているキーと一致します。 |
1 つのアセットを使用したシングルバンド レンダリング | assets=elevation |
| 3 つの 独立した シングルバンド アセットを使用した 3 バンド レンダリング (順序によって R、G、B が決まります) | assets=B04&assets=B03&assets=B02 |
||
| 1 つのマルチバンド アセットを使用したレンダリング |
assets=image (多くの場合、 asset_bidxで使用されます) |
||
asset_bidx={asset_key}\|{band_index1},{band_index2},... |
で指定された単一のマルチバンド アセットassets特定のバンド インデックスを選択します。 バンド インデックスは通常、1 から始まります。 |
アセット のバンド 1、2、3 からの image RGB |
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 データのスタイル設定
| Parameter | Description | Example |
|---|---|---|
colormap_name={name} |
定義済みの名前付きカラーマップを適用します。 一般的な例: viridis、 plasma、 gray、 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) データのスタイル設定
| Parameter | Description | Example |
|---|---|---|
| RGB バンドの順序 | RGB バンドは、 assets (個別のアセットの場合) または asset_bidx (アセット内のバンドの場合) の順序によって暗黙的に定義されます。 |
資産/バンドの識別テーブルの例を参照してください |
rescale={min_val},{max_val} |
(省略可能) 0 から 255 の表示範囲にマッピングする前に、R、G、B バンドの入力値をスケーリングするために使用できます。 ソース データがまだ 8 ビットでない場合に便利です。 | assets=B04&assets=B03&assets=B02&rescale=0,3000 |
color_formula={formula_string} |
(省略可能) 色補正の数式を適用します。 | 次のセクションの詳細オプションを参照してください。 |
手順 5: 高度な options パラメーターを追加する (必要に応じて)
基本以外に、TiTiler では、 options 文字列を介して多くの高度なパラメーターが提供されます。
1. 表現
| Parameter | Description | Format/Values | Example |
|---|---|---|---|
expression={formula} |
資産キーを変数として使用して数式を定義する | 標準演算子 (+、 -、 *、 /) とかっこ |
expression=(B08-B04)/(B08+B04) |
asset_as_band=true |
式で複数 のシングルバンド アセットを 使用する場合に必要です |
true または false |
expression=(B08-B04)/(B08+B04)&asset_as_band=true |
Examples
- 単一バンドの結果の例:
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. アルゴリズム
| Parameter | Description | Format/Values | Example |
|---|---|---|---|
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 Hillshade を参照してください。
3. 色補正(RGB/3バンド出力用)
| Parameter | Description | Format | Example |
|---|---|---|---|
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. カスタムカラーマップ(シングルバンド出力用)
| Parameter | Description | Format | Example |
|---|---|---|---|
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. データ処理
| Parameter | Description | Example |
|---|---|---|
nodata={value} |
透明にするピクセル値を指定する |
nodata=0 または nodata=-9999 または nodata=nan |
unscale={true\|false} |
GeoTIFF メタデータからスケール/オフセットを適用する | unscale=true |
6.パフォーマンス/タイリング ビヘイビアー
| Parameter | Description | Format | Example |
|---|---|---|---|
maxItemsPerTile={integer} |
タイルあたりの STAC 項目の数を制限する | Integer | 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)
| Parameter | データ型 | Description | Example |
|---|---|---|---|
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: レンダー構成をコレクションに追加する
レンダリング構成リスト (1 つ以上の JSON オブジェクト) を作成したら、STAC コレクションに追加します。
Web インターフェイスの使用:
- 惑星コンピューター Pro ポータルでコレクションに移動します。
- [ 構成 ] ボタンを選択します。
- [ レンダリング ]タブに移動します。
- JSON リストをエディターに貼り付けます。
- [更新] を選択して変更を保存します。
コレクションの構成の詳細については、「 Web インターフェイスを使用したコレクションの構成」を参照してください。
API の使用:
create stac collection render オプション エンドポイントを使用して、コレクションのレンダリング構成を定義します。 Python で REST API を使用してこのエンドポイントを使用する例を次に示します。
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 の例)」を参照してください。
Examples
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.個別のアセットからの 3 バンド自然色 (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.単一アセット内のバンドからの 3 バンド疑似色 (NIR、R、G):
{
"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 文字列は、次のキーと値のペアを受け入れます (最新の詳細については、TiTiler のドキュメントを参照してください)。
| Parameter | タイプ | Description | 使用例 |
|---|---|---|---|
assets |
str |
item_assets からのアセット キー。 複数の資産に対してキーを繰り返します。 |
assets=B04&assets=B03&assets=B02 |
expression |
str | 資産キーを使用した数式。 | expression=(B08-B04)/(B08+B04) |
asset_bidx |
str | マルチバンド アセットのバンド インデックス。 形式: {asset_key}|{idx1},{idx2},... |
asset_bidx=image|4,1,2 |
asset_as_band |
bool |
expressionのアセットを単一のバンドとして扱います。 式で複数の資産を使用する場合に必要です。 |
asset_as_band=true |
colormap_name |
str | 定義済みの TiTiler カラーマップ名。 | colormap_name=viridis |
colormap |
str | カスタム カラーマップを定義する URL エンコード JSON。 | colormap=%7B%221%22%3A%5B...%5D%7D |
rescale |
str | データ スケーリングのためのコンマ区切りの最小値と最大値。 | rescale=0,3000 |
color_formula |
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 | TiTiler 処理アルゴリズムの名前。 | algorithm=hillshade |
algorithm_params |
str | アルゴリズムのパラメーターを含む URL エンコード JSON 文字列。 | algorithm_params=%7B%22azimuth%22%3A315%7D |
buffer |
float | タイルの周囲のピクセル バッファー (多くの場合、アルゴリズムに必要)。 | 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 | NetCDF データの変数名。 | subdataset_name=temperature |
datetime |
str | NetCDF でタイム スライスを選択するための ISO 8601 タイムスタンプ。 | datetime=2023-10-26T12:00:00Z |
resampling |
str | リサンプリング メソッド (nearest、 bilinear)。 |
resampling=nearest |