Работа с различными форматами времени

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

В основе лежит механизм определения временного поля в датасете и его последующая нормализация. Kepler.gl не требует строгого единственного формата времени, но ожидает возможность однозначного преобразования значения в timestamp.

Основные поддерживаемые форматы времени

ISO 8601 строки

Наиболее универсальный формат — строки ISO 8601:

2026-06-14T12:45:00Z
2026-06-14T15:45:00+03:00
2026-06-14

Kepler.gl автоматически интерпретирует такие строки через внутренние парсеры даты JavaScript (Date.parse и расширенные утилиты). Важная особенность — корректная обработка часовых поясов.

При использовании ISO 8601:

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

UNIX timestamp (milliseconds / seconds)

Числовой формат времени — один из самых производительных для обработки:

1718369100000   // milliseconds
1718369100      // seconds (требует уточнения)

Kepler.gl предпочитает миллисекунды, так как они напрямую совместимы с Date в Jav * aScript:

new Date(1718369100000)

При работе с секундами требуется предварительное преобразование:

const ms = seconds * 1000;

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

Строковые кастомные форматы

Данные часто приходят в виде нестандартизированных строк:

14/06/2026 15:45
06-14-2026 03:45 PM
2026.06.14 15:45:00

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

import { parse } from 'date-fns';

const parsed = parse('14/06/2026 15:45', 'dd/MM/yyyy HH:mm', new Date()).getTime();

Ключевой принцип — приведение всех нестандартных форматов к timestamp до передачи в слой данных.

Определение временного поля в dataset

При загрузке данных Kepler.gl автоматически анализирует структуру таблицы и пытается определить временные колонки. Однако в продакшн-режиме предпочтительно явное указание.

Пример dataset:

const data = {
  fields: [
    { name: 'timestamp', type: 'timestamp' },
    { name: 'lat', type: 'real' },
    { name: 'lng', type: 'real' }
  ],
  rows: [
    { timestamp: 1718369100000, lat: 40.7, lng: -74.0 }
  ]
};

Тип timestamp играет ключевую роль: он включает поле в систему временной фильтрации и анимации.

Временная шкала и фильтрация

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

Фильтр задаётся через состояние слоя:

filters: [
  {
    id: 'time_filter',
    name: 'timestamp',
    type: 'timeRange',
    value: [1718000000000, 1719000000000]
  }
]

Диапазон всегда выражается в миллисекундах UNIX time.

Особенность механизма:

  • поддержка multiple filters
  • синхронизация с UI временной шкалы
  • мгновенное пересчитывание видимых точек

Анимация времени (time playback)

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

Конфигурация анимации:

const config = {
  animationConfig: {
    currentTime: 1718369100000,
    speed: 1,
    timeSteps: 100
  }
};

Здесь:

  • currentTime — текущее положение временного курсора
  • speed — скорость проигрывания
  • timeSteps — количество дискретных шагов

Анимация синхронизируется с временным фильтром, создавая эффект «движения данных во времени».

Преобразование времени при загрузке данных

При импорте CSV или JSON часто требуется этап препроцессинга.

CSV пример:

timestamp,lat,lng
14/06/2026 15:45,40.7,-74.0

Обработка перед передачей в Kepler.gl:

import Papa from 'papaparse';
import { parse } from 'date-fns';

const csv = Papa.parse(rawCSV, { header: true });

const processed = csv.data.map(row => ({
  ...row,
  timestamp: parse(row.timestamp, 'dd/MM/yyyy HH:mm', new Date()).getTime()
}));

Такая нормализация гарантирует единообразие временной шкалы независимо от источника.

Временные зоны и их влияние

Kepler.gl не хранит временные зоны как отдельную сущность, а опирается на конечное timestamp значение в UTC. Это означает:

  • все значения приводятся к UTC
  • локальное представление зависит от браузера
  • визуализация не искажает порядок событий

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

Интервальные данные и агрегация по времени

При работе с большими массивами событий используется временная агрегация:

  • биннинг по часам
  • дневные группы
  • недельные интервалы

Kepler.gl выполняет агрегацию в рамках layer processing pipeline, особенно для heatmap и point density layers.

Пример логики:

timestamp → bucket(timeInterval) → aggregation

Это позволяет уменьшить нагрузку на рендер и улучшить производительность.

Использование времени в слоях

Разные типы слоёв по-разному используют временную ось:

  • Point layer — отображение событий во времени
  • Arc layer — перемещение объектов между временными точками
  • Trip layer — непрерывные маршруты с временной интерполяцией

Trip layer особенно чувствителен к корректности временных данных:

{
  path: [
    [lng, lat, timestamp],
    [lng, lat, timestamp]
  ]
}

Здесь третья координата строго обязательна для интерполяции движения.

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

На практике чаще всего встречаются следующие проблемы:

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

Kepler.gl может визуализировать такие данные, но результаты будут искажены, особенно при анимации.

Производительность при больших временных рядах

При миллионах записей временная обработка становится критическим фактором.

Рекомендации по оптимизации:

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

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

Оглавление