Geometry Library

Пространственные вычисления в браузере

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

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

Библиотека логически разделена на несколько модулей:

  • google.maps.geometry.spherical
  • google.maps.geometry.encoding
  • google.maps.geometry.poly

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

Подключение Geometry Library

Geometry Library не загружается автоматически и подключается через параметр libraries при инициализации API.

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

Загрузка API с подключением геометрического модуля:

<script
  src="https://maps.googleapis.com/maps/api/js?key=API_KEY&libraries=geometry"
></script>

После загрузки становятся доступны объекты:

google.maps.geometry.spherical
google.maps.geometry.encoding
google.maps.geometry.poly

Модуль spherical: сферическая геометрия

Основной модуль Geometry Library — spherical. Он выполняет вычисления на сфере, используя модель Земли как сфероида с радиусом ~6378137 метров.

Расстояние между точками

Ключевая функция:

google.maps.geometry.spherical.computeDistanceBetween(latLngA, latLngB);

Функция возвращает расстояние в метрах между двумя точками.

Пример:

const a = new google.maps.LatLng(55.751244, 37.618423);
const b = new google.maps.LatLng(59.931058, 30.360909);

const distance = google.maps.geometry.spherical.computeDistanceBetween(a, b);

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

Длина ломаной линии

google.maps.geometry.spherical.computeLength(path);

path — массив координат LatLng.

const path = [
  new google.maps.LatLng(55.75, 37.61),
  new google.maps.LatLng(56.00, 38.00),
  new google.maps.LatLng(57.00, 39.00)
];

const length = google.maps.geometry.spherical.computeLength(path);

Результат выражается в метрах.

Площадь полигона

google.maps.geometry.spherical.computeArea(polygonPath);

Функция вычисляет площадь на поверхности сферы.

const polygon = [
  new google.maps.LatLng(55.75, 37.61),
  new google.maps.LatLng(55.80, 37.70),
  new google.maps.LatLng(55.70, 37.80)
];

const area = google.maps.geometry.spherical.computeArea(polygon);

Возвращаемое значение — квадратные метры.

Направление (heading)

google.maps.geometry.spherical.computeHeading(pointA, pointB);

Возвращает азимут в градусах от северного направления.

const heading = google.maps.geometry.spherical.computeHeading(a, b);

Значение лежит в диапазоне от -180 до 180 градусов.

Интерполяция между точками

google.maps.geometry.spherical.interpolate(pointA, pointB, fraction);

fraction — доля пути от 0 до 1.

const mid = google.maps.geometry.spherical.interpolate(a, b, 0.5);

Функция используется для построения плавных траекторий и анимации перемещения объектов.

Смещение точки по направлению

google.maps.geometry.spherical.computeOffset(origin, distance, heading);

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

const destination = google.maps.geometry.spherical.computeOffset(
  a,
  1000,
  90
);

Результат — точка на расстоянии 1 км на восток.

Модуль encoding: кодирование и декодирование полилиний

Модуль encoding работает с компактным представлением геометрических линий.

Кодирование пути

google.maps.geometry.encoding.encodePath(path);
const encoded = google.maps.geometry.encoding.encodePath(path);

Результат — строка, содержащая сжатое представление координат.

Декодирование строки

google.maps.geometry.encoding.decodePath(encodedString);
const decoded = google.maps.geometry.encoding.decodePath(encoded);

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

Модуль poly: работа с полигонами

Модуль poly предоставляет инструменты анализа принадлежности точек и проверки пересечений.

Проверка принадлежности точки полигону

google.maps.geometry.poly.containsLocation(point, polygon);
const inside = google.maps.geometry.poly.containsLocation(
  new google.maps.LatLng(55.75, 37.61),
  polygon
);

Результат — логическое значение.

Проверка пересечения полилиний

google.maps.geometry.poly.isLocationOnEdge(point, polyline, tolerance);
const onE dge = google.maps.geometry.poly.isLocationOnEdge(
  point,
  path,
  10e-6
);

tolerance задаёт допустимое отклонение.

Геодезическая модель и сферические искажения

Все вычисления Geometry Library основаны на сферической модели Земли. Это приводит к отличиям от плоской геометрии:

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

Используется радиус Земли:

R ≈ 6378137 м

Сферическая модель обеспечивает баланс между точностью и вычислительной эффективностью.

Координатная система

Geometry Library работает с объектами LatLng, где:

  • lat — широта (-90 до 90)
  • lng — долгота (-180 до 180)

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

rad = deg × π / 180

Далее применяются тригонометрические функции сферической геометрии.

Производительность вычислений

Сферическая геометрия включает тригонометрические операции, что делает её более затратной по сравнению с евклидовой.

Факторы, влияющие на производительность:

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

Для оптимизации применяются:

  • кэширование результатов вычислений
  • упрощение геометрии (simplification)
  • предварительное декодирование полилиний

Работа с большими маршрутами

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

  • декодирование через encoding.decodePath
  • вычисление длины через computeLength
  • сегментный анализ для поиска аномалий

Пример анализа маршрута:

const path = google.maps.geometry.encoding.decodePath(encoded);

const totalDistance = google.maps.geometry.spherical.computeLength(path);

const segments = [];
for (let i = 0; i < path.length - 1; i++) {
  segments.push(
    google.maps.geometry.spherical.computeDistanceBetween(path[i], path[i + 1])
  );
}

Геометрические ограничения и точность

Точность вычислений зависит от:

  • модели Земли (сфера vs эллипсоид)
  • плотности точек
  • масштаба карты

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

Комбинирование модулей

Geometry Library часто используется совместно:

  • spherical для базовых вычислений
  • encoding для передачи данных
  • poly для анализа областей

Типичный сценарий обработки геоданных включает:

  1. получение маршрута
  2. декодирование полилинии
  3. вычисление длины
  4. проверку попадания в геозоны
  5. анализ направлений между сегментами

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

Geometry Library применяется для задач:

  • расчёт маршрутов доставки
  • геофенсинг (geo-fencing)
  • анализ зон покрытия
  • проверка доступности объектов
  • построение тепловых карт перемещений

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

Оглавление