API методы

Kepler.gl представляет собой высокоуровневую библиотеку для визуализации геоданных, построенную поверх React и Redux. Архитектура построена вокруг централизованного состояния карты и набора action-методов, через которые выполняются все операции: загрузка данных, управление слоями, фильтрами, взаимодействиями и стилями отображения.

Основной принцип API заключается в том, что любое изменение карты проходит через единый поток действий (actions), которые диспатчатся в Redux store. Это обеспечивает предсказуемость состояния и упрощает интеграцию с внешними приложениями.

С точки зрения API выделяются следующие уровни:

  • React-компонент KeplerGl
  • Redux actions (основной API управления)
  • selectors (чтение состояния)
  • конфигурация (mapState, visState, uiState)

React-компонент KeplerGl

Базовой точкой входа является компонент:

  • KeplerGl

Компонент принимает следующие ключевые параметры:

  • id — уникальный идентификатор инстанса карты
  • width, height — размеры контейнера
  • mapboxApiAccessToken — токен Mapbox
  • data — начальные данные (опционально)
  • theme — тема оформления (light/dark)
  • appState — начальное состояние UI и карты
  • onStateChange — callback для отслеживания изменений состояния

Компонент не содержит бизнес-логики, а полностью делегирует её Redux-слою.

Redux Actions как основной API

addDataToMap

Ключевой метод загрузки данных в визуализацию.

Назначение:

  • добавление датасета
  • автоматическое создание слоя (если включено)
  • генерация базовой конфигурации отображения

Сигнатура (концептуально):

  • datasets: массив объектов с данными

  • options:

    • centerMap: центрирование карты
    • readOnly: запрет редактирования слоя
    • keepExistingConfig: сохранение текущих слоёв

Поведение:

  • создаётся dataset в visState.datasets
  • генерируется layerConfig
  • обновляются фильтры при необходимости

addDataToMapFlow

Упрощённый вариант добавления данных с автоматической обработкой пайплайна.

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

  • динамической загрузки CSV/JSON
  • потоковой интеграции данных

Особенность:

  • включает стадии parsing → normalization → mapping → rendering

removeDataset

Удаление датасета из состояния.

Последствия:

  • удаляются связанные слои
  • очищаются фильтры
  • пересчитывается bounding box карты

Важно:

  • операция необратима без сохранения предыдущего состояния

renameDataset

Позволяет изменить идентификатор или имя датасета.

Влияет на:

  • ссылки в слоях
  • фильтры
  • tooltips

Управление картой (Map State API)

updateMap

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

Позволяет изменять:

  • центр карты (latitude, longitude)
  • масштаб (zoom)
  • угол наклона (bearing)
  • наклон камеры (pitch)

Поведение:

  • изменения применяются мгновенно
  • поддерживается анимация переходов при включённых transitions

fitBounds

Автоматическая подгонка карты под границы данных.

Вход:

  • bounding box (min/max координаты)
  • padding

Результат:

  • центрирование карты
  • корректировка zoom уровня

Используется после:

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

togglePerspective

Переключение между 2D и 3D режимами.

Влияние:

  • изменение pitch
  • активация 3D слоёв (hexagon, grid)

Управление слоями (Layers API)

updateLayerConfig

Основной метод изменения слоя.

Позволяет модифицировать:

  • тип слоя (point, line, arc, heatmap)
  • визуальные параметры (цвет, радиус, высота)
  • данные (dataId, columns)

Механизм:

  • происходит перегенерация layer instance
  • триггерится rerender WebGL слоя

addLayer

Добавление нового слоя к существующей визуализации.

Параметры:

  • type
  • config
  • dataId

Особенность:

  • слой добавляется в конец стека отрисовки
  • влияет на z-index визуализации

removeLayer

Удаление слоя по идентификатору.

Последствия:

  • пересборка pipeline рендеринга
  • освобождение GPU ресурсов слоя

duplicateLayer

Создание копии слоя с сохранением всех параметров.

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

  • A/B визуализации
  • сравнения разных фильтров
  • тестирования параметров

Фильтрация данных (Filters API)

addFilter

Создание нового фильтра для датасета.

Типы фильтров:

  • time filter
  • range filter
  • select filter

Параметры:

  • dataId
  • field
  • domain
  • value

updateFilter

Изменение текущего фильтра.

Операции:

  • изменение диапазона
  • изменение выбранных значений
  • переключение режима инклюзивности

removeFilter

Удаление фильтра и пересчёт отображаемых данных.

Эффект:

  • обновление всех слоёв, зависящих от фильтра
  • пересчёт статистики датасета

Взаимодействие (Interaction API)

updateInteractionConfig

Контроль интерактивности карты:

  • включение tooltip
  • hover events
  • click events
  • brush selection

Конфигурация позволяет управлять:

  • реакцией слоёв на события
  • отображением всплывающих окон

setInteraction

Более низкоуровневый метод, управляющий поведением событийной модели.

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

  • отключения взаимодействий
  • настройки кастомных обработчиков

UI State API

toggleModal

Управление модальными окнами интерфейса:

  • легенда
  • настройки слоя
  • импорт данных

updateVisData

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

Особенность:

  • оптимизированный rerender
  • сохраняются слои и фильтры

Конфигурационный API

exportToJson

Сериализация полного состояния карты.

Включает:

  • visState
  • mapState
  • uiState

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

  • сохранения проекта
  • передачи состояния между приложениями

loadMap

Загрузка ранее сохранённой конфигурации.

Этапы:

  • восстановление datasets
  • восстановление layers
  • восстановление filters
  • восстановление map viewport

updateMapConfig

Обновление глобальной конфигурации визуализации:

  • theme
  • style
  • animation settings
  • interaction defaults

Селекторы состояния

Kepler.gl предоставляет доступ к состоянию через selectors:

  • getMapState
  • getVisState
  • getUIState
  • getDataset

Особенности:

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

Асинхронные потоки данных

Некоторые методы API поддерживают асинхронный режим:

  • загрузка больших CSV/GeoJSON
  • потоковая агрегация данных
  • WebWorker parsing

Внутренний pipeline:

  1. ingestion
  2. parsing
  3. normalization
  4. schema inference
  5. layer generation
  6. render dispatch

Взаимодействие API с WebGL-рендерингом

Все изменения через API транслируются в Deck.gl слой рендеринга. Это приводит к:

  • перерасчёту геометрии
  • обновлению GPU buffers
  • оптимизации draw calls

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

Оглавление