在Microsoft行星计算机专业版中配置用于可视化数据的呈现设置

若要使用 Microsoft Planetary Computer Pro 数据浏览器或 Tiler API 可视化地理空间数据，必须为 SpatioTemporal 资产目录 (STAC) 集合定义 渲染配置。 呈现配置指定如何组合、处理和设置 STAC 项中的数据资产以创建地图图块。

本指南指导你完成创建呈现配置的过程，从了解先决条件到配置高级选项。 行星计算机专业版的渲染功能是基于开源 TiTiler 项目构建的。

先决条件

在配置渲染之前，请确保完成以下先决条件步骤：

1. STAC 集合存在： 你在 行星计算机专业版中创建了 STAC 集合。
2. 数据引入： 您将包含要可视化的地理空间数据资产的 STAC 项 添加到了集合中。
3. item_assets 在集合中定义： 您的 STAC 集合的 JSON 定义 必须 包含清晰明确定义的部分。 这些属性告知渲染引擎有关集合中各项可用的通用数据资产及其属性（如数据类型或波段）的信息。 呈现配置引用此处定义的资产密钥。

生成呈现配置的过程

步骤	标题	DESCRIPTION
1	在集合 JSON 中定义item_assets	首先，需要确保您的 STAC 集合 JSON 包含一个定义良好的 item_assets 部分，该部分用于描述项中的常见资产。
2	了解数据和可视化目标	接下来，确定正在使用的数据类型，并决定希望数据以可视方式显示（单带色图、多带 RGB）。
3	构造呈现配置对象	现在，创建用于存储 Explorer 用户界面一个或多个渲染配置的基本 JSON 结构体。
4	options定义字符串 - 核心参数	配置 options 字符串中的 TiTiler 的基本参数，以选择正确的资产或波段，并应用基本样式，如色彩图或重新缩放。
5	添加高级 options 参数（根据需要）	（可选）通过使用字符串添加高级 TiTiler 功能（如表达式、算法、颜色更正或自定义色图 options ）来增强可视化效果。
6	将呈现配置添加到集合	最后，使用 Web 界面或 API 将创建的呈现配置列表应用到 STAC 集合。

步骤 1：在集合 JSON 中定义item_assets

集合 JSON 中的item_assets字段对于呈现至关重要，因为它提供描述集合项中包含的资产的架构。 此架构允许呈现引擎和资源管理器 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：了解数据和可视化目标

在生成配置之前，请确定要如何可视化数据：

数据类型	DESCRIPTION	示例：	可视化目标
单波段数据	每个像素都有一个值。	海拔、温度、土地覆盖分类、计算索引	使用 颜色图将这些单个值映射到颜色范围或离散颜色。
多带数据	每个像素包含多个波段的数据。	RGB 卫星图像，多光谱数据	组合三个特定带以表示输出图像的红色、绿色和蓝色通道。
派生数据（表达式）	从一个或多个波段/资产计算新值。	红和 NIR 波段中的 NDVI	定义数学表达式并可视化结果（单波段配色图或直接多波段）。
派生数据（算法）	跨像素计算新值。	山体阴影显示高程数据的轮廓	使用数学 算法 将数据转换为可视化效果。
数据立方体 （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：一个字符串，包含 URL 查询参数（由 key=value 对组成并用 & 分隔），用于控制 TiTiler 渲染引擎。 这是大多数自定义发生的地方。
• minZoom：可选整数，用于指定此层可见的最小地图缩放级别。 可用于使用高分辨率数据管理性能。

使用相同的结构，可以针对同一数据具有多个呈现配置，以便以多种方式可视化数据。

步骤 4：定义 options 字符串 - 核心参数

字符串 options 是呈现配置的核心。 它使用格式 key=value&key=value 。 下面是最常见的参数：

1.标识资产/波段

参数	DESCRIPTION	用例	示例：
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},...	从 指定的单个多波段资产中选择特定的波段索引assets。 波段索引通常是基于 1 的。	来自资产 的波段 1、2、3 的三波段image RGB	assets=image&asset_bidx=image\|1,2,3
		来自资产 的波段 4、1、2 的三波段image假彩色红外（NIR、红、绿）	assets=image&asset_bidx=image\|4,1,2
		仅使用资产 的波段 4 的单波段image呈现	assets=image&asset_bidx=image\|4

2.设置单波段数据的样式

参数	DESCRIPTION	示例：
colormap_name={name}	应用预定义的命名颜色映射。 常见示例：viridis、、plasmagrayrdylgn. 请参阅可用的 命名颜色图。	assets=elevation&colormap_name=viridis
rescale={min_val},{max_val}	拉伸或压缩数据值，以适应颜色图的完整范围。 此范围之外的值将固定到最小/最大颜色。	映射整个颜色映射中 100 米到 1500 米的高程值：assets=elevation&colormap_name=viridis&rescale=100,1500

3.设置多波段 (RGB) 数据的样式

参数	DESCRIPTION	示例：
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. 表达式

参数	DESCRIPTION	格式/值	示例：
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. 算法

参数	DESCRIPTION	格式/值	示例：
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/三带输出）

参数	DESCRIPTION	格式	示例：
color_formula={formula_string}	应用颜色调整	具有亮度、饱和度和/或 S 形调整的空格分隔字符串	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. 自定义颜色图 （用于单带输出）

参数	DESCRIPTION	格式	示例：
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. 数据处理

参数	DESCRIPTION	示例：
nodata={value}	指定像素值以使透明	nodata=0 或 nodata=-9999 或 nodata=nan
unscale={true\|false}	从 GeoTIFF 元数据应用缩放/偏移量	unscale=true

6. 性能/平铺行为

参数	DESCRIPTION	格式	示例：
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)

参数	数据类型	DESCRIPTION	示例：
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 界面：

1. 在 Planetary Computer Pro 门户中导航到你的集合。
2. 选择 “配置 ”按钮。
3. 转到“ 呈现 ”选项卡。
4. 将 JSON 列表粘贴到编辑器中，或使用 UI 字段生成它。
5. 保存更改。

有关配置集合的详细信息，请参阅 使用 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.使用颜色映射和重新缩放的单波段生物量变化：

 {
    "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)：

 {
    "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.来自单个资产中的波段的三波段假彩色 (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 文档以获取最新详细信息）：

参数	类型	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	布尔	将 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	以空格分隔的色彩校正公式（伽马，饱和度，S曲线）。	color_formula=Gamma RGB 2.2 Saturation 1.1
nodata	str/float/int	要视为无数据的像素值（透明）。	nodata=0 或 nodata=-9999.0 或 nodata=nan
unscale	布尔	应用 GeoTIFF 元数据的缩放/偏移量。	unscale=true
algorithm	str	TiTiler 处理算法的名称。	algorithm=hillshade
algorithm_params	str	带有算法参数的 URL 编码 JSON 字符串。	algorithm_params=%7B%22azimuth%22%3A315%7D
buffer	漂浮	磁贴周围的像素缓冲区（算法通常需要）。	buffer=3
maxItemsPerTile	整数 (int)	每个图块要处理的最大 STAC 项数。	maxItemsPerTile=20
skipcovered	布尔	跳过被其他物体完全遮挡的项目。	skipcovered=true
exitwhenfull	布尔	完全覆盖后，停止处理图块。	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

相关内容

• 使用“Microsoft 行星计算机专业版”Web 界面配置一个集合
• 集合的马赛克配置
• 集合的图块设置
• 自定义搜索筛选器的可查询对象
• 可视化数据多维数据集资产 (GRIB/NetCDF)
• STAC 概述
• TiTiler 文档