EntityCollection

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

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

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

  • в Viewer через viewer.entities
  • внутри DataSource как основной механизм хранения сущностей
  • в пользовательских слоях для ручного управления объектами

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

Основные операции с коллекцией

EntityCollection предоставляет базовый набор операций CRUD, оптимизированных для работы в реальном времени.

Добавление объектов

Добавление выполняется через метод add:

const entity = viewer.entities.add({
    id: "point-1",
    position: Cesium.Cartesian3.fromDegrees(37.6173, 55.7558),
    point: {
        pixelSize: 10,
        color: Cesium.Color.RED
    }
});

При добавлении происходит:

  • регистрация Entity в коллекции
  • создание реактивных привязок свойств
  • постановка на рендеринг в следующем кадре
  • включение в систему picking (выделения)

Удаление объектов

Удаление осуществляется через remove или removeAll:

viewer.entities.remove(entity);
viewer.entities.removeAll();

Удаление приводит к:

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

Доступ к элементам коллекции

EntityCollection поддерживает несколько способов доступа:

По идентификатору

const entity = viewer.entities.getById("point-1");

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

Перебор коллекции

viewer.entities.values.forEach(e => {
    console.log(e.id);
});

Коллекция предоставляет массив values, содержащий все Entity в порядке добавления.

Наблюдение за изменениями

EntityCollection поддерживает события, позволяющие отслеживать изменения состава коллекции:

  • collectionChanged — изменение состава (добавление/удаление)
  • реактивные обновления свойств Entity

Пример обработки изменений:

viewer.entities.collectionChanged.addEventListener((collection, added, removed) => {
    console.log("Добавлено:", added.length);
    console.log("Удалено:", removed.length);
});

События позволяют строить синхронизацию с внешними источниками данных и UI-системами.

Свойства коллекции

EntityCollection содержит набор управляющих параметров:

show

Глобальное управление видимостью всех объектов:

viewer.entities.show = false;

При отключении:

  • объекты остаются в памяти
  • рендеринг прекращается
  • состояние объектов сохраняется

извлечение массива значений

const allEntities = viewer.entities.values;

Возвращает живую коллекцию, отражающую текущее состояние.

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

EntityCollection тесно связана с DataSource API. Каждый DataSource содержит собственную EntityCollection.

Основные отличия:

  • EntityCollection — низкоуровневый контейнер
  • DataSource — логический слой данных (CZML, GeoJSON, custom sources)
  • Viewer.entities — глобальная коллекция сцены

При подключении DataSource:

viewer.dataSources.add(Cesium.GeoJsonDataSource.load(url));

внутри создаётся отдельная EntityCollection, синхронизированная с источником данных.

Реактивные свойства Entity внутри коллекции

EntityCollection обеспечивает реактивность всех свойств Entity:

const entity = viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(0, 0),
    point: { pixelSize: 5 }
});

entity.point.pixelSize = 20;

Изменение свойства приводит к немедленному обновлению сцены без повторного добавления объекта.

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

EntityCollection оптимизирована под работу с большим количеством объектов, однако существуют ограничения:

  • большое число Entity увеличивает нагрузку на scene graph
  • динамические изменения вызывают перерасчёт отрисовки
  • сложные callback-свойства могут снижать FPS

Для оптимизации применяются:

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

Клонирование и временные коллекции

EntityCollection может использоваться для создания временных наборов объектов:

const tempCollection = new Cesium.EntityCollection();

tempCollection.add(new Cesium.Entity({
    position: Cesium.Cartesian3.fromDegrees(10, 10)
}));

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

Идентификаторы и жизненный цикл Entity

ID играет ключевую роль в управлении коллекцией:

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

При отсутствии ID Cesium генерирует внутренний идентификатор, что усложняет последующий доступ.

Вложенные структуры и композиция объектов

EntityCollection поддерживает сложные композиции через вложенные Entity:

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

Пример:

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(30, 30),
    ellipse: {
        semiMinorAxis: 1000,
        semiMajorAxis: 2000,
        material: Cesium.Color.BLUE.withAlpha(0.5)
    },
    label: {
        text: "Zone"
    }
});

Один Entity может содержать несколько визуальных компонентов, управляемых как единое целое внутри коллекции.

Работа с временными данными

EntityCollection активно используется в сценариях с временной динамикой:

  • перемещение объектов по времени
  • изменение стилей в зависимости от timeline
  • интерполяция координат

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

Ограничения модели EntityCollection

Несмотря на гибкость, модель имеет ограничения:

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

Для высоконагруженных сценариев применяются альтернативы:

  • Primitive API
  • Cesium 3D Tiles
  • custom spatial indexing

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

EntityCollection интегрирована с системой picking:

  • каждый Entity участвует в ray-casting
  • поддерживается выбор объектов мышью
  • события клика привязываются к Entity

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

Оглавление