Viewer и его конфигурация

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

Именно через объект Viewer обычно начинается разработка большинства приложений на CesiumJS.

Базовое создание экземпляра выглядит следующим образом:

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

После выполнения этой команды внутри HTML-элемента с идентификатором cesiumContainer будет создан полноценный интерфейс Cesium с набором стандартных инструментов управления.

Структура Viewer

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

  • Scene — трёхмерная сцена.
  • Camera — камера наблюдения.
  • Globe — глобус Земли.
  • Clock — системное время.
  • DataSourceCollection — набор источников данных.
  • EntityCollection — коллекция сущностей.
  • ScreenSpaceEventHandler — обработчик пользовательских событий.
  • CesiumWidget — базовый виджет визуализации.
  • набор стандартных UI-компонентов.

Доступ к ним осуществляется через свойства объекта:

const scene = viewer.scene;
const camera = viewer.camera;
const globe = viewer.scene.globe;
const clock = viewer.clock;

Контейнер Viewer

Первым аргументом конструктора выступает контейнер отображения.

Использование идентификатора элемента:

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

HTML:

<div id="map"></div>

Использование ссылки на DOM-элемент:

const container = document.getElementById("map");

const viewer = new Cesium.Viewer(container);

Объект конфигурации

Вторым параметром конструктора передаётся объект настроек.

Общий синтаксис:

const viewer = new Cesium.Viewer("map", {
    animation: true,
    timeline: true,
    baseLayerPicker: true
});

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

Управление интерфейсом

animation

Отображает панель управления временем и анимацией.

Включено по умолчанию:

const viewer = new Cesium.Viewer("map", {
    animation: true
});

Отключение:

const viewer = new Cesium.Viewer("map", {
    animation: false
});

После отключения исчезает блок управления временем в левом нижнем углу.

timeline

Управляет временной шкалой.

const viewer = new Cesium.Viewer("map", {
    timeline: false
});

Особенно полезно для статических картографических проектов, где работа со временем не требуется.

fullscreenButton

Кнопка перехода в полноэкранный режим.

const viewer = new Cesium.Viewer("map", {
    fullscreenButton: false
});

geocoder

Строка поиска объектов на карте.

Включение:

const viewer = new Cesium.Viewer("map", {
    geocoder: true
});

Отключение:

const viewer = new Cesium.Viewer("map", {
    geocoder: false
});

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

homeButton

Кнопка возврата к начальному виду камеры.

const viewer = new Cesium.Viewer("map", {
    homeButton: false
});

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

sceneModePicker

Переключатель режимов отображения:

  • 3D
  • 2D
  • Columbus View

Отключение:

const viewer = new Cesium.Viewer("map", {
    sceneModePicker: false
});

Кнопка справки по управлению.

const viewer = new Cesium.Viewer("map", {
    navigationHelpButton: false
});

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

infoBox

Информационное окно сущностей.

const viewer = new Cesium.Viewer("map", {
    infoBox: false
});

Если объект содержит описание (description), окно отображать его не будет.

selectionIndicator

Индикатор выбора объекта.

const viewer = new Cesium.Viewer("map", {
    selectionIndicator: false
});

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

vrButton

Кнопка перехода в VR-режим.

const viewer = new Cesium.Viewer("map", {
    vrButton: true
});

Используется значительно реже остальных элементов интерфейса.

Настройка слоёв карты

baseLayerPicker

Панель выбора базовых карт.

Стандартный вариант:

const viewer = new Cesium.Viewer("map", {
    baseLayerPicker: true
});

Отключение:

const viewer = new Cesium.Viewer("map", {
    baseLayerPicker: false
});

При отключении пользователь теряет возможность менять подложку через интерфейс.

Создание собственной базовой карты

Вместо стандартного набора карт можно сразу задать собственный слой.

Например, OpenStreetMap:

const viewer = new Cesium.Viewer("map", {
    baseLayerPicker: false,
    imageryProvider: new Cesium.OpenStreetMapImageryProvider({
        url: "https://tile.openstreetmap.org/"
    })
});

imageryProvider

Позволяет указать источник картографических изображений.

Пример с OSM:

const viewer = new Cesium.Viewer("map", {
    imageryProvider: new Cesium.OpenStreetMapImageryProvider()
});

Пример с Tile Map Service:

const viewer = new Cesium.Viewer("map", {
    imageryProvider: new Cesium.TileMapServiceImageryProvider({
        url: "./tiles"
    })
});

terrainProvider

Подключение рельефа местности.

Без рельефа используется эллипсоидальная поверхность Земли.

Подключение глобального terrain:

const viewer = new Cesium.Viewer("map", {
    terrainProvider: await Cesium.createWorldTerrainAsync()
});

После активации становятся доступны:

  • горы;
  • холмы;
  • ущелья;
  • реалистичные высоты поверхности.

Начальный режим сцены

sceneMode

Определяет стартовый режим отображения.

Трёхмерный режим:

sceneMode: Cesium.SceneMode.SCENE3D

Двумерный режим:

sceneMode: Cesium.SceneMode.SCENE2D

Режим Columbus View:

sceneMode: Cesium.SceneMode.COLUMBUS_VIEW

Полный пример:

const viewer = new Cesium.Viewer("map", {
    sceneMode: Cesium.SceneMode.SCENE2D
});

Настройка времени

shouldAnimate

Автоматическое движение времени после запуска.

const viewer = new Cesium.Viewer("map", {
    shouldAnimate: true
});

Без этой настройки часы остаются остановленными.

clockViewModel

Передача собственной модели времени.

const clock = new Cesium.Clock();

const viewer = new Cesium.Viewer("map", {
    clockViewModel: new Cesium.ClockViewModel(clock)
});

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

Производительность

requestRenderMode

Один из наиболее важных параметров оптимизации.

Стандартно Cesium выполняет рендеринг непрерывно:

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

В режиме событийной отрисовки:

const viewer = new Cesium.Viewer("map", {
    requestRenderMode: true
});

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

  • движение камеры;
  • изменение объектов;
  • обновление времени;
  • ручной вызов рендеринга.

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

viewer.scene.requestRender();

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

maximumRenderTimeChange

Используется совместно с requestRenderMode.

const viewer = new Cesium.Viewer("map", {
    requestRenderMode: true,
    maximumRenderTimeChange: Infinity
});

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

Настройка контекста WebGL

contextOptions

Позволяет передавать параметры WebGL.

Пример:

const viewer = new Cesium.Viewer("map", {
    contextOptions: {
        webgl: {
            alpha: true,
            antialias: true,
            preserveDrawingBuffer: true
        }
    }
});

Наиболее часто используются параметры:

Параметр Назначение
alpha прозрачный фон
antialias сглаживание
stencil буфер трафарета
depth буфер глубины
preserveDrawingBuffer сохранение кадра

Управление небесными объектами

После создания Viewer можно управлять содержимым сцены.

Отключение неба:

viewer.scene.skyBox.show = false;

Отключение атмосферы:

viewer.scene.skyAtmosphere.show = false;

Отключение солнца:

viewer.scene.sun.show = false;

Отключение луны:

viewer.scene.moon.show = false;

Формирование полностью нейтральной сцены:

viewer.scene.skyBox.show = false;
viewer.scene.skyAtmosphere.show = false;
viewer.scene.sun.show = false;
viewer.scene.moon.show = false;

Настройка глобуса

Отключение глобуса

Иногда требуется визуализация объектов без отображения Земли.

viewer.scene.globe.show = false;

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

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

Цвет базовой поверхности

viewer.scene.globe.baseColor = Cesium.Color.BLACK;

Пример белой поверхности:

viewer.scene.globe.baseColor = Cesium.Color.WHITE;

Освещение рельефа

viewer.scene.globe.enableLighting = true;

После включения положение солнца начинает влиять на освещение поверхности.

Управление камерой через Viewer

Камера доступна напрямую:

const camera = viewer.camera;

Переход к координатам:

viewer.camera.flyTo({
    destination: Cesium.Cartesian3.fromDegrees(
        37.6176,
        55.7558,
        5000
    )
});

Мгновенное перемещение:

viewer.camera.setView({
    destination: Cesium.Cartesian3.fromDegrees(
        37.6176,
        55.7558,
        5000
    )
});

Минималистичная конфигурация Viewer

Для профессиональных корпоративных ГИС-интерфейсов часто используется максимально облегчённая конфигурация:

const viewer = new Cesium.Viewer("map", {
    animation: false,
    timeline: false,
    geocoder: false,
    homeButton: false,
    sceneModePicker: false,
    navigationHelpButton: false,
    baseLayerPicker: false,
    fullscreenButton: false,
    infoBox: false,
    selectionIndicator: false,
    requestRenderMode: true,
    terrainProvider: await Cesium.createWorldTerrainAsync()
});

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

Полная конфигурация Viewer

Пример комплексной настройки большого приложения:

const viewer = new Cesium.Viewer("map", {
    animation: true,
    timeline: true,
    geocoder: true,
    homeButton: true,
    sceneModePicker: true,
    navigationHelpButton: true,
    baseLayerPicker: false,
    fullscreenButton: true,
    infoBox: true,
    selectionIndicator: true,
    shouldAnimate: true,
    requestRenderMode: true,
    maximumRenderTimeChange: Infinity,

    terrainProvider: await Cesium.createWorldTerrainAsync(),

    imageryProvider: new Cesium.OpenStreetMapImageryProvider(),

    contextOptions: {
        webgl: {
            antialias: true,
            alpha: true
        }
    }
});

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

Оглавление