LngLat класс

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

Основная задача этого класса — предоставить безопасный и предсказуемый способ работы с координатами, учитывая особенности сферической модели Земли и ограничений диапазонов значений.

Конструктор и базовая структура

Объект создаётся через передачу двух числовых значений:

  • lng — долгота (longitude)
  • lat — широта (latitude)
const point = new maplibregl.LngLat(37.6173, 55.7558);

Порядок аргументов принципиально важен: сначала долгота, затем широта. Это соответствует стандарту GeoJSON и внутренним соглашениям MapLibre GL JS.

Нарушение порядка является одной из наиболее частых ошибок при работе с геоданными, особенно при миграции с API, где используется формат [lat, lng].

Свойства объекта

После создания экземпляра доступны два неизменяемых смысловых свойства:

  • lng — значение долготы в градусах
  • lat — значение широты в градусах
console.log(point.lng); // 37.6173
console.log(point.lat); // 55.7558

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

Нормализация координат

Одной из ключевых особенностей является необходимость нормализации долготы. Географическая система координат допускает значения долготы за пределами диапазона [-180, 180], однако для корректного отображения на карте такие значения приводятся к стандартному интервалу.

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

const normalized = maplibregl.LngLat.convert([190, 10]);

или при необходимости явного «оборачивания»:

const wrapped = point.wrap();

wrap()

Метод wrap() возвращает новый объект координат, в котором долгота приведена к диапазону [-180, 180].

const p = new maplibregl.LngLat(200, 40);
const w = p.wrap();

console.log(w.lng); // -160

Это особенно важно при работе с:

  • повторяющимися мировыми проекциями
  • интерактивным панорамированием карты
  • слоями, пересекающими антимеридиан

Статический метод convert

Для преобразования различных форматов координат используется статический метод convert.

Он принимает:

  • массив [lng, lat]
  • объект LngLat
  • уже корректный экземпляр класса
const a = maplibregl.LngLat.convert([30, 50]);
const b = maplibregl.LngLat.convert(a);

Такой механизм позволяет унифицировать входные данные, поступающие из разных источников (GeoJSON, API, пользовательский ввод).

Сравнение координат

Для проверки эквивалентности координат используется метод equals.

const a = new maplibregl.LngLat(10, 20);
const b = new maplibregl.LngLat(10, 20);

console.log(a.equals(b)); // true

Сравнение производится по строгому равенству значений долготы и широты.

Следует учитывать, что метод не выполняет нормализацию автоматически:

new maplibregl.LngLat(180, 0).equals(new maplibregl.LngLat(-180, 0)); // false

Представление в виде массива

Для интеграции с GeoJSON и сторонними библиотеками координаты часто преобразуются в массив:

const arr = point.toArray();
console.log(arr); // [37.6173, 55.7558]

Такой формат используется в:

  • GeoJSON Feature geometry
  • Turf.js
  • API пространственного анализа

Строковое представление

Метод toString() возвращает человекочитаемое представление координат:

console.log(point.toString());
// LngLat(37.6173, 55.7558)

Он полезен при отладке, логировании и трассировке географических данных.

Использование в API карты

Экземпляры LngLat активно используются в методах управления картой:

map.setCenter(new maplibregl.LngLat(37.6173, 55.7558));
map.flyTo({
  center: new maplibregl.LngLat(37.6173, 55.7558),
  zoom: 10
});

Также часто применяются при обработке событий:

map.on('click', (e) => {
  console.log(e.lngLat.lng, e.lngLat.lat);
});

Объект e.lngLat уже является экземпляром LngLat, что упрощает дальнейшие вычисления без дополнительного преобразования.

Географические особенности и ограничения

Работа класса учитывает фундаментальные особенности глобальной координатной системы:

  • долгота ограничена периодичностью 360°
  • широта ограничена диапазоном [-90, 90]
  • пересечение антимеридиана требует нормализации
  • визуализация зависит от проекции карты

При выходе за допустимые пределы широты поведение зависит от внутренних механизмов MapLibre GL JS, которые могут ограничивать значение или приводить его к ближайшему допустимому.

Типовые сценарии применения

Центрирование карты

map.setCenter(new maplibregl.LngLat(lng, lat));

Расчёт расстояний (совместно с внешними алгоритмами)

const p1 = new maplibregl.LngLat(0, 0);
const p2 = new maplibregl.LngLat(10, 10);

Обработка пользовательского ввода

function handleInput(lng, lat) {
  return maplibregl.LngLat.convert([lng, lat]);
}

Особенности иммутабельности

Объект координат не предназначен для изменения после создания. Изменение значений напрямую не предусмотрено API.

point.lng = 100; // не рекомендуется и не поддерживается

Для получения новых координат создаётся новый экземпляр:

const updated = new maplibregl.LngLat(point.lng + 1, point.lat);

Такой подход снижает количество ошибок, связанных с побочными эффектами в геометрических вычислениях.

Взаимодействие с другими сущностями карты

Класс тесно связан с другими географическими структурами:

  • LngLatBounds — описывает прямоугольные области
  • Point — экранные координаты
  • MercatorCoordinate — координаты в проекции Меркатора

Преобразование между ними осуществляется через методы MapLibre GL JS или вспомогательные утилиты.

const bounds = new maplibregl.LngLatBounds(
  new maplibregl.LngLat(10, 10),
  new maplibregl.LngLat(20, 20)
);

Поведение при пересечении 180° меридиана

При работе с глобальными слоями возникает необходимость корректной обработки координат, пересекающих антимеридиан. Метод wrap() обеспечивает приведение долготы к корректному диапазону, предотвращая визуальные артефакты:

const edge = new maplibregl.LngLat(179, 0);
const moved = new maplibregl.LngLat(181, 0);

console.log(moved.wrap().lng); // -179

Это критически важно при:

  • отображении мировых маршрутов
  • анимации перемещения объектов
  • рендеринге геометрий на глобальных картах

Взаимодействие с событиями карты

При обработке событий карта возвращает координаты в формате LngLat, что позволяет сразу использовать их в логике приложения:

map.on('mousemove', (e) => {
  const { lng, lat } = e.lngLat;
  updateMarker(lng, lat);
});

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

Оглавление