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

Библиотека Kepler.gl построена поверх React и Redux и ориентирована на визуализацию больших геопространственных наборов данных. Основная интеграция осуществляется через React-компонент KeplerGl, который связывается с глобальным состоянием приложения.

Установка выполняется через менеджер пакетов:

npm install kepler.gl react-map-gl mapbox-gl

Для корректной работы требуется подключение стилей Mapbox:

import 'mapbox-gl/dist/mapbox-gl.css';

Также необходимо подключение редьюсера библиотеки в Redux-хранилище, поскольку Kepler.gl хранит состояние карты (слои, фильтры, данные) в глобальном сторе.

Подготовка Redux-хранилища

Архитектура Kepler.gl опирается на единый store. Базовая интеграция требует добавления редьюсера:

import { createStore, combineReducers, applyMiddleware } from 'redux';
import keplerGlReducer from 'kepler.gl/reducers';

const reducers = combineReducers({
  keplerGl: keplerGlReducer
});

const store = createStore(reducers);

Состояние keplerGl становится центральной точкой управления картой. В него записываются:

  • наборы данных (datasets)
  • слои визуализации (layers)
  • состояние камеры (viewState)
  • фильтры и интерактивные параметры

Подключение компонента карты

Компонент KeplerGl размещается внутри React-приложения и получает идентификатор инстанса. Этот идентификатор используется для изоляции нескольких карт.

import KeplerGl from 'kepler.gl';

function MapContainer() {
  return (
    <KeplerGl
      id="geo-map"
      width={800}
      height={600}
    />
  );
}

Ключевой момент: id связывает компонент с соответствующей частью Redux-структуры state.keplerGl.geo-map.

Формат данных для первой карты

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

Минимально допустимый формат:

const sampleData = {
  fields: [
    { name: 'lat', type: 'real' },
    { name: 'lng', type: 'real' }
  ],
  rows: [
    [55.751244, 37.618423],
    [59.931058, 30.360909]
  ]
};

Обязательные требования:

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

Добавление набора данных в карту

Данные передаются через action addDataToMap. Этот механизм синхронизирует dataset с Redux-состоянием и автоматически инициирует отрисовку слоя.

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

store.dispatch(
  addDataToMap({
    datasets: {
      info: {
        label: 'Cities',
        id: 'cities'
      },
      data: sampleData
    }
  })
);

После выполнения действия система автоматически:

  • создаёт слой визуализации
  • определяет тип отображения
  • обновляет viewState при необходимости

Управление состоянием карты

Состояние карты включает три ключевых блока:

viewState

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

viewState: {
  latitude: 55.751244,
  longitude: 37.618423,
  zoom: 5,
  bearing: 0,
  pitch: 0
}

Особенность: изменение zoom и координат влияет только на текущий инстанс карты.

layers

Слои определяют способ визуализации данных:

  • точечные (PointLayer)
  • тепловые (HeatmapLayer)
  • линии (LineLayer)
  • полигоны (PolygonLayer)

Каждый слой конфигурируется отдельно и привязывается к dataset.

filters

Фильтры позволяют ограничивать отображаемые данные по диапазонам значений:

  • числовые диапазоны
  • временные интервалы
  • категориальные значения

Фильтрация выполняется на уровне GPU-рендеринга, что обеспечивает высокую производительность.

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

Хотя Kepler.gl автоматически генерирует слой, возможна ручная настройка:

import { layers } from 'kepler.gl';

const pointLayer = new layers.PointLayer({
  dataId: 'cities',
  color: [255, 0, 0],
  columns: {
    lat: 'lat',
    lng: 'lng'
  },
  isVisible: true
});

Ключевые параметры:

  • dataId — связывает слой с dataset
  • columns — определяет географические поля
  • color — задаёт визуальное оформление

Подключение базового viewState при инициализации

Инициализация карты с заданной позицией выполняется через addDataToMap с параметром config:

store.dispatch(
  addDataToMap({
    datasets: {
      info: { id: 'cities', label: 'Cities' },
      data: sampleData
    },
    options: {
      centerMap: true,
      readOnly: false
    },
    config: {
      mapState: {
        latitude: 55.751244,
        longitude: 37.618423,
        zoom: 4
      }
    }
  })
);

Обработка множественных наборов данных

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

datasets: [
  {
    info: { id: 'cities' },
    data: citiesData
  },
  {
    info: { id: 'routes' },
    data: routesData
  }
]

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

Связь React-компонента и Redux

Компонент KeplerGl подписывается на соответствующую часть состояния через mapStateToProps:

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

Архитектурно система работает по принципу однонаправленного потока данных:

Action → Reducer → Store → Component

Базовая структура приложения

Типичная интеграция включает:

  • Redux store
  • Provider из react-redux
  • компонент KeplerGl
  • набор actions для загрузки данных
import { Provider } from 'react-redux';

function App() {
  return (
    <Provider store={store}>
      <MapContainer />
    </Provider>
  );
}

Инициализация интерактивной карты

После подключения store и компонента происходит последовательный процесс:

  1. создание instance карты
  2. регистрация dataset
  3. автоматическая генерация слоя
  4. вычисление центра карты
  5. первичный рендер WebGL

Kepler.gl использует WebGL-рендеринг, что обеспечивает обработку больших массивов координат без значительной нагрузки на CPU.

Оглавление