Структура JSON-спецификации стиля

В основе работы MapLibre GL JS лежит Style Specification — JSON-документ, описывающий источники данных, визуальное оформление карты, порядок отрисовки слоёв, параметры отображения объектов и поведение карты.

Стиль представляет собой декларативное описание карты. Вместо прямого рисования объектов через JavaScript-разметку разработчик определяет структуру данных в JSON, а движок MapLibre самостоятельно выполняет визуализацию.

Типичный стиль выглядит следующим образом:

{
  "version": 8,
  "name": "My Style",
  "sources": {},
  "layers": []
}

Несмотря на внешнюю простоту, внутри такой структуры может содержаться несколько сотен слоёв и тысячи параметров оформления.

Общая структура стиля

На верхнем уровне JSON обычно располагаются следующие секции:

{
  "version": 8,
  "name": "My Style",
  "metadata": {},
  "center": [37.62, 55.75],
  "zoom": 10,
  "bearing": 0,
  "pitch": 0,
  "sprite": "sprites/sprite",
  "glyphs": "fonts/{fontstack}/{range}.pbf",
  "sources": {},
  "layers": []
}

Каждое поле отвечает за отдельный аспект конфигурации карты.

Поле Назначение
version Версия спецификации
name Название стиля
metadata Произвольные метаданные
center Начальный центр карты
zoom Начальный масштаб
bearing Поворот карты
pitch Наклон карты
sprite Набор иконок
glyphs Шрифтовые ресурсы
sources Источники данных
layers Слои отображения

Поле version

Поле version является обязательным.

{
  "version": 8
}

Число обозначает версию спецификации стиля.

Для современных стилей используется:

{
  "version": 8
}

MapLibre GL JS поддерживает формат, совместимый со спецификацией версии 8, изначально разработанной для Mapbox Style Specification.

Отсутствие данного поля делает стиль некорректным.

Поле name

Позволяет задать человекочитаемое название стиля.

{
  "name": "City Map"
}

Название не влияет на визуализацию карты.

Чаще всего используется:

  • в редакторах стилей;
  • в системах управления картами;
  • при хранении нескольких конфигураций.

Поле metadata

Секция предназначена для хранения произвольной информации.

{
  "metadata": {
    "author": "GIS Team",
    "project": "Transport Map"
  }
}

MapLibre не анализирует содержимое этого объекта.

Через него удобно хранить:

  • автора стиля;
  • версию проекта;
  • дату создания;
  • внутренние идентификаторы;
  • служебные настройки.

Начальное положение карты

center

Определяет координаты центра карты.

{
  "center": [37.6176, 55.7558]
}

Формат:

[longitude, latitude]

Важно помнить порядок координат:

Долгота → Широта

а не наоборот.

zoom

Начальный уровень масштабирования.

{
  "zoom": 12
}

Типичные значения:

Zoom Масштаб
0 Весь мир
3 Страна
8 Регион
12 Город
16 Район
20+ Отдельные здания

bearing

Угол поворота карты.

{
  "bearing": 45
}

Значение задаётся в градусах.

Примеры:

{
  "bearing": 0
}

Север сверху.

{
  "bearing": 90
}

Карта повернута на восток.

pitch

Угол наклона карты.

{
  "pitch": 60
}

Пример:

{
  "pitch": 0
}

Вид сверху.

{
  "pitch": 60
}

Псевдо-3D представление.

Секция glyphs

Используется для загрузки шрифтов.

{
  "glyphs": "fonts/{fontstack}/{range}.pbf"
}

Плейсхолдеры:

Переменная Назначение
{fontstack} Название шрифта
{range} Диапазон символов

При отображении текста MapLibre автоматически подставляет нужные значения.

Пример запроса:

fonts/Open Sans Regular/0-255.pbf

Секция sprite

Определяет набор графических иконок.

{
  "sprite": "sprites/sprite"
}

MapLibre будет искать файлы:

sprite.json
sprite.png

или

sprite@2x.json
sprite@2x.png

для экранов высокой плотности.

Через спрайты обычно подключаются:

  • маркеры;
  • пиктограммы;
  • дорожные знаки;
  • пользовательские символы.

Источники данных (sources)

Раздел sources является фундаментом любого стиля.

Именно здесь описываются данные, которые будут использоваться слоями.

Простейший пример:

{
  "sources": {
    "cities": {
      "type": "geojson",
      "data": "cities.geojson"
    }
  }
}

Каждый источник получает уникальный идентификатор.

Структура:

{
  "sources": {
    "source-id": {
      "...": "..."
    }
  }
}

Источник GeoJSON

Самый распространённый вариант.

{
  "sources": {
    "cities": {
      "type": "geojson",
      "data": "cities.geojson"
    }
  }
}

Либо данные могут быть встроены непосредственно в стиль.

{
  "sources": {
    "cities": {
      "type": "geojson",
      "data": {
        "type": "FeatureCollection",
        "features": []
      }
    }
  }
}

Поддерживаются:

  • Point;
  • MultiPoint;
  • LineString;
  • MultiLineString;
  • Polygon;
  • MultiPolygon.

Векторный источник

Используется для тайловых наборов.

{
  "sources": {
    "osm": {
      "type": "vector",
      "tiles": [
        "https://server/{z}/{x}/{y}.pbf"
      ]
    }
  }
}

Векторные тайлы являются основой большинства современных картографических сервисов.

Преимущества:

  • высокая производительность;
  • малый размер данных;
  • динамическая стилизация.

Raster-источник

Предназначен для растровых тайлов.

{
  "sources": {
    "satellite": {
      "type": "raster",
      "tiles": [
        "https://server/{z}/{x}/{y}.png"
      ],
      "tileSize": 256
    }
  }
}

Обычно применяется для:

  • спутниковых снимков;
  • сканов карт;
  • тепловых изображений.

Raster DEM

Источник данных рельефа.

{
  "sources": {
    "terrain": {
      "type": "raster-dem",
      "tiles": [
        "https://server/{z}/{x}/{y}.png"
      ]
    }
  }
}

Используется при построении:

  • трёхмерного рельефа;
  • анализа высот;
  • 3D-карт.

Слои (layers)

Секция layers определяет визуальное отображение данных.

Именно слои создают изображение карты.

Пример:

{
  "layers": [
    {
      "id": "water",
      "type": "fill",
      "source": "osm"
    }
  ]
}

Каждый слой получает:

  • уникальный идентификатор;
  • тип отображения;
  • источник данных.

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

{
  "id": "roads",
  "type": "line",
  "source": "osm",
  "source-layer": "transportation",
  "layout": {},
  "paint": {}
}

Главные элементы слоя:

Поле Назначение
id Уникальное имя
type Тип слоя
source Источник данных
source-layer Слой внутри векторного тайла
filter Фильтрация объектов
minzoom Минимальный zoom
maxzoom Максимальный zoom
layout Параметры компоновки
paint Параметры оформления

Идентификатор слоя

{
  "id": "buildings"
}

Идентификатор должен быть уникальным в пределах всего массива слоёв.

Нельзя создавать два слоя с одинаковым id.

Типы слоёв

background

Фоновая заливка карты.

{
  "id": "background",
  "type": "background"
}

fill

Отображение полигонов.

{
  "id": "parks",
  "type": "fill"
}

Подходит для:

  • парков;
  • озёр;
  • административных границ.

line

Линейные объекты.

{
  "id": "roads",
  "type": "line"
}

Используется для:

  • дорог;
  • рек;
  • маршрутов.

symbol

Текст и иконки.

{
  "id": "cities",
  "type": "symbol"
}

Применяется для:

  • подписей;
  • обозначений;
  • пиктограмм.

circle

Точки в виде окружностей.

{
  "id": "earthquakes",
  "type": "circle"
}

Часто используется для визуализации статистики.

raster

Растровые изображения.

{
  "id": "satellite",
  "type": "raster"
}

hillshade

Отмывка рельефа.

{
  "id": "hillshade",
  "type": "hillshade"
}

fill-extrusion

Трёхмерные полигоны.

{
  "id": "3d-buildings",
  "type": "fill-extrusion"
}

Используется для отображения зданий.

Layout-свойства

Раздел layout определяет структуру отображения объекта.

Пример:

{
  "layout": {
    "visibility": "visible"
  }
}

Часто используемые параметры:

{
  "layout": {
    "line-cap": "round",
    "line-join": "round"
  }
}

Для символов:

{
  "layout": {
    "text-field": ["get", "name"],
    "text-size": 14
  }
}

visibility

Включение и отключение слоя.

{
  "layout": {
    "visibility": "none"
  }
}

Возможные значения:

visible
none

Paint-свойства

Секция paint отвечает за внешний вид объектов.

Пример:

{
  "paint": {
    "fill-color": "#00ff00"
  }
}

Именно здесь задаются:

  • цвета;
  • прозрачность;
  • размеры;
  • контуры;
  • эффекты.

Цвета

Для полигонов:

{
  "paint": {
    "fill-color": "#90EE90"
  }
}

Для линий:

{
  "paint": {
    "line-color": "#ff0000"
  }
}

Для окружностей:

{
  "paint": {
    "circle-color": "#0000ff"
  }
}

Прозрачность

{
  "paint": {
    "fill-opacity": 0.5
  }
}

Диапазон:

0.0 – полностью прозрачно
1.0 – полностью непрозрачно

Толщина линий

{
  "paint": {
    "line-width": 4
  }
}

Радиус окружности

{
  "paint": {
    "circle-radius": 8
  }
}

Фильтры

Фильтры позволяют отображать только нужные объекты.

Пример:

{
  "filter": [
    "==",
    ["get", "type"],
    "highway"
  ]
}

Отобразятся только дороги типа highway.

Несколько условий

{
  "filter": [
    "all",
    ["==", ["get", "type"], "road"],
    [">", ["get", "lanes"], 2]
  ]
}

Здесь будут показаны только дороги:

  • имеющие тип road;
  • содержащие более двух полос.

Масштабные ограничения

Слои могут отображаться только на определённых уровнях масштаба.

{
  "minzoom": 10,
  "maxzoom": 18
}

Поведение:

Zoom Видимость
8 скрыт
10 показан
15 показан
18 скрыт

Это один из важнейших инструментов оптимизации производительности.

Выражения (Expressions)

Современные стили активно используют выражения.

Пример динамического цвета:

{
  "paint": {
    "circle-color": [
      "match",
      ["get", "status"],
      "active",
      "#00ff00",
      "inactive",
      "#ff0000",
      "#cccccc"
    ]
  }
}

Цвет зависит от значения атрибута status.

Интерполяция

Размер объекта может изменяться вместе с масштабом.

{
  "paint": {
    "circle-radius": [
      "interpolate",
      ["linear"],
      ["zoom"],
      5, 2,
      15, 12
    ]
  }
}

При увеличении масштаба круги становятся больше.

Порядок отрисовки слоёв

Слои рисуются сверху вниз согласно порядку в массиве.

Пример:

{
  "layers": [
    {
      "id": "water"
    },
    {
      "id": "roads"
    },
    {
      "id": "labels"
    }
  ]
}

Последовательность визуализации:

  1. Вода.
  2. Дороги.
  3. Подписи.

Следовательно, подписи окажутся поверх всех остальных объектов.

Грамотное расположение слоёв является одним из ключевых факторов создания качественного картографического стиля.

Полная схема минимального рабочего стиля

{
  "version": 8,
  "name": "Simple Style",
  "sources": {
    "cities": {
      "type": "geojson",
      "data": "cities.geojson"
    }
  },
  "layers": [
    {
      "id": "cities",
      "type": "circle",
      "source": "cities",
      "paint": {
        "circle-radius": 6,
        "circle-color": "#007cbf"
      }
    }
  ]
}

В этом примере присутствуют все ключевые элементы спецификации:

  • версия стиля;
  • имя стиля;
  • источник данных;
  • слой визуализации;
  • параметры отображения объекта.

Именно вокруг взаимодействия секций sources, layers, layout, paint, filter и выражений строится вся архитектура JSON-спецификации стиля в MapLibre GL JS.

Оглавление