Программная навигация

В основе Kepler.gl лежит централизованное состояние, построенное вокруг Redux. Любая программная навигация по карте сводится к изменению mapState, который описывает текущую камеру: координаты центра, масштаб, угол поворота и наклон.

Ключевые параметры состояния:

  • latitude / longitude — центр карты
  • zoom — уровень масштабирования
  • bearing — поворот карты
  • pitch — наклон камеры
  • dragRotate / scrollZoom / doubleClickZoom — параметры взаимодействия

Изменение этих значений напрямую через редьюсер не является предпочтительным способом. Вместо этого используется набор action creators Kepler.gl, которые обеспечивают корректную синхронизацию состояния и внутренних подсистем визуализации.

Базовые принципы программной навигации

Программная навигация в Kepler.gl означает управление картой без пользовательского взаимодействия. Это включает:

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

Основной инструмент — dispatch действий в Redux-хранилище Kepler.gl.

Использование action creators Kepler.gl

Для управления картой используется набор встроенных actions:

  • updateMap
  • fitBounds
  • togglePerspective
  • setMapMode
  • addDataToMap
  • updateVisData

Наиболее важные для навигации:

  • updateMap — прямое изменение viewport
  • fitBounds — автоматическое масштабирование под географические границы

Прямое изменение viewport через updateMap

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

import {updateMap} from 'kepler.gl/actions';

dispatch(updateMap({
  latitude: 55.751244,
  longitude: 37.618423,
  zoom: 10,
  bearing: 0,
  pitch: 0,
  transitionDuration: 1000
}));

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

  • перехода к выбранному объекту
  • синхронизации с внешним списком
  • реализации кнопок «перейти к региону»

Параметр transitionDuration включает анимацию перемещения камеры.

Плавные переходы и анимация камеры

Kepler.gl поддерживает анимированные переходы между состояниями камеры. Это достигается через интеграцию с deck.gl transition system.

При использовании updateMap можно задавать:

  • длительность перехода
  • тип интерполяции
  • параметры easing (в зависимости от версии deck.gl)

Пример:

dispatch(updateMap({
  latitude: 48.8566,
  longitude: 2.3522,
  zoom: 12,
  transitionDuration: 2000
}));

При таком подходе карта не «прыгает», а плавно перемещается к новой точке.

Автоматическое масштабирование через fitBounds

Одним из ключевых инструментов программной навигации является fitBounds. Он вычисляет оптимальный viewport, чтобы все точки попадали в видимую область.

import {fitBounds} from 'kepler.gl/actions';

dispatch(fitBounds([
  [30.0, 50.0],
  [40.0, 55.0]
]));

Где:

  • первый массив — юго-западная точка
  • второй массив — северо-восточная точка

Алгоритм внутри Kepler.gl автоматически вычисляет:

  • центр
  • оптимальный zoom
  • отступы от краёв

Это используется при:

  • отображении маршрутов
  • выделении регионов
  • визуализации кластеров точек

Программное перемещение к данным слоя

В Kepler.gl данные структурированы в виде слоёв (layers). Часто требуется навигация не по координатам, а по набору данных.

Пример сценария:

  • пользователь выбирает слой
  • система вычисляет bounding box
  • карта автоматически фокусируется

Типичный поток:

dispatch(addDataToMap({
  datasets: data,
  options: {
    centerMap: true,
    readOnly: false
  }
}));

Параметр centerMap: true инициирует автоматическую навигацию к загруженным данным.

Работа с bounding box вручную

Если требуется более точный контроль, bounding box можно вычислять самостоятельно:

const bounds = [
  [minLng, minLat],
  [maxLng, maxLat]
];

dispatch(fitBounds(bounds));

Это позволяет:

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

Навигация в ответ на внешние события

Kepler.gl часто интегрируется в приложения, где карта не является единственным источником управления.

Типичные источники событий:

  • таблицы данных
  • графики
  • списки объектов
  • API-ответы

Пример связки:

function onSelectRow(row) {
  dispatch(updateMap({
    latitude: row.lat,
    longitude: row.lng,
    zoom: 14,
    transitionDuration: 800
  }));
}

Таким образом создаётся синхронная система взаимодействия между UI и картой.

Управление состоянием через keplerGlReducer

Все изменения навигации проходят через keplerGlReducer. Он объединяет:

  • visState (данные и слои)
  • mapState (камера)
  • uiState (интерфейс)

Программная навигация фактически изменяет mapState, но может зависеть от visState, например при автофокусе.

Синхронизация нескольких карт

Kepler.gl поддерживает несколько инстансов карт в одном приложении. Каждый имеет свой ключ состояния.

dispatch(updateMap({
  mapIndex: 'map_1',
  latitude: 51.5074,
  longitude: -0.1278,
  zoom: 11
}));

Это важно для сценариев:

  • сравнение городов
  • split-view аналитика
  • синхронное перемещение нескольких карт

Ограничение области навигации

В некоторых приложениях требуется ограничить перемещение камеры:

  • запрет выхода за границы страны
  • ограничение zoom range
  • фиксация поворота

Это реализуется через mapState ограничения:

mapState: {
  minZoom: 2,
  maxZoom: 15,
  dragRotate: false
}

Хотя это не прямое управление навигацией, оно формирует допустимое пространство перемещений.

Интеграция с React-компонентом KeplerGl

При использовании React-обёртки KeplerGl навигация осуществляется через Redux dispatch из внешних компонентов.

<KeplerGl
  id="map"
  mapboxApiAccessToken={token}
  width={width}
  height={height}
/>

Навигация выполняется вне компонента:

dispatch(updateMap({
  latitude: 40.7128,
  longitude: -74.0060,
  zoom: 13
}));

Такой подход разделяет:

  • визуализацию (React)
  • управление состоянием (Redux)
  • логику навигации (actions)

Камера как объект состояния

В Kepler.gl камера рассматривается как сериализуемый объект. Это позволяет:

  • сохранять текущий viewport
  • восстанавливать сессии
  • переключать пресеты видов

Пример сохранения состояния:

const savedView = store.getState().keplerGl.mapState;

И последующего восстановления:

dispatch(updateMap(savedView));

Программная навигация и временные данные

При работе с временными слоями (time filter, animation) навигация может зависеть от текущего шага времени.

Например:

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

Это достигается комбинацией visState и mapState.

Кастомные сценарии навигации

Kepler.gl допускает построение сложных сценариев, например:

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

Пример последовательной навигации:

cities.forEach((city, i) => {
  setTimeout(() => {
    dispatch(updateMap({
      latitude: city.lat,
      longitude: city.lng,
      zoom: city.zoom
    }));
  }, i * 2000);
});

Синхронизация навигации с фильтрами

Навигация часто связана с фильтрацией данных. При изменении фильтра можно автоматически пересчитывать viewport:

  • фильтр применяется к dataset
  • вычисляется новый bounding box
  • вызывается fitBounds

Так формируется динамическая карта, реагирующая на аналитические условия.

Работа с transition state

Каждый переход камеры формирует промежуточное состояние. Kepler.gl хранит параметры перехода внутри mapState, включая:

  • duration
  • easing
  • interpolation progress

Это позволяет корректно синхронизировать:

  • слои
  • tooltips
  • взаимодействие с пользователем во время анимации

Управление навигацией через middleware

В сложных приложениях навигация может быть централизована через Redux middleware:

  • перехват действий
  • вычисление новых координат
  • модификация updateMap перед dispatch

Это используется для:

  • логирования перемещений
  • ограничения геозон
  • аналитики пользовательских маршрутов
Оглавление