Настройка временного диапазона

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

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

Подготовка временного поля в датасете

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

Поддерживаются два основных формата:

  • UNIX timestamp (рекомендуется)
  • ISO 8601 строка (преобразуется в timestamp при загрузке)

Пример структуры записи:

const data = [
  {
    id: 1,
    lat: 40.7128,
    lng: -74.0060,
    timestamp: 1697040000000
  },
  {
    id: 2,
    lat: 40.7138,
    lng: -74.0010,
    timestamp: 1697043600000
  }
];

При работе с CSV или GeoJSON важно обеспечить единообразие временного поля, иначе фильтрация будет работать некорректно или частично.

Привязка временного поля к слою

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

Пример слоя:

const layer = {
  id: 'points',
  type: 'point',
  config: {
    dataId: 'my_dataset',
    columns: {
      lat: 'lat',
      lng: 'lng',
      altitude: null
    }
  }
};

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

Система фильтров и временной диапазон

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

Основная структура временного фильтра:

const filter = {
  id: 'time_filter',
  dataId: ['my_dataset'],
  name: 'timestamp',
  type: 'timeRange',
  value: [1697040000000, 1697047200000],
  enlarged: true,
  plotType: 'histogram',
  animationWindow: 'free'
};

Основные параметры:

  • value — текущий активный диапазон времени
  • name — поле датасета
  • type — тип фильтра (timeRange)
  • animationWindow — способ интерпретации окна анимации

Управление диапазоном через действия (actions)

Kepler.gl построен на Redux-архитектуре, поэтому изменение временного диапазона выполняется через dispatch действий.

Наиболее важное действие:

import { addFilter, setFilter } from 'kepler.gl/actions';

Добавление временного фильтра:

dispatch(addFilter({
  dataId: 'my_dataset',
  name: 'timestamp',
  type: 'timeRange',
  value: [1697040000000, 1697047200000]
}));

Изменение диапазона:

dispatch(setFilter('time_filter', {
  value: [1697043600000, 1697049000000]
}));

Обновление фильтра напрямую влияет на все слои, привязанные к соответствующему dataset.

Анимация временного диапазона

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

Основные параметры анимации:

  • текущая позиция времени
  • шаг обновления
  • скорость воспроизведения
  • режим окна (full или free)

Пример конфигурации:

const filter = {
  id: 'time_filter',
  type: 'timeRange',
  name: 'timestamp',
  value: [1697040000000, 1697040000000 + 3600000],
  animationWindow: 'incremental',
  speed: 1
};

Логика поведения:

  • animationWindow: 'incremental' — окно движется вместе с временем
  • animationWindow: 'full' — фиксированный диапазон, меняется только позиция указателя

Связь временного диапазона с визуализацией слоёв

Каждый слой Kepler.gl пересчитывается при изменении фильтра. Это означает, что временной диапазон фактически влияет на геометрическое состояние слоя.

Особенно это заметно в слоях:

  • Point Layer
  • Line Layer
  • Heatmap Layer
  • Arc Layer

При изменении времени происходит:

  • перерасчёт видимых объектов
  • пересборка агрегаций (heatmap)
  • обновление траекторий (lines/arcs)

Множественные временные фильтры

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

Пример:

const filters = [
  {
    id: 'time_filter_1',
    dataId: ['dataset_1'],
    name: 'timestamp',
    type: 'timeRange',
    value: [1697040000000, 1697043600000]
  },
  {
    id: 'time_filter_2',
    dataId: ['dataset_2'],
    name: 'event_time',
    type: 'timeRange',
    value: [1697030000000, 1697050000000]
  }
];

Такой подход позволяет синхронизировать разные источники данных по независимым временным шкалам.

Типичные ошибки при работе с временным диапазоном

Некорректная работа временной фильтрации чаще всего связана с:

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

Особенно критична ошибка, когда timestamp передаётся в секундах, тогда как Kepler.gl ожидает миллисекунды, что приводит к визуально «пустой» карте.

Производительность при изменении диапазона

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

Основные факторы влияния:

  • количество объектов в датасете
  • число активных слоёв
  • сложность агрегации (heatmap, grid)
  • частота обновления анимации

Оптимизация достигается через:

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

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

Kepler.gl можно интегрировать с внешним UI или приложением, где временной диапазон управляется отдельно от карты.

Типичный сценарий:

function updateTimeRange(start, end) {
  dispatch(setFilter('time_filter', {
    value: [start, end]
  }));
}

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

Оглавление