Описания и метаданные

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

Метаданные в CesiumJS представляют собой набор именованных свойств, привязанных к объектам сцены. Эти свойства могут быть:

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

Базовая идея заключается в том, что визуальный объект отделён от описательных данных. Геометрия отвечает за форму, а метаданные — за смысл.

В рамках API метаданные чаще всего реализуются через систему свойств (Property system), где каждое свойство может возвращать значение в зависимости от времени сцены.

Entity API и описательные свойства

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

  • name — человекочитаемое имя
  • description — HTML/строковое описание
  • properties — произвольный набор пользовательских атрибутов

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

const entity = viewer.entities.add({
  name: "Станция наблюдения",
  description: "Объект мониторинга окружающей среды",
});

Поле description часто используется как контейнер для HTML-разметки, что позволяет формировать интерактивные информационные панели при выборе объекта.

Динамические описания

Описание может быть связано с временными данными:

entity.description = new Cesium.CallbackProperty(() => {
  return `Температура: ${sensor.value} °C`;
}, false);

Такая модель позволяет связывать визуализацию с потоковыми данными, например телеметрией или IoT-сенсорами.

Система Property и типы значений

В основе метаданных CesiumJS лежит интерфейс Property. Он определяет контракт:

  • getValue(time) — получение значения
  • isConstant — признак неизменности

Основные реализации:

ConstantProperty

Фиксированное значение.

position: new Cesium.ConstantProperty(Cesium.Cartesian3.fromDegrees(30, 60))

SampledProperty

Набор дискретных значений во времени с интерполяцией.

const property = new Cesium.SampledProperty(Number);

property.addSample(time1, 10);
property.addSample(time2, 20);

CompositeProperty

Комбинация нескольких свойств, применяемых по времени.

CallbackProperty

Функция вычисления значения в реальном времени.

Метаданные примитивов и геометрий

Низкоуровневые объекты (Primitives) не имеют встроенной Entity-модели, но могут хранить пользовательские данные через:

  • attributes
  • custom uniforms
  • feature tables (в 3D Tiles)
  • metadata на уровне вершин или экземпляров

Пример хранения пользовательского атрибута:

primitive.customData = {
  id: 42,
  type: "radar"
};

Такие данные используются при picking (выборе объекта) и аналитике сцены.

Метаданные в 3D Tiles

Особенно мощная система метаданных реализована в Cesium ion и 3D Tiles. Каждый тайл или feature может содержать структурированные свойства:

  • batchId
  • feature table properties
  • metadata semantics (height, name, category)
  • бинарные таблицы свойств

При выборе объекта:

const picked = viewer.scene.pick(position);
const height = picked.getProperty("height");

Метаданные доступны напрямую через API Feature.

Семантика и типизация свойств

3D Tiles поддерживает строгую семантику:

  • POSITION
  • RGB
  • HEIGHT
  • NAME

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

  • Scalar (числа)
  • Vector (векторы)
  • String
  • Boolean
  • Arrays

Типизация важна для корректной интерпретации в шейдерах и UI.

Свойство description в 3D Tiles Features

Feature может содержать собственное описание:

feature.getProperty("name");
feature.getProperty("description");

Эти значения часто приходят из tileset.json или бинарных таблиц.

HTML-описания и UI-интеграция

Описание Entity может содержать HTML:

description: `
  <h3>Объект</h3>
  <p>Уровень сигнала: высокий</p>
`

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

Динамические метаданные и время

Ключевая особенность системы — зависимость от времени сцены:

viewer.clock.currentTime

Любое Property может учитывать текущий момент времени, что позволяет моделировать:

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

Пример:

position: new Cesium.SampledProperty(Cesium.Cartesian3)

Metadata в GeoJSON и CZML

При загрузке данных из форматов высокого уровня метаданные сохраняются автоматически.

GeoJSON

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

Каждый feature получает properties из JSON-атрибутов.

CZML

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

{
  "id": "satellite",
  "position": {
    "epoch": "2020-01-01T00:00:00Z",
    "cartesian": [0,0,0, 10,0,0]
  }
}

Пользовательские свойства (Custom Properties)

Entity поддерживает произвольные поля:

entity.properties = new Cesium.PropertyBag({
  id: 101,
  category: "sensor",
  status: "active"
});

Доступ к ним:

entity.properties.id.getValue(time);

PropertyBag позволяет хранить сложные структуры, сохраняя совместимость с системой времени.

Picking и извлечение метаданных

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

const pickedObject = viewer.scene.pick(clickPosition);

if (pickedObject) {
  console.log(pickedObject.id?.name);
}

В зависимости от уровня объекта доступ могут предоставлять:

  • Entity
  • Primitive
  • Feature
  • Tile

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

Стиль и метаданные

Метаданные часто используются в стилях (особенно 3D Tiles styling):

tileset.style = new Cesium.Cesium3DTileStyle({
  color: "color('red')",
});

Условные выражения могут опираться на свойства:

color: "(${height} > 1000) ? color('red') : color('green')"

Таким образом метаданные становятся основой визуальной семантики.

Производные и вычисляемые данные

CesiumJS позволяет строить производные свойства:

  • скорость из координат
  • направление движения
  • классификация объектов
  • агрегированные показатели

Эти вычисления часто реализуются через CallbackProperty или внешние модели данных, интегрированные в Entity.

Роль метаданных в архитектуре сцены

Метаданные формируют второй слой сцены:

  • геометрический слой (форма)
  • семантический слой (смысл)

Именно второй слой делает возможными:

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

Без этой системы 3D-сцена остаётся статической визуализацией без контекста.

Оглавление