Класс LatLng

Назначение и роль в системе координат

Класс LatLng представляет географическую точку в пространстве карты, задаваемую широтой и долготой в градусах. Это базовая единица геоданных, используемая для всех операций позиционирования: размещения маркеров, построения линий, вычисления расстояний и работы с границами.

Основная идея класса — инкапсуляция географической точки с удобным API для математических и геодезических операций.

Создание экземпляра LatLng

Объект LatLng может быть создан несколькими способами через фабричную функцию L.latLng:

L.latLng(51.505, -0.09);
L.latLng([51.505, -0.09]);
L.latLng({ lat: 51.505, lng: -0.09 });
L.latLng(51.505, -0.09, 120); // с высотой

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

  • lat — широта
  • lng — долгота
  • alt — высота (опционально)

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

Экземпляр LatLng содержит фиксированные свойства:

  • lat — широта в градусах
  • lng — долгота в градусах
  • alt — высота (если задана)

Пример:

const point = L.latLng(40.7128, -74.0060);

console.log(point.lat); // 40.7128
console.log(point.lng); // -74.0060

Неизменяемость и модель данных

LatLng в Leaflet проектируется как практически неизменяемый объект. Хотя свойства технически доступны для чтения и записи, изменение координат напрямую считается антипаттерном.

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

const p1 = L.latLng(10, 20);
const p2 = L.latLng(15, 25);

Это важно, поскольку многие внутренние структуры Leaflet кэшируют результаты на основе координат.

Метод equals

Метод equals позволяет сравнивать две точки с учётом допустимой погрешности:

latlng1.equals(latlng2, maxMargin);
  • latlng2 — сравниваемая точка
  • maxMargin — допустимая погрешность (в метрах)

Пример:

const a = L.latLng(51.5, -0.1);
const b = L.latLng(51.5000001, -0.1000001);

console.log(a.equals(b)); // true (в пределах погрешности)

Сравнение учитывает особенности представления координат в числах с плавающей точкой.

Метод distanceTo

Метод distanceTo вычисляет расстояние между двумя точками в метрах.

latlng1.distanceTo(latlng2);

Пример:

const london = L.latLng(51.5074, -0.1278);
const paris = L.latLng(48.8566, 2.3522);

const distance = london.distanceTo(paris);
console.log(distance);

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

Метод wrap

Метод wrap нормализует долготу в диапазон, соответствующий системе координат карты.

latlng.wrap(left, right);
  • left — левая граница долготы
  • right — правая граница долготы

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

Пример:

const p = L.latLng(10, 190);
const wrapped = p.wrap(-180, 180);

console.log(wrapped.lng); // -170

Метод toString

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

latlng.toString();

Пример:

const p = L.latLng(51.5, -0.1);

console.log(p.toString());
// LatLng(51.5, -0.1)

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

Нормализация входных данных

Фабричная функция L.latLng выполняет строгую нормализацию входных форматов:

Поддерживаемые варианты:

  • массив [lat, lng]
  • объект {lat, lng}
  • отдельные аргументы (lat, lng, alt)

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

Взаимодействие с другими компонентами Leaflet

LatLng используется как фундаментальная структура во всех геометрических объектах:

  • маркеры (Marker)
  • линии (Polyline)
  • полигоны (Polygon)
  • круги (Circle)
  • границы (LatLngBounds)

Пример использования в маркере:

L.marker(L.latLng(55.751244, 37.618423)).addTo(map);

Работа с высотой (alt)

Поле alt не всегда учитывается в стандартных 2D-операциях, но может использоваться в расширенных сценариях:

  • 3D-визуализация
  • интеграция с WebGL-слоями
  • анализ высотных данных

Пример:

const p = L.latLng(48.8566, 2.3522, 35);

console.log(p.alt); // 35

Особенности точности и вычислений

Все вычисления, связанные с LatLng, зависят от ограничений IEEE 754 (числа с плавающей точкой). Это влияет на:

  • точность сравнения координат
  • стабильность вычисления расстояний
  • поведение при накоплении ошибок округления

Методы equals и distanceTo компенсируют часть этих ограничений через допуски и геодезические формулы.

Связь с системой проекций

LatLng существует в географической системе координат (широта/долгота), тогда как отображение на экране происходит через проекции (например, Web Mercator).

Преобразование:

  • LatLng → Pixel coordinates выполняется через CRS
  • Pixel → LatLng используется при обработке событий карты

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

При работе с интерактивной картой LatLng часто приходит в объектах событий:

map.on('click', function(e) {
    console.log(e.latlng);
});

e.latlng — это экземпляр LatLng, описывающий точку клика в географических координатах.

Клонирование объектов

Хотя прямого метода clone нет, копирование осуществляется через повторное создание:

const original = L.latLng(10, 20);
const copy = L.latLng(original.lat, original.lng, original.alt);

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

Оглавление