mapState

mapState — один из центральных разделов внутреннего состояния Kepler.gl, отвечающий за параметры отображения карты. В этом объекте хранится информация о текущем положении камеры, масштабе, угле поворота, наклоне, стиле базовой карты и множестве других параметров, определяющих визуальное представление геоданных.

С точки зрения архитектуры Kepler.gl, mapState представляет собой часть Redux-хранилища, которая описывает текущее состояние карты независимо от наборов данных, слоёв или фильтров.

Упрощённо структура выглядит следующим образом:

{
  mapState: {
    latitude: 37.7749,
    longitude: -122.4194,
    zoom: 10,
    bearing: 0,
    pitch: 0
  }
}

Каждое изменение положения карты приводит к обновлению соответствующих полей внутри этого объекта.

Назначение mapState

Объект mapState решает несколько задач:

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

Без mapState невозможно корректно воспроизвести текущее состояние визуализации.

Основная структура mapState

Типичная структура выглядит следующим образом:

{
  mapState: {
    bearing: 0,
    dragRotate: false,
    isSplit: false,
    latitude: 37.7749,
    longitude: -122.4194,
    pitch: 0,
    zoom: 9,
    maxZoom: 20,
    minZoom: 0,
    transitionDuration: 0
  }
}

В зависимости от версии библиотеки могут присутствовать дополнительные параметры.

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

Основу состояния карты составляют два поля:

latitude
longitude

Пример:

{
  latitude: 55.7558,
  longitude: 37.6176
}

В данном случае центр карты расположен над Москвой.

При перемещении карты мышью или через программный интерфейс эти значения автоматически обновляются.

Поле zoom

Параметр zoom определяет масштаб отображения.

Пример:

{
  zoom: 3
}

Такой уровень подходит для отображения континентов.

Большие значения позволяют приблизиться к отдельным объектам:

{
  zoom: 15
}

На этом масштабе уже видны улицы и отдельные здания.

Типичный диапазон:

0–20

При этом допустимые границы определяются параметрами:

minZoom
maxZoom

Например:

{
  minZoom: 2,
  maxZoom: 18
}

Поле bearing

bearing отвечает за вращение карты вокруг вертикальной оси.

Пример:

{
  bearing: 0
}

Север находится сверху.

Поворот на 90 градусов:

{
  bearing: 90
}

Поворот на 180 градусов:

{
  bearing: 180
}

Поворот особенно полезен при анализе транспортных маршрутов и трёхмерных сцен.

Поле pitch

Параметр pitch определяет угол наклона камеры.

Без наклона:

{
  pitch: 0
}

Трёхмерный вид:

{
  pitch: 45
}

Более выраженная перспектива:

{
  pitch: 60
}

Высокие значения активно используются при работе с:

  • 3D-столбцами;
  • экструзиями полигонов;
  • зданиями;
  • визуализацией плотности населения;
  • транспортными потоками.

Ограничения масштаба

Для предотвращения слишком сильного приближения используются поля:

{
  minZoom: 1,
  maxZoom: 16
}

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

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

Управление вращением

Поле:

dragRotate

определяет возможность вращения карты мышью.

Разрешено:

{
  dragRotate: true
}

Запрещено:

{
  dragRotate: false
}

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

Разделение экрана

Параметр:

isSplit

указывает, используется ли режим сравнения карт.

Пример:

{
  isSplit: true
}

В этом режиме отображаются две синхронизированные карты.

Такая функциональность применяется для:

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

Переходы камеры

Kepler.gl поддерживает плавное перемещение между позициями карты.

Для этого используются параметры:

{
  transitionDuration: 1000
}

Значение задаётся в миллисекундах.

Одна секунда:

1000

Две секунды:

2000

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

Программное изменение положения карты

Изменение состояния возможно через Redux-действия.

Пример обновления центра карты:

dispatch({
  type: 'UPDATE_MAP',
  payload: {
    latitude: 48.8566,
    longitude: 2.3522,
    zoom: 11
  }
});

После выполнения действия карта переместится к Парижу.

Синхронизация с внешними компонентами

Поскольку mapState находится в Redux-хранилище, любые React-компоненты могут получать актуальное состояние карты.

Пример:

const mapState = useSelector(
  state => state.keplerGl.map.mapState
);

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

const {
  latitude,
  longitude,
  zoom
} = mapState;

Далее данные могут использоваться для:

  • отображения текущих координат;
  • загрузки внешних данных;
  • построения аналитики;
  • выполнения пространственных запросов.

Автоматическое определение области просмотра

После загрузки набора данных Kepler.gl способен самостоятельно вычислить подходящую область отображения.

В результате обновляются:

{
  latitude,
  longitude,
  zoom
}

Центр и масштаб подбираются таким образом, чтобы все объекты оказались в зоне видимости.

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

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

При экспорте конфигурации состояние карты сохраняется внутри раздела:

config.mapState

Пример:

{
  config: {
    mapState: {
      latitude: 40.7128,
      longitude: -74.0060,
      zoom: 10,
      bearing: 0,
      pitch: 0
    }
  }
}

После повторной загрузки проекта карта откроется в том же положении.

Это обеспечивает воспроизводимость визуализаций.

mapState и сохранение сессий

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

{
  visState,
  mapState,
  mapStyle,
  uiState
}

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

Связь mapState и mapStyle

Важно различать два независимых объекта.

mapState

Отвечает за положение камеры:

{
  latitude,
  longitude,
  zoom,
  pitch,
  bearing
}

mapStyle

Отвечает за внешний вид карты:

{
  styleType: 'dark'
}

Изменение стиля не влияет на координаты карты.

Изменение координат не влияет на выбранный стиль.

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

Во многих проектах состояние карты используется как источник пространственного контекста.

Пример получения текущих координат:

const {
  latitude,
  longitude,
  zoom
} = mapState;

Затем могут выполняться запросы:

fetch(
  `/api/objects?lat=${latitude}&lng=${longitude}`
);

Таким образом загружаются данные только для текущей области просмотра.

Это значительно снижает объём передаваемой информации.

Использование в режиме реального времени

При отображении телеметрии, GPS-треков и потоковых данных mapState позволяет автоматически следовать за объектом.

Пример обновления координат:

dispatch({
  type: 'UPDATE_MAP',
  payload: {
    latitude: vehicle.lat,
    longitude: vehicle.lng
  }
});

Карта будет перемещаться вслед за транспортным средством.

Подобный подход применяется в системах:

  • мониторинга транспорта;
  • диспетчеризации;
  • логистики;
  • отслеживания судов;
  • авиационного мониторинга.

Типичные ошибки при работе с mapState

Неверный диапазон координат

Широта должна находиться в диапазоне:

-90 ... 90

Долгота:

-180 ... 180

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

Слишком большой масштаб

Например:

{
  zoom: 50
}

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

Отрицательный масштаб

{
  zoom: -10
}

Следует использовать ограничения через:

minZoom

Чрезмерный наклон

{
  pitch: 89
}

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

Практический пример полного состояния карты

const mapState = {
  latitude: 51.5074,
  longitude: -0.1278,
  zoom: 12,
  bearing: 25,
  pitch: 45,
  minZoom: 1,
  maxZoom: 20,
  dragRotate: true,
  isSplit: false,
  transitionDuration: 1000
};

Данная конфигурация создаёт трёхмерный вид Лондона с умеренным наклоном камеры, разрешённым вращением карты и плавной анимацией переходов.

Роль mapState в архитектуре Kepler.gl

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

Оглавление