Расширение функциональности

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

Внутренняя структура Kepler.gl разделена на несколько ключевых слоёв:

  • состояние приложения (Redux store)
  • слой визуализации (deck.gl layers)
  • UI-слой (React компоненты)
  • слой конфигурации (mapState, visState, uiState)

Расширение функциональности происходит не через модификацию ядра, а через подключение к этим слоям. Такой подход позволяет внедрять новые возможности без форка библиотеки.

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

Расширение через кастомные слои визуализации

Наиболее мощный механизм расширения — добавление пользовательских слоёв поверх deck.gl.

Kepler.gl поддерживает регистрацию новых типов слоёв через расширение конфигурации layerClasses. Это позволяет внедрять собственные WebGL-слои или адаптировать существующие.

Пример подключения кастомного слоя:

import KeplerGl from 'kepler.gl';
import { Layer } from '@deck.gl/core';

class CustomScatterLayer extends Layer {
  initializeState() {
    this.getAttributeManager().addInstanced({
      positions: { size: 3, accessor: 'getPosition' }
    });
  }

  draw({ uniforms }) {
    // WebGL рендеринг логики слоя
  }
}

Далее слой регистрируется в конфигурации:

const customLayers = {
  custom_scatter: CustomScatterLayer
};

<KeplerGl
  id="map"
  width={800}
  height={600}
  layers={customLayers}
/>

Расширение через слои используется для:

  • визуализации нестандартных геометрий
  • интеграции потоковых данных (WebSocket, Kafka)
  • построения специализированных аналитических слоёв (heatmap с кастомной логикой)
  • отрисовки GPU-ускоренных индикаторов

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

В основе Kepler.gl лежит централизованное состояние. Оно разбито на:

  • visState — данные слоёв, фильтров и взаимодействий
  • mapState — позиция камеры и параметры карты
  • uiState — интерфейс

Расширение через Redux позволяет внедрять бизнес-логику без изменения UI.

Подключение кастомного reducer:

import keplerGlReducer from 'kepler.gl/reducers';

const customizedReducer = keplerGlReducer.initialState({
  uiState: {
    readOnly: false
  }
});

Дополнительные действия можно внедрять через middleware:

const customMiddleware = store => next => action => {
  if (action.type === 'LAYER_CLICK') {
    console.log('Layer clicked:', action);
  }
  return next(action);
};

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

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

Расширение через кастомные actions

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

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

export const CUSTOM_FILTER_UPDATE = 'CUSTOM_FILTER_UPDATE';

export function updateCustomFilter(payload) {
  return {
    type: CUSTOM_FILTER_UPDATE,
    payload
  };
}

Reducer расширяется:

function customReducer(state, action) {
  switch (action.type) {
    case CUSTOM_FILTER_UPDATE:
      return {
        ...state,
        customFilter: action.payload
      };
    default:
      return state;
  }
}

Использование такого подхода особенно важно при:

  • интеграции с внешними API аналитики
  • реализации доменных фильтров поверх стандартных
  • построении multi-tenant систем

Модификация UI-слоя

UI Kepler.gl построен на React-компонентах и может быть переопределён через injection-механизмы.

Основные точки расширения:

  • панели слоёв
  • фильтры
  • тулбары
  • модальные окна
  • инспектор данных

Пример замены панели фильтров:

import {injectComponents} from 'kepler.gl/components';

const CustomFilterPanel = () => (
  <div>
    <h3>Custom Filters</h3>
  </div>
);

const KeplerGlWithCustomUI = injectComponents([
  [FilterPanelFactory, CustomFilterPanel]
])(KeplerGl);

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

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

Расширение через visState и динамическую модификацию данных

visState — центральный объект, управляющий слоями и визуализацией.

Его можно расширять программно:

dispatch(
  addDataToMap({
    datasets: {
      info: { label: 'Custom Data' },
      data: geojsonData
    },
    options: {
      centerMap: true
    }
  })
);

Расширенные сценарии:

  • потоковая подача данных (real-time ingestion)
  • агрегация данных на клиенте
  • динамическое переключение источников
  • мультислойные аналитические представления

Интеграция внешних источников данных

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

Пример адаптера:

async function fetchFromApi(url) {
  const res = await fetch(url);
  const json = await res.json();

  return {
    fields: Object.keys(json[0]),
    rows: json.map(Object.values)
  };
}

После адаптации данные подаются в Kepler.gl как стандартный dataset.

Использование:

  • REST API аналитических систем
  • GIS-серверы
  • потоковые источники
  • IoT телеметрия

Расширение фильтров и аналитических операторов

Фильтрация в Kepler.gl реализована как часть visState, но может быть расширена через пользовательские вычисления.

Пример кастомной логики фильтрации:

function customFilter(data, threshold) {
  return data.filter(row => row.value > threshold);
}

Интеграция в pipeline:

  • предобработка перед загрузкой
  • постобработка через middleware
  • вычисляемые поля в runtime

Расширение фильтров применяется для:

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

Расширение взаимодействия с картой

Kepler.gl позволяет перехватывать события взаимодействия:

  • click
  • hover
  • drag
  • zoom

Через middleware или кастомные handlers можно расширить поведение:

map.onCl ick = (info) => {
  dispatch({
    type: 'FEATURE_SELECTED',
    payload: info.object
  });
};

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

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

Подключение плагинной архитектуры

Хотя Kepler.gl не имеет классической plugin API, расширение реализуется через композицию:

  • кастомные reducers
  • injectComponents
  • расширенные layers
  • middleware цепочки

Типовая схема плагина:

export function createKeplerPlugin() {
  return {
    reducer: customReducer,
    components: customComponents,
    layers: customLayers,
    middleware: customMiddleware
  };
}

Далее интеграция:

const store = createStore(
  combineReducers({
    keplerGl: keplerGlReducer,
    custom: customReducer
  }),
  applyMiddleware(customMiddleware)
);

Расширение через синхронизацию состояния

Одной из ключевых возможностей является синхронизация состояния карты с URL или внешними системами.

Пример сериализации:

const state = store.getState().keplerGl;
const encoded = btoa(JSON.stringify(state.visState));

Использование:

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

Встраивание в сложные приложения

Kepler.gl часто используется как часть более крупных систем:

  • аналитические панели
  • геоинформационные платформы
  • системы мониторинга

Расширение в таких сценариях включает:

  • изоляцию store
  • проксирование actions
  • разделение UI слоёв
  • интеграцию с внешними системами авторизации

Работа с кастомными форматами визуализации

Помимо стандартных GeoJSON и таблиц, расширение возможно через предварительную трансформацию данных.

Пример трансформации:

function normalizeData(raw) {
  return raw.map(item => ({
    lat: item.coordinates[0],
    lng: item.coordinates[1],
    value: item.metric
  }));
}

Такая нормализация позволяет:

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

Оптимизация расширений

Расширение функциональности требует учёта производительности WebGL-рендеринга deck.gl.

Ключевые ограничения:

  • количество инстансов в слоях
  • частота пересчёта state
  • объём передаваемых данных
  • сложность кастомных шейдеров

Оптимизационные практики:

  • мемоизация вычисляемых данных
  • батчинг обновлений через Redux
  • использование WebGL buffer reuse
  • ограничение rerender циклов

Безопасное расширение состояния

Расширение Redux-слоя требует строгого разделения ответственности:

  • Kepler.gl state остаётся неизменяемым ядром
  • кастомные данные хранятся отдельно
  • интеграция происходит через selectors

Пример селектора:

const selectCustomData = state => state.customModule.data;

Такой подход снижает риск конфликтов при обновлениях библиотеки и упрощает поддержку крупных систем на основе Kepler.gl.

Оглавление