Mapbox GL Draw

Библиотека Mapbox GL JS предоставляет высокопроизводительный рендеринг векторных карт на WebGL и служит базой для построения интерактивных картографических приложений. Поверх неё построен набор расширений, среди которых ключевое место занимает Mapbox GL Draw — инструмент для рисования, редактирования и удаления геометрий непосредственно на карте.

Mapbox GL Draw функционирует как слой интерактивного редактирования поверх карты и оперирует данными в формате GeoJSON, обеспечивая синхронизацию между визуальным представлением и внутренним состоянием геометрий.

Архитектура Mapbox GL Draw

Mapbox GL Draw представляет собой модуль, который интегрируется в экземпляр карты Mapbox GL JS и добавляет пользовательские инструменты редактирования. Его внутренняя модель основана на следующих компонентах:

  • Источник данных (GeoJSON Source) — хранит все создаваемые объекты
  • Слои (Layers) — визуализируют состояния объектов (активные, выбранные, редактируемые)
  • Контрол (Control API) — подключается через стандартный интерфейс Mapbox GL JS
  • Режимы (Modes) — определяют поведение взаимодействия (рисование, редактирование, удаление)

Все изменения геометрий отражаются в GeoJSON-хранилище, которое синхронизируется с картой в реальном времени.

Подключение и инициализация

Mapbox GL Draw подключается как расширение к карте Mapbox GL JS и требует создания экземпляра контроллера.

import mapboxgl from "mapbox-gl";
import MapboxDraw from "@mapbox/mapbox-gl-draw";

mapboxgl.accessToken = "TOKEN";

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/streets-v12",
  center: [37.6173, 55.7558],
  zoom: 10
});

const draw = new MapboxDraw({
  displayControlsDefault: false,
  controls: {
    polygon: true,
    line_string: true,
    point: true,
    trash: true
  }
});

map.addControl(draw);

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

Модель данных GeoJSON

Внутреннее состояние Mapbox GL Draw полностью основано на стандарте GeoJSON.

Основные типы объектов:

  • Point — точечные маркеры
  • LineString — ломаные линии
  • Polygon — полигоны с возможными отверстиями

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

{
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [37.61, 55.75],
        [37.62, 55.75],
        [37.62, 55.76],
        [37.61, 55.76],
        [37.61, 55.75]
      ]
    ]
  }
}

Все операции редактирования преобразуют эту структуру без необходимости ручного вмешательства.

Основные режимы работы

Mapbox GL Draw использует систему режимов, определяющих поведение курсора и обработку событий.

Режимы создания

  • draw_point — добавление точек
  • draw_line_string — построение линий
  • draw_polygon — построение полигонов

Режим редактирования

  • simple_select — выбор объектов
  • direct_select — редактирование вершин

Пользовательские режимы

Архитектура позволяет расширять поведение через кастомные режимы:

const customMode = {
  onSetup() {
    return {};
  },
  onClick(state, e) {
    state.clicked = true;
  }
};

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

Mapbox GL Draw предоставляет API для программного взаимодействия с геометриями.

Добавление объектов

const id = draw.add({
  type: "Feature",
  geometry: {
    type: "Point",
    coordinates: [37.61, 55.75]
  },
  properties: {}
});

Получение всех объектов

const data = draw.getAll();

Обновление объектов

draw.setFeatureProperty(id, "name", "upd ated");

Удаление объектов

draw.delete(id);

Очистка всех объектов

draw.deleteAll();

События и реактивное поведение

Mapbox GL Draw генерирует события, синхронизированные с действиями пользователя и изменениями состояния.

Основные события:

  • draw.create — создание объекта
  • draw.update — изменение геометрии
  • draw.delete — удаление объекта
  • draw.selectionchange — изменение выделения

Пример обработки событий:

map.on("draw.create", (e) => {
  console.log("Создан объект:", e.features);
});

map.on("draw.update", (e) => {
  console.log("Обновление:", e.features);
});

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

Настройка отображения объектов

Визуализация объектов управляется через стили Mapbox GL JS, так как Mapbox GL Draw добавляет собственные слои.

Основные слои:

  • активные вершины
  • линии редактирования
  • неактивные объекты
  • выбранные объекты

Пример кастомизации:

const draw = new MapboxDraw({
  styles: [
    {
      id: "gl-draw-polygon-fill",
      type: "fill",
      paint: {
        "fill-color": "#ff0000",
        "fill-opacity": 0.3
      }
    }
  ]
});

Стили позволяют полностью переопределить внешний вид геометрий.

Работа с ограничениями и правилами валидации

Mapbox GL Draw поддерживает валидацию геометрий на уровне режимов:

  • запрет самопересечений
  • ограничение количества вершин
  • контроль замыкания полигонов
  • фильтрация недопустимых координат

Эти ограничения реализуются либо через режимы, либо через постобработку GeoJSON.

Интеграция с внешними источниками данных

Mapbox GL Draw может использоваться совместно с серверными API и базами геоданных.

Типовой поток:

  • загрузка GeoJSON с сервера
  • добавление в Draw
  • редактирование на клиенте
  • экспорт изменённых данных обратно

Пример загрузки:

fetch("/data.geojson")
  .then(res => res.json())
  .then(data => {
    draw.se t(data);
  });

Экспорт:

const updated = draw.getAll();

Производительность и масштабирование

При работе с большим количеством объектов важны особенности оптимизации:

  • использование минимального числа слоёв
  • кэширование GeoJSON
  • ограничение количества одновременно редактируемых объектов
  • отключение ненужных контролов

Mapbox GL JS обеспечивает WebGL-рендеринг, что снижает нагрузку при отображении сложных сцен, однако Mapbox GL Draw добавляет DOM- и event-слой, который требует аккуратного управления состоянием.

Пользовательские расширения и модификации

Mapbox GL Draw допускает расширение функциональности через:

  • кастомные режимы рисования
  • пользовательские кнопки контролов
  • внешние валидаторы геометрий
  • интеграцию с аналитическими сервисами

Пример расширения контролов:

const draw = new MapboxDraw({
  controls: {
    polygon: true,
    trash: true
  },
  defaultMode: "draw_polygon"
});

Система хранения состояния

Внутреннее состояние Mapbox GL Draw основано на immutable-подходе:

  • каждая геометрия имеет уникальный ID
  • изменения создают новые версии объектов
  • выделение объектов отделено от данных

Такая модель упрощает синхронизацию с внешними хранилищами и предотвращает конфликты при редактировании.

Геометрические операции

Mapbox GL Draw поддерживает базовые операции над геометриями:

  • добавление вершин
  • удаление вершин
  • перетаскивание узлов
  • объединение линий (через расширения)

Все операции транслируются в изменения GeoJSON без необходимости ручного пересчёта координат.

Взаимодействие с Mapbox GL JS слоями

Mapbox GL Draw интегрируется в систему слоёв Mapbox GL JS, создавая собственные источники данных (sources) и слои (layers).

Основные принципы взаимодействия:

  • Draw управляет источником mapbox-gl-draw-cold
  • активные объекты отображаются в hot source
  • слои автоматически обновляются при изменении состояния

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

Обработка координат и пространственные особенности

Все координаты хранятся в формате WGS84:

  • долгота (longitude)
  • широта (latitude)

Mapbox GL Draw не выполняет сложных геодезических преобразований, что делает его зависимым от внешних библиотек при необходимости расчёта:

  • площадей
  • расстояний
  • буферных зон

Интеграция с такими вычислениями обычно реализуется через обработчики событий.

Роль Mapbox GL Draw в архитектуре веб-картографии

Mapbox GL Draw формирует слой интерактивного редактирования поверх рендеринга WebGL, предоставляемого Mapbox GL JS. Его архитектурная функция заключается в превращении статической карты в среду редактирования геоданных, где визуализация и моделирование пространственных объектов объединены в одной системе.

Оглавление