Configurare le impostazioni di rendering per la visualizzazione dei dati in Microsoft Planetary Computer Pro

Per visualizzare i dati geospaziali usando Esplora dati Microsoft Planetary Computer Pro o l'API Tiler, è necessario definire una o più configurazioni di rendering per ognuna delle raccolte SpatioTemporal Asset Catalog (STAC). Una configurazione di rendering specifica il modo in cui gli asset di dati all'interno degli elementi STAC vengono combinati, elaborati e stilizzati per creare tiles della mappa.

Questa guida illustra il processo di creazione di configurazioni di rendering, dalla comprensione dei prerequisiti alla configurazione delle opzioni avanzate. Le funzionalità di rendering di Planetary Computer Pro sono basate sul progetto TiTiler open source.

Prerequisites

Prima di poter configurare il rendering, assicurarsi che siano stati completati i passaggi prerequisiti seguenti:

Raccolta STAC esistente: È stata creata una raccolta STAC in Planetary Computer Pro.
Dati inseriti: Hai aggiunto elementi STAC contenenti gli asset di dati geospaziali che vuoi visualizzare nella raccolta.

Processo per compilare una configurazione di rendering

Step	Title	Description
1	Definire `item_assets` nel codice JSON della raccolta	Prima di tutto, è necessario assicurarsi che il codice JSON della raccolta STAC includa una sezione ben definita `item_assets` che descrive gli asset comuni all'interno degli elementi.
2	Comprendere l'obiettivo di dati e visualizzazione	Successivamente, determinare il tipo di dati con cui si sta lavorando e decidere come visualizzarlo visivamente (mappa a colori a banda singola, RGB a più bande).
3	Costruire l'oggetto di configurazione del rendering	Creare ora la struttura JSON di base che contiene una o più configurazioni di rendering per l'interfaccia utente di Explorer.
4	Definire la `options` stringa - Parametri fondamentali	Configurare i parametri TiTiler essenziali all'interno della `options` stringa per selezionare gli asset o le bande corrette e applicare stili di base come mappe a colori o ridimensionamento.
5	Aggiungere parametri avanzati `options` (se necessario)	Facoltativamente, migliorare la visualizzazione aggiungendo funzionalità titiler avanzate, ad esempio espressioni, algoritmi, correzione dei colori o mappe colori personalizzate usando la `options` stringa.
6	Aggiungere la configurazione di rendering alla raccolta	Infine, applica l'elenco di configurazione di rendering creato alla raccolta STAC usando l'interfaccia web o l'API.

Passaggio 1: Definire `item_assets` nella raccolta JSON

Il campo item_assets nel codice JSON della raccolta è essenziale per il rendering perché fornisce una descrizione consolidata degli asset contenuti negli elementi della raccolta. Il motore di rendering e l'applicazione Web Explorer usano il campo item_assets per comprendere i dati disponibili per la visualizzazione senza esaminare singoli elementi. Dichiara le chiavi (nomi) degli asset, ad esempio image, , redNIRo elevation, a cui fanno quindi riferimento le configurazioni di rendering. Inoltre, item_assets può includere metadati dell'estensione STAC, ad eo:bands esempio per asset a più bande, semplificando la selezione di bande specifiche per il rendering. L'Esploratore usa queste informazioni per popolare i menu e capire la struttura complessiva dei dati.

Esempio item_assets per un asset NAIP a 4 bande:

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

Per altre informazioni su item_assets, vedere la sezione Asset elemento nella panoramica di STAC. Vedere anche la specifica ufficiale dell'estensione asset elemento STAC.

Assicurarsi che il codice JSON della raccolta STAC includa questa sezione prima di procedere. È possibile aggiornare la definizione della raccolta tramite l'API o l'interfaccia Web.

Passaggio 2: Comprendere i tuoi dati e l'obiettivo della visualizzazione

Prima di compilare la configurazione, determinare come visualizzare i dati:

Tipo di dati	Description	Example	Obiettivo della visualizzazione
Dati single-band	Ogni pixel ha un valore.	elevazione, temperatura, classificazione copertura terra, indice calcolato	Eseguire il mapping di questi singoli valori a un intervallo di colori o a colori discreti usando una mappa colori.
Dati su più bande	I dati hanno più bande per pixel.	Immagini satellitari RGB, dati multi-spettrali	Combinare tre bande specifiche per rappresentare i canali Red, Green e Blue dell'immagine di output.
Dati derivati (espressioni)	Calcolare un nuovo valore da una o più bande/asset.	Indice di Vegetazione a Differenza Normalizzata (NDVI) delle bande rosso e NIR	Definire un'espressione matematica e visualizzare il risultato (singola banda con mappa a colori o multi-banda direttamente).
Dati derivati (algoritmi)	Calcolare un nuovo valore in pixel.	Hillshade mostra le linee di contorno dei dati altimetrici	Usare un algoritmo matematico per trasformare i dati in una visualizzazione.
Cubi di dati (GRIB/NetCDF)	Dati archiviati in formati GRIB o NetCDF con più variabili e dimensioni.	tempo, livelli di pressione	Selezionare una variabile specifica e potenzialmente una sezione attraverso altre dimensioni (ad esempio il tempo) per la visualizzazione 2D.

Passaggio 3: Costruire l'oggetto di configurazione del rendering

Le configurazioni di rendering sono definite come un elenco di oggetti JSON (o dizionari Python se si usa l'API). Ogni oggetto nell'elenco rappresenta un'opzione di visualizzazione che verrà visualizzata nell'elenco a discesa Explorer.

Struttura di base:

[
  {
    "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: identificatore univoco leggibile dal computer per questa opzione di rendering all'interno della raccolta.
name: il nome visualizzato nell'interfaccia utente di Explorer.
description: testo facoltativo che fornisce più contesto.
type: In genere "raster-tile".
options: stringa contenente parametri di query URL (key=value coppie separate da &) che controllano il motore di rendering TiTiler. Questa è la posizione in cui viene eseguita la maggior parte della personalizzazione.
minZoom: numero intero facoltativo che specifica il livello di zoom minimo della mappa in corrispondenza del quale questo livello diventa visibile. Utile per la gestione delle prestazioni con dati ad alta risoluzione.

Usando la stessa struttura, è possibile avere più configurazioni di rendering per gli stessi dati in modo che i dati possano essere visualizzati in più modi.

Passaggio 4: Definire la `options` stringa - Parametri di base

La options stringa è il cuore della configurazione di rendering. Usa un key=value&key=value formato. Ecco i parametri più comuni:

1. Identificazione di asset/bande

Parameter	Description	Caso d'uso	Example
`assets={asset_key}`	Specifica gli asset da usare, dove `{asset_key}` corrisponde a una chiave definita nella raccolta.`item_assets`	Rendering a banda singola con un solo asset	`assets=elevation`
		Rendering a tre bande usando tre asset a banda singola separati (l'ordine determina R, G, B)	`assets=B04&assets=B03&assets=B02`
		Rendering con un singolo asset a più bande	`assets=image` (spesso usato con `asset_bidx`)
`asset_bidx={asset_key}\\|{band_index1},{band_index2},...`	Seleziona indici di banda specifici dall'interno di un singolo asset a più bande specificato da `assets`. Gli indici di banda sono in genere basati su 1.	Rgb a tre bande da bande 1, 2, 3 di asset `image`	`assets=image&asset_bidx=image\\|1,2,3`
		Tre bande False Color Infrared (NIR, Red, Green) dalle bande 4, 1, 2 di asset `image`	`assets=image&asset_bidx=image\\|4,1,2`
		Rendering a banda singola con solo banda 4 di asset `image`	`assets=image&asset_bidx=image\\|4`

2. Applicazione di stili ai dati a banda singola

Parameter	Description	Example
`colormap_name={name}`	Applica una mappa colori denominata predefinita. Esempi comuni: `viridis`, `plasma`, `gray`, `rdylgn`. Vedere le mappe colori supportate.	`assets=elevation&colormap_name=viridis`
`rescale={min_val},{max_val}`	Estende o comprime i valori dei dati per adattarsi all'intervallo completo della mappa colori. I valori al di fuori di questo intervallo sono bloccati ai colori min/max.	Mappare le altitudini da 100 m a 1500 m nella mappa a colori completa: `assets=elevation&colormap_name=viridis&rescale=100,1500`

3. Applicazione di stili ai dati a più bande (RGB)

Parameter	Description	Example
Ordine delle bande RGB	Le bande RGB sono definite in modo implicito dall'ordine in `assets` (per asset separati) o `asset_bidx` (per le bande all'interno di un asset).	Vedere esempi nella tabella Identificazione di asset/bande
`rescale={min_val},{max_val}`	(Facoltativo) Può essere usato per ridimensionare i valori di input delle bande R, G, B prima di eseguirne il mapping all'intervallo di visualizzazione da 0 a 255. Utile se i dati di origine non sono già a 8 bit.	`assets=B04&assets=B03&assets=B02&rescale=0,3000`
`color_formula={formula_string}`	(Facoltativo) Applica formule di correzione del colore.	Vedere opzioni avanzate nella sezione successiva.

Passaggio 5: Aggiungere parametri avanzati `options` (se necessario)

Oltre alle nozioni di base, TiTiler offre molti parametri avanzati tramite la options stringa :

1. Espressioni

Parameter	Description	Format/Values	Example
`expression={formula}`	Definire una formula matematica usando le chiavi di asset come variabili	Operatori standard (`+`, `-`, `*`, `/`) e parentesi	`expression=(B08-B04)/(B08+B04)`
`asset_as_band=true`	Obbligatorio quando l'espressione usa più asset a banda singola	`true` o `false`	`expression=(B08-B04)/(B08+B04)&asset_as_band=true`

Examples

Esempio di risultato a banda singola: expression=(B08-B04)/(B08+B04)&asset_as_band=true&colormap_name=rdylgn&rescale=-1,1
Le espressioni a più bande usano punti e virgola: expression=B04*1.5;B03*1.1;B02*1.3&asset_as_band=true
Quando si usa expression, in genere non è necessario assets o asset_bidx

2. Algoritmi

Parameter	Description	Format/Values	Example
`algorithm={name}`	Applicare un algoritmo di elaborazione pixel predefinito	`hillshade`, `contours`, `terrarium`, `terrainrgbnormalizedIndex`	`algorithm=hillshade`
`algorithm_params={json_string}`	Parametri per l'algoritmo (JSON con codifica URL)	Varia in base all'algoritmo	`algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D`
`buffer={integer}`	Aggiungere buffer pixel intorno ai riquadri (spesso necessari per gli algoritmi)	Valore intero	`buffer=3`

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

Per informazioni dettagliate su algoritmi specifici, vedere la documentazione dell'algoritmo TiTiler e Mapbox Hillshade

3. Correzione dei colori (per l'output RGB/ a tre bande)

Parameter	Description	Format	Example
`color_formula={formula_string}`	Applicare le regolazioni dei colori	Stringa delimitata da spazi con regolazioni Gamma, Saturazione e/o Sigmoidal	`color_formula=Gamma RGB 2.5 Saturation 1.4 Sigmoidal RGB 15 0.35`

Dettagli formato:

Gamma {BANDS} {VALUE} - Regolare la luminosità
Saturation {PROPORTION} - Regolare l'intensità del colore
Sigmoidal {BANDS} {CONTRAST} {BIAS} - Regolare il contrasto

Per altre informazioni sulla correzione dei colori, vedere la documentazione di TiTiler.

4. Mappe colori personalizzate (per l'output a banda singola)

Parameter	Description	Format	Example
`colormap={json_string}`	Definire una mappa colori personalizzata	Valori dei dati di mapping JSON codificati con URL a elenchi 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]}`

Decodifica di esempio in: Mappa il valore da 1 a verde scuro, da 2 a verde molto scuro, da 3 a verde oliva, da 4 a rosso arancione, da 5 a giallo, da 6 a rosa/magenta, da 7 a viola blu e da 8 a rosso.

5. Gestione dei dati

Parameter	Description	Example
`nodata={value}`	Specificare il valore pixel per rendere trasparente	`nodata=0` o `nodata=-9999` o `nodata=nan`
`unscale={true\\|false}`	Applicare scalabilità/offset dai metadati GeoTIFF	`unscale=true`

6. Prestazioni/Comportamento di tiling

Parameter	Description	Format	Example
`maxItemsPerTile={integer}`	Limitare il numero di elementi STAC per riquadro	Integer	`maxItemsPerTile=20`
`skipcovered={true\\|false}`	Ignorare gli elementi coperti da altri utenti	`true` o `false`	`skipcovered=true`
`exitwhenfull={true\\|false}`	Interrompere l'elaborazione quando il riquadro è completamente coperto	`true` o `false`	`exitwhenfull=true`
`time_limit={seconds}`	Tempo massimo per il rendering di un riquadro	Integer (secondi)	`time_limit=10`

7. Parametri del cubo di dati (GRIB/NetCDF)

Parameter	Tipo di dati	Description	Example
`subdataset_bands={band_index}`	GRIB	Selezionare messaggio/banda specifica	`assets=grib_data&subdataset_bands=1&colormap_name=jet&rescale=273,300`
`subdataset_name={variable_name}`	NetCDF	Selezionare la variabile da visualizzare	`assets=netcdf_data&subdataset_name=temperature`
`datetime={timestamp}`	NetCDF	Selezionare la sezione temporale (ISO 8601)	`datetime=2023-10-26T12:00:00Z`

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

Passaggio 6: Aggiungere la configurazione di rendering alla raccolta

Dopo aver creato l'elenco di configurazione del rendering (uno o più oggetti JSON), aggiungerlo alla raccolta STAC:

Uso dell'interfaccia Web:

Vai alla tua raccolta nel portale del Planetary Computer Pro.
Selezionare il pulsante Configurazione .
Passare alla scheda Rendering .
Incollare l'elenco JSON nell'editor.
Salvare le modifiche selezionando Aggiorna.

Per altre informazioni sulla configurazione delle raccolte, vedere Configurare una raccolta con l'interfaccia Web.

Uso dell'API:

Definire una configurazione di rendering della raccolta utilizzando l'endpoint create stac collection render options. Di seguito è riportato un esempio di uso di questo endpoint usando l'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)

Per altre informazioni sull'uso dell'API raccolta STAC, vedere Creare una raccolta STAC (esempi di API).

Examples

Di seguito sono riportati vari esempi della options stringa e dell'oggetto di configurazione di rendering completo:

1. Modifica della biomassa a banda singola con mappa a colori e ridimensionamento:

 {
    "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. Colore naturale Three-Band (RGB) da risorse separate:

 {
    "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) da bande all'interno di un singolo asset:

{
    "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. Calcolo NDVI tramite Espressione:

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

Riferimento: Tutti i parametri `options`

La stringa options accetta le coppie chiave-valore seguenti (vedere la documentazione di TiTiler per i dettagli più aggiornati):

Parameter	Type	Description	Esempio di utilizzo
`assets`	str	Chiavi asset da `item_assets`. Ripetere la chiave per più asset.	`assets=B04&assets=B03&assets=B02`
`expression`	str	Espressione matematica che usa le chiavi di asset.	`expression=(B08-B04)/(B08+B04)`
`asset_bidx`	str	Indici di banda per un asset multi-banda. Formato: `{asset_key}\|{idx1},{idx2},...`	`asset_bidx=image\|4,1,2`
`asset_as_band`	bool	Considera gli asset in `expression` come singole bande. Obbligatorio quando l'espressione usa più asset.	`asset_as_band=true`
`colormap_name`	str	Nome predefinito della mappa a colori TiTiler.	`colormap_name=viridis`
`colormap`	str	JSON con codifica URL che definisce una mappa colori personalizzata.	`colormap=%7B%221%22%3A%5B...%5D%7D`
`rescale`	str	Min delimitato da virgole, valori massimi per il ridimensionamento dei dati.	`rescale=0,3000`
`color_formula`	str	Formula di correzione del colore separata da spazi (Gamma, Saturazione, Sigmoidal).	`color_formula=Gamma RGB 2.2 Saturation 1.1`
`nodata`	str/float/int	Valore pixel da considerare come nessun dato (trasparente).	`nodata=0` o `nodata=-9999.0` o `nodata=nan`
`unscale`	bool	Applicare la scala/offset dai metadati GeoTIFF.	`unscale=true`
`algorithm`	str	Nome di un algoritmo di elaborazione TiTiler.	`algorithm=hillshade`
`algorithm_params`	str	Stringa JSON con codifica URL con parametri per l'algoritmo.	`algorithm_params=%7B%22azimuth%22%3A315%7D`
`buffer`	float	Buffer pixel intorno ai riquadri (spesso necessari per gli algoritmi).	`buffer=3`
`maxItemsPerTile`	int	Numero massimo di elementi STAC da elaborare per riquadro.	`maxItemsPerTile=20`
`skipcovered`	bool	Ignorare gli elementi completamente nascosti da altri utenti.	`skipcovered=true`
`exitwhenfull`	bool	Interrompere l'elaborazione di un riquadro una volta completamente coperto.	`exitwhenfull=true`
`time_limit`	int	Tempo massimo di elaborazione (secondi) per riquadro.	`time_limit=10`
`subdataset_bands`	int	Indice di banda/messaggio per i dati GRIB.	`subdataset_bands=1`
`subdataset_name`	str	Nome della variabile per i dati NetCDF.	`subdataset_name=temperature`
`datetime`	str	Timestamp ISO 8601 per selezionare una sezione temporale in NetCDF.	`datetime=2023-10-26T12:00:00Z`
`resampling`	str	Metodo di ricampionamento (`nearest`, `bilinear`).	`resampling=nearest`

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-07-26