Konfigurera återgivningsinställningar för visualisering av data i Microsoft Planetary Computer Pro

Om du vill visualisera geospatiala data med datautforskaren Microsoft Planetary Computer Pro eller Tiler-API:et måste du definiera en eller flera återgivningskonfigurationer för var och en av dina STAC-samlingar (SpatioTemporal Asset Catalog). En återgivningskonfiguration anger hur datatillgångarna i dina STAC-objekt kombineras, bearbetas och utformas för att skapa kartpaneler.

Den här guiden vägleder dig genom processen att skapa renderingskonfigurationer, från att förstå förutsättningar till att konfigurera avancerade alternativ. Planetary Computer Pros återgivningsfunktioner bygger på TiTiler-projektet med öppen källkod.

Prerequisites

Innan du kan konfigurera renderingen kontrollerar du att följande nödvändiga steg är slutförda:

  1. STAC-samlingen finns: Du skapade en STAC-samling i Planetary Computer Pro.
  2. Inmatade data: Du har lagt till STAC-objekt som innehåller de geospatiala datatillgångar som du vill visualisera i samlingen.
  3. En Python 3.10-miljö (eller senare)

Process för att skapa en renderkonfiguration

Step Title Description
1 Definiera item_assets i samlingens JSON Först måste du se till att din STAC-samlings-JSON innehåller ett väldefinierat item_assets avsnitt som beskriver de gemensamma tillgångarna i dina objekt.
2 Förstå ditt data- och visualiseringsmål Bestäm sedan vilken typ av data du arbetar med och bestäm hur du vill att den ska visas visuellt (enbandsfärgkarta, RGB med flera band).
3 Konstruera återgivningskonfigurationsobjektet Skapa nu den grundläggande JSON-strukturen som innehåller en eller flera återgivningskonfigurationer för Explorer-användargränssnittet.
4 Definiera strängen options – kärnparametrar Konfigurera de viktiga TiTiler-parametrarna i strängen options för att välja rätt tillgångar eller band och tillämpa grundläggande stilinställningar, som färgkartor eller skaländringar.
5 Lägg till avancerade options parametrar (efter behov) Du kan också förbättra visualiseringen genom att lägga till avancerade TiTiler-funktioner som uttryck, algoritmer, färgkorrigering eller anpassade färgkartor med hjälp av strängen options .
6 Lägg till återgivningskonfigurationen i samlingen Tillämpa slutligen konfigurationslistan för återgivning som du skapade i din STAC-samling med antingen webbgränssnittet eller API:et.

Steg 1: Definiera item_assets i samlingens JSON

Det item_assets fältet i samlingens JSON är viktigt för återgivning eftersom det innehåller en konsoliderad beskrivning av de tillgångar som ingår i samlingens objekt. Renderingsmotorn och Explorer-webbprogrammet använder fältet item_assets för att förstå tillgängliga data för visualisering utan att inspektera enskilda objekt. Den deklarerar nycklarna (namnen) för tillgångarna, till exempel image, red, NIReller elevation, som sedan refereras till av återgivningskonfigurationerna. Dessutom kan item_assets innehålla STAC-tilläggsmetadata som eo:bands för tillgångar med flera band, vilket underlättar valet av specifika band för återgivning. Utforskaren använder den här informationen för att fylla i menyer och förstå den övergripande datastrukturen.

Exempel item_assets på en 4-bands NAIP-tillgång:

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

Mer information om item_assetsfinns i avsnittet Objekttillgångar i STAC-översikten. Se även den officiella STAC Item Assets Extension-specifikationen.

Se till att din STAC-samlings-JSON innehåller det här avsnittet innan du fortsätter. Du kan uppdatera din samlingsdefinition via API :et eller webbgränssnittet.

Steg 2: Förstå ditt data- och visualiseringsmål

Innan du skapar konfigurationen ska du bestämma hur du vill visualisera dina data:

Datatyp Description Example Visualiseringsmål
Single-Band data Varje pixel har ett värde. höjd, temperatur, marktäcke klassificering, beräknat index Mappa dessa enkla värden till ett färgintervall eller diskreta färger med hjälp av en färgkarta.
Data med flera band Data har flera band per pixel. RGB-satellitbilder, multispektrala data Kombinera tre specifika band för att representera kanalerna Röd, Grön och Blå i utdatabilden.
Härledda data (uttryck) Beräkna ett nytt värde från ett eller flera band/tillgångar. Normaliserat differensvegetationsindex (NDVI) från det röda och NIR-banden Definiera ett matematiskt uttryck och visualisera resultatet (enkelband med färgkarta eller flera band direkt).
Härledning av data (algoritmer) Beräkna ett nytt värde mellan bildpunkter. Hillshade visar konturer av höjddata Använd en matematisk algoritm för att omvandla data till en visualisering.
Datakuber (GRIB/NetCDF) Data som lagras i GRIB- eller NetCDF-format med flera variabler och dimensioner. tid, trycknivåer Välj en specifik variabel och potentiellt ett segment genom andra dimensioner (till exempel tid) för 2D-visualisering.

Steg 3: Konstruera återgivningskonfigurationsobjektet

Renderingskonfigurationer definieras som en lista över JSON-objekt (eller Python-ordlistor om du använder API:et). Varje objekt i listan representerar ett visualiseringsalternativ som visas i listrutan Utforskaren.

Grundläggande struktur:

[
  {
    "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
    "info_options": "assets=<asset_key>&subdataset_name=<var>" // Optional URL query-string for Explorer time slider discovery
  },
  {
    // ... another render configuration object ...
  }
]
  • id: En unik maskinläsbar identifierare för det här återgivningsalternativet i samlingen.
  • name: Visningsnamnet som visas i Explorer-användargränssnittet.
  • description: Valfri text som ger mer kontext.
  • type: Vanligtvis "raster-tile".
  • options: En sträng som innehåller URL-frågepar (key=value par avgränsade med &) som styr TiTiler-återgivningsmotorn. Det är här som de flesta anpassningar sker.
  • minZoom: Valfritt heltal som anger den minsta zoomnivå för kartan där det här lagret blir synligt. Användbart för att hantera prestanda med högupplösta data.
  • info_options: Valfri URL-frågesträng som aktiverar Utforskarens tidsreglage för datakubsamlingar (NetCDF, HDF5, GRIB2). Se Konfigurera tidsreglaget för Utforskaren för detaljer.

Med samma struktur är det möjligt att ha flera återgivningskonfigurationer för samma data så att data kan visualiseras på flera sätt.

Steg 4: Definiera strängen options – kärnparametrar

Strängen options är hjärtat i återgivningskonfigurationen. Det använder ett key=value&key=value format. Här är de vanligaste parametrarna:

1. Identifiera tillgångar/band

Parameter Description Användningsfall Example
assets={asset_key} Anger vilka tillgångar som ska användas, där {asset_key} matchar en nyckel som definierats i samlingens item_assets. Enkelbandsrendering med en resurs assets=elevation
Trebandsrendering med tre separata enskilda bandresurser (ordningen bestämmer R, G, B) assets=B04&assets=B03&assets=B02
Rendering med en enskild multiband-tillgång assets=image (används ofta med asset_bidx)
asset_bidx={asset_key}\|{band_index1},{band_index2},... Väljer specifika bandindex från en enskild multibandstillgång som anges av assets. Bandindex är vanligtvis 1-baserade. Trebands RGB från band 1, 2, 3 av resursen image assets=image&asset_bidx=image\|1,2,3
Trebands falsk färginfraröd (NIR, röd, grön) från banden 4, 1 och 2 av tillgången image assets=image&asset_bidx=image\|4,1,2
Rendering med ett enda band med endast band 4 av resursen image assets=image&asset_bidx=image\|4

2. Formatera Single-Band Data

Parameter Description Example
colormap_name={name} Tillämpar en fördefinierad colormap med ett specifikt namn. Vanliga exempel: viridis, plasma, gray, rdylgn. Se färgkartor som stöds. assets=elevation&colormap_name=viridis
rescale={min_val},{max_val} Sträcker ut eller komprimerar datavärdena så att de passar hela färgkartans intervall. Värden utanför det här intervallet är fastklämda i min/max-färgerna. Mappa höjdvärden från 100 m till 1 500 m över den fullständiga färgkartan: assets=elevation&colormap_name=viridis&rescale=100,1500

3. Formatera RGB-data (Multi-Band)

Parameter Description Example
RGB-bandordning RGB-band definieras implicit av ordningen i assets (för separata tillgångar) eller asset_bidx (för band inom en tillgång). Se exempel i tabellen Identifiera tillgångar/band
rescale={min_val},{max_val} (Valfritt) Kan användas för att skala indatavärdena för R-, G-, B-banden innan de mappas till visningsintervallet 0–255. Användbart om källdata inte redan är 8-bitars. assets=B04&assets=B03&assets=B02&rescale=0,3000
color_formula={formula_string} (Valfritt) Tillämpar formler för färgkorrigering. Se avancerade alternativ i nästa avsnitt.

Steg 5: Lägg till avancerade options parametrar (efter behov)

Utöver grunderna erbjuder TiTiler många avancerade parametrar via strängen options :

1. Uttryck

Parameter Description Format/Values Example
expression={formula} Definiera en matematisk formel med tillgångsnycklar som variabler Standardoperatorer (+, -, *, /) och parenteser expression=(B08-B04)/(B08+B04)
asset_as_band=true Krävs när uttrycket använder flera enbandstillgångar true eller false expression=(B08-B04)/(B08+B04)&asset_as_band=true

Examples

  • Exempel på enbandsresultat: expression=(B08-B04)/(B08+B04)&asset_as_band=true&colormap_name=rdylgn&rescale=-1,1
  • Flerbandsuttryck använder semikolon: expression=B04*1.5;B03*1.1;B02*1.3&asset_as_band=true
  • När du använder expression behöver du generellt inte assets eller asset_bidx

2. Algoritmer

Parameter Description Format/Values Example
algorithm={name} Använda en fördefinierad algoritm för pixelbearbetning hillshade, contours, terrarium, terrainrgb, normalizedIndex algorithm=hillshade
algorithm_params={json_string} Parametrar för algoritmen (URL-kodad JSON) Varierar beroende på algoritm algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D
buffer={integer} Lägg till pixelbuffert runt paneler (behövs ofta för algoritmer) Heltalsvärde buffer=3

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

Mer information om specifika algoritmer finns i dokumentationen för TiTiler-algoritmen och Mapbox Hillshade

3. Färgkorrigering (för RGB/Trebandsutdata)

Parameter Description Format Example
color_formula={formula_string} Tillämpa färgjusteringar Blankstegsavgränsad sträng med gamma-, mättnads- och/eller Sigmoidal-justeringar color_formula=Gamma RGB 2.5 Saturation 1.4 Sigmoidal RGB 15 0.35

Formatinformation:

  • Gamma {BANDS} {VALUE} - Justera ljusstyrka
  • Saturation {PROPORTION} - Justera färgintensiteten
  • Sigmoidal {BANDS} {CONTRAST} {BIAS} - Justera kontrast

Mer information om färgkorrigering finns i TiTiler-dokumentationen.

4. Anpassade färgkartor (för enbandsutdata)

Parameter Description Format Example
colormap={json_string} Definiera en anpassad färgkarta URL-kodad JSON-mappning av datavärden till RGBA-listor [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]}

Exemplet avkodas till: Mappar värden 1 till mörkgrön, 2 till mycket mörkgrön, 3 till olivgrön, 4 till orangeröd, 5 till gul, 6 till rosa/magenta, 7 till blåviolett och 8 till röd.

5. Datahantering

Parameter Description Example
nodata={value} Ange pixelvärde för att göra transparent nodata=0 eller nodata=-9999 eller nodata=nan
unscale={true\|false} Tillämpa skalning/förskjutning från GeoTIFF-metadata unscale=true

6. Prestanda/tiling-beteende

Parameter Description Format Example
maxItemsPerTile={integer} Begränsa antalet STAC-objekt per panel Integer maxItemsPerTile=20
skipcovered={true\|false} Hoppa över objekt som omfattas av andra true eller false skipcovered=true
exitwhenfull={true\|false} Sluta bearbeta när panelen är helt täckt true eller false exitwhenfull=true
time_limit={seconds} Maximal tid för återgivning av en panel Heltal (sekunder) time_limit=10

7. Data-kubparametrar (GRIB/NetCDF)

Parameter Datatyp Description Example
subdataset_bands={band_index} GRIB Välj specifikt meddelande/band assets=grib_data&subdataset_bands=1&colormap_name=jet&rescale=273,300
subdataset_name={variable_name} NetCDF Välj variabel för att visualisera assets=netcdf_data&subdataset_name=temperature
datetime={timestamp} NetCDF Välj tidssektor (ISO 8601) datetime=2023-10-26T12:00:00Z
sel={dimension}={value} Zarr Indexerare i Xarray-stil, upprepbar för varje dimension. sel=time=2024-01-01
sel_method={method} Zarr Xarray-indexeringsmetod för icke-exakta matchningar. sel_method=nearest

Fullständigt NetCDF-exempel:assets=netcdf_data&subdataset_name=temperature&datetime=2023-10-26T12:00:00Z&colormap_name=viridis&rescale=0,30

8. Konfigurera Explorer-tidsreglaget (Data Cubes)

För att aktivera Utforskarens tidsreglage för ett renderingsalternativ för datakuben, lägg till ett info_options fält i ditt renderingskonfigurationsobjekt. info_options är en URL-frågesträng, i samma format som options, som Utforskaren vidarebefordrar till Tilerens /info slutpunkt för varje synligt STAC-objekt. Explorer använder beskrivningarna av de returnerade banden för att bygga reglagets tickpositioner, så reglaget speglar vad Tilern kan servera. Detta fält gäller endast för raster-tile renderingsalternativ.

Ange info_options som den delmängd av options som är relevant för upptäckt: vanligtvis assets-parametern och, för NetCDF, HDF5 och Zarr, subdataset_name. Utelämna styling- och slicingparametrar som rescale, colormap_name, datetime, sel, och sel_method eftersom de inte påverkar bandupptäckten. När du aktiverar reglaget ska du också ta bort alla datetime= från options, annars åsidosätter det fixerade värdet reglaget.

{
  "id": "my-netcdf-render",
  "name": "Temperature over time",
  "type": "raster-tile",
  "options": "assets=t2m-kerchunk&subdataset_name=t2m&colormap_name=viridis&rescale=250,310",
  "minZoom": 1,
  "info_options": "assets=t2m-kerchunk&subdataset_name=t2m"
}

För GRIB2-samlingar innehåller info_options vanligtvis endast det resursurval som används för identifiering:

{
  "info_options": "assets=data"
}

Note

När info_options saknas återgår Explorer till det äldre beteendet – och läser cube:dimensions och start_datetime/end_datetime från metadata för STAC-objekt. Båda metoderna stöds samtidigt, så befintliga samlingar fortsätter att fungera utan förändringar.

Steg 6: Lägg till återgivningskonfigurationen i samlingen

När du har konstruerat konfigurationslistan för rendering (ett eller flera JSON-objekt) lägger du till den i DIN STAC-samling:

Använda webbgränssnittet:

  1. Gå till samlingen i Planetary Computer Pro-portalen.
  2. Välj knappen Konfiguration .
  3. Gå till fliken Rendera .
  4. Klistra in din JSON-lista i redigeraren.
  5. Spara ändringarna genom att välja Uppdatera.

Skärmbild av visningsalternativen för webbgränssnittet för renderingskonfiguration för konfiguration av renderingskonfigurationer.

Mer information om hur du konfigurerar samlingar finns i Konfigurera en samling med webbgränssnittet.

Använda API:et:

Definiera en konfiguration för samlingsåtergivning med hjälp av slutpunkten skapa stac-samlingsåtergivningsalternativ .

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": "2026-04-15"} # 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)

Mer information om hur du använder STAC Collection API finns i Skapa en STAC-samling (API-exempel).

Examples

Här är olika exempel på strängen options och konfigurationsobjektet för fullständig återgivning:

1. Single-Band biomassaändring med färgkarta och omskalning:

 {
    "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 Naturlig färg (RGB) från separata element:

 {
    "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 Falskfärg (NIR, R, G) från band inom en enda datakälla:

{
    "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. NDVI-beräkning med uttryck:

{
    "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. Hillshade-algoritm:

{
    "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. NetCDF-temperaturvisualisering:

{
    "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",
    "minZoom": 4,
    "info_options": "assets=cmip&subdataset_name=pr"
  }

Referens: Alla options parametrar

Strängen options kan innehålla följande nyckel/värde-par (se TiTiler-dokumentationen för den senaste informationen):

Parameter Type Description Exempel på användning
assets str Tillgångsnycklar från item_assets. Upprepa nyckeln för flera tillgångar. assets=B04&assets=B03&assets=B02
expression str Matematiskt uttryck med tillgångsnycklar. expression=(B08-B04)/(B08+B04)
asset_bidx str Bandindex för en tillgång med flera band. Format: {asset_key}|{idx1},{idx2},... asset_bidx=image|4,1,2
asset_as_band bool Behandla tillgångar i expression som enskilda band. Krävs när uttrycket använder flera tillgångar. asset_as_band=true
colormap_name str Fördefinierat TiTiler-färgkartanamn. colormap_name=viridis
colormap str URL-kodad JSON som definierar en anpassad färgkarta. colormap=%7B%221%22%3A%5B...%5D%7D
rescale str Kommaavgränsade min-, maxvärden för datanormalisering. rescale=0,3000
color_formula str Blankstegsavgränsad färgkorrigeringsformel (Gamma, Mättnad, Sigmoidal). color_formula=Gamma RGB 2.2 Saturation 1.1
nodata str/float/int Pixelvärde som ska behandlas som inga data (transparent). nodata=0 eller nodata=-9999.0 eller nodata=nan
unscale bool Tillämpa skalning/förskjutning från GeoTIFF-metadata. unscale=true
algorithm str Namnet på en TiTiler-bearbetningsalgoritm. algorithm=hillshade
algorithm_params str URL-kodad JSON-sträng med parametrar för algoritmen. algorithm_params=%7B%22azimuth%22%3A315%7D
buffer float Pixelbuffert runt paneler (behövs ofta för algoritmer). buffer=3
maxItemsPerTile int Maximalt antal STAC-objekt att bearbeta per panel. maxItemsPerTile=20
skipcovered bool Hoppa över objekt som är helt dolda av andra. skipcovered=true
exitwhenfull bool Sluta bearbeta en panel när den är helt täckt. exitwhenfull=true
time_limit int Maximal bearbetningstid (sekunder) per panel. time_limit=10
subdataset_bands int Band/meddelandeindex för GRIB-data. subdataset_bands=1
subdataset_name str Variabelnamn för NetCDF-data. subdataset_name=temperature
datetime str ISO 8601-tidsstämpel för att välja tidssektor i NetCDF. datetime=2023-10-26T12:00:00Z
resampling str Omsamplingsmetod (nearest, bilinear). resampling=nearest

Relaterat innehåll

  • Uppdaterades senast