Configurar opciones de representación para visualizar datos en Microsoft Planetary Computer Pro

Para visualizar datos geoespaciales mediante el Explorador de datos de Microsoft Planetary Computer Pro o la API de Tiler, debe definir una o varias configuraciones de representación para cada una de las colecciones del Catálogo de activos spatioTemporales (STAC). Una configuración de representación especifica cómo se combinan, procesan y aplican estilos a los recursos de datos dentro de los elementos de STAC para crear iconos de mapa.

Esta guía le guía por el proceso de creación de configuraciones de representación, desde la comprensión de los requisitos previos para configurar opciones avanzadas. Las funcionalidades de representación de Planetary Computer Pro se basan en el proyecto TiTiler de código abierto.

Prerequisites

Antes de configurar la representación, asegúrese de que se han completado los siguientes pasos previos:

La colección STAC existe: Ha creado una colección STAC en Planetary Computer Pro.
Datos ingeridos: Ha agregado elementos STAC que contienen los recursos de datos geoespaciales que desea visualizar en la colección.

Proceso para compilar una configuración de representación

Step	Title	Description
1	Definir `item_assets` en el JSON de la colección	En primer lugar, debe asegurarse de que el JSON de la colección STAC incluye una sección bien definida `item_assets` que describe los recursos comunes dentro de los elementos.
2	Descripción de los datos y el objetivo de visualización	A continuación, determine el tipo de datos con los que trabaja y decida cómo desea que aparezca visualmente (mapa de colores de banda única, RGB de varias bandas).
3	Construir el objeto de configuración de representación	Ahora, cree la estructura JSON básica que contiene una o varias configuraciones de representación para la interfaz de usuario del Explorador.
4	Definición de la `options` cadena: parámetros principales	Configure los parámetros TiTiler esenciales dentro de la cadena `options` para seleccionar los recursos o bandas correctos y aplicar estilos básicos como mapas de colores o escalado.
5	Agregar parámetros avanzados `options` (según sea necesario)	Opcionalmente, mejore la visualización agregando características avanzadas de TiTiler, como expresiones, algoritmos, corrección de color o mapas de colores personalizados mediante la `options` cadena.
6	Agregar la configuración de representación a la colección	Por último, aplique la lista de configuración de representación que ha creado a la colección STAC usando la interfaz web o la API.

Paso 1: Definir `item_assets` en el JSON de la colección

El campo item_assets de la colección JSON es esencial para la representación, ya que proporciona una descripción consolidada de los recursos contenidos en los elementos de la colección. El motor de representación y la aplicación web Explorer usan el campo item_assets para comprender los datos disponibles para su visualización sin inspeccionar elementos individuales. Declara las claves (nombres) de los recursos, como image, red, NIRo elevation, a las que se hace referencia a continuación mediante las configuraciones de representación. Además, item_assets pueden incluir metadatos de extensión STAC como eo:bands para recursos de varias bandas, lo que facilita la selección de bandas específicas para la representación. El Explorador usa esta información para rellenar menús y comprender la estructura de datos general.

Ejemplo item_assets de un recurso 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 obtener más información sobre item_assets, vea la sección Activos de los elementos en la Información general de STAC. Consulte también la especificación oficial de la Extensión de activos del elemento de STAC.

Asegúrese de que el CÓDIGO JSON de la colección STAC incluye esta sección antes de continuar. Puede actualizar la definición de la colección a través de la API o la interfaz web.

Paso 2: Comprender los datos y el objetivo de visualización

Antes de compilar la configuración, determine cómo desea visualizar los datos:

Tipo de datos	Description	Example	Objetivo de visualización
Datos de Single-Band	Cada píxel tiene un valor.	elevación, temperatura, clasificación de cobertura terrestre, índice calculado	Asigne estos valores únicos a un rango de colores o colores discretos mediante un mapa de colores.
Datos de varias bandas	Los datos tienen varias bandas por píxel.	Imágenes de satélite RGB, datos multiespectrales	Combine tres bandas específicas para representar los canales Rojo, Verde y Azul de la imagen de salida.
Datos derivados (expresiones)	Calcule un nuevo valor de una o varias bandas o activos.	Índice de vegetación de diferencia normalizada (NDVI) de bandas rojas y NIR	Defina una expresión matemática y visualice el resultado (banda única con mapa de colores o varias bandas directamente).
Datos derivados (algoritmos)	Calcule un nuevo valor en píxeles.	Hillshade muestra contornos de los datos de elevación	Use un algoritmo matemático para transformar los datos en una visualización.
Cubos de datos (GRIB/NetCDF)	Datos almacenados en formatos GRIB o NetCDF con varias variables y dimensiones.	tiempo, niveles de presión	Seleccione una variable específica y, posiblemente, un segmento a través de otras dimensiones (como el tiempo) para la visualización 2D.

Paso 3: Construir el objeto de configuración de representación

Las configuraciones de representación se definen como una lista de objetos JSON (o diccionarios de Python si se usa la API). Cada objeto de la lista representa una opción de visualización que aparecerá en la lista desplegable Explorador.

Estructura 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: identificador único legible por máquina para esta opción de representación dentro de la colección.
name: el nombre que se muestra en la interfaz de usuario del Explorador.
description: texto opcional que proporciona más contexto.
type: normalmente "raster-tile".
options: cadena que contiene parámetros de consulta url (key=value pares separados por &) que controlan el motor de representación de TiTiler. Aquí es donde se produce la mayoría de la personalización.
minZoom: entero opcional que especifica el nivel mínimo de zoom del mapa en el que esta capa se vuelve visible. Resulta útil para administrar el rendimiento con datos de alta resolución.

Con la misma estructura, es posible tener varias configuraciones de representación para los mismos datos para que los datos se puedan visualizar de varias maneras.

Paso 4: Definir la `options` cadena: parámetros principales

La options cadena es el corazón de la configuración de representación. Usa un key=value&key=value formato. Estos son los parámetros más comunes:

1. Identificación de activos/bandas

Parameter	Description	Caso de uso	Example
`assets={asset_key}`	Especifica los recursos que se van a usar, donde `{asset_key}` coincide con una clave definida en la colección `item_assets`.	Representación de una sola banda mediante un recurso	`assets=elevation`
		Representación de tres bandas con tres activos independientes de banda única (el orden determina R, G, B)	`assets=B04&assets=B03&assets=B02`
		Representación mediante un único recurso de varias bandas	`assets=image` (a menudo se usa con `asset_bidx`)
`asset_bidx={asset_key}\\|{band_index1},{band_index2},...`	Selecciona índices de banda específicos dentro de un único recurso de varias bandas especificado por `assets`. Normalmente, los índices de banda se basan en 1.	RGB de tres bandas de las bandas 1, 2, 3 del activo `image`	`assets=image&asset_bidx=image\\|1,2,3`
		Infrarrojo de color falso de tres bandas (NIR, rojo, verde) de las bandas 4, 1, 2 del activo `image`	`assets=image&asset_bidx=image\\|4,1,2`
		Representación de una sola banda con solo la banda 4 del recurso`image`	`assets=image&asset_bidx=image\\|4`

2. Aplicar estilos a datos Single-Band

Parameter	Description	Example
`colormap_name={name}`	Aplica un mapa de colores con nombre predefinido. Ejemplos comunes: `viridis`, `plasma`, `gray`, `rdylgn`. Consulte mapas de colores admitidos.	`assets=elevation&colormap_name=viridis`
`rescale={min_val},{max_val}`	Amplía o comprime los valores de datos para ajustarse al rango completo del mapa de colores. Los valores fuera de este intervalo se fijan a los colores min/max.	Asigne valores de elevación de 100 m a 1500 m a través del mapa de colores completo: `assets=elevation&colormap_name=viridis&rescale=100,1500`

3. Aplicar estilos a datos de banda múltiple (RGB)

Parameter	Description	Example
Orden de las bandas RGB	Las bandas RGB se definen implícitamente mediante el orden en `assets` (para activos independientes) o `asset_bidx` (para bandas dentro de un recurso).	Vea ejemplos en la tabla Identificación de activos/bandas.
`rescale={min_val},{max_val}`	(Opcional) Se puede usar para escalar los valores de entrada de las bandas R, G, B antes de asignarlos al intervalo de visualización de 0 a 255. Resulta útil si los datos de origen aún no son de 8 bits.	`assets=B04&assets=B03&assets=B02&rescale=0,3000`
`color_formula={formula_string}`	(Opcional) Aplica fórmulas de corrección de color.	Consulte opciones avanzadas en la sección siguiente.

Paso 5: Agregar parámetros avanzados `options` (según sea necesario)

Además de los conceptos básicos, TiTiler ofrece muchos parámetros avanzados a través de la options cadena:

1. Expresiones

Parameter	Description	Format/Values	Example
`expression={formula}`	Definir una fórmula matemática utilizando claves de activos como variables	Operadores estándar (`+`, `-`, `*`, `/`) y paréntesis	`expression=(B08-B04)/(B08+B04)`
`asset_as_band=true`	Obligatorio cuando la expresión usa varios recursos de banda única	`true` o `false`	`expression=(B08-B04)/(B08+B04)&asset_as_band=true`

Examples

Ejemplo de resultado de banda única: expression=(B08-B04)/(B08+B04)&asset_as_band=true&colormap_name=rdylgn&rescale=-1,1
Las expresiones de varias bandas usan punto y coma: expression=B04*1.5;B03*1.1;B02*1.3&asset_as_band=true
Al usar expression, por lo general no necesita assets o asset_bidx

2. Algoritmos

Parameter	Description	Format/Values	Example
`algorithm={name}`	Aplicación de un algoritmo de procesamiento de píxeles predefinido	`hillshade`, `contours`, `terrarium`, , `terrainrgb`, `normalizedIndex`	`algorithm=hillshade`
`algorithm_params={json_string}`	Parámetros para el algoritmo (JSON con codificación URL)	Varía según el algoritmo.	`algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D`
`buffer={integer}`	Agregar búfer de píxeles alrededor de los iconos (a menudo necesarios para los algoritmos)	Valor entero	`buffer=3`

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

Para obtener más información sobre algoritmos específicos, consulte la documentación del algoritmo TiTiler y Mapbox Hillshade.

3. Corrección de color (para la salida RGB /Tres bandas)

Parameter	Description	Format	Example
`color_formula={formula_string}`	Aplicar ajustes de color	Cadena separada por espacios con ajustes Gamma, Saturación o Sigmoidal	`color_formula=Gamma RGB 2.5 Saturation 1.4 Sigmoidal RGB 15 0.35`

Detalles del formato:

Gamma {BANDS} {VALUE} - Ajustar el brillo
Saturation {PROPORTION} - Ajustar la intensidad del color
Sigmoidal {BANDS} {CONTRAST} {BIAS} - Ajustar el contraste

Para obtener más información sobre la corrección de color, consulte la documentación de TiTiler.

4. Mapas de colores personalizados (para salida de banda única)

Parameter	Description	Format	Example
`colormap={json_string}`	Definir un mapa de colores personalizado	Valores de datos de asignación de JSON con codificación URL a 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]}`

Ejemplo se descodifica en: Asigna valor 1 a verde oscuro, 2 a verde muy oscuro, 3 a verde oliva, 4 a rojo naranja, 5 a amarillo, 6 a rosa/magenta, 7 a azul-violeta y 8 a rojo.

5. Control de datos

Parameter	Description	Example
`nodata={value}`	Especificar el valor de píxel para que sea transparente	`nodata=0`, `nodata=-9999` o `nodata=nan`
`unscale={true\\|false}`	Aplicar escala o desplazamiento a partir de metadatos de GeoTIFF	`unscale=true`

6. Rendimiento/comportamiento de mosaico

Parameter	Description	Format	Example
`maxItemsPerTile={integer}`	Límite del número de elementos de STAC por icono	Integer	`maxItemsPerTile=20`
`skipcovered={true\\|false}`	Omitir elementos cubiertos por otros usuarios	`true` o `false`	`skipcovered=true`
`exitwhenfull={true\\|false}`	Detener el procesamiento cuando el icono está completamente cubierto	`true` o `false`	`exitwhenfull=true`
`time_limit={seconds}`	Tiempo máximo para representar un icono	Entero (segundos)	`time_limit=10`

7. Parámetros de cubo de datos (GRIB/NetCDF)

Parameter	Tipo de datos	Description	Example
`subdataset_bands={band_index}`	GRIB	Seleccionar mensaje o banda específicos	`assets=grib_data&subdataset_bands=1&colormap_name=jet&rescale=273,300`
`subdataset_name={variable_name}`	NetCDF	Seleccionar variable para visualizar	`assets=netcdf_data&subdataset_name=temperature`
`datetime={timestamp}`	NetCDF	Seleccionar segmento de tiempo (ISO 8601)	`datetime=2023-10-26T12:00:00Z`

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

Paso 6: Agregar la configuración de representación a la colección

Una vez que construya la lista de configuración de representación (uno o varios objetos JSON), agréguela a la colección STAC:

Mediante la interfaz web:

Ve a tu colección en el portal de Planetary Computer Pro.
Seleccione el botón Configuración .
Vaya a la pestaña Render.
Pegue la lista JSON en el editor.
Para guardar los cambios, seleccione Actualizar.

Para obtener más información sobre cómo configurar colecciones, consulte Configuración de una colección con la interfaz web.

Uso de la API:

Defina una configuración de representación de colección a través del punto de conexión crear opciones de representación de colección stac. A continuación se muestra un ejemplo del uso de este punto de conexión mediante la API REST con 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 obtener más información sobre el uso de la API de recopilación de STAC, consulte Creación de una colección de STAC (ejemplos de API).

Examples

Estos son varios ejemplos de la options cadena y el objeto de configuración de renderización completa.

1. Single-Band Cambio de biomasa con mapa de colores y reescalado:

 {
    "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. Color natural de tres bandas (RGB) de recursos independientes:

 {
    "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. Color falso de tres bandas (NIR, R, G) de las bandas dentro de un único recurso:

{
    "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 de NDVI mediante expresión:

{
    "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. Visualización de temperatura de 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
  }

Referencia: Todos los parámetros `options`

La cadena options acepta los siguientes pares clave-valor (consulte la documentación de TiTiler para obtener los detalles más actualizados):

Parameter	Type	Description	Ejemplo de uso
`assets`	str	Claves del recurso de `item_assets`. Repita la clave para varios recursos.	`assets=B04&assets=B03&assets=B02`
`expression`	str	Expresión matemática mediante claves de activos.	`expression=(B08-B04)/(B08+B04)`
`asset_bidx`	str	Índices de banda para un recurso de varias bandas. Formato: `{asset_key}\|{idx1},{idx2},...`	`asset_bidx=image\|4,1,2`
`asset_as_band`	bool	Trate los recursos en `expression` como bandas únicas. Obligatorio cuando la expresión usa varios recursos.	`asset_as_band=true`
`colormap_name`	str	Nombre predefinido del mapa de colores TiTiler.	`colormap_name=viridis`
`colormap`	str	JSON con codificación URL que define un mapa de colores personalizado.	`colormap=%7B%221%22%3A%5B...%5D%7D`
`rescale`	str	Valores máximos mínimos separados por comas para el escalado de datos.	`rescale=0,3000`
`color_formula`	str	Fórmula de corrección de color separada por espacios (Gamma, Saturación, Sigmoidal).	`color_formula=Gamma RGB 2.2 Saturation 1.1`
`nodata`	str/float/int	Valor de píxel que se va a tratar como sin datos (transparente).	`nodata=0`, `nodata=-9999.0` o `nodata=nan`
`unscale`	bool	Aplique el escalado o desplazamiento de los metadatos de GeoTIFF.	`unscale=true`
`algorithm`	str	Nombre de un algoritmo de procesamiento TiTiler.	`algorithm=hillshade`
`algorithm_params`	str	Cadena JSON codificada con dirección URL con parámetros para el algoritmo.	`algorithm_params=%7B%22azimuth%22%3A315%7D`
`buffer`	float	Búfer de píxeles alrededor de los iconos (a menudo necesarios para los algoritmos).	`buffer=3`
`maxItemsPerTile`	int	Número máximo de elementos de STAC que se van a procesar por icono.	`maxItemsPerTile=20`
`skipcovered`	bool	Omita los elementos completamente ocultos por otros objetos.	`skipcovered=true`
`exitwhenfull`	bool	Detenga el procesamiento del icono una vez totalmente cubierto.	`exitwhenfull=true`
`time_limit`	int	Tiempo máximo de procesamiento (segundos) por icono.	`time_limit=10`
`subdataset_bands`	int	Índice de banda/mensaje para los datos GRIB.	`subdataset_bands=1`
`subdataset_name`	str	Nombre de variable para los datos de NetCDF.	`subdataset_name=temperature`
`datetime`	str	Marca de tiempo ISO 8601 para seleccionar el segmento de tiempo en NetCDF.	`datetime=2023-10-26T12:00:00Z`
`resampling`	str	Método de remuestreo (`nearest`, `bilinear`).	`resampling=nearest`

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-07-26