Coordinates

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

Библиотека опирается на географическую систему координат WGS84, которая использует значения широты (latitude) и долготы (longitude) для определения положения точки на поверхности Земли.

Формат координат

Во всех основных API Mapbox GL JS координаты передаются в формате:

[longitude, latitude]

Пример:

[37.6176, 55.7558]

Данная запись соответствует координатам Москвы:

  • долгота: 37.6176
  • широта: 55.7558

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

Правильно:

[37.6176, 55.7558]

Неправильно:

[55.7558, 37.6176]

Ошибочный порядок координат приводит к отображению объектов в совершенно другой точке мира.

Тип LngLat

Для представления географических координат Mapbox GL JS предоставляет специальный класс LngLat.

Создание объекта:

const point = new mapboxgl.LngLat(
    37.6176,
    55.7558
);

Получение отдельных значений:

console.log(point.lng);
console.log(point.lat);

Результат:

37.6176
55.7558

Экземпляр LngLat является объектно-ориентированным представлением обычного массива координат.

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

Начальное положение карты задаётся через параметр center.

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

После загрузки карта будет центрирована на указанных координатах.

Получение центра карты

Текущий центр карты можно получить методом getCenter().

const center = map.getCenter();

console.log(center);

Результат:

LngLat {
    lng: 37.6176,
    lat: 55.7558
}

Доступ к отдельным координатам:

const center = map.getCenter();

console.log(center.lng);
console.log(center.lat);

Преобразование LngLat в массив

Для совместимости с другими API объект можно преобразовать обратно в массив.

const center = map.getCenter();

const coords = center.toArray();

console.log(coords);

Результат:

[37.6176, 55.7558]

Преобразование массива в LngLat

Создание объекта из массива:

const coords = [37.6176, 55.7558];

const point = mapboxgl.LngLat.convert(coords);

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

console.log(point.lng);
console.log(point.lat);

Координаты маркеров

Маркер размещается на карте с помощью метода setLngLat().

new mapboxgl.Marker()
    .setLngLat([37.6176, 55.7558])
    .addTo(map);

Использование объекта LngLat также допустимо:

const point = new mapboxgl.LngLat(
    37.6176,
    55.7558
);

new mapboxgl.Marker()
    .setLngLat(point)
    .addTo(map);

Получение координат маркера

Координаты существующего маркера можно получить через getLngLat().

const marker = new mapboxgl.Marker()
    .setLngLat([37.6176, 55.7558])
    .addTo(map);

const position = marker.getLngLat();

console.log(position.lng);
console.log(position.lat);

Координаты при перемещении маркера

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

const marker = new mapboxgl.Marker({
    draggable: true
})
.setLngLat([37.6176, 55.7558])
.addTo(map);

marker.on('dragend', () => {
    const pos = marker.getLngLat();

    console.log(pos.lng);
    console.log(pos.lat);
});

Координаты пользовательского клика

Каждое событие мыши содержит географические координаты точки взаимодействия.

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

Результат:

LngLat {
    lng: 37.62,
    lat: 55.75
}

Получение отдельных значений:

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

Создание маркера по месту клика

Частая задача — добавление маркера в точку нажатия.

map.on('click', (event) => {
    new mapboxgl.Marker()
        .setLngLat(event.lngLat)
        .addTo(map);
});

Теперь каждый клик создаёт новый маркер в выбранной позиции.

Географические координаты GeoJSON

GeoJSON является основным форматом пространственных данных в Mapbox GL JS.

Точка:

{
    "type": "Point",
    "coordinates": [37.6176, 55.7558]
}

Линия:

{
    "type": "LineString",
    "coordinates": [
        [37.6176, 55.7558],
        [37.6500, 55.7700],
        [37.7000, 55.7800]
    ]
}

Полигон:

{
    "type": "Polygon",
    "coordinates": [
        [
            [37.60, 55.75],
            [37.70, 55.75],
            [37.70, 55.80],
            [37.60, 55.80],
            [37.60, 55.75]
        ]
    ]
}

Во всех случаях используется порядок:

[longitude, latitude]

Координаты границ карты

Для определения текущей видимой области используется метод getBounds().

const bounds = map.getBounds();

Получение углов:

console.log(bounds.getNorthEast());
console.log(bounds.getSouthWest());

Пример результата:

LngLat {
    lng: 37.85,
    lat: 55.90
}

LngLat {
    lng: 37.30,
    lat: 55.55
}

Тип LngLatBounds

Класс LngLatBounds представляет прямоугольную область на карте.

Создание:

const bounds = new mapboxgl.LngLatBounds(
    [37.30, 55.55],
    [37.85, 55.90]
);

Где:

  • первая точка — юго-западный угол;
  • вторая точка — северо-восточный угол.

Масштабирование карты по координатам

Метод fitBounds() автоматически подбирает масштаб таким образом, чтобы вся область оказалась в пределах экрана.

const bounds = [
    [37.30, 55.55],
    [37.85, 55.90]
];

map.fitBounds(bounds);

С отступами:

map.fitBounds(bounds, {
    padding: 50
});

Проверка попадания точки в область

const bounds = map.getBounds();

const point = [37.6176, 55.7558];

console.log(
    bounds.contains(point)
);

Результат:

true

или

false

Координаты и мировая карта

Долгота может изменяться от:

-180 до 180

Широта:

-90 до 90

Примеры:

[-74.0060, 40.7128]

Нью-Йорк.

[2.3522, 48.8566]

Париж.

[139.6917, 35.6895]

Токио.

Нормализация долготы

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

Например:

[190, 55]

или

[-190, 55]

Метод wrap() приводит координаты к корректному диапазону.

const point = new mapboxgl.LngLat(
    190,
    55
);

const wrapped = point.wrap();

console.log(wrapped);

Результат:

LngLat {
    lng: -170,
    lat: 55
}

Преобразование координат в экранные пиксели

Иногда требуется узнать положение точки внутри HTML-контейнера карты.

Для этого используется метод project().

const pixel = map.project(
    [37.6176, 55.7558]
);

console.log(pixel);

Результат:

Point {
    x: 512,
    y: 341
}

Координаты указываются в пикселях относительно контейнера карты.

Преобразование пикселей в географические координаты

Обратная операция выполняется методом unproject().

const lngLat = map.unproject([
    512,
    341
]);

console.log(lngLat);

Результат:

LngLat {
    lng: 37.6176,
    lat: 55.7558
}

Использование project() для пользовательских интерфейсов

Метод полезен при создании собственных HTML-элементов поверх карты.

const point = map.project(
    [37.6176, 55.7558]
);

element.style.left = `${point.x}px`;
element.style.top = `${point.y}px`;

Таким образом можно синхронизировать произвольные DOM-элементы с географическими объектами.

Координаты в анимациях

Перемещение камеры к определённой точке:

map.flyTo({
    center: [37.6176, 55.7558],
    zoom: 12
});

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

map.easeTo({
    center: [37.6176, 55.7558],
    duration: 3000
});

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

Работа с несколькими точками

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

const points = [
    [37.6176, 55.7558],
    [37.7000, 55.8000],
    [37.5000, 55.7000]
];

Создание ограничивающего прямоугольника:

const bounds = new mapboxgl.LngLatBounds();

points.forEach(point => {
    bounds.extend(point);
});

После чего область отображается целиком:

map.fitBounds(bounds, {
    padding: 40
});

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

Основные классы и методы для работы с координатами

Объект Назначение
LngLat Представление одной географической точки
LngLatBounds Прямоугольная область карты
getCenter() Получение центра карты
setLngLat() Установка координат объекта
getLngLat() Получение координат объекта
getBounds() Получение видимой области
fitBounds() Масштабирование по области
contains() Проверка принадлежности точки области
project() Преобразование координат в пиксели
unproject() Преобразование пикселей в координаты
wrap() Нормализация долготы
flyTo() Анимированное перемещение камеры
easeTo() Плавное изменение положения карты

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

Оглавление