DataSource API

DataSource API в CesiumJS представляет собой слой абстракции, который отделяет источники пространственных данных от механизма их визуализации на глобусе. Эта система позволяет унифицировать работу с различными форматами геоданных, предоставляя единый интерфейс для загрузки, обновления и управления сущностями сцены.

Основная идея заключается в том, что любые данные — GeoJSON, CZML, KML или пользовательские структуры — приводятся к модели Entity, после чего могут быть отрисованы через единый механизм рендеринга сцены.

Базовая концепция DataSource

Каждый DataSource в CesiumJS реализует интерфейс, который включает:

  • коллекцию entities
  • методы load и update
  • событие changedEvent
  • флаг isLoading

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

const dataSource = new Cesium.GeoJsonDataSource();
viewer.dataSources.add(dataSource);

dataSource.load("data.geojson");

В этом примере источник данных загружается асинхронно, а все объекты автоматически преобразуются в Entity.

DataSourceCollection и интеграция с Viewer

Контейнером всех источников данных выступает DataSourceCollection, доступный через viewer.dataSources.

const viewer = new Cesium.Viewer("cesiumContainer");

viewer.dataSources.add(new Cesium.CzmlDataSource());
viewer.dataSources.add(new Cesium.KmlDataSource());

Каждый добавленный DataSource:

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

Удаление DataSource полностью очищает связанные сущности:

viewer.dataSources.remove(dataSource, true);

Entity-модель как результат DataSource

Вся логика DataSource сводится к созданию объектов Entity. Это универсальная модель, включающая:

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

Пример структуры Entity:

const entity = new Cesium.Entity({
    id: "unique-id",
    position: Cesium.Cartesian3.fromDegrees(30, 50),
    point: {
        pixelSize: 10,
        color: Cesium.Color.RED
    }
});

DataSource автоматически управляет созданием таких сущностей на основе входных данных.

GeoJsonDataSource

GeoJSON является одним из наиболее часто используемых форматов в CesiumJS. GeoJsonDataSource преобразует геометрии в объекты Entity.

const geoJsonSource = new Cesium.GeoJsonDataSource();

geoJsonSource.load("cities.geojson", {
    clampToGround: true
});

viewer.dataSources.add(geoJsonSource);

Особенности:

  • поддержка Point, LineString, Polygon
  • автоматическое назначение стилей
  • возможность привязки к поверхности земли
  • поддержка свойства properties

Каждый feature GeoJSON становится отдельным Entity с набором атрибутов.

CzmlDataSource и временные данные

CZML — формат, ориентированный на динамические сцены и временные зависимости. CzmlDataSource используется для потоковой анимации объектов.

const czmlSource = new Cesium.CzmlDataSource();

viewer.dataSources.add(czmlSource);
czmlSource.load("flight.czml");

Ключевая особенность — поддержка времени:

  • перемещение объектов по траектории
  • изменение свойств во времени
  • синхронизация с Clock сцены

CZML тесно связан с системой JulianDate в CesiumJS.

KmlDataSource и интеграция с геоэкосистемой

KmlDataSource обеспечивает поддержку формата KML, используемого в геоинформационных системах.

const kmlSource = new Cesium.KmlDataSource();

viewer.dataSources.add(kmlSource);

kmlSource.load("regions.kml", {
    camera: viewer.scene.camera,
    canvas: viewer.scene.canvas
});

Особенности:

  • поддержка папок и иерархий
  • стилизация через KML Style
  • работа с NetworkLink
  • поддержка изображений и описаний

Асинхронная модель загрузки

Все DataSource работают асинхронно. Метод load возвращает Promise:

geoJsonSource.load("data.geojson")
    .then(function(dataSource) {
        console.log("Загружено:", dataSource.entities.values.length);
    })
    .catch(function(error) {
        console.error(error);
    });

Это позволяет:

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

Обновление и жизненный цикл DataSource

Каждый DataSource проходит через несколько стадий:

  1. создание экземпляра
  2. регистрация в DataSourceCollection
  3. асинхронная загрузка данных
  4. генерация Entity
  5. участие в рендере
  6. обновление при изменении времени сцены

Метод update вызывается на каждом кадре:

dataSource.update(time);

Он используется для:

  • анимации объектов
  • пересчёта позиций
  • синхронизации временных интервалов

Custom DataSource

Пользовательский DataSource позволяет полностью контролировать генерацию сущностей.

function CustomDataSource() {
    this.entities = new Cesium.EntityCollection();
    this.changedEvent = new Cesium.Event();
    this.isLoading = false;
}

CustomDataSource.prototype.load = function() {
    this.isLoading = true;

    const entity = new Cesium.Entity({
        position: Cesium.Cartesian3.fromDegrees(40, 55),
        point: {
            pixelSize: 12,
            color: Cesium.Color.BLUE
        }
    });

    this.entities.add(entity);
    this.isLoading = false;

    this.changedEvent.raiseEvent(this);
};

Такой подход используется для:

  • интеграции с REST API
  • потоковых данных
  • IoT-источников
  • собственных форматов

Свойства Entity и их реактивность

DataSource активно использует реактивную модель Entity:

  • изменение свойства автоматически обновляет визуализацию
  • не требуется ручной перерисовки
  • поддерживается Property система Cesium

Пример динамического изменения:

entity.point.color = Cesium.Color.YELLOW;

Или через property:

entity.position = new Cesium.SampledPositionProperty();

Кластеризация объектов

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

geoJsonSource.clustering.enabled = true;
geoJsonSource.clustering.pixelRange = 50;
geoJsonSource.clustering.minimumClusterSize = 3;

Кластеризация:

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

Стилизация DataSource

Каждый DataSource поддерживает глобальную стилизацию через EntityStyle:

geoJsonSource.entities.values.forEach(function(entity) {
    entity.point.color = Cesium.Color.ORANGE;
    entity.point.outlineColor = Cesium.Color.BLACK;
});

Дополнительно можно использовать ColorMaterialProperty, LabelStyle, HeightReference.

Временная синхронизация

DataSource тесно интегрирован с системой времени Cesium:

  • viewer.clock
  • JulianDate
  • TimeIntervalCollection

Это позволяет строить:

  • маршруты движения
  • исторические реконструкции
  • прогнозные модели

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

При работе с DataSource важно учитывать:

  • количество Entity напрямую влияет на FPS
  • KML может быть тяжелее GeoJSON
  • CZML требует постоянного обновления
  • clustering снижает нагрузку

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

  • использование batch-данных
  • ограничение видимых объектов
  • отключение неиспользуемых DataSource
  • упрощение геометрии

Обработка событий DataSource

Каждый DataSource предоставляет события:

dataSource.changedEvent.addEventListener(function() {
    console.log("DataSource изменился");
});

Также доступны:

  • errorEvent
  • loadingEvent

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

Интеграция с Cesium Ion

В экосистеме Cesium DataSource часто используется совместно с облачной платформой Cesium ion, которая предоставляет:

  • оптимизацию 3D-тайлов
  • хранение данных
  • потоковую доставку ресурсов

DataSource может загружать данные напрямую из ion assets, включая tilesets и геометрии.

Расширенные сценарии использования

DataSource API применяется в системах:

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

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

Оглавление