Концепция Entity

CesiumJS строится вокруг высокоуровневой модели представления объектов на глобусе через сущности (Entity). Entity является центральной абстракцией, объединяющей геометрическое представление, визуальные свойства и временную изменчивость в единую структуру.

Entity как унифицированная модель пространственного объекта

Entity представляет собой логическое описание объекта в сцене, не завязанное на конкретный способ рендеринга. Вместо прямого управления графическими примитивами (Primitive API), Entity инкапсулирует:

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

Ключевая особенность Entity — декларативный подход: описывается «что существует», а не «как это рисуется».

Entity и Property-система

В основе Entity лежит система свойств (Property). Почти любое поле Entity может быть либо статическим значением, либо вычисляемым во времени объектом.

Типичная структура:

  • ConstantProperty — фиксированное значение
  • SampledProperty — набор значений по времени
  • TimeIntervalCollectionProperty — интервальные значения
  • CallbackProperty — вычисление в рантайме

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

Пример временной координаты:

position: new Cesium.SampledPositionProperty()

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

EntityCollection как контейнер сущностей

Entity редко используется изолированно. Основная структура хранения — EntityCollection, представляющая собой реактивный набор объектов.

Особенности коллекции:

  • автоматическое обновление сцены при изменениях
  • привязка к viewer.entities
  • поддержка событий добавления и удаления
  • интеграция с механизмом выбора (picking)

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

Геометрические компоненты Entity

Entity может содержать несколько типов визуальных примитивов одновременно:

  • PointGraphics — точечные объекты
  • BillboardGraphics — спрайты и иконки
  • LabelGraphics — текстовые метки
  • PolylineGraphics — линии и маршруты
  • PolygonGraphics — полигоны и области
  • ModelGraphics — 3D-модели glTF

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

Пример:

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(30, 50),
    point: {
        pixelSize: 10,
        color: Cesium.Color.RED
    }
});

Динамические свойства и временные интервалы

Одной из ключевых возможностей Entity является поддержка временной оси (JulianDate). Любое свойство может зависеть от времени.

Наиболее важные типы:

  • PositionProperty — движение объекта
  • ColorProperty — изменение цвета
  • PropertyBag — набор динамических атрибутов

Пример движения объекта:

const property = new Cesium.SampledPositionProperty();

property.addSample(
    Cesium.JulianDate.fromIso8601("2026-01-01T00:00:00Z"),
    Cesium.Cartesian3.fromDegrees(30, 50)
);

property.addSample(
    Cesium.JulianDate.fromIso8601("2026-01-01T01:00:00Z"),
    Cesium.Cartesian3.fromDegrees(31, 51)
);

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

DataSource и автоматическое создание Entity

Entity часто создаются не вручную, а через DataSource API:

  • GeoJSONDataSource
  • CzmlDataSource
  • KmlDataSource

DataSource преобразуют внешние форматы в набор Entity, сохраняя семантику данных.

Например, CZML напрямую отображает временные изменения свойств через Entity, что делает его естественным форматом для анимаций.

CZML и связь с Entity

CZML (Cesium Language) представляет собой JSON-подобный формат, ориентированный на описание динамических сцен.

Каждый пакет CZML фактически описывает Entity:

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

Entity в CesiumJS выступает как runtime-реализация CZML-модели.

Производительность и уровень абстракции

Entity является высокоуровневой абстракцией, что влияет на производительность:

  • удобство разработки выше, чем у Primitive API
  • накладные расходы на Property-систему
  • динамические свойства требуют пересчётов
  • большое количество Entity может снижать FPS

Для высоконагруженных сцен применяется гибридный подход: Entity для логики, Primitive для рендера.

Взаимодействие Entity с Viewer

Viewer интегрирует Entity через встроенную коллекцию:

viewer.entities.add(...)

Взаимодействие включает:

  • автоматический рендер
  • управление выделением (selection)
  • интеграцию с camera flyTo
  • обработку событий мыши

Entity становится частью глобальной сцены без дополнительной конфигурации рендера.

Семантическая модель Entity

Entity несёт не только визуальную, но и смысловую нагрузку. Каждая сущность может содержать:

  • id
  • name
  • description
  • произвольные пользовательские свойства

Эти данные используются для:

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

Entity превращает 3D-сцену в семантически насыщенную модель данных.

Событийная модель Entity

Entity поддерживает реакцию на изменения через Property observers и EntityCollection events.

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

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

Это позволяет строить реактивные геопространственные приложения.

Роль Entity в архитектуре CesiumJS

Entity занимает промежуточный уровень между низкоуровневым рендерингом и прикладной логикой:

  • Primitive API — геометрия и GPU-оптимизация
  • Entity API — модель данных и динамика
  • DataSource API — импорт внешних форматов

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

Оглавление