Symbol слой

Symbol-слой в MapLibre GL JS предназначен для отображения подписей, иконок и комбинированных маркеров на карте. Он является одним из наиболее функциональных и одновременно сложных типов слоёв, поскольку объединяет визуализацию растровых ресурсов (иконок) и текстового рендеринга с системой коллизий и приоритизации отображения.

Основная задача Symbol-слоя — представить точечные или линейные объекты в виде:

  • текстовых подписей;
  • пиктограмм (иконок);
  • комбинации текста и иконки;
  • динамически формируемых меток на основе данных источника.

Источники данных и структура слоя

Symbol-слой работает с любым поддерживаемым источником данных MapLibre GL JS:

  • GeoJSON источники;
  • векторные тайлы;
  • кластеризованные наборы точек.

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

Пример логической структуры данных:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [37.6173, 55.7558]
  },
  "properties": {
    "name": "Москва",
    "population": 12000000
  }
}

Основные принципы рендеринга символов

Symbol-слой отличается от других типов слоёв тем, что он работает не только с геометрией, но и с системой:

  • глифов (glyphs) для текста;
  • sprite-атласа для иконок;
  • системы коллизий (collision detection);
  • приоритетов размещения (placement priority).

Каждый символ проходит этапы:

  1. выбор данных;
  2. вычисление layout;
  3. проверка пересечений;
  4. размещение;
  5. рендеринг.

Layout-параметры Symbol-слоя

Layout отвечает за поведение символов, их форму и правила размещения.

text-field

Определяет текст подписи. Поддерживает выражения на основе свойств объекта:

"text-field": ["get", "name"]

Также возможно комбинирование строк:

"text-field": ["concat", ["get", "name"], " ", ["get", "type"]]

icon-image

Определяет изображение иконки из sprite-атласа.

"icon-image": "airport-15"

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

"icon-image": ["get", "icon"]

text-font

Задаёт шрифт из загруженного набора glyphs.

"text-font": ["Open Sans Regular", "Arial Unicode MS Regular"]

text-size и icon-size

Управляют масштабом текста и иконок.

"text-size": 14,
"icon-size": 1.2

Возможна интерполяция:

"text-size": ["interpolate", ["linear"], ["zoom"], 10, 12, 15, 18]

symbol-placement

Определяет способ размещения символов:

  • point — в точке;
  • line — вдоль линии;
  • line-center — центр линии.
"symbol-placement": "point"

При размещении вдоль линий учитывается направление сегментов и кривизна геометрии.

Управление столкновениями (collision detection)

Одной из ключевых особенностей Symbol-слоя является система предотвращения наложений.

text-allow-overlap и icon-allow-overlap

Разрешают перекрытие символов:

"text-allow-overlap": false,
"icon-allow-overlap": false

При включении значений true символы игнорируют коллизии и могут перекрывать друг друга.

text-ignore-placement и icon-ignore-placement

Позволяют игнорировать уже размещённые элементы других слоёв:

"text-ignore-placement": true

text-optional и icon-optional

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

Якоря, смещения и позиционирование

text-anchor

Определяет точку привязки текста относительно геометрии:

  • center
  • top
  • bottom
  • left
  • right
  • комбинации (например top-left)
"text-anchor": "top"

text-offset и icon-offset

Сдвигают символ относительно исходной точки:

"text-offset": [0, 1.5]

Ось X — горизонталь, Y — вертикаль (в единицах высоты текста).

text-rotate и icon-rotate

Поворот символов:

"text-rotate": 45

Работа с подписями на линиях

При использовании symbol-placement: "line" текст распределяется вдоль геометрии линии.

Ключевые параметры:

  • text-rotation-alignment — выравнивание относительно линии;
  • symbol-spacing — расстояние между повторяющимися символами;
  • text-pitch-alignment — поведение при наклоне карты.
"text-rotation-alignment": "map",
"symbol-spacing": 250

Зависимость от масштаба (zoom)

Symbol-слой активно использует масштабирование карты.

minzoom и maxzoom

Ограничивают видимость слоя:

"minzoom": 5,
"maxzoom": 18

zoom-выражения

Позволяют менять свойства в зависимости от масштаба:

"text-size": [
  "interpolate",
  ["linear"],
  ["zoom"],
  5, 10,
  10, 14,
  15, 20
]

Работа с иконками и sprite-атласами

Иконки в Symbol-слое не загружаются напрямую как изображения. Вместо этого используется sprite atlas.

Sprite содержит:

  • набор изображений;
  • метаданные размеров;
  • имена ключей.

Пример добавления изображения:

map.addImage("custom-marker", image);

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

"icon-image": "custom-marker"

Глифы и текстовый рендеринг

Текст в Symbol-слое не отрисовывается стандартными шрифтами браузера. Вместо этого используются glyph ranges, загружаемые с сервера.

Параметр:

"glyphs": "https://fonts.example.com/{fontstack}/{range}.pbf"

Глифы позволяют:

  • уменьшить нагрузку на рендеринг;
  • обеспечить единообразие шрифтов;
  • поддерживать сложные языки.

Динамическая стилизация через выражения

Symbol-слой активно использует expression system.

Условная логика

"text-color": [
  "case",
  [">", ["get", "population"], 1000000],
  "#ff0000",
  "#000000"
]

Работа с категориями

"icon-image": [
  "match",
  ["get", "type"],
  "airport", "airport-icon",
  "hospital", "hospital-icon",
  "default-icon"
]

Производительность Symbol-слоя

Symbol-слой является одним из наиболее ресурсоёмких.

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

  • количество отображаемых символов;
  • сложность выражений;
  • плотность коллизий;
  • количество загруженных глифов;
  • размер sprite-атласа.

Оптимизационные подходы:

  • использование кластеризации точек;
  • ограничение zoom-диапазона;
  • фильтрация данных на уровне слоя;
  • упрощение текстовых выражений.

Фильтрация данных

Symbol-слой поддерживает фильтрацию features:

"filter": ["==", ["get", "type"], "city"]

Фильтрация выполняется до стадии layout, что снижает нагрузку на рендеринг.

Комбинированные символы (иконка + текст)

Частый сценарий — одновременное отображение иконки и подписи:

{
  "type": "symbol",
  "layout": {
    "icon-image": "marker",
    "text-field": ["get", "name"],
    "text-offset": [0, 1.2],
    "text-anchor": "top"
  }
}

Такой подход используется для:

  • POI (points of interest);
  • городов;
  • транспортных узлов.

Приоритеты отображения

MapLibre GL JS использует систему приоритетов:

  • порядок слоёв в стиле;
  • text-field длина;
  • важность features;
  • zoom level.

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

Поведение при наклоне и вращении карты

Symbol-слой адаптируется к:

  • pitch (наклон карты);
  • bearing (поворот).

Параметры:

"text-pitch-alignment": "viewport",
"text-rotation-alignment": "map"

Типичные ошибки при использовании Symbol-слоя

  • перегрузка карты тысячами подписей;
  • отсутствие контроля коллизий;
  • использование слишком крупных sprite-атласов;
  • некорректные glyphs или их отсутствие;
  • одинаковые идентификаторы icon-image.

Роль Symbol-слоя в визуальной иерархии карты

Symbol-слой формирует семантический уровень карты, отвечающий за читаемость и интерпретацию пространства. Он связывает географические данные с человеческим восприятием, превращая координаты в именованные и визуально различимые объекты.

Оглавление