addDataToMap

Функция addDataToMap является ключевым механизмом интеграции данных в Kepler.gl и служит центральной точкой взаимодействия между приложением и визуализационным состоянием карты. Именно через неё происходит добавление, обновление и связывание геопространственных наборов данных с визуальными слоями, фильтрами и конфигурацией карты.

Общая концепция работы addDataToMap

Kepler.gl построен на архитектуре Redux-подобного состояния, где все изменения карты происходят через диспатч экшенов. addDataToMap представляет собой action creator, который формирует структурированный объект действия для добавления данных.

Основная задача:

  • передать набор данных (datasets) в Kepler.gl
  • обновить состояние карты
  • синхронизировать слои и фильтры
  • инициировать перерасчёт визуализаций

Сигнатура и структура вызова

Базовая форма вызова выглядит следующим образом:

addDataToMap({
  datasets: [...],
  options: {
    centerMap: true,
    readOnly: false
  },
  config: {
    mapState: {},
    mapStyle: {}
  }
});

Ключевые компоненты:

  • datasets — массив данных, передаваемых в карту
  • options — параметры поведения при загрузке
  • config — начальная конфигурация состояния карты

Структура datasets

Каждый элемент массива datasets представляет собой объект, содержащий данные и метаданные:

{
  info: {
    id: 'my_dataset',
    label: 'Dataset Label'
  },
  data: {
    fields: [...],
    rows: [...]
  }
}

Поле info

Содержит метаданные:

  • id — уникальный идентификатор набора данных
  • label — отображаемое имя слоя данных

Поле data

Содержит фактические данные:

  • fields — описание столбцов (имя, тип, формат)
  • rows — строки данных (массив значений)

Пример:

fields: [
  { name: 'lat', type: 'real' },
  { name: 'lng', type: 'real' }
],
rows: [
  [55.75, 37.61],
  [59.93, 30.31]
]

Параметр options

Объект options управляет поведением карты при добавлении данных.

centerMap

centerMap: true

При значении true карта автоматически центрируется и масштабируется под загруженные данные. Это особенно важно при первом добавлении данных, когда текущий viewport не задан.

readOnly

readOnly: false

Определяет, можно ли пользователю изменять визуализацию после загрузки данных:

  • true — блокирует изменения слоёв и фильтров
  • false — разрешает интерактивное редактирование

Конфигурация config

Параметр config позволяет задать начальное состояние карты. Он используется для восстановления сохранённых сессий или предустановленных визуализаций.

mapState

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

mapState: {
  latitude: 55.75,
  longitude: 37.61,
  zoom: 10
}

Основные свойства:

  • latitude — широта центра карты
  • longitude — долгота центра карты
  • zoom — уровень масштабирования

mapStyle

Определяет визуальный стиль карты:

mapStyle: {
  styleType: 'dark',
  visibleLayerGroups: {
    label: true,
    road: true,
    border: false
  }
}

Механизм обработки действия

После вызова addDataToMap происходит последовательность внутренних операций:

  1. Создание action объекта
  2. Передача его в Redux store
  3. Обновление datasets в состоянии kepler.gl
  4. Генерация слоёв на основе структуры данных
  5. Применение фильтров (если заданы)
  6. Пересчёт viewport при необходимости
  7. Перерисовка WebGL сцены

Взаимодействие с слоями (layers)

При добавлении данных Kepler.gl автоматически создаёт базовые слои в зависимости от структуры данных.

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

  • Point Layer — при наличии координат lat/lng
  • Arc Layer — при наличии пар координат
  • Heatmap Layer — при плотных распределениях точек
  • Grid Layer — при агрегируемых данных

Добавление через addDataToMap может быть дополнено пользовательской конфигурацией слоёв через config.visState.layers.

Работа с несколькими наборами данных

Kepler.gl поддерживает одновременную загрузку нескольких datasets:

addDataToMap({
  datasets: [
    datasetA,
    datasetB
  ]
});

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

  • каждый dataset получает уникальный идентификатор
  • слои группируются по источнику данных
  • фильтры могут применяться локально или глобально
  • возможно связывание данных через join-поля

Обновление данных через addDataToMap

Повторный вызов addDataToMap с тем же id приводит к обновлению существующего набора данных.

Поведение:

  • старые данные заменяются новыми
  • слои пересоздаются при изменении структуры
  • фильтры сбрасываются, если изменены поля
  • viewport может быть пересчитан при centerMap: true

Типизация данных и производительность

Kepler.gl чувствителен к структуре данных. Для оптимальной производительности важно:

  • использовать плоские массивы rows
  • избегать вложенных объектов
  • минимизировать количество полей
  • предварительно очищать данные от null-значений

Особенно важно при больших наборах:

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

Интеграция с Redux store

В Redux-архитектуре Kepler.gl addDataToMap диспатчится следующим образом:

dispatch(addDataToMap({
  datasets,
  options
}));

После диспатча данные попадают в:

  • keplerGl.map.datasets
  • keplerGl.map.visState
  • keplerGl.map.mapState

Связь с состоянием visState

visState является центральным узлом визуализации:

После вызова addDataToMap обновляются:

  • layers
  • filters
  • interactionConfig
  • animationConfig

Каждый dataset становится источником для формирования визуальных объектов.

Обработка ошибок и некорректных данных

При некорректной структуре данных поведение Kepler.gl зависит от типа ошибки:

  • отсутствуют fields → dataset игнорируется
  • отсутствуют rows → слой не создаётся
  • несовпадение типов → фильтры работают некорректно
  • отсутствуют координаты → spatial layer не генерируется

Ошибки не всегда приводят к исключению, чаще происходит деградация визуализации.

Расширенные сценарии использования

Предзагрузка конфигурации карты

addDataToMap({
  datasets,
  config: savedMapConfig
});

Используется для восстановления состояния приложения.

Динамическое обновление данных

При потоковых данных (real-time):

  • вызывается addDataToMap с обновлённым dataset
  • сохраняется тот же id
  • визуализация обновляется без перезагрузки карты

Связывание нескольких источников

При наличии нескольких datasets возможно создание аналитических связей через:

  • join keys
  • фильтры по общим полям
  • синхронизацию слоёв

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

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

  • данные попадают в систему
  • формируется граф слоёв
  • инициализируется визуальное состояние
  • активируется WebGL pipeline
  • связываются фильтры и взаимодействия

Без addDataToMap Kepler.gl остаётся пустым визуальным контейнером без источника данных.

Оглавление