Paint properties

В Mapbox GL JS визуальное оформление карты разделено на два крупных блока настроек:

Layout properties — управляют размещением объектов, видимостью слоёв, расположением подписей и другими структурными параметрами.
Paint properties — отвечают за внешний вид объектов: цвет, прозрачность, толщину линий, размеры символов, тени, размытие и другие графические характеристики.

Paint-свойства применяются внутри объекта paint при описании слоя.

Пример:

map.addLayer({
    id: 'water-layer',
    type: 'fill',
    source: 'water',
    paint: {
        'fill-color': '#4A90E2',
        'fill-opacity': 0.7
    }
});

В данном случае:

fill-color задаёт цвет полигона;
fill-opacity определяет уровень прозрачности.

Каждый тип слоя поддерживает собственный набор paint-свойств.

Общая структура paint

Слой Mapbox GL JS состоит из нескольких секций.

{
    id: 'roads',
    type: 'line',
    source: 'roads-source',

    layout: {
        ...
    },

    paint: {
        ...
    }
}

Блок paint может содержать десятки различных параметров в зависимости от типа слоя.

Например:

paint: {
    'line-color': '#ff0000',
    'line-width': 4,
    'line-opacity': 0.8
}

Типы слоёв и их Paint Properties

Разные типы слоёв имеют различные наборы свойств.

Тип слоя	Основные paint-свойства
fill	fill-color, fill-opacity
line	line-color, line-width
circle	circle-radius, circle-color
symbol	text-color, icon-opacity
fill-extrusion	fill-extrusion-height
raster	raster-opacity
hillshade	hillshade-shadow-color
background	background-color

Каждая категория рассматривается отдельно.

Paint Properties для Fill Layers

Fill-слои используются для отображения полигонов.

Пример:

{
    id: 'parks',
    type: 'fill',
    source: 'parks'
}

fill-color

Определяет цвет заливки полигона.

paint: {
    'fill-color': '#00AA55'
}

Можно использовать любые CSS-цвета:

'fill-color': 'red'

'fill-color': 'rgb(0,255,0)'

'fill-color': 'rgba(0,255,0,0.5)'

fill-opacity

Управляет прозрачностью.

Диапазон:

0 — полностью прозрачный
1 — полностью непрозрачный

Пример:

paint: {
    'fill-opacity': 0.4
}

fill-outline-color

Задаёт цвет контура полигона.

paint: {
    'fill-color': '#55AAFF',
    'fill-outline-color': '#000000'
}

Результат:

внутренняя область синяя;
граница чёрная.

fill-pattern

Позволяет использовать изображение вместо однотонной заливки.

Сначала изображение добавляется в стиль:

map.loadImage('pattern.png', (error, image) => {
    map.addImage('pattern', image);
});

После этого:

paint: {
    'fill-pattern': 'pattern'
}

fill-antialias

Управляет сглаживанием границ.

paint: {
    'fill-antialias': true
}

По умолчанию обычно включено.

Paint Properties для Line Layers

Line-слои используются для дорог, рек, маршрутов и границ.

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

line-color

Определяет цвет линии.

paint: {
    'line-color': '#FF5500'
}

line-width

Задаёт толщину линии в пикселях.

paint: {
    'line-width': 6
}

line-opacity

Прозрачность линии.

paint: {
    'line-opacity': 0.5
}

line-blur

Добавляет размытие.

paint: {
    'line-blur': 2
}

Чем больше значение, тем мягче выглядит линия.

line-gap-width

Создаёт внутренний зазор.

paint: {
    'line-width': 8,
    'line-gap-width': 4
}

Часто применяется для отображения дорог.

line-offset

Смещение линии относительно исходной геометрии.

paint: {
    'line-offset': 3
}

Полезно при рисовании параллельных маршрутов.

line-dasharray

Создаёт пунктирную линию.

paint: {
    'line-dasharray': [2, 2]
}

Пример:

paint: {
    'line-color': '#000',
    'line-width': 2,
    'line-dasharray': [4, 2]
}

line-gradient

Позволяет создавать градиенты вдоль линии.

Пример:

paint: {
    'line-gradient': [
        'interpolate',
        ['linear'],
        ['line-progress'],
        0, 'blue',
        1, 'red'
    ]
}

Результат:

начало маршрута синее;
конец красный.

Paint Properties для Circle Layers

Circle-слои используются для отображения точек.

{
    id: 'cities',
    type: 'circle'
}

circle-radius

Радиус круга.

paint: {
    'circle-radius': 10
}

circle-color

Цвет маркера.

paint: {
    'circle-color': '#FF0000'
}

circle-opacity

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

paint: {
    'circle-opacity': 0.7
}

circle-stroke-color

Цвет обводки.

paint: {
    'circle-stroke-color': '#FFFFFF'
}

circle-stroke-width

Толщина границы.

paint: {
    'circle-stroke-width': 3
}

circle-stroke-opacity

Прозрачность контура.

paint: {
    'circle-stroke-opacity': 0.8
}

circle-blur

Размытие круга.

paint: {
    'circle-blur': 1
}

Часто применяется для визуализации плотности объектов.

Paint Properties для Symbol Layers

Symbol-слои отображают иконки и текст.

{
    id: 'labels',
    type: 'symbol'
}

text-color

Цвет текста.

paint: {
    'text-color': '#222222'
}

text-opacity

Прозрачность подписи.

paint: {
    'text-opacity': 0.8
}

text-halo-color

Цвет ореола вокруг текста.

paint: {
    'text-halo-color': '#FFFFFF'
}

text-halo-width

Толщина ореола.

paint: {
    'text-halo-width': 2
}

Очень полезно для улучшения читаемости подписей.

text-halo-blur

Размытие ореола.

paint: {
    'text-halo-blur': 1
}

icon-opacity

Прозрачность иконки.

paint: {
    'icon-opacity': 0.5
}

icon-color

Изменяет цвет SDF-иконок.

paint: {
    'icon-color': '#00AAFF'
}

Работает только для Signed Distance Field иконок.

icon-halo-color

Цвет ореола вокруг иконки.

paint: {
    'icon-halo-color': '#FFFFFF'
}

icon-halo-width

Ширина ореола.

paint: {
    'icon-halo-width': 2
}

Paint Properties для Fill Extrusion Layers

Используются для создания трёхмерных зданий.

{
    id: 'buildings',
    type: 'fill-extrusion'
}

fill-extrusion-color

Цвет здания.

paint: {
    'fill-extrusion-color': '#AAAAAA'
}

fill-extrusion-height

Высота объекта.

paint: {
    'fill-extrusion-height': 100
}

fill-extrusion-base

Высота основания.

paint: {
    'fill-extrusion-base': 10
}

fill-extrusion-opacity

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

paint: {
    'fill-extrusion-opacity': 0.9
}

Динамическое управление Paint Properties

После создания слоя свойства можно изменять программно.

Для этого используется метод:

map.setPaintProperty()

Синтаксис:

map.setPaintProperty(
    layerId,
    propertyName,
    value
);

Пример:

map.setPaintProperty(
    'roads',
    'line-color',
    '#ff0000'
);

Изменение прозрачности

map.setPaintProperty(
    'parks',
    'fill-opacity',
    0.3
);

Изменение толщины линии

map.setPaintProperty(
    'roads',
    'line-width',
    8
);

Получение значения свойства

Для чтения используется:

map.getPaintProperty()

Пример:

const width = map.getPaintProperty(
    'roads',
    'line-width'
);

Data-Driven Styling

Одно из важнейших преимуществ Paint Properties — возможность стилизовать объекты на основе данных.

Предположим, имеется поле:

population

в GeoJSON:

{
    "population": 1500000
}

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

paint: {
    'circle-radius': [
        'interpolate',
        ['linear'],
        ['get', 'population'],
        100000, 4,
        1000000, 12,
        5000000, 25
    ]
}

Чем больше население, тем больше круг.

Использование Expressions в Paint Properties

Практически любое paint-свойство поддерживает выражения.

Пример цветовой шкалы:

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

Если:

status = active

объект станет зелёным.

Масштабозависимые стили

Paint-свойства могут изменяться в зависимости от масштаба карты.

Пример:

paint: {
    'line-width': [
        'interpolate',
        ['linear'],
        ['zoom'],
        5, 1,
        10, 4,
        15, 10
    ]
}

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

Переходы между состояниями

Mapbox GL JS умеет плавно анимировать изменение paint-свойств.

Для этого используются свойства вида:

*-transition

Пример:

paint: {
    'fill-color': '#00AAFF',
    'fill-color-transition': {
        duration: 1000,
        delay: 0
    }
}

Параметры:

Свойство	Описание
duration	продолжительность анимации
delay	задержка перед запуском

Анимированная смена цвета

map.setPaintProperty(
    'water',
    'fill-color',
    '#FF0000'
);

Если задан переход, цвет будет изменяться плавно.

Производительность Paint Properties

Наиболее дешёвыми по производительности обычно являются:

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

Более затратными считаются:

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

Для крупных карт рекомендуется:

минимизировать количество одновременно отображаемых слоёв;
избегать избыточных выражений;
использовать простые цветовые схемы;
ограничивать применение размытия и прозрачности;
объединять объекты в источниках данных, когда это возможно.

Практический пример комплексного оформления

map.addLayer({
    id: 'cities',
    type: 'circle',
    source: 'cities',
    paint: {
        'circle-radius': [
            'interpolate',
            ['linear'],
            ['get', 'population'],
            100000, 5,
            5000000, 25
        ],

        'circle-color': [
            'interpolate',
            ['linear'],
            ['get', 'population'],
            100000, '#A5D6A7',
            1000000, '#42A5F5',
            5000000, '#E53935'
        ],

        'circle-stroke-color': '#FFFFFF',
        'circle-stroke-width': 2,
        'circle-opacity': 0.8
    }
});

В результате:

размер маркеров зависит от населения;
цвет отражает численность населения;
присутствует белая обводка;
используется частичная прозрачность.

Такой подход демонстрирует основную идею Paint Properties: отделение визуального представления объектов от их геометрии и данных, что позволяет строить сложные, масштабируемые и динамически изменяемые стили карт непосредственно средствами Mapbox GL JS.