KML и KMZ

CesiumJS предоставляет встроенную поддержку форматов KML и KMZ через модуль KmlDataSource, который позволяет загружать, отображать и интерактивно использовать геоданные, созданные в стандартах Keyhole Markup Language. Эти форматы широко применяются для описания геометрии, стилей, временных интервалов и сложных пространственных структур.

Архитектура загрузки KML/KMZ

В основе работы с KML в Cesium лежит объект KmlDataSource. Он выполняет разбор XML-структуры, преобразование геометрии в примитивы Cesium и привязку стилей к сущностям сцены.

Основной поток обработки включает:

  • загрузку локального или удалённого KML/KMZ файла
  • парсинг структуры документа
  • создание Entity объектов
  • применение стилей и параметров отображения
  • добавление в DataSourceCollection сцены
const viewer = new Cesium.Viewer("cesiumContainer");

const kmlDataSource = new Cesium.KmlDataSource();

viewer.dataSources.add(
  kmlDataSource.load("data/sample.kml", {
    camera: viewer.scene.camera,
    canvas: viewer.scene.canvas
  })
);

Загрузка KML и KMZ

Cesium поддерживает как текстовые KML-файлы, так и архивированные KMZ. KMZ представляет собой ZIP-архив, внутри которого находится KML и связанные ресурсы: изображения, иконки, модели.

Cesium.KmlDataSource.load("data/complex.kmz", {
  camera: viewer.scene.camera,
  canvas: viewer.scene.canvas
}).then(function (dataSource) {
  viewer.dataSources.add(dataSource);
});

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

Основные параметры загрузки

KmlDataSource.load принимает объект опций, влияющих на поведение визуализации и интерпретацию данных:

  • camera — используется для корректного позиционирования объектов относительно текущего вида
  • canvas — необходим для расчёта размеров и экранных координат
  • ellipsoid — задаёт модель Земли
  • screenOverlayContainer — контейнер для HTML-оверлеев
  • show — начальная видимость слоя
Cesium.KmlDataSource.load("data.kml", {
  camera: viewer.scene.camera,
  canvas: viewer.scene.canvas,
  clampToGround: true
});

Геометрия KML и её отображение

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

Point

Точки преобразуются в Billboard или Label.

LineString

Линии становятся Polyline.

Polygon

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

Model

3D-модели (например, COLLADA .dae) интегрируются как ModelGraphics.

Привязка к рельефу

Одной из ключевых особенностей является возможность прижатия геометрии к поверхности Земли:

Cesium.KmlDataSource.load("terrain.kml", {
  clampToGround: true
});

Это особенно важно для:

  • маршрутов
  • географических границ
  • объектов инфраструктуры

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

Стили KML

KML включает встроенную систему стилей (Style, StyleMap). Cesium интерпретирует:

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

Пример KML-стиля:

<Style id="routeStyle">
  <LineStyle>
    <color>ff0000ff</color>
    <width>4</width>
  </LineStyle>
</Style>

Cesium автоматически применяет стиль к соответствующим Entity.

ExtendedData и пользовательские свойства

ExtendedData позволяет хранить произвольные атрибуты объектов. Cesium сохраняет их в properties сущности.

<ExtendedData>
  <Data name="speed">
    <value>120</value>
  </Data>
</ExtendedData>

Доступ в Jav * aScript:

entity.properties.speed.getValue();

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

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

Временные данные и TimeSpan

KML поддерживает временные интервалы (TimeSpan, TimeStamp), которые Cesium интерпретирует как availability.

<TimeSpan>
  <begin>2024-01-01</begin>
  <end>2024-01-02</end>
</TimeSpan>

В Cesium это позволяет:

  • анимацию движения объектов
  • фильтрацию по времени
  • построение исторических сцен

NetworkLink позволяет загружать внешние KML по URL, включая обновляемые данные.

Cesium поддерживает автоматическое обновление:

<NetworkLink>
  <Link>
    <href>https://example.com/data.kml</href>
    <refreshMode>onInterval</refreshMode>
    <refreshInterval>60</refreshInterval>
  </Link>
</NetworkLink>

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

  • потоковые данные
  • обновляемые треки
  • серверные геосервисы

Работа с KMZ ресурсами

KMZ может содержать:

  • изображения для иконок
  • 3D модели
  • вложенные KML
  • стилевые ресурсы

Cesium выполняет:

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

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

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

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

После загрузки KML/KMZ доступен контроль через DataSource:

kmlDataSource.show = false;
viewer.dataSources.remove(kmlDataSource);

Также можно фильтровать сущности:

kmlDataSource.entities.values.forEach(e => {
  if (e.name === "restricted") {
    e.show = false;
  }
});

Кастомизация отображения

Cesium позволяет переопределять стили после загрузки KML:

kmlDataSource.entities.values.forEach(entity => {
  if (entity.billboard) {
    entity.billboard.scale = 1.5;
  }
});

Распространённые сценарии:

  • замена иконок
  • динамическая окраска линий
  • изменение прозрачности полигонов

Производительность при работе с KML

При больших KML/KMZ файлах возникают узкие места:

  • количество сущностей
  • сложные полигоны
  • текстуры в KMZ
  • глубина вложенности

Оптимизационные подходы:

  • упрощение геометрии
  • разделение KML на слои
  • использование clampToGround вместо 3D-экструзий
  • отключение ненужных Label

Частые ограничения формата

При интеграции KML в Cesium проявляются особенности стандарта:

  • ограниченная поддержка сложных gx: расширений
  • частичная интерпретация анимаций
  • различия в стилях между Google Earth и Cesium
  • не все элементы Tour поддерживаются

Интерактивность объектов

Каждый KML-объект становится Entity, что даёт доступ к интерактивности:

  • обработка кликов
  • всплывающие окна
  • динамическое изменение свойств
viewer.selectedEntityChanged.addEventListener(function(entity) {
  if (entity && entity.name) {
    console.log(entity.name);
  }
});

Привязка пользовательского интерфейса

KML-данные часто используются как слой поверх кастомного UI:

  • карточки объектов
  • панели атрибутов
  • фильтры по ExtendedData

Cesium предоставляет прямой доступ к свойствам без необходимости парсинга XML вручную, что упрощает интеграцию в приложения пространственного анализа.

Оглавление