Создание первого приложения

Первое приложение на базе CesiumJS обычно решает несколько базовых задач:

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

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

Подготовка проекта

CesiumJS может использоваться несколькими способами:

  • через CDN;
  • через npm;
  • в составе проектов на Vite;
  • в проектах на Webpack;
  • в приложениях на React, Vue или Angular.

Для знакомства с библиотекой наиболее простым вариантом является использование npm и современного сборщика.

Установка пакета:

npm install cesium

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

project/
│
├── src/
│   ├── main.js
│   └── style.css
│
├── public/
│
├── package.json
└── vite.config.js

Подключение CesiumJS

В основном файле приложения выполняется импорт библиотеки:

import * as Cesium from "cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

Первый импорт предоставляет доступ ко всем классам движка.

Второй импорт подключает стили пользовательского интерфейса:

  • панели навигации;
  • кнопки управления;
  • временную шкалу;
  • элементы анимации;
  • другие встроенные виджеты.

Без подключения CSS многие элементы будут отображаться некорректно.

Подготовка HTML-контейнера

Cesium отрисовывает сцену внутри указанного HTML-элемента.

Пример разметки:

<div id="cesiumContainer"></div>

Контейнер должен иметь размеры.

Пример CSS:

html,
body,
#cesiumContainer {
    width: 100%;
    height: 100%;
    margin: 0;
    padding: 0;
    overflow: hidden;
}

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

Создание объекта Viewer

Основой любого приложения является класс Viewer.

Минимальный пример:

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

После выполнения этой строки происходит:

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

Результатом становится интерактивная трёхмерная модель Земли.

Что входит в Viewer

Класс Viewer представляет собой высокоуровневую оболочку над большим количеством подсистем.

В его состав входят:

Компонент Назначение
Scene Трёхмерная сцена
Camera Управление камерой
Globe Отображение планеты
Clock Работа со временем
EntityCollection Коллекция объектов
DataSourceCollection Источники данных
ImageryLayers Картографические слои

Через объект viewer осуществляется доступ практически ко всем возможностям движка.

Например:

viewer.scene
viewer.camera
viewer.clock
viewer.entities
viewer.imageryLayers

Настройка интерфейса

По умолчанию Cesium создаёт большое количество виджетов.

Можно управлять их отображением.

Пример:

const viewer = new Cesium.Viewer("cesiumContainer", {
    animation: false,
    timeline: false,
    fullscreenButton: false,
    vrButton: false,
    geocoder: false
});

Параметры отвечают за следующие элементы:

Параметр Назначение
animation Панель анимации
timeline Временная шкала
geocoder Поиск объектов
homeButton Кнопка возврата
sceneModePicker Выбор режима сцены
navigationHelpButton Справка
fullscreenButton Полноэкранный режим
vrButton Режим виртуальной реальности

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

Управление режимами отображения

Cesium поддерживает несколько способов визуализации планеты.

3D-режим

Полноценная трёхмерная Земля:

sceneMode: Cesium.SceneMode.SCENE3D

2D-режим

Плоская карта:

sceneMode: Cesium.SceneMode.SCENE2D

Columbus View

Промежуточный режим:

sceneMode: Cesium.SceneMode.COLUMBUS_VIEW

Пример:

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

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

После запуска приложения камера автоматически располагается над Землёй.

Для перемещения используется метод:

viewer.camera.flyTo();

Пример перелёта:

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

Параметры:

  • долгота;
  • широта;
  • высота.

В данном случае камера перемещается к Москве на высоту 10 километров.

Координаты в CesiumJS

Большая часть API работает с географическими координатами.

Формат:

долгота,
широта,
высота

Создание позиции:

const position =
    Cesium.Cartesian3.fromDegrees(
        37.6176,
        55.7558,
        0
    );

Важно помнить, что порядок отличается от привычного формата:

широта, долгота

Используемого во многих геоинформационных системах.

Добавление первой точки

Коллекция сущностей находится в:

viewer.entities

Создание точки:

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(
        37.6176,
        55.7558
    ),
    point: {
        pixelSize: 12,
        color: Cesium.Color.RED
    }
});

После добавления объект автоматически отображается на карте.

Добавление подписи

Точка часто сопровождается текстом.

Пример:

viewer.entities.add({
    position: Cesium.Cartesian3.fromDegrees(
        37.6176,
        55.7558
    ),
    point: {
        pixelSize: 10,
        color: Cesium.Color.RED
    },
    label: {
        text: "Москва",
        font: "18px sans-serif"
    }
});

Теперь рядом с точкой отображается надпись.

Масштабирование к объекту

После добавления сущности удобно автоматически перемещать камеру.

Для этого используется:

viewer.zoomTo(
    viewer.entities
);

Либо:

viewer.flyTo(
    viewer.entities
);

Разница заключается в том, что flyTo() выполняет плавную анимацию, а zoomTo() осуществляет быстрое позиционирование.

Управление глобусом

Объект глобуса доступен через:

viewer.scene.globe

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

viewer.scene.skyAtmosphere.show = false;

Пример скрытия глобуса:

viewer.scene.globe.show = false;

Пример отключения освещения:

viewer.scene.globe.enableLighting = false;

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

Работа с базовыми слоями

Основой отображения являются картографические изображения.

Cesium использует систему Imagery Layers.

Получение коллекции слоёв:

const layers =
    viewer.imageryLayers;

Добавление нового слоя:

layers.addImageryProvider(
    new Cesium.OpenStreetMapImageryProvider()
);

После загрузки слой автоматически накладывается на поверхность Земли.

Изменение начального положения камеры

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

Пример:

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

В отличие от flyTo(), метод setView() выполняется мгновенно.

Управление анимацией перелёта

Продолжительность перелёта задаётся через параметр duration.

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

В данном случае анимация займёт пять секунд.

Работа с цветами

Cesium содержит встроенный набор цветов.

Примеры:

Cesium.Color.RED
Cesium.Color.BLUE
Cesium.Color.GREEN
Cesium.Color.YELLOW
Cesium.Color.ORANGE

Создание собственного цвета:

const color =
    Cesium.Color.fromCssColorString(
        "#4CAF50"
    );

Использование прозрачности:

Cesium.Color.RED.withAlpha(0.5)

Значение находится в диапазоне:

0.0 – полностью прозрачно
1.0 – полностью непрозрачно

Получение доступа к сцене

Сцена является центральным объектом рендеринга.

Получение ссылки:

const scene =
    viewer.scene;

Через неё доступны:

  • освещение;
  • туман;
  • атмосфера;
  • режимы рендеринга;
  • постобработка;
  • низкоуровневые возможности WebGL.

Пример:

scene.fog.enabled = false;

Полный пример первого приложения

import * as Cesium from "cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

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

viewer.entities.add({
    position:
        Cesium.Cartesian3.fromDegrees(
            37.6176,
            55.7558
        ),
    point: {
        pixelSize: 12,
        color: Cesium.Color.RED
    },
    label: {
        text: "Москва",
        font: "18px sans-serif"
    }
});

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

После запуска приложение выполняет следующие действия:

  1. создаёт трёхмерную сцену;
  2. отображает глобус Земли;
  3. добавляет точку на карте;
  4. отображает подпись объекта;
  5. выполняет автоматический перелёт камеры к выбранному месту.

Типичные ошибки при создании первого приложения

Отсутствует высота контейнера

Ошибка:

#cesiumContainer {
    width: 100%;
}

Результат:

Пустая страница

Решение:

#cesiumContainer {
    width: 100%;
    height: 100%;
}

Неверный порядок координат

Ошибка:

Cesium.Cartesian3.fromDegrees(
    55.7558,
    37.6176
);

Результат:

Объект оказывается в другой точке мира

Правильно:

Cesium.Cartesian3.fromDegrees(
    37.6176,
    55.7558
);

Не подключены стили виджетов

Ошибка:

import * as Cesium from "cesium";

Результат:

Интерфейс отображается некорректно

Правильно:

import * as Cesium from "cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

Неверный идентификатор контейнера

Ошибка:

new Cesium.Viewer("map");

При наличии:

<div id="cesiumContainer"></div>

Результат:

Контейнер не найден

Правильно:

new Cesium.Viewer("cesiumContainer");

Базовая структура дальнейшего развития приложения

После создания минимального проекта обычно добавляются:

  • маркеры и сущности;
  • геометрические примитивы;
  • 3D-модели формата glTF;
  • тайловые наборы 3D Tiles;
  • пользовательские слои карт;
  • обработчики событий мыши;
  • инструменты измерения расстояний;
  • маршруты движения объектов;
  • временные анимации;
  • пространственный анализ данных.

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

Оглавление