Source-layer в стилях

Векторные тайлы в MapLibre GL JS организованы в виде слоёв внутри тайлсета, и ключевым механизмом выбора данных внутри источника является свойство source-layer.

Векторный тайл (vector tile) — это контейнер, внутри которого данные разделены на логические слои. Каждый такой внутренний слой называется source-layer (иногда встречается термин «layer в тайлсете»).

source-layer — это не слой карты в стиле MapLibre GL JS, а слой внутри данных источника (source), загруженного из vector tiles.

Ключевой смысл:

  • source — источник данных (tileset)
  • source-layer — конкретный слой внутри этого tileset
  • layer (в стиле) — визуальное представление на карте

Эти три уровня часто путают, но они отвечают за разные этапы обработки данных.

Структура векторного тайлсета

Векторный тайл обычно содержит несколько тематических слоёв:

  • roads — дороги
  • buildings — здания
  • water — водные объекты
  • landuse — землепользование
  • poi — точки интереса

Каждый из них доступен через source-layer.

Пример структуры:

tileset (source)
 ├── roads
 ├── buildings
 ├── water
 ├── poi

MapLibre GL JS не «угадывает» эти названия — они должны точно совпадать с тем, что определено в тайлсете.

Использование source-layer в стиле MapLibre GL JS

В стиле MapLibre GL JS source-layer указывается внутри объекта слоя (layer), который использует vector source.

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

{
  "id": "road-layer",
  "type": "line",
  "source": "transportation",
  "source-layer": "roads",
  "paint": {
    "line-color": "#333",
    "line-width": 2
  }
}

Здесь:

  • source — имя источника, заданного в sources
  • source-layer — внутренний слой внутри тайлсета
  • type — тип визуализации (line, fill, circle и т.д.)

Привязка источника данных

Перед использованием source-layer необходимо определить vector source:

{
  "sources": {
    "transportation": {
      "type": "vector",
      "url": "mapbox://examples.8fgz4egr"
    }
  }
}

Без корректного источника source-layer не имеет смысла, так как он работает только внутри конкретного tileset.

Пример работы с несколькими source-layer

Один источник может содержать множество логических слоёв, и каждый из них может быть отображён отдельным стилевым слоем.

{
  "id": "road-major",
  "type": "line",
  "source": "transportation",
  "source-layer": "roads",
  "filter": ["==", ["get", "class"], "primary"],
  "paint": {
    "line-color": "#ff8800",
    "line-width": 3
  }
}
{
  "id": "road-secondary",
  "type": "line",
  "source": "transportation",
  "source-layer": "roads",
  "filter": ["==", ["get", "class"], "secondary"],
  "paint": {
    "line-color": "#ffaa00",
    "line-width": 2
  }
}

Оба слоя используют один source-layer, но различаются фильтрацией.

Фильтрация данных внутри source-layer

После выбора source-layer данные дополнительно уточняются через filter.

Фильтрация позволяет:

  • разделять объекты по типу
  • выделять категории
  • управлять видимостью элементов

Пример:

"filter": ["all",
  ["==", ["geometry-type"], "LineString"],
  ["has", "highway"]
]

Важно понимать: фильтр применяется после извлечения данных из source-layer.

Отличие source-layer от layer

Распространённая ошибка — путать:

  • layer в стиле — визуальная сущность
  • source-layer — слой данных внутри тайлсета

Пример различия:

// layer (стиль)
{
  "id": "roads-style-layer"
}
// source-layer (данные)
"source-layer": "roads"

Один source-layer может использоваться десятками style layers.

Типичные ошибки при работе с source-layer

Несовпадение имени слоя

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

"source-layer": "road"  // ошибка

если в тайлсете слой называется:

roads

MapLibre GL JS не исправляет такие ошибки автоматически.

Использование source-layer с raster source

source-layer применяется только к vector sources. В raster источниках он игнорируется.

Попытка фильтровать несуществующие свойства

Если поле отсутствует в тайле:

["has", "name_en"]

фильтр не вернёт ожидаемых результатов.

Как определить доступные source-layer

Векторные тайлы не всегда документируют структуру, поэтому используются:

  • TileJSON описание
  • инспектор стилей MapLibre GL JS
  • утилиты анализа vector tiles
  • просмотр схемы tileset в Mapbox Studio-совместимых источниках

В debug-режиме MapLibre можно увидеть доступные слои через инспекцию данных.

Взаимодействие source-layer и zoom

source-layer сам по себе не управляет масштабом, но часто используется вместе с minzoom и maxzoom:

{
  "id": "buildings",
  "type": "fill",
  "source": "composite",
  "source-layer": "building",
  "minzoom": 14,
  "paint": {
    "fill-color": "#999"
  }
}

Таким образом:

  • source-layer выбирает данные
  • zoom параметры определяют их видимость

Практическая модель работы pipeline

Обработка данных происходит по цепочке:

  1. Загрузка vector tile из source
  2. Выбор внутреннего source-layer
  3. Применение filter
  4. Интерполяция стиля (paint, layout)
  5. Отрисовка на canvas/WebGL

Любая ошибка в source-layer обрывает цепочку на втором шаге.

Использование одного source-layer в разных стилях

Один и тот же source-layer может быть использован для создания сложной визуальной системы:

  • базовые дороги
  • дороги с трафиком
  • дороги с событиями
  • ночной режим отображения

Пример:

{
  "id": "roads-glow",
  "type": "line",
  "source": "transportation",
  "source-layer": "roads",
  "paint": {
    "line-color": "#00ffff",
    "line-blur": 6,
    "line-width": 4
  }
}
{
  "id": "roads-core",
  "type": "line",
  "source": "transportation",
  "source-layer": "roads",
  "paint": {
    "line-color": "#0066ff",
    "line-width": 2
  }
}

Такая композиция создаёт визуальную глубину без изменения данных.

Поведение при отсутствии source-layer

Если source-layer не указан:

  • MapLibre GL JS не сможет извлечь данные из vector source
  • слой не будет отрисован
  • ошибок в стиле может не появиться явно, но данные будут пустыми

В отличие от многих других ошибок, это часто проявляется как «пустая карта» для конкретного слоя без диагностического сообщения.

Оглавление