Konfigurowanie ustawień renderowania pod kątem wizualizowania danych w microsoft Planetary Computer Pro

Aby wizualizować dane geoprzestrzenne przy użyciu Eksploratora danych Microsoft Planetary Computer Pro lub interfejsu API Tiler, należy zdefiniować co najmniej jedną konfigurację renderowania dla każdej kolekcji katalogu zasobów SpatioTemporal (STAC). Konfiguracja renderowania określa sposób łączenia, przetwarzania i stylu zasobów danych w elementach STAC w celu utworzenia kafelków mapy.

Ten przewodnik przeprowadzi Cię przez proces tworzenia konfiguracji renderowania, od zrozumienia wymagań wstępnych do konfigurowania zaawansowanych opcji. Możliwości renderowania Planetary Computer Pro są oparte na projekcie TiTiler typu open source.

Prerequisites

Przed skonfigurowaniem renderowania upewnij się, że zostały spełnione następujące czynności wstępne:

1. Kolekcja STAC istnieje: Utworzono kolekcję STAC w Planetary Computer Pro.
2. Pozyskane dane: Dodano elementy STAC zawierające zasoby danych geoprzestrzennych, które chcesz wizualizować w kolekcji.

Proces tworzenia konfiguracji renderowania

Step	Title	Description
1	Zdefiniuj item_assets w JSON kolekcji	Najpierw należy upewnić się, że plik JSON kolekcji STAC zawiera dobrze zdefiniowaną item_assets sekcję, która opisuje wspólne zasoby w twoich elementach.
2	Informacje o danych i celu wizualizacji	Następnie określ typ danych, z którymi pracujesz, i zdecyduj, jak mają być wyświetlane wizualnie (mapa kolorów jednopasmowa, wielopasmowy RGB).
3	Konstruowanie obiektu konfiguracji renderowania	Teraz utwórz podstawową strukturę JSON zawierającą co najmniej jedną konfigurację renderowania dla interfejsu użytkownika eksploratora.
4	Definiowanie ciągu options — podstawowe parametry	Skonfiguruj podstawowe parametry TiTiler w ciągu options , aby wybrać odpowiednie zasoby lub pasma i zastosować podstawowe style, takie jak mapy kolorów lub ponowne skalowanie.
5	Dodawanie parametrów zaawansowanych options (zgodnie z potrzebami)	Opcjonalnie możesz ulepszyć wizualizację, dodając zaawansowane funkcje TiTiler, takie jak wyrażenia, algorytmy, korekta kolorów lub niestandardowe mapy kolorów przy użyciu options ciągu.
6	Dodawanie konfiguracji renderowania do kolekcji	Na koniec zastosuj listę konfiguracji renderowania utworzoną do kolekcji STAC przy użyciu interfejsu internetowego lub interfejsu API.

Krok 1. Zdefiniuj item_assets w JSON kolekcji

Pole item_assets w kodzie JSON kolekcji jest niezbędne do renderowania, ponieważ zawiera skonsolidowany opis zasobów zawartych w elementach kolekcji. Aparat renderowania i aplikacja internetowa Eksploratora używają pola item_assets, aby zrozumieć dostępne dane do wizualizacji bez sprawdzania poszczególnych elementów. Deklaruje klucze (nazwy) zasobów, takich jak image, red, NIRlub elevation, które następnie odwołują się do konfiguracji renderowania. Ponadto item_assets mogą zawierać metadane rozszerzenia STAC, takie jak eo:bands w przypadku zasobów wielopasmowych, ułatwiając wybór określonych przedziałów do renderowania. Eksplorator używa tych informacji do wypełniania menu i zrozumienia ogólnej struktury danych.

Przykład item_assets zasobu NAIP 4-pasmowego:

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

Aby uzyskać więcej informacji na temat item_assets, zobacz sekcję Zasoby obiektu w Przeglądzie STAC. Zapoznaj się również z oficjalną specyfikacją rozszerzenia zasobów elementów STAC.

Przed kontynuowaniem upewnij się, że kod JSON kolekcji STAC zawiera tę sekcję. Definicję kolekcji można zaktualizować za pomocą interfejsu API lub interfejsu internetowego.

Krok 2. Zrozumienie celu danych i wizualizacji

Przed utworzeniem konfiguracji określ, jak chcesz wizualizować dane:

Typ danych	Description	Example	Cel wizualizacji
dane jednopasmowe	Każdy piksel ma jedną wartość.	podniesienie, temperatura, klasyfikacja pokrywy lądowej, indeks obliczeniowy	Zamapuj te pojedyncze wartości na zakres kolorów lub odrębne kolory przy użyciu mapy kolorów.
Dane wielopasmowe	Dane mają wiele pasm na piksel.	Obrazy satelitarne RGB, dane wielospektralne	Połącz trzy konkretne pasma, aby reprezentować kanały Czerwony, Zielony i Niebieski obrazu wyjściowego.
Dane wynikowe (wyrażenia)	Oblicz nową wartość z co najmniej jednego przedziału/zasobów.	Znormalizowany różnicowy wskaźnik wegetacji (NDVI) z pasm czerwonego i bliskiej podczerwieni	Zdefiniuj wyrażenie matematyczne i zwizualizuj wynik (jednopasmowy z mapą kolorów lub bezpośrednio wielopasmową).
Dane pochodne (algorytmy)	Oblicz nową wartość w pikselach.	Hillshade przedstawia kontury danych o wysokości	Użyj algorytmu matematycznego, aby przekształcić dane w wizualizację.
Moduły danych (GRIB/NetCDF)	Dane przechowywane w formatach GRIB lub NetCDF z wieloma zmiennymi i wymiarami.	czas, poziomy ciśnienia	Wybierz określoną zmienną i potencjalnie wycinek przez inne wymiary (takie jak czas) do wizualizacji 2D.

Krok 3. Konstruowanie obiektu konfiguracji renderowania

Konfiguracje renderowania są definiowane jako lista obiektów JSON (lub słowników języka Python w przypadku korzystania z interfejsu API). Każdy obiekt na liście reprezentuje jedną opcję wizualizacji, która będzie wyświetlana na liście rozwijanej Eksplorator.

Podstawowa struktura:

[
  {
    "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: unikatowy identyfikator czytelny dla maszyny dla tej opcji renderowania w kolekcji.
• name: nazwa wyświetlana w interfejsie użytkownika eksploratora.
• description: Opcjonalny tekst zapewniający więcej kontekstu.
• type: zazwyczaj "raster-tile".
• options: ciąg zawierający parametry zapytania adresu URL (key=value pary rozdzielone przez &) kontrolujące aparat renderowania TiTiler. W tym miejscu odbywa się większość dostosowań.
• minZoom: Opcjonalna liczba całkowita określająca minimalny poziom powiększenia mapy, na którym ta warstwa staje się widoczna. Przydatne do zarządzania wydajnością przy użyciu danych o wysokiej rozdzielczości.

Korzystając z tej samej struktury, można mieć wiele konfiguracji renderowania dla tych samych danych, dzięki czemu dane mogą być wizualizowane na wiele sposobów.

Krok 4. Definiowanie options ciągu — podstawowe parametry

Ciąg options jest sercem konfiguracji renderowania. Używa key=value&key=value formatu. Poniżej przedstawiono najbardziej typowe parametry:

1. Identyfikowanie zasobów/pasm

Parameter	Description	Przypadek użycia	Example
assets={asset_key}	Określa zasoby do użycia, gdzie {asset_key} pasuje do klucza zdefiniowanego w kolekcji item_assets.	Renderowanie jednopasmowe przy użyciu jednego zasobu	assets=elevation
		Renderowanie trójpasmowe przy użyciu trzech oddzielnych zasobów jednopasmowych (kolejność określa R, G, B)	assets=B04&assets=B03&assets=B02
		Renderowanie przy użyciu pojedynczego zasobu wielopasmowego	assets=image (często używane z asset_bidx)
asset_bidx={asset_key}\|{band_index1},{band_index2},...	Wybiera określone indeksy przedziałów z jednego zasobu wielopasmowego określonego przez assets. Indeksy pasmowe są zwykle oparte na 1.	Trzypasmowe RGB z pasm 1, 2, 3 zasobu image	assets=image&asset_bidx=image\|1,2,3
		Trzypasmowa Fałszywa Kolorystyka Podczerwieni (NIR, Czerwony, Zielony) z pasm 4, 1, 2 zasobu image	assets=image&asset_bidx=image\|4,1,2
		Renderowanie jednopasmowe przy użyciu tylko pasma 4 zasobuimage	assets=image&asset_bidx=image\|4

2. Stylowanie danych Single-Band

Parameter	Description	Example
colormap_name={name}	Stosuje wstępnie zdefiniowaną mapę kolorów. Typowe przykłady: viridis, , plasmagray, rdylgn. Zobacz obsługiwane mapy kolorów.	assets=elevation&colormap_name=viridis
rescale={min_val},{max_val}	Rozciąga lub kompresuje wartości danych w celu dopasowania do pełnego zakresu mapy kolorów. Wartości poza tym zakresem są przypisane do kolorów minimalnych i maksymalnych.	Mapuj wartości wysokości od 100 m do 1500 m na pełnej mapie kolorów: assets=elevation&colormap_name=viridis&rescale=100,1500

3. Stylowanie danych wielopasmowych (RGB)

Parameter	Description	Example
Kolejność pasm RGB	Pasma RGB są niejawnie definiowane przez kolejność w assets (dla oddzielnych zasobów) lub asset_bidx (dla pasm w obrębie zasobu).	Zobacz przykłady w tabeli Identyfikowanie zasobów/pasm
rescale={min_val},{max_val}	(Opcjonalnie) Można użyć do skalowania wartości wejściowych pasm R, G, B przed mapowaniem ich na zakres wyświetlania 0–255. Przydatne, jeśli dane źródłowe nie są jeszcze 8-bitowe.	assets=B04&assets=B03&assets=B02&rescale=0,3000
color_formula={formula_string}	(Opcjonalnie) Stosuje formuły korekty kolorów.	Zobacz opcje zaawansowane w następnej sekcji.

Krok 5. Dodawanie parametrów zaawansowanych options (zgodnie z potrzebami)

Poza podstawowymi elementami TiTiler oferuje wiele zaawansowanych parametrów poprzez ciąg options

1. Wyrażenia

Parameter	Description	Format/Values	Example
expression={formula}	Definiowanie formuły matematycznej przy użyciu kluczy zasobów jako zmiennych	Operatory standardowe (+, , -*, /) i nawiasy	expression=(B08-B04)/(B08+B04)
asset_as_band=true	Wymagane, gdy wyrażenie używa wielu zasobów jednopasmowych	true lub false	expression=(B08-B04)/(B08+B04)&asset_as_band=true

Examples

• Przykład wyniku jednopasmowego: expression=(B08-B04)/(B08+B04)&asset_as_band=true&colormap_name=rdylgn&rescale=-1,1
• Wyrażenia wielopasmowe używają średników: expression=B04*1.5;B03*1.1;B02*1.3&asset_as_band=true
• Podczas używania expression, zazwyczaj nie potrzebujesz assets ani asset_bidx.

2. Algorytmy

Parameter	Description	Format/Values	Example
algorithm={name}	Stosowanie wstępnie zdefiniowanego algorytmu przetwarzania pikseli	hillshade, , contours, terrarium, , terrainrgbnormalizedIndex	algorithm=hillshade
algorithm_params={json_string}	Parametry algorytmu (kodowany za pomocą adresu URL JSON)	Różni się w zależności od algorytmu	algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D
buffer={integer}	Dodawanie buforu pikseli wokół kafelków (często potrzebnych dla algorytmów)	Wartość całkowita	buffer=3

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

Aby uzyskać szczegółowe informacje na temat określonych algorytmów, zobacz dokumentację algorytmu TiTiler i Mapbox Hillshade

3. Korekta koloru (dla danych wyjściowych RGB/trójpasmowych)

Parameter	Description	Format	Example
color_formula={formula_string}	Stosowanie korekt kolorów	Ciąg rozdzielony spacjami z korektami Gamma, Nasycenia i/lub Sigmoidalnymi	color_formula=Gamma RGB 2.5 Saturation 1.4 Sigmoidal RGB 15 0.35

Szczegóły formatu:

• Gamma {BANDS} {VALUE} - Dopasowuje jasność
• Saturation {PROPORTION} - Dopasuj intensywność kolorów
• Sigmoidal {BANDS} {CONTRAST} {BIAS} - Dopasuj kontrast

Aby uzyskać więcej informacji na temat korekty kolorów, zobacz dokumentację TiTiler.

4. Mapy kolorów niestandardowe (dla jednopasmowego wyjścia)

Parameter	Description	Format	Example
colormap={json_string}	Definiowanie niestandardowej mapy kolorów	Zakodowane w formacie URL wartości danych z mapowania JSON na listy 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]}

Przykładowe dekodowanie do: Mapuje wartość 1 na ciemnozieloną, 2 na bardzo ciemnozieloną, 3 na oliwkowo-zieloną, 4 na pomarańczowo-czerwoną, 5 na żółtą, 6 na różową/magenta, 7 na niebiesko-fioletową i 8 na czerwoną.

5. Obsługa danych

Parameter	Description	Example
nodata={value}	Określ wartość pikseli, aby uczynić przezroczystą	nodata=0 lub nodata=-9999 lub nodata=nan
unscale={true\|false}	Zastosuj skalowanie/przesunięcie z metadanych GeoTIFF	unscale=true

6. Wydajność / Zachowanie kafelkowania

Parameter	Description	Format	Example
maxItemsPerTile={integer}	Ogranicz liczbę elementów STAC na płytkę	Integer	maxItemsPerTile=20
skipcovered={true\|false}	Pomiń elementy objęte innymi	true lub false	skipcovered=true
exitwhenfull={true\|false}	Zatrzymaj przetwarzanie, gdy kafelek jest całkowicie pokryty	true lub false	exitwhenfull=true
time_limit={seconds}	Maksymalny czas renderowania kafelka	Integer (w sekundach)	time_limit=10

7. Parametry modułu danych (GRIB/NetCDF)

Parameter	Typ danych	Description	Example
subdataset_bands={band_index}	GRIB	Wybieranie określonej wiadomości/przedziału	assets=grib_data&subdataset_bands=1&colormap_name=jet&rescale=273,300
subdataset_name={variable_name}	NetCDF	Wybieranie zmiennej do wizualizacji	assets=netcdf_data&subdataset_name=temperature
datetime={timestamp}	NetCDF	Wybieranie wycinka czasu (ISO 8601)	datetime=2023-10-26T12:00:00Z

Pełny przykład usługi NetCDF:assets=netcdf_data&subdataset_name=temperature&datetime=2023-10-26T12:00:00Z&colormap_name=viridis&rescale=0,30

Krok 6. Dodawanie konfiguracji renderowania do kolekcji

Po utworzeniu listy konfiguracji renderowania (co najmniej jeden obiekt JSON) dodaj go do kolekcji STAC:

Korzystanie z interfejsu internetowego:

1. Przejdź do kolekcji w portalu Planetary Computer Pro.
2. Wybierz przycisk Konfiguracja .
3. Przejdź do karty Renderowanie .
4. Wklej listę JSON do edytora.
5. Zapisz zmiany, wybierając pozycję Aktualizuj.

Aby uzyskać więcej informacji na temat konfigurowania kolekcji, zobacz Konfigurowanie kolekcji za pomocą interfejsu internetowego.

Korzystanie z interfejsu API:

Zdefiniuj konfigurację renderowania kolekcji, używając punktu końcowego create stac collection render options. Poniżej przedstawiono przykład użycia tego punktu końcowego przy użyciu interfejsu API REST w języku 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)

Aby uzyskać więcej informacji na temat korzystania z interfejsu API kolekcji STAC, zobacz Tworzenie kolekcji STAC (przykłady interfejsu API).

Examples

Poniżej przedstawiono różne przykłady options ciągu i pełnego obiektu konfiguracji renderowania:

1. Single-Band Zmiana biomasy z mapą kolorów i przeskalowaniem:

 {
    "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 kolor naturalny (RGB) z oddzielnych elementów:

 {
    "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) z pasm w ramach jednego elementu:

{
    "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. Obliczenie NDVI przy użyciu wyrażenia:

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

Referencja: wszystkie options parametry

Ciąg options akceptuje następujące pary klucz-wartość (zapoznaj się z dokumentacją TiTiler , aby uzyskać najbardziej up-to-date details):

Parameter	Typ	Description	Przykładowe użycie
assets	str	Klucze zasobu z item_assets. Powtórz klucz dla wielu zasobów.	assets=B04&assets=B03&assets=B02
expression	str	Wyrażenie matematyczne przy użyciu kluczy zasobów.	expression=(B08-B04)/(B08+B04)
asset_bidx	str	Indeksy zakresów dla zasobu wielopasmowego. Formatowanie: {asset_key}|{idx1},{idx2},...	asset_bidx=image|4,1,2
asset_as_band	bool	Traktuj zasoby w expression jako pojedyncze pasma. Wymagane, gdy wyrażenie używa wielu zasobów.	asset_as_band=true
colormap_name	str	Wstępnie zdefiniowana nazwa mapy kolorów TiTiler.	colormap_name=viridis
colormap	str	Kodowany przez adres URL kod JSON definiujący niestandardową mapę kolorów.	colormap=%7B%221%22%3A%5B...%5D%7D
rescale	str	Wartości minimalne rozdzielone przecinkami, maksymalne wartości skalowania danych.	rescale=0,3000
color_formula	str	Formuła korekty koloru rozdzielanego spacjami (Gamma, Nasycenie, Sigmoidal).	color_formula=Gamma RGB 2.2 Saturation 1.1
nodata	str/float/int	Wartość piksela oznaczająca brak danych (przezroczysty).	nodata=0 lub nodata=-9999.0 lub nodata=nan
unscale	bool	Zastosuj skalowanie/przesunięcie z metadanych GeoTIFF.	unscale=true
algorithm	str	Nazwa algorytmu przetwarzania TiTiler.	algorithm=hillshade
algorithm_params	str	Ciąg JSON zakodowany w adresie URL z parametrami algorytmu.	algorithm_params=%7B%22azimuth%22%3A315%7D
buffer	float	Bufor pikseli wokół kafelków (często potrzebny dla algorytmów).	buffer=3
maxItemsPerTile	int	Maksymalna liczba elementów STAC do przetworzenia na kafelek.	maxItemsPerTile=20
skipcovered	bool	Pomiń elementy całkowicie zasłaniane przez inne.	skipcovered=true
exitwhenfull	bool	Zatrzymaj przetwarzanie kafelka, gdy jest całkowicie pokryty.	exitwhenfull=true
time_limit	int	Maksymalny czas przetwarzania (w sekundach) na kafelek.	time_limit=10
subdataset_bands	int	Indeks pasma/komunikatu dla danych GRIB.	subdataset_bands=1
subdataset_name	str	Nazwa zmiennej dla danych NetCDF.	subdataset_name=temperature
datetime	str	Sygnatura czasowa ISO 8601 dotycząca wybierania wycinka czasu w usłudze NetCDF.	datetime=2023-10-26T12:00:00Z
resampling	str	Metoda ponownego próbkowania (nearest, bilinear).	resampling=nearest

Treści powiązane

• Przykładowy przewodnik wizualizacji danych
• Konfigurowanie kolekcji przy użyciu interfejsu internetowego Microsoft Planetary Computer Pro
• Konfiguracje mozaiki dla kolekcji
• Ustawienia kafelków dla kolekcji
• Zapytania dotyczące niestandardowych filtrów wyszukiwania
• Przegląd STAC
• Dokumentacja TiTiler