Definir configurações de renderização para visualizar dados no Microsoft Planetary Computer Pro

Para visualizar dados geoespaciais usando o explorador de dados Microsoft Planetary Computer Pro ou a API Tiler, você deve definir uma ou mais configurações de renderização para cada uma de suas coleções STAC (SpatioTemporal Asset Catalog). Uma configuração de renderização especifica como os ativos de dados em seus itens STAC são combinados, processados e estilizados para criar blocos de mapa.

Este guia orienta você pelo processo de criação de configurações de renderização, desde a compreensão dos pré-requisitos até a configuração de opções avançadas. Os recursos de renderização do Planetary Computer Pro são construídos com base no projeto TiTiler de código aberto.

Prerequisites

Antes de configurar a renderização, verifique se as seguintes etapas de pré-requisito estão concluídas:

1. A coleção STAC existe: Você criou uma coleção STAC no Planetary Computer Pro.
2. Dados ingeridos: Você adicionou itens STAC contendo os ativos de dados geoespaciais que deseja visualizar na coleção.

Processo para criar uma configuração de renderização

Step	Title	Description
1	Definir item_assets na sua coleção JSON	Primeiro, você precisa garantir que seu JSON de coleção STAC inclua uma seção bem definida item_assets que descreva os ativos comuns em seus itens.
2	Entenda sua meta de dados e visualização	Em seguida, determine o tipo de dados com os quais você está trabalhando e decida como deseja que eles apareçam visualmente (mapa de cores de banda única, RGB de banda única).
3	Construir o objeto de configuração de renderização	Agora, crie a estrutura JSON básica que contém uma ou mais configurações de renderização para a interface do usuário do Explorer.
4	Definir a options cadeia de caracteres - parâmetros principais	Configure os parâmetros essenciais do TiTiler dentro da options cadeia de caracteres para selecionar os ativos ou bandas corretas e aplicar estilos básicos, como mapas de cores ou reescalonamento.
5	Adicionar parâmetros avançados options (conforme necessário)	Opcionalmente, aprimore sua visualização adicionando recursos avançados do TiTiler, como expressões, algoritmos, correção de cores ou mapas de cores personalizados usando a options cadeia de caracteres.
6	Adicionar a configuração de renderização à sua coleção	Finalmente, aplique a lista de configuração de renderização que você criou à sua coleção STAC usando a interface da Web ou a API.

Etapa 1: Definir item_assets na sua coleção JSON

O campo item_assets em sua coleção JSON é essencial para a renderização, pois fornece uma descrição consolidada dos ativos contidos nos itens da coleção. O mecanismo de renderização e o aplicativo Web Explorer usam o campo item_assets para entender os dados disponíveis para visualização sem inspecionar itens individuais. Ele declara as chaves (nomes) dos ativos, como image, red, NIR, ou elevation, que são referenciadas pelas configurações de renderização. Além disso, item_assets pode incluir metadados de extensão STAC, como eo:bands para ativos multibanda, facilitando a seleção de bandas específicas para renderização. O Explorer usa essas informações para preencher menus e entender a estrutura geral de dados.

Exemplo item_assets de um ativo NAIP de 4 bandas:

{
  "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 ...
}

Para obter mais informações sobre item_assetso, consulte a Secção de Recursos do Item na Visão Geral do STAC. Consulte também a especificação oficial STAC Item Assets Extension.

Certifique-se de que seu JSON de coleção STAC inclua esta seção antes de prosseguir. Você pode atualizar sua definição de coleção por meio da API ou da interface web.

Etapa 2: Entender sua meta de dados e visualização

Antes de criar a configuração, determine como você deseja visualizar seus dados:

Tipo de dados	Description	Example	Objetivo de Visualização
Dados de Banda Única	Cada pixel tem um valor.	elevação, temperatura, classificação da cobertura do solo, índice calculado	Mapeie esses valores únicos para um intervalo de cores ou cores discretas usando um mapa de cores.
Dados Multibanda	Os dados têm várias bandas por pixel.	Imagens de satélite RGB, dados multiespectrais	Combine três bandas específicas para representar os canais Vermelho, Verde e Azul da imagem de saída.
Dados derivados (expressões)	Calcule um novo valor a partir de uma ou mais bandas/ativos.	Índice de Vegetação de Diferença Normalizada (NDVI) das bandas Vermelha e Infravermelho Próximo (NIR)	Defina uma expressão matemática e visualize o resultado (banda única com mapa de cores ou multibanda diretamente).
Dados derivados (algoritmos)	Calcule um novo valor para os pixels.	Hillshade mostra contornos de dados de elevação	Use um algoritmo matemático para transformar dados em uma visualização.
Cubos de dados (GRIB/NetCDF)	Dados armazenados nos formatos GRIB ou NetCDF com múltiplas variáveis e dimensões.	tempo, níveis de pressão	Selecione uma variável específica e, potencialmente, uma fatia através de outras dimensões (como o tempo) para visualização 2D.

Etapa 3: Construir o objeto de configuração de renderização

As configurações de renderização são definidas como uma lista de objetos JSON (ou dicionários Python se estiverem usando a API). Cada objeto na lista representa uma opção de visualização que aparecerá no menu suspenso do Explorer.

Estrutura Básica:

[
  {
    "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: Um identificador exclusivo legível por máquina para esta opção de renderização dentro da coleção.
• name: O nome para exibição mostrado na interface do usuário do Explorer.
• description: Texto opcional que fornece mais contexto.
• type: Normalmente "raster-tile".
• options: Uma cadeia de caracteres que contém parâmetros de consulta de URL (key=value pares separados por &) que controlam o mecanismo de renderização Tiler. É aqui que acontece a maior parte da personalização.
• minZoom: Inteiro opcional especificando o nível mínimo de zoom do mapa no qual essa camada se torna visível. Útil para gerenciar o desempenho com dados de alta resolução.

Usando a mesma estrutura, é possível ter várias configurações de renderização para os mesmos dados para que os dados possam ser visualizados de várias maneiras.

Etapa 4: Definir a options cadeia de caracteres - parâmetros principais

A options cadeia de caracteres é o coração da configuração de renderização. Ele usa um key=value&key=value formato. Aqui estão os parâmetros mais comuns:

1. Identificação de Ativos/Bandas

Parameter	Description	Caso de uso	Example
assets={asset_key}	Especifica o(s) ativo(s) a ser usado(s), onde {asset_key} corresponde a uma chave definida no item_assets.	Renderização de banda única usando um recurso	assets=elevation
		Renderização de três bandas usando três ativos de banda única separados (a ordem determina R, G, B)	assets=B04&assets=B03&assets=B02
		Renderização usando um único ativo multibanda	assets=image (frequentemente utilizado com asset_bidx)
asset_bidx={asset_key}\|{band_index1},{band_index2},...	Seleciona índices de banda específicos de dentro de um único ativo multibanda especificado pelo assets. Os índices de banda são tipicamente baseados em 1.	Três bandas RGB a partir das bandas 1, 2, 3 do ativo image	assets=image&asset_bidx=image\|1,2,3
		Três bandas Infravermelho de cor falsa (NIR, vermelho, verde) das bandas 4, 1, 2 do ativo image	assets=image&asset_bidx=image\|4,1,2
		Renderização de banda única usando apenas a banda 4 do ativo image	assets=image&asset_bidx=image\|4

2. Estilo de Dados Single-Band

Parameter	Description	Example
colormap_name={name}	Aplica um mapa de cores nomeado predefinido. Exemplos comuns: viridis, plasma, gray, rdylgn. Veja os mapas de cores suportados.	assets=elevation&colormap_name=viridis
rescale={min_val},{max_val}	Estende ou compacta os valores de dados para ajustar o intervalo completo do mapa de cores. Os valores fora deste intervalo são fixados às cores min/max.	Mapeie os valores de elevação de 100 m a 1500 m no mapa de cores completo: assets=elevation&colormap_name=viridis&rescale=100,1500

3. Estilizando dados RGB (Multi-Band)

Parameter	Description	Example
Ordem das bandas RGB	As bandas RGB são implicitamente definidas pela ordem em assets (para ativos separados) ou asset_bidx (para bandas dentro de um ativo).	Veja exemplos na tabela Identificação de Ativos/Bandas
rescale={min_val},{max_val}	(Opcional) Pode ser usado para dimensionar os valores de entrada das bandas R, G e B antes de mapeá-los para o intervalo de exibição de 0-255. Útil se os dados de origem ainda não forem de 8 bits.	assets=B04&assets=B03&assets=B02&rescale=0,3000
color_formula={formula_string}	(Opcional) Aplica fórmulas de correção de cor.	Consulte as opções avançadas na próxima seção.

Etapa 5: Adicionar parâmetros avançados options (conforme necessário)

Além do básico, o TiTiler oferece muitos parâmetros avançados através da options string:

1. Expressões

Parameter	Description	Format/Values	Example
expression={formula}	Definir uma fórmula matemática usando chaves de ativos como variáveis	Operadores normalizados (+, -, *, /) e parênteses	expression=(B08-B04)/(B08+B04)
asset_as_band=true	Necessário quando a expressão usa vários ativos de banda única	true ou false	expression=(B08-B04)/(B08+B04)&asset_as_band=true

Examples

• Exemplo de resultado de banda única: expression=(B08-B04)/(B08+B04)&asset_as_band=true&colormap_name=rdylgn&rescale=-1,1
• As expressões multibanda usam ponto-e-vírgula: expression=B04*1.5;B03*1.1;B02*1.3&asset_as_band=true
• Ao usar expression, geralmente não precisa de assets ou asset_bidx

2. Algoritmos

Parameter	Description	Format/Values	Example
algorithm={name}	Aplicar um algoritmo de processamento de pixel predefinido	hillshade, contours, terrarium, terrainrgb, normalizedIndex	algorithm=hillshade
algorithm_params={json_string}	Parâmetros para o algoritmo (JSON codificado por URL)	Varia de acordo com o algoritmo	algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D
buffer={integer}	Adicionar buffer de pixel em torno de blocos (geralmente necessário para algoritmos)	Valor inteiro	buffer=3

Exemploassets=elevation&algorithm=hillshade&colormap_name=gray&buffer=3&algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D

Para obter detalhes sobre algoritmos específicos, consulte a documentação do algoritmo TiTiler e o Mapbox Hillshade

3. Correção de cor (para saída RGB / três bandas)

Parameter	Description	Format	Example
color_formula={formula_string}	Aplicar ajustes de cor	Cadeia separada por espaço com ajustes de gama, saturação e/ou sigmoidal	color_formula=Gamma RGB 2.5 Saturation 1.4 Sigmoidal RGB 15 0.35

Detalhes do formato:

• Gamma {BANDS} {VALUE} - Ajuste o brilho
• Saturation {PROPORTION} - Ajustar a intensidade da cor
• Sigmoidal {BANDS} {CONTRAST} {BIAS} - Ajustar o contraste

Para obter mais informações sobre correção de cor, consulte a documentação do TiTiler.

4. Mapas de cores personalizados (para saída de banda única)

Parameter	Description	Format	Example
colormap={json_string}	Definir um mapa de cores personalizado	Valores de dados de mapeamento JSON codificados por URL para listas 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]}

Exemplo decodifica para: Mapeia o valor 1 a verde escuro, 2 a verde muito escuro, 3 a verde-oliva, 4 a laranja-avermelhado, 5 a amarelo, 6 a rosa/magenta, 7 a azul-violeta e 8 a vermelho.

5. Tratamento de Dados

Parameter	Description	Example
nodata={value}	Especificar valor de pixel para tornar transparente	nodata=0 ou nodata=-9999 ou nodata=nan
unscale={true\|false}	Aplicar escala/deslocamento a partir de metadados GeoTIFF	unscale=true

6. Desempenho / Comportamento de Mosaico

Parameter	Description	Format	Example
maxItemsPerTile={integer}	Limitar o número de itens STAC por bloco	Integer	maxItemsPerTile=20
skipcovered={true\|false}	Ignorar itens cobertos por outros	true ou false	skipcovered=true
exitwhenfull={true\|false}	Parar o processamento quando o mosaico estiver totalmente coberto	true ou false	exitwhenfull=true
time_limit={seconds}	Tempo máximo para renderizar um bloco	Inteiro (segundos)	time_limit=10

7. Parâmetros do cubo de dados (GRIB/NetCDF)

Parameter	Tipo de dados	Description	Example
subdataset_bands={band_index}	GRIB	Selecionar mensagem/banda específica	assets=grib_data&subdataset_bands=1&colormap_name=jet&rescale=273,300
subdataset_name={variable_name}	NetCDF	Selecionar variável para visualizar	assets=netcdf_data&subdataset_name=temperature
datetime={timestamp}	NetCDF	Selecionar fatia de tempo (ISO 8601)	datetime=2023-10-26T12:00:00Z

Exemplo completo de NetCDF:assets=netcdf_data&subdataset_name=temperature&datetime=2023-10-26T12:00:00Z&colormap_name=viridis&rescale=0,30

Etapa 6: Adicionar a configuração de renderização à sua coleção

Depois de construir sua lista de configuração de renderização (um ou mais objetos JSON), adicione-a à sua coleção STAC:

Usando a interface web:

1. Navegue até a sua coleção no portal Planetary Computer Pro.
2. Selecione o botão Configuração .
3. Vá para o separador Render.
4. Cole sua lista JSON no editor.
5. Salve as alterações selecionando Atualizar.

Para obter mais informações sobre como configurar coleções, consulte Configurar uma coleção com a interface da Web.

Usando a API:

Defina uma configuração de representação de coleção utilizando o endpoint create stac collection render options. A seguir está um exemplo de uso deste endpoint usando a API REST com Python:

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)

Para obter mais informações sobre como usar a API de coleção STAC, consulte Criar uma coleção STAC (exemplos de API).

Examples

Aqui estão vários exemplos da cadeia de caracteres options e do objeto de configuração de renderização completa.

1. Single-Band Mudança de biomassa com Mapa de cores e Reescalonar:

 {
    "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 Cor Natural (RGB) de elementos separados:

 {
    "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 (NIR, R, G) de bandas dentro de um único ativo:

{
    "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. Cálculo NDVI usando expressão:

{
    "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. Algoritmo 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. Visualização de temperatura 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
  }

Referência: Todos os options parâmetros

A options cadeia de caracteres aceita os seguintes pares chave-valor (consulte a documentação do TiTiler para obter os detalhes mais up-to-date):

Parameter	Tipo	Description	Exemplo de Utilização
assets	str	Chave(s) de ativo de item_assets. Repita a chave para vários ativos.	assets=B04&assets=B03&assets=B02
expression	str	Expressão matemática usando identificadores de ativo.	expression=(B08-B04)/(B08+B04)
asset_bidx	str	Índices de banda para um activo multibanda. Formato: {asset_key}|{idx1},{idx2},...	asset_bidx=image|4,1,2
asset_as_band	bool	Trate os ativos em expression como bandas únicas. Necessário quando a expressão usa vários ativos.	asset_as_band=true
colormap_name	str	Nome predefinido do mapa de cores TiLer.	colormap_name=viridis
colormap	str	JSON codificado por URL definindo um mapa de cores personalizado.	colormap=%7B%221%22%3A%5B...%5D%7D
rescale	str	Valores mínimos e máximos separados por vírgulas para dimensionamento de dados.	rescale=0,3000
color_formula	str	Fórmula de correção de cor separada por espaço (Gama, Saturação, Sigmoidal).	color_formula=Gamma RGB 2.2 Saturation 1.1
nodata	str/float/int	Valor de píxel para tratar como ausência de dados (transparente).	nodata=0 ou nodata=-9999.0 ou nodata=nan
unscale	bool	Aplique escala/deslocamento a partir de metadados GeoTIFF.	unscale=true
algorithm	str	Nome de um algoritmo de processamento TiTiler.	algorithm=hillshade
algorithm_params	str	Cadeia de caracteres JSON codificada por URL com parâmetros para o algoritmo.	algorithm_params=%7B%22azimuth%22%3A315%7D
buffer	float	Buffer de pixel em torno de blocos (geralmente necessário para algoritmos).	buffer=3
maxItemsPerTile	int	Máximo de itens STAC para processar por tile.	maxItemsPerTile=20
skipcovered	bool	Ignore itens totalmente obscurecidos por outros.	skipcovered=true
exitwhenfull	bool	Pare de processar um mosaico quando está completamente coberto.	exitwhenfull=true
time_limit	int	Tempo máximo de processamento (segundos) por bloco.	time_limit=10
subdataset_bands	int	Índice de banda/mensagem para dados GRIB.	subdataset_bands=1
subdataset_name	str	Nome da variável para dados NetCDF.	subdataset_name=temperature
datetime	str	Timestamp ISO 8601 para selecionar intervalo de tempo no NetCDF.	datetime=2023-10-26T12:00:00Z
resampling	str	Método de nova amostragem (nearest, bilinear).	resampling=nearest

Conteúdo relacionado

• Guia de exemplo de visualização de dados
• Configurar uma coleção com a interface Web do Microsoft Planetary Computer Pro
• Configurações de mosaico para coleções
• Configurações de ícones para coleções
• Objetos de consulta para filtros de pesquisa personalizados
• Visão Geral STAC
• Documentação TiTiler