CZML формат

CZML (Cesium Language) представляет собой JSON-подобный формат описания временных и пространственных сцен, используемый в экосистеме CesiumJS для потоковой передачи и декларативного описания 3D-данных.

CZML-документ представляет собой массив объектов, называемых пакетами (packets). Каждый пакет описывает отдельный объект сцены или его состояние во времени.

Базовая форма:

[
  {
    "id": "document",
    "version": "1.0"
  },
  {
    "id": "entity-1",
    "name": "Объект"
  }
]

Первый пакет с id: "document" задаёт метаинформацию. Остальные пакеты описывают графические сущности.

Идентификаторы и связывание пакетов

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

[
  {
    "id": "satellite",
    "label": {
      "text": "Спутник"
    }
  },
  {
    "id": "satellite",
    "position": {
      "cartesian": [0, 0, 7000000]
    }
  }
]

Принцип декларативного описания

CZML не содержит логики или процедурного кода. Все состояния задаются декларативно:

  • геометрия
  • материалы
  • анимации
  • временные интервалы
  • свойства визуализации

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

Временная модель CZML

Ключевая особенность CZML — поддержка временных интервалов и динамических значений.

Interval-based свойства

"position": {
  "interval": "2026-01-01T00:00:00Z/2026-01-02T00:00:00Z",
  "cartesian": [0, 0, 0]
}

Интервал задаётся в формате ISO 8601:

start/end

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

"position": {
  "epoch": "2026-01-01T00:00:00Z",
  "cartesian": [
    0, 0, 0, 0,
    60, 1000, 0,
    120, 2000, 0
  ]
}

Здесь:

  • первое число — смещение от epoch в секундах
  • далее координаты в формате Cartesian

Геометрические представления

CZML поддерживает несколько типов координат:

Cartesian

"position": {
  "cartesian": [1000, 2000, 3000]
}

Используется для локальных или глобальных 3D координат.

CartographicDegrees

"position": {
  "cartographicDegrees": [37.7749, -122.4194, 1000]
}

Формат:

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

Spherical

Используется реже, описывает сферические координаты.

Основные графические сущности CZML

Точка (Point)

{
  "id": "point-1",
  "point": {
    "pixelSize": 10,
    "color": {
      "rgba": [255, 0, 0, 255]
    }
  }
}

Линия (Polyline)

{
  "id": "path",
  "polyline": {
    "positions": {
      "cartographicDegrees": [
        0, 0, 0,
        10, 0, 0
      ]
    },
    "width": 2
  }
}

Полигон

{
  "id": "polygon",
  "polygon": {
    "hierarchy": {
      "cartographicDegrees": [
        0, 0,
        10, 0,
        10, 10,
        0, 10
      ]
    },
    "material": {
      "solidColor": {
        "color": {
          "rgba": [0, 255, 0, 100]
        }
      }
    }
  }
}

Материалы и стилизация

CZML поддерживает параметрические материалы:

Цвет

"color": {
  "rgba": [0, 0, 255, 255]
}

Градиенты и изображения

"material": {
  "image": {
    "uri": "texture.png"
  }
}

Прозрачность

Контролируется альфа-каналом RGBA или отдельными свойствами transparency.

Анимация объектов

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

Пример траектории

{
  "id": "moving-object",
  "position": {
    "epoch": "2026-01-01T00:00:00Z",
    "cartesian": [
      0, 0, 0, 0,
      60, 10000, 0, 0,
      120, 20000, 0, 0
    ]
  }
}

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

Пакеты и наследование свойств

CZML использует модель наследования через повторяющиеся id.

[
  {
    "id": "vehicle",
    "model": {
      "gltf": "vehicle.gltf"
    }
  },
  {
    "id": "vehicle",
    "position": {
      "cartographicDegrees": [30, 60, 1000]
    }
  }
]

Данные объединяются в единую сущность.

Интеграция CZML в CesiumJS

Загрузка CZML осуществляется через CzmlDataSource.

import { CzmlDataSource, Viewer } from "cesium";

const viewer = new Viewer("cesiumContainer");

const dataSource = new CzmlDataSource();
viewer.dataSources.add(dataSource);

dataSource.load([
  {
    id: "document",
    version: "1.0"
  },
  {
    id: "point",
    position: {
      cartographicDegrees: [30, 60, 1000]
    },
    point: {
      pixelSize: 10
    }
  }
]);

Потоковая загрузка CZML

CZML может обновляться инкрементально:

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

Удаление объекта

{
  "id": "point",
  "delete": true
}

Камера и привязка к объектам

CZML может содержать свойства для управления камерой:

"viewFrom": {
  "cartesian": [0, -10000, 5000]
}

Это задаёт относительное положение камеры.

Работа с 3D-моделями

CZML поддерживает glTF-модели:

{
  "id": "aircraft",
  "model": {
    "gltf": "aircraft.gltf",
    "scale": 1.0
  }
}

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

Условные выражения и динамические свойства

Некоторые свойства поддерживают интерполяцию и зависимости от времени:

  • position interpolation
  • color transitions
  • visibility intervals
"availability": "2026-01-01T00:00:00Z/2026-01-02T00:00:00Z"

Если объект вне диапазона availability, он не отображается.

Формат времени и точность

CZML строго использует ISO 8601:

  • UTC предпочтителен
  • миллисекунды допустимы
  • локальные временные зоны не применяются

Оптимизация больших сцен

Для сложных сцен применяются следующие подходы:

  • разделение CZML на сегменты
  • стриминг по времени
  • использование упрощённых геометрий
  • группировка объектов по id

Типичные ошибки при работе с CZML

  • несоответствие координатной системы
  • отсутствие document пакета
  • дублирование id без необходимости
  • некорректный формат времени
  • смешение cartesian и cartographicDegrees в одном свойстве

Связь CZML и Cesium Entity API

CZML транслируется в сущности Entity API:

  • packet → entity
  • position → SampledProperty
  • interval → TimeIntervalCollection
  • material → MaterialProperty

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

Архитектурная роль CZML

CZML используется как:

  • формат обмена геоданными
  • потоковое представление сцены
  • слой над Entity API
  • способ серверной генерации 3D-сцен

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

Оглавление