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

Para visualizar dados geoespaciais usando o data explorer do Microsoft Planetary Computer Pro ou a API tiler, você deve definir uma ou mais configurações de renderização para cada uma das coleções do Catálogo de Ativos SpatioTemporal (STAC). 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 de pré-requisitos até a configuração de opções avançadas. As funcionalidades de renderização do Planetry Computer Pro são criadas com base no projeto TiTiler de software livre.

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 Planetry Computer Pro.
2. Dados ingeridos: Você adicionou itens STAC que contêm os ativos de dados geoespaciais que deseja visualizar na coleção.

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

Etapa 1: Definir item_assets em seu JSON de coleção

O campo item_assets em sua coleção JSON é essencial para 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, , redNIRou elevation, que são referenciados pelas configurações de renderização. Além disso, item_assets pode incluir metadados de extensão STAC, como eo:bands para ativos de várias bandas, 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 para 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_assets, consulte a seção Ativos de Item na Visão Geral do STAC. Consulte também a especificação oficial STAC Item Assets Extension.

Verifique se o JSON da coleção STAC inclui esta seção antes de continuar. Você pode atualizar sua definição de coleção por meio da API ou da interface da Web.

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

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

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 será exibida na Lista suspensa 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 único legível por máquina para essa opção de renderização dentro da coleção.
• name: o nome de exibição mostrado na interface do Explorer.
• description: texto opcional fornecendo 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 tiTiler. É aqui que ocorre a maior parte da personalização.
• minZoom: inteiro opcional que especifica 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 cadeia options 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. Identificando Ativos/Bandas

2. Estilizando dados de banda única

3. Estilização de dados multibanda (RGB)

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

Além dos conceitos básicos, o TiTiler oferece muitos parâmetros avançados por meio da options cadeia de caracteres:

1. Expressões

Examples

• Exemplo de resultado de banda única: expression=(B08-B04)/(B08+B04)&asset_as_band=true&colormap_name=rdylgn&rescale=-1,1
• 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, você geralmente não precisa assets ou asset_bidx

2. Algoritmos

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 Mapbox Hillshade

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

Detalhes do formato:

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

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

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

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

5. Tratamento de dados

6. Desempenho / Comportamento de mosaico

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

Exemplo completo do 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 à coleção STAC:

Usando a Interface da Web:

1. Navegue até sua coleção no portal do Planetry Computer Pro.
2. Selecione o botão Configuração .
3. Vá para a aba 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 renderização de coleção usando o endpoint create stac collection render options. Veja a seguir um exemplo de como usar esse 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 options caracteres e do objeto de configuração de renderização completa:

1. Mudança de biomassa de banda única com mapa de cores e redimensionamento:

 {
    "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. Cor natural de três bandas (RGB) de ativos 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. Cor falsa de três bandas (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 do 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 cadeia de caracteres options aceita os seguintes pares chave-valor (consulte a documentação do TiTiler para obter os detalhes mais atualizados):

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 blocos para coleções
• Consultas para filtros de pesquisa personalizados
• Visão geral do STAC
• Documentação do TiTiler