Настройка параметров отрисовки для визуализации данных в Microsoft Planetary Computer Pro

Чтобы визуализировать геопространственные данные с помощью обозревателя данных Microsoft Planetary Computer Pro или API Tiler, необходимо определить одну или несколько конфигураций отрисовки для каждой из коллекций SpatioTemporal Asset Catalog (STAC). Конфигурация отрисовки указывает, как ресурсы данных в элементах STAC объединяются, обрабатываются и стилизуются для создания тайлов карт.

В этом руководстве описывается процесс создания конфигураций отрисовки, от понимания предварительных требований к настройке дополнительных параметров. Возможности визуализации Planetary Computer Pro основаны на проекте TiTiler с открытым исходным кодом.

Prerequisites

Прежде чем настроить отрисовку, убедитесь, что выполнены следующие необходимые действия.

  1. Коллекция STAC существует: Вы создали коллекцию STAC в Planetary Computer Pro.
  2. Прием данных: Вы добавили элементы STAC , содержащие геопространственные ресурсы данных, которые необходимо визуализировать в коллекции.
  3. Среда Python 3.10 (или более поздней версии)

Процесс создания конфигурации рендеринга

Step Title Description
1 Определение item_assets в JSON коллекции Во-первых, необходимо убедиться, что JSON коллекции STAC содержит четко определенный item_assets раздел, описывающий общие ресурсы в элементах.
2 Поймите вашу цель в работе с данными и их визуализацией Затем определите тип данных, с которыми вы работаете, и решите, как она будет отображаться визуально (цветовая карта с одним диапазоном, многополосная RGB).
3 Создание объекта конфигурации отрисовки Теперь создайте базовую структуру JSON, содержащую одну или несколько конфигураций отрисовки для пользовательского интерфейса обозревателя.
4 options Определение строки — основные параметры Настройте основные параметры TiTiler в строке options , чтобы выбрать правильные ресурсы или полосы и применить базовые стили, такие как цветные карты или изменение размера.
5 Добавление дополнительных options параметров (по мере необходимости) При необходимости расширьте визуализацию, добавив расширенные функции TiTiler, такие как выражения, алгоритмы, цветовая коррекция или пользовательские карты цветов с помощью options строки.
6 Добавьте конфигурацию отрисовки в вашу коллекцию Наконец, примените созданный вами список конфигурации визуализации к вашей коллекции STAC с помощью веб-интерфейса или API.

Шаг 1. Определение item_assets в JSON коллекции

Поле item_assets в JSON-коллекции является необходимым для рендеринга, так как оно предоставляет консолидированное описание ресурсов, содержащихся в элементах коллекции. Подсистема отрисовки и веб-приложение Explorer используют поле item_assets для понимания доступных данных для визуализации без проверки отдельных элементов. Он объявляет ключи (имена) ресурсов, таких как image, red, NIR или elevation, которые затем ссылаются на конфигурации отрисовки. Кроме того, item_assets могут включать метаданные расширения STAC, такие как eo:bands, для многополосных активов, что способствует выбору определенных полос для отрисовки. Обозреватель использует эти сведения для заполнения меню и понимания общей структуры данных.

Пример item_assets для 4-полосного ресурса NAIP:

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

Дополнительные сведения см. в item_assets. Также обратитесь к официальной спецификации расширения элементов STAC.

Прежде чем продолжить, убедитесь, что JSON вашей коллекции STAC содержит этот раздел. Определение коллекции можно обновить с помощью API или веб-интерфейса.

Шаг 2. Понимание цели данных и визуализации

Перед созданием конфигурации определите, как визуализировать данные:

Тип данных Description Example Цель визуализации
Данные Single-Band Каждый пиксель имеет одно значение. повышение, температура, классификация земли, вычисляемый индекс Сопоставляйте эти отдельные значения с диапазоном цветов или дискретными цветами с помощью цветовой карты.
Данные многополосного диапазона Данные имеют несколько полос на пиксель. Спутниковые изображения RGB, многоспектральные данные Объедините три конкретные полосы для того, чтобы представлять каналы красного, зеленого и синего цветов в выходном изображении.
Производные данные (выражения) Вычислите новое значение из одного или нескольких диапазонов или ресурсов. Нормализованный разностный индекс растительности (NDVI) из красного и ближнего инфракрасного диапазонов Определите математическое выражение и визуализируйте результат (одноканальный с цветовой схемой или многоканальный напрямую).
Производные данные (алгоритмы) Вычислите новое значение в пикселях. Теневая карта показывает контуры данных о высотах Используйте математический алгоритм для преобразования данных в визуализацию.
Кубы данных (GRIB/NetCDF) Данные, хранящиеся в форматах GRIB или NetCDF с несколькими переменными и измерениями. время, уровни давления Выберите конкретную переменную и, возможно, сделайте срез по другим измерениям (например, времени) для 2D визуализации.

Шаг 3. Создание объекта конфигурации отрисовки

Конфигурации отрисовки определяются как список объектов JSON (или словарей Python при использовании API). Каждый объект в списке представляет один параметр визуализации, который будет отображаться в раскрывающемся списке Обозревателя.

Базовая структура:

[
  {
    "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: уникальный удобочитаемый компьютером идентификатор для этого параметра отрисовки в коллекции.
  • name: имя, отображаемое в пользовательском интерфейсе обозревателя.
  • description: необязательный текст, предоставляющий дополнительный контекст.
  • type: обычно "raster-tile".
  • options: строка, содержащая параметры запроса URL-адресов (key=value пары, разделенные &), которые управляют движком отрисовки TiTiler. Это место, где выполняется большая часть настройки.
  • minZoom: необязательное целое число, указывающее минимальный уровень масштабирования карты, на котором этот слой становится видимым. Полезно для управления производительностью с данными высокого разрешения.
  • info_options: Опциональная строка запроса URL, которая активирует временной слайдер Explorer для коллекций кубов данных (NetCDF, HDF5, GRIB2). Подробнее см. Настройка ползунка времени в Explorer.

Используя одну и ту же структуру, можно иметь несколько конфигураций отрисовки для одних и того же данных, чтобы данные могли визуализироваться несколькими способами.

Шаг 4. Определение options строки — основные параметры

Строка options является сердцем конфигурации отрисовки. В нем используется key=value&key=value формат. Ниже приведены наиболее распространенные параметры:

1. Определение активов/диапазонов

Parameter Description Вариант использования Example
assets={asset_key} Указывает используемые ресурсы, где {asset_key} соответствует ключу, определенному в коллекции item_assets. Отрисовка одного диапазона с помощью одного ресурса assets=elevation
Трехполосный рендеринг с использованием трех отдельных однополосных ресурсов (порядок определяет R, G, B) assets=B04&assets=B03&assets=B02
Визуализация с помощью одного многополосного объекта assets=image (часто используется с asset_bidx)
asset_bidx={asset_key}\|{band_index1},{band_index2},... Выбирает конкретные индексы каналов изнутри одного многополосного ресурса, указанного assets. Индексы групп обычно основаны на 1. Три полосы RGB из полос 1, 2, 3 актива image assets=image&asset_bidx=image\|1,2,3
Трёхканальная «False Color Infrared» (NIR, Red, Green) с диапазонами 4, 1, 2 ресурса image assets=image&asset_bidx=image\|4,1,2
Рендеринг одночастотный с использованием только диапазона 4 ассета assets=image&asset_bidx=image\|4

2. Стилизация Single-Band данных

Parameter Description Example
colormap_name={name} Применяет предопределенную именованную цветовую карту. Распространенные примеры: viridis, plasma, grayrdylgn. См. поддерживаемые цветовые карты. assets=elevation&colormap_name=viridis
rescale={min_val},{max_val} Растягивает или сжимает значения данных, чтобы соответствовать полному диапазону цветовой карты. Значения за пределами этого диапазона ограничиваются минимальными и максимальными цветами. Значения высот от 100 до 1500 м на полной цветовой карте: assets=elevation&colormap_name=viridis&rescale=100,1500

Стилизование многополосных (RGB) данных

Parameter Description Example
Порядок полос RGB Полосы RGB неявно определяются порядком assets (для отдельных активов) или asset_bidx (для полос в ресурсе). См. примеры в таблице "Идентификация активов/групп"
rescale={min_val},{max_val} (Необязательно) Можно использовать для масштабирования входных значений диапазонов R, G, B перед сопоставлением их с диапазоном отображения от 0 до 255. Полезно, если исходные данные еще не 8-разрядные. assets=B04&assets=B03&assets=B02&rescale=0,3000
color_formula={formula_string} (Необязательно) Применяет формулы коррекции цвета. Дополнительные параметры см. в следующем разделе.

Шаг 5. Добавление дополнительных options параметров (по мере необходимости)

Помимо основных принципов, TiTiler предлагает множество расширенных параметров через options строку:

1. Выражения

Parameter Description Format/Values Example
expression={formula} Определение математической формулы с помощью ключей активов в качестве переменных Стандартные операторы (+, -, *) /и круглые скобки expression=(B08-B04)/(B08+B04)
asset_as_band=true Обязательный, если выражение использует несколько ресурсов с одним диапазоном true или false expression=(B08-B04)/(B08+B04)&asset_as_band=true

Examples

  • Пример результата с одним диапазоном: expression=(B08-B04)/(B08+B04)&asset_as_band=true&colormap_name=rdylgn&rescale=-1,1
  • Многополосные выражения используют точки с запятой: expression=B04*1.5;B03*1.1;B02*1.3&asset_as_band=true
  • При использовании expressionобычно не требуется assets или asset_bidx

2. Алгоритмы

Parameter Description Format/Values Example
algorithm={name} Применение предопределенного алгоритма обработки пикселей hillshade, , contoursterrarium, terrainrgbnormalizedIndex algorithm=hillshade
algorithm_params={json_string} Параметры для алгоритма (URL-кодированный JSON) Зависит от алгоритма algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D
buffer={integer} Добавление буфера пикселей вокруг плиток (часто требуется для алгоритмов) Целочисленное значение buffer=3

Пример assets=elevation&algorithm=hillshade&colormap_name=gray&buffer=3&algorithm_params=%7B%22azimuth%22%3A%20315%2C%20%22angle_altitude%22%3A%2045%7D

Дополнительные сведения о конкретных алгоритмах см. в документации по алгоритму TiTiler и Mapbox Hillshade

3. Цветовая коррекция (для выходных данных RGB или трех полос)

Parameter Description Format Example
color_formula={formula_string} Примените корректировки цвета Разделенная пробелами строка с Гамма, насыщенностью и /или Сигмоидальной корректировкой color_formula=Gamma RGB 2.5 Saturation 1.4 Sigmoidal RGB 15 0.35

Сведения о формате:

  • Gamma {BANDS} {VALUE} — настройка яркости
  • Saturation {PROPORTION} - Настройка интенсивности цвета
  • Sigmoidal {BANDS} {CONTRAST} {BIAS} - Настройка контрастности

Дополнительные сведения о цветовой коррекции см. в документации по TiTiler.

4. Пользовательские цветовые схемы (для выходных данных с одним каналом)

Parameter Description Format Example
colormap={json_string} Определение пользовательской цветовой карты Значения данных в кодировке URL-адреса JSON сопоставляются со списками 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]}

Пример декодирует: Сопоставляет значение 1 с темно-зеленым, от 2 до очень темно-зеленого, от 3 до оливкового зеленого, от 4 до оранжевого красного, от 5 до желтого, от 6 до розового/magenta, 7 до сине-фиолета и 8 до красного.

5. Обработка данных

Parameter Description Example
nodata={value} Укажите значение пикселя, чтобы сделать прозрачным nodata=0 или nodata=-9999 или nodata=nan
unscale={true\|false} Примените масштаб/смещение из метаданных GeoTIFF unscale=true

6. Производительность / Поведение мозаичного отображения

Parameter Description Format Example
maxItemsPerTile={integer} Ограничение количества элементов STAC на плитку Integer maxItemsPerTile=20
skipcovered={true\|false} Пропускать элементы, охватываемые другими пользователями true или false skipcovered=true
exitwhenfull={true\|false} Остановите обработку, когда плитка полностью покрыта true или false exitwhenfull=true
time_limit={seconds} Максимальное время отрисовки плитки Целое число (секунды) time_limit=10

7. Параметры куба данных (GRIB/NetCDF)

Parameter Тип данных Description Example
subdataset_bands={band_index} GRIB Выбор определенного сообщения или полосы assets=grib_data&subdataset_bands=1&colormap_name=jet&rescale=273,300
subdataset_name={variable_name} NetCDF Выбор переменной для визуализации assets=netcdf_data&subdataset_name=temperature
datetime={timestamp} NetCDF Выбор среза времени (ISO 8601) datetime=2023-10-26T12:00:00Z
sel={dimension}={value} Зарр Индексатор в стиле Xarray, повторяемый для каждого измерения. sel=time=2024-01-01
sel_method={method} Зарр Метод индексирования в Xarray для неточных совпадений. sel_method=nearest

Полный пример NetCDF:assets=netcdf_data&subdataset_name=temperature&datetime=2023-10-26T12:00:00Z&colormap_name=viridis&rescale=0,30

8. Настройка слайдера времени Explorer (Data Cubes)

Чтобы включить слайдер времени в Explorer для опции рендеринга куба данных, добавьте info_options поле в объект настройки рендера. info_options — это строка запроса URL в том же формате, что и options, которую Explorer передаёт конечной точке /info компонента Tiler для каждого видимого элемента STAC. Explorer использует возвращённые описания диапазонов для построения положений отметок на ползунке, поэтому ползунок соответствует тому, что может предоставить Tiler. Это поле действимо только для raster-tile опций рендера.

Определите info_options как релевантное для обнаружения подмножество options: как правило, параметр assets, а для NetCDF, HDF5 и Zarr — subdataset_name. Опустите параметры стилизации и срезки, такие как rescale, colormap_name, datetime, selи sel_method потому что они не влияют на обнаружение группы. Когда вы включаете ползунок, также удалите все datetime= из options, иначе зафиксированное значение будет иметь приоритет над ползунком.

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

Для коллекций GRIB2 info_options обычно содержит только выборку ресурсов, используемую для обнаружения:

{
  "info_options": "assets=data"
}

Note

Когда info_options отсутствует, Explorer возвращается к устаревшему поведению — чтению cube:dimensions и start_datetime/end_datetime из метаданных элемента STAC. Оба подхода поддерживаются одновременно, поэтому существующие коллекции продолжают работать без изменений.

Шаг 6. Добавление конфигурации отрисовки в коллекцию

После создания списка конфигурации отрисовки (одного или нескольких объектов JSON) добавьте его в коллекцию STAC:

Использование веб-интерфейса:

  1. Перейдите к коллекции на портале Planetary Computer Pro.
  2. Нажмите кнопку "Конфигурация".
  3. Перейдите на вкладку Отрисовка.
  4. Вставьте список JSON в редактор.
  5. Сохраните изменения, нажав кнопку "Обновить".

Снимок экрана: веб-интерфейс конфигурации отрисовки, отображающий параметры настройки отрисовки.

Дополнительные сведения о настройке коллекций см. в разделе "Настройка коллекции с помощью веб-интерфейса".

Использование API:

С помощью конечной точки создания параметров рендеринга коллекции stac определите конфигурацию рендеринга коллекции.

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)

Дополнительные сведения об использовании API коллекции STAC см. в разделе "Создание коллекции STAC" (примеры API).

Examples

Ниже приведены различные примеры строки options и объекта полной конфигурации отрисовки:

1. Изменение биомассы Single-Band с помощью цветовой карты и повторного масштабирования:

 {
    "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 естественный цвет (RGB) из отдельных элементов:

 {
    "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) из полос в одном ресурсе:

{
    "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 с помощью выражения:

{
    "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:

{
    "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:

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

Справочник. Все options параметры

Строка options принимает следующие пары «ключ-значение» (актуальную информацию см. в документации TiTiler):

Parameter Type Description Пример использования
assets str Ключи актива из item_assets. Повторите ключ для нескольких ресурсов. assets=B04&assets=B03&assets=B02
expression str Математическое выражение с использованием ключей активов. expression=(B08-B04)/(B08+B04)
asset_bidx str Индексы диапазонов для многополосного ресурса. Формат: {asset_key}|{idx1},{idx2},... asset_bidx=image|4,1,2
asset_as_band bool Рассматривать активы в expression как отдельные полосы. Требуется, если выражение использует несколько ресурсов. asset_as_band=true
colormap_name str Предопределенное имя цветовой карты TiTiler. colormap_name=viridis
colormap str URL-кодированный JSON, определяющий настраиваемую цветовую карту. colormap=%7B%221%22%3A%5B...%5D%7D
rescale str Значения min и max, разделенные запятыми, для масштабирования данных. rescale=0,3000
color_formula str Формула коррекции цвета, разделенные пробелом (Гамма, насыщенность, Сигмоид). color_formula=Gamma RGB 2.2 Saturation 1.1
nodata str/float/int Значение пикселя, которое следует трактовать как отсутствие данных (прозрачный). nodata=0 или nodata=-9999.0 или nodata=nan
unscale bool Применить масштаб/смещение из метаданных GeoTIFF. unscale=true
algorithm str Имя алгоритма обработки TiTiler. algorithm=hillshade
algorithm_params str Строка JSON, закодированная по URL-адресу, с параметрами для алгоритма. algorithm_params=%7B%22azimuth%22%3A315%7D
buffer float Буфер пикселей вокруг плиток (часто требуется для алгоритмов). buffer=3
maxItemsPerTile int Максимальное количество элементов STAC для обработки на одну плитку. maxItemsPerTile=20
skipcovered bool Пропустить элементы, полностью скрытые другими. skipcovered=true
exitwhenfull bool Остановите обработку плитки после полного покрытия. exitwhenfull=true
time_limit int Максимальное время обработки (в секундах) на плитку. time_limit=10
subdataset_bands int Индекс полосы или сообщения для данных GRIB. subdataset_bands=1
subdataset_name str Имя переменной для данных NetCDF. subdataset_name=temperature
datetime str Метка времени ISO 8601 для выбора среза времени в NetCDF. datetime=2023-10-26T12:00:00Z
resampling str Метод повторной выборки (nearest, bilinear). resampling=nearest

Связанный контент

  • Последнее обновление: