TimeIntervalCollectionProperty

В CesiumJS временные изменяемые свойства представляются через систему свойств (Property API), где каждое значение может зависеть от текущего времени сцены. Одним из ключевых механизмов управления такими данными является TimeIntervalCollectionProperty, позволяющий задавать набор временных интервалов, каждому из которых соответствует собственное значение свойства.

Модель временных интервалов в CesiumJS

В основе работы лежит структура временных интервалов:

  • каждый интервал задаётся началом и концом времени;
  • внутри интервала действует фиксированное значение свойства;
  • интервалы могут быть непрерывными или разрозненными;
  • значение определяется на основе текущего времени сцены (JulianDate).

Cesium использует TimeIntervalCollection как контейнер интервалов, где каждый элемент содержит:

  • start — начало интервала;
  • stop — конец интервала;
  • data — значение, связанное с интервалом.

TimeIntervalCollectionProperty: назначение

TimeIntervalCollectionProperty реализует интерфейс Property и предназначен для хранения временно-зависимых значений, не требующих интерполяции между точками, но меняющихся дискретно по времени.

Ключевые особенности:

  • хранение значений по интервалам времени;
  • выбор значения по текущему времени;
  • отсутствие обязательной интерполяции;
  • поддержка любых типов данных Cesium (цвета, числа, координаты, объекты);
  • эффективное обновление в рамках анимации времени.

Типичная область применения:

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

Создание TimeIntervalCollectionProperty

Объект создаётся через конструктор, принимающий коллекцию интервалов:

const property = new Cesium.TimeIntervalCollectionProperty(
  new Cesium.TimeIntervalCollection([
    new Cesium.TimeInterval({
      start: Cesium.JulianDate.fromIso8601("2026-01-01T00:00:00Z"),
      stop: Cesium.JulianDate.fromIso8601("2026-01-02T00:00:00Z"),
      data: Cesium.Color.RED
    }),
    new Cesium.TimeInterval({
      start: Cesium.JulianDate.fromIso8601("2026-01-02T00:00:00Z"),
      stop: Cesium.JulianDate.fromIso8601("2026-01-03T00:00:00Z"),
      data: Cesium.Color.BLUE
    })
  ])
);

В этом примере значение свойства зависит от даты:

  • 1 января — красный цвет;
  • 2 января — синий цвет.

Добавление и управление интервалами

Интервалы могут формироваться динамически:

const intervals = new Cesium.TimeIntervalCollection();

intervals.addInterval(
  new Cesium.TimeInterval({
    start: Cesium.JulianDate.fromIso8601("2026-06-01T00:00:00Z"),
    stop: Cesium.JulianDate.fromIso8601("2026-06-02T00:00:00Z"),
    data: 10
  })
);

intervals.addInterval(
  new Cesium.TimeInterval({
    start: Cesium.JulianDate.fromIso8601("2026-06-02T00:00:00Z"),
    stop: Cesium.JulianDate.fromIso8601("2026-06-03T00:00:00Z"),
    data: 20
  })
);

const property = new Cesium.TimeIntervalCollectionProperty(intervals);

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

  • addInterval(interval) — добавление нового интервала;
  • removeInterval(interval) — удаление;
  • findInterval() — поиск интервала по времени;
  • contains() — проверка принадлежности времени интервалу.

Получение значения свойства

При обращении к свойству Cesium автоматически вычисляет активный интервал:

const time = Cesium.JulianDate.now();
const value = property.getValue(time);

Алгоритм работы:

  1. определяется текущий JulianDate;
  2. выполняется поиск интервала, содержащего это время;
  3. возвращается data из найденного интервала;
  4. если интервал отсутствует — возвращается undefined.

Поведение вне интервалов

Если текущее время не попадает ни в один интервал:

  • возвращается undefined;
  • объект, использующий свойство, может скрываться или использовать значение по умолчанию;
  • визуальное состояние становится неопределённым, если не предусмотрена обработка.

Это поведение важно учитывать при построении временных сцен.

Типы поддерживаемых значений

TimeIntervalCollectionProperty не ограничивает тип данных, однако наиболее часто используются:

Цветовые значения

data: Cesium.Color.YELLOW

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

Числовые значения

data: 42

Применяется для параметров масштабирования, прозрачности, скорости.

Координаты

data: Cesium.Cartesian3.fromDegrees(30, 50, 1000)

Используется для дискретного перемещения объектов.

Сложные структуры

data: {
  speed: 10,
  direction: Cesium.Cartesian3.UNIT_X
}

Применяется для пользовательской логики, где интервал управляет состоянием объекта.

Отсутствие интерполяции

В отличие от SampledProperty, где значения плавно интерполируются, TimeIntervalCollectionProperty работает по принципу ступенчатого изменения:

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

Это делает структуру подходящей для:

  • событийных систем;
  • дискретных анимаций;
  • режимов отображения.

Совместимость с Entity API

TimeIntervalCollectionProperty часто используется внутри сущностей Cesium:

viewer.entities.add({
  position: new Cesium.TimeIntervalCollectionProperty(intervals),
  point: {
    pixelSize: 10,
    color: new Cesium.TimeIntervalCollectionProperty(colorIntervals)
  }
});

При обновлении времени сцены свойства автоматически пересчитываются.

Взаимодействие с системой времени Cesium

Основой вычислений служит Clock и Timeline Cesium:

  • текущее время обновляется через Clock.currentTime;
  • каждый кадр пересчитываются свойства объектов;
  • getValue() вызывается многократно в цикле рендеринга.

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

Особенности производительности

При большом количестве интервалов важно учитывать:

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

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

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

Сценарии применения

Наиболее характерные случаи использования:

  • отображение объектов, активных только в определённые периоды;
  • смена стиля карты в зависимости от времени суток;
  • моделирование этапов процессов (строительство, миграции, движение);
  • дискретное управление состояниями систем;
  • временные симуляции событий.

Особенности поведения при пересечении интервалов

При перекрытии интервалов:

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

Работа с ISO 8601 и JulianDate

Cesium использует JulianDate как внутреннее представление времени, однако часто применяется конвертация из ISO-формата:

Cesium.JulianDate.fromIso8601("2026-06-08T12:00:00Z")

Это обеспечивает:

  • точность временных вычислений;
  • совместимость с временными стандартами;
  • удобство задания интервалов.

Поведение в анимации сцены

При включённой анимации:

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

Интеграция с пользовательскими свойствами

Допускается создание собственных логических структур внутри data:

data: {
  visible: true,
  intensity: 0.8,
  label: "active"
}

В этом случае внешний код интерпретирует данные интервала самостоятельно, используя текущее значение как состояние.

Отличие от SampledProperty и ConstantProperty

  • ConstantProperty — фиксированное значение без зависимости от времени;
  • SampledProperty — непрерывная интерполяция между точками;
  • TimeIntervalCollectionProperty — дискретные состояния по временным диапазонам.

Эта тройка формирует базовую модель временных данных CesiumJS.

Оглавление