Partilhar via

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 configurações de renderização para suas coleções STAC (SpatioTemporal Asset Catalog). Uma configuração de renderização especifica como os ativos de dados em seus itens STAC devem ser 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.

Pré-requisitos

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.
  3. item_assets Definido na Coleção: A sua coleção STAC deve ter uma definição JSON que inclua uma secção claramente definida . Essas propriedades informam o mecanismo de renderização sobre os ativos de dados comuns (e suas propriedades, como tipo de dados ou bandas) disponíveis nos itens da coleção. As configurações de renderização fazem referência às chaves de ativo definidas aqui.

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

Passo Título Descrição
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 renderização porque fornece um esquema que descreve os ativos contidos nos itens da coleção. Esse esquema permite que o mecanismo de renderização e o aplicativo Web Explorer compreendam 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 fazem referência às suas configurações de renderização. Além disso, item_assets pode incluir metadados 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 Descrição Exemplo Objetivo de visualização
DadosSingle-Band 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. NDVI das bandas vermelho e infravermelho próximo 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

Parâmetro Descrição Caso de uso Exemplo
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

Parâmetro Descrição Exemplo
colormap_name={name} Aplica um mapa de cores nomeado predefinido. Exemplos comuns: viridis, plasma, gray, rdylgn. Veja os mapas de cores nomeados disponíveis. 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)

Parâmetro Descrição Exemplo
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

Parâmetro Descrição Formato/Valores Exemplo
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

Outros detalhes:

  • 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

Parâmetro Descrição Formato/Valores Exemplo
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

Exemplo completo:assets=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 os algoritmos Mapbox

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

Parâmetro Descrição Formato Exemplo
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)

Parâmetro Descrição Formato Exemplo
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

Parâmetro Descrição Exemplo
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

Parâmetro Descrição Formato Exemplo
maxItemsPerTile={integer} Limitar o número de itens STAC por bloco Número inteiro 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)

Parâmetro Tipo de dados Descrição Exemplo
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 ou use os campos da interface do usuário para criá-la.
  5. Salve as alterações.

Captura de tela da interface da Web de configuração de renderização exibindo opções para configurar configurações de renderização.

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

Usando a API:

Utilize um pedido HTTP POST para o endpoint das opções de renderização da coleção.

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).

Exemplos

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):

Parâmetro Tipo Descrição 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 flutuante 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