Система координат LatLng

Система координат, используемая в Google Maps JavaScript API, основана на географической модели широты и долготы, где каждая точка на поверхности Земли определяется парой значений: latitude (широта) и longitude (долгота). В API эти значения инкапсулируются в объект LatLng, который является фундаментальной единицей позиционирования объектов на карте.

Базовая система координат соответствует модели WGS84 (World Geodetic System 1984), применяемой в GPS-навигации. Она описывает положение точки на эллипсоиде Земли:

  • Широта (latitude) — угол между экватором и точкой на поверхности Земли.
  • Долгота (longitude) — угол между нулевым меридианом и меридианом точки.

Диапазоны значений строго определены:

  • широта: от -90 до +90
  • долгота: от -180 до +180

Эта система не является плоской, поэтому напрямую не используется для отрисовки на экране. Для визуализации Google Maps применяет проекцию Mercator, но внутри логика координат остаётся географической.

Объект google.maps.LatLng

В JavaScript API координаты чаще всего представлены через класс google.maps.LatLng. Он инкапсулирует широту и долготу и предоставляет методы для работы с ними.

Основные способы создания:

const point = new google.maps.LatLng(55.751244, 37.618423);

Также поддерживается объектный литерал:

const point = { lat: 55.751244, lng: 37.618423 };

Однако такой формат не является полноценным экземпляром LatLng, а относится к типу LatLngLiteral.

Методы доступа к координатам

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

const lat = point.lat();
const lng = point.lng();

Координаты нельзя изменять напрямую. Объект является иммутабельным, что важно для предсказуемости работы API и кэширования.

LatLngLiteral и LatLng

В API существует два близких представления координат:

LatLng (класс)

  • полноценный объект API
  • содержит методы
  • используется внутри API

LatLngLiteral (объект)

  • простой JavaScript-объект
  • формат { lat: number, lng: number }
  • используется в конфигурациях и входных параметрах

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

const mapOptions = {
  center: { lat: 48.8566, lng: 2.3522 },
  zoom: 10
};

API автоматически преобразует литералы в LatLng.

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

Google Maps выполняет нормализацию значений долготы. Это означает, что значения вне диапазона -180…180 приводятся к допустимому виду.

Пример:

  • 190° долготы интерпретируется как -170°
  • -190° долготы интерпретируется как 170°

Широта ограничивается жёстче и не “зацикливается”, а обрезается к допустимому диапазону.

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

Сравнение объектов LatLng требует осторожности. Прямое сравнение через === не работает, так как сравниваются ссылки на объекты.

Правильный подход:

point1.equals(point2);

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

Точность и особенности floating point

Координаты хранятся в формате IEEE 754 double precision. Это означает:

  • возможны микроскопические погрешности
  • сравнение через === ненадёжно
  • результаты вычислений (например, смещения) могут давать дробные артефакты

Поэтому API использует встроенные методы сравнения и округления.

Преобразование в примитивные формы

Объект LatLng поддерживает преобразование в JSON:

point.toJSON();

Результат:

{ lat: 55.751244, lng: 37.618423 }

Это важно при сериализации данных, например при сохранении состояния карты или передаче координат на сервер.

Также существует строковое представление:

point.toString();

Формат обычно выглядит как:

(55.751244, 37.618423)

Работа с картой и центром координат

Объект LatLng используется во всех ключевых компонентах API:

Центр карты

const map = new google.maps.Map(document.getElementById("map"), {
  center: new google.maps.LatLng(40.7128, -74.0060),
  zoom: 12
});

Маркеры

const marker = new google.maps.Marker({
  position: { lat: 40.7128, lng: -74.0060 },
  map: map
});

Области (Bounds)

const bounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(40.5, -74.2),
  new google.maps.LatLng(40.9, -73.7)
);

LatLngBounds использует две координаты: юго-западную и северо-восточную точки.

Анти-меридиан и особенности долготы

Одной из сложных ситуаций является пересечение линии ±180° долготы (анти-меридиана). В этом случае:

  • стандартное увеличение долготы может “перепрыгивать” через карту
  • LatLngBounds учитывает это и корректно расширяет границы
  • визуально карта может отображать область, охватывающую Тихий океан целиком

Это особенно важно при работе с глобальными масштабами и маршрутами.

Внутреннее представление и проекция

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

  • сфера Земли проецируется на цилиндр
  • широта нелинейно преобразуется
  • долгота отображается линейно

Это позволяет отображать карту в 2D-пространстве браузера, сохраняя географическую логичность.

Конвертация между типами

Часто требуется переход между формами координат:

const literal = point.toJSON();
const latLng = new google.maps.LatLng(literal.lat, literal.lng);

API также автоматически выполняет такие преобразования при передаче параметров.

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

Многие события API возвращают координаты в формате LatLng:

map.addListener("click", (event) => {
  const position = event.latLng;
});

event.latLng всегда является экземпляром google.maps.LatLng, что позволяет сразу использовать методы объекта без дополнительной обработки.

Практическое значение модели LatLng

Модель LatLng служит универсальным стандартом для:

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

Её неизменяемость, точность и совместимость с географической системой координат обеспечивают стабильную работу всей экосистемы Google Maps JavaScript API.

Оглавление