Типы для источников

В системе MapLibre GL JS источники данных являются фундаментальным слоем архитектуры стиля. Именно они определяют, откуда и в каком виде поступает географическая информация, которая затем визуализируется слоями (layers). Типизация источников строго определяет структуру данных, допустимые параметры и поведение при рендеринге.

В спецификации стилей MapLibre GL JS все источники описываются через объединённый тип SourceSpecification, который представляет собой дискриминированное объединение нескольких конкретных типов. Ключевым полем выступает type, определяющее формат данных и набор поддерживаемых опций.

Базовая структура источника

Каждый источник в MapLibre GL JS определяется объектом следующего общего вида:

{
  id: "unique-source-id",
  type: "vector | raster | geojson | image | video | raster-dem",
  ...options
}

В TypeScript-терминах это соответствует:

type SourceSpecification =
  | VectorSourceSpecification
  | RasterSourceSpecification
  | GeoJSONSourceSpecification
  | ImageSourceSpecification
  | VideoSourceSpecification
  | RasterDemSourceSpecification;

Общее поле type является дискриминатором объединения и определяет, какой именно набор свойств будет допустим.

Векторные источники (VectorSourceSpecification)

Векторные источники являются наиболее гибким и производительным способом работы с геоданными. Они основаны на тайлах Mapbox Vector Tiles (MVT) и позволяют хранить геометрию в компактном бинарном формате.

Типизация

type VectorSourceSpecification = {
  type: "vector";
  url?: string;
  tiles?: string[];
  bounds?: number[];
  minzoom?: number;
  maxzoom?: number;
  scheme?: "xyz" | "tms";
};

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

  • url — ссылка на TileJSON, описывающий источник.
  • tiles — массив URL-шаблонов тайлов.
  • bounds — географические границы источника в формате [west, south, east, north].
  • minzoom / maxzoom — диапазон зумов доступности данных.
  • scheme — схема нумерации тайлов (xyz используется по умолчанию).

Особенности

Векторные источники не содержат финальной визуализации. Они предоставляют геометрию и свойства объектов, а отображение определяется стилями слоёв (fill, line, circle, symbol).

Растровые источники (RasterSourceSpecification)

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

Типизация

type RasterSourceSpecification = {
  type: "raster";
  url?: string;
  tiles?: string[];
  tileSize?: number;
  bounds?: number[];
  minzoom?: number;
  maxzoom?: number;
  scheme?: "xyz" | "tms";
};

Важные параметры

  • tileSize — размер тайла в пикселях (обычно 256 или 512).
  • tiles — шаблоны URL для загрузки изображений.
  • url — TileJSON-описание источника.

Поведение

Растровые источники не поддерживают семантические данные. Каждый тайл — это готовое изображение, которое просто накладывается на карту без возможности фильтрации объектов внутри него.

GeoJSON источники (GeoJSONSourceSpecification)

GeoJSON является одним из наиболее популярных форматов для динамических данных. MapLibre GL JS поддерживает его напрямую через источник типа geojson.

Типизация

type GeoJSONSourceSpecification = {
  type: "geojson";
  dat a: string | GeoJSON.FeatureCollection | GeoJSON.Feature;
  maxzoom?: number;
  buffer?: number;
  tolerance?: number;
  cluster?: boolean;
  clusterRadius?: number;
  clusterMaxZoom?: number;
};

Основные поля

  • data — может быть URL, объект GeoJSON или отдельный Feature.
  • buffer — расширение тайла для сглаживания границ геометрии.
  • tolerance — упрощение геометрии при генерации тайлов.
  • cluster — включает кластеризацию точечных объектов.

Кластеризация

При включённой кластеризации GeoJSON источник группирует точки на стороне клиента:

{
  type: "geojson",
  data: points,
  cluster: true,
  clusterRadius: 40,
  clusterMaxZoom: 14
}

Кластеры становятся отдельными объектами с собственными свойствами:

  • point_count
  • cluster_id

Изображения как источники (ImageSourceSpecification)

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

Типизация

type ImageSourceSpecification = {
  type: "image";
  url: string;
  coordinates: number[][];
};

Координаты

Поле coordinates представляет собой массив из четырёх углов изображения:

coordinates: [
  [-77.0369, 38.9072],
  [-77.0090, 38.9072],
  [-77.0090, 38.8895],
  [-77.0369, 38.8895]
]

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

Поведение

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

Видеоисточники (VideoSourceSpecification)

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

Типизация

type VideoSourceSpecification = {
  type: "video";
  urls: string[];
  coordinates: number[][];
};

Особенности

  • urls — массив источников видео (mp4, webm, HLS в зависимости от поддержки браузера).
  • coordinates — географическая привязка углов видео.

Поведение

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

Цифровые модели рельефа (RasterDemSourceSpecification)

Raster DEM источники применяются для работы с высотами и 3D-террейном.

Типизация

type RasterDemSourceSpecification = {
  type: "raster-dem";
  url?: string;
  tiles?: string[];
  encoding?: "terrarium" | "mapbox";
  tileSize?: number;
  bounds?: number[];
  minzoom?: number;
  maxzoom?: number;
};

Кодирование высот

  • terrarium — высоты закодированы в RGB значениях.
  • mapbox — специализированный формат Mapbox Terrain RGB.

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

Raster DEM источники используются вместе с:

  • terrain конфигурацией карты
  • 3D extrusion слоями
  • освещением и тенями

Унифицированный доступ к источникам через API

MapLibre GL JS предоставляет runtime API для управления источниками:

map.addSource("cities", {
  type: "geojson",
  data: "/data/cities.geojson"
});

Получение источника:

const source = map.getSource("cities");

Удаление:

map.removeSource("cities");

Типизация runtime-объектов источников

После добавления в карту источники становятся экземплярами классов, а не только конфигурационными объектами.

Обобщённый тип:

type Source =
  | GeoJSONSource
  | VectorTileSource
  | RasterTileSource
  | ImageSource
  | VideoSource
  | RasterDEMTileSource;

Каждый тип имеет собственный набор методов.

GeoJSONSource

interface GeoJSONSource {
  setData(data: GeoJSON.FeatureCollection | GeoJSON.Feature): void;
}

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

Поведение загрузки и кэширования

Тип источника влияет на стратегию загрузки данных:

  • Vector и Raster используют тайловую модель с HTTP-кэшированием.
  • GeoJSON загружается целиком или частично при кластеризации.
  • Image и Video требуют полной загрузки ресурса перед отображением.
  • Raster DEM дополнительно обрабатывается в WebGL-пайплайне.

Сопоставление источников и слоёв

Источник не существует изолированно. Его тип определяет совместимость с типами слоёв:

  • vector → fill, line, circle, symbol, fill-extrusion
  • raster → raster
  • geojson → любой векторный слой (после тайлизации)
  • image → raster-like overlay
  • video → raster-like animated overlay
  • raster-dem → terrain, hillshade

Ограничения типизации и архитектурные особенности

Типизация источников в MapLibre GL JS отражает WebGL-ориентированную архитектуру:

  • Источники не рендерятся напрямую
  • Все преобразования происходят через слой
  • Тайлы являются основной единицей масштабирования
  • Геометрия нормализуется до загрузки в GPU

Это приводит к строгому разделению:

  • Data layer (sources)
  • Presentation layer (layers)

Конфигурационные различия между типами

Тип источника Данные Формат хранения Динамическое обновление
vector геометрия + атрибуты MVT ограничено
raster изображения PNG/JPEG tiles нет
geojson JSON геометрия объект или URL да
image одиночное изображение bitmap замена координат
video видеопоток media stream замена источника
raster-dem высоты encoded RGB частично

Взаимодействие типов источников с стилями

Тип источника напрямую влияет на доступные выражения (expressions) в слоях:

  • Векторные источники поддерживают фильтрацию по атрибутам:

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

  • Raster источники не поддерживают feature-state.

  • GeoJSON позволяет использовать feature-state и runtime mutation.

  • DEM источники используются только через terrain API.

Особенности типизации в TypeScript интеграции

При использовании TypeScript ключевым моментом является дискриминация по полю type:

function isVectorSource(
  source: SourceSpecification
): source is VectorSourceSpecification {
  return source.type === "vector";
}

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

Обработка ошибок типов источников

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

  • отсутствие обязательного поля type
  • несовместимость url и tiles
  • некорректный формат координат для image/video
  • превышение допустимых значений zoom bounds

MapLibre GL JS выполняет частичную валидацию на этапе добавления источника и продолжает асинхронную проверку при загрузке тайлов.

Расширяемость модели источников

Архитектура допускает появление новых типов источников через расширение спецификации. Однако на уровне runtime система опирается на фиксированный набор типов, определяющих:

  • стратегию загрузки
  • формат декодирования
  • WebGL-пайплайн
  • совместимость со слоями
Оглавление