Debug режимы

Встроенные визуальные отладочные инструменты Viewer

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

Ключевые параметры:

  • viewer.scene.debugShowFramesPerSecond — отображение текущего FPS прямо в сцене
  • viewer.scene.globe.depthTestAgainstTerrain — проверка перекрытия геометрии рельефом
  • viewer.scene.globe.show — временное отключение отрисовки глобуса
  • viewer.scene.skyBox.show и viewer.scene.skyAtmosphere.show — исключение фоновых эффектов для изоляции рендеринга

Отдельное значение имеет переключение FPS-индикатора, который позволяет фиксировать деградацию производительности при изменении плотности тайлов, включении 3D Tiles или динамической подгрузке данных.

Режимы отладки Globe

Глобус CesiumJS содержит встроенные визуализации геометрии и пространственных структур.

Основные debug-флаги:

  • viewer.scene.globe.showWireframe — отображение каркасной сетки поверхности
  • viewer.scene.globe.enableLighting — проверка влияния освещения на террейн
  • viewer.scene.globe.translucency.enabled — анализ полупрозрачности слоёв
  • viewer.scene.globe.tileCacheSize — косвенный контроль поведения кэша тайлов

Каркасный режим особенно полезен при анализе плотности сетки terrain provider и выявлении зон избыточной детализации, приводящих к падению FPS.

Debug режим примитивов (Primitives)

Низкоуровневый слой Primitive и GroundPrimitive содержит инструменты диагностики геометрии и bounding volumes.

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

  • primitive.debugShowBoundingVolume — визуализация bounding volume (сферы/коробки)
  • primitive.debugWireframe — отображение треугольной сетки
  • primitive.show — отключение/включение рендера без удаления из сцены

Bounding volumes позволяют анализировать эффективность culling-а. При корректной работе системы отсечения в кадр должны попадать только пересекающиеся объекты, остальные — исключаться на уровне CPU/GPU.

Отладка 3D Tiles

Механизм 3D Tiles имеет собственные встроенные инструменты диагностики, так как является одной из наиболее сложных подсистем CesiumJS.

Основные свойства Cesium3DTileset:

  • tileset.debugShowBoundingVolume — отображение bounding volumes тайлов
  • tileset.debugShowContentBoundingVolume — визуализация контента тайлов
  • tileset.debugShowMemoryUsage — отображение потребления памяти
  • tileset.debugWireframe — каркасная геометрия 3D Tiles
  • tileset.maximumScreenSpaceError — контроль уровня детализации LOD
  • tileset.debugColorizeTiles — окрашивание тайлов по состоянию загрузки и LOD

Особое значение имеет визуализация состояния тайлового дерева: активные, разгруженные, ожидающие загрузки. Цветовая индикация позволяет выявлять проблемы с LOD-скейлингом и некорректными геометрическими ошибками.

Cesium Inspector

CesiumInspector представляет собой встроенный UI-инструмент анализа сцены. Он предоставляет доступ к ряду визуальных диагностик без ручной настройки флагов.

Основные функции:

  • просмотр draw calls
  • анализ количества геометрических примитивов
  • переключение wireframe-режимов
  • отображение bounding volumes
  • инспекция текущих shader-проходов

Инспектор ориентирован на диагностику рендер-пайплайна WebGL и позволяет выявлять узкие места на уровне GPU.

Debug-режим камеры и frustum

Камера является критическим компонентом производительности, особенно при работе с большими сценами и 3D Tiles.

Инструменты анализа:

  • визуализация frustum (усечённой пирамиды видимости)
  • контроль near/far plane
  • анализ резких скачков LOD при перемещении камеры
  • диагностика jitter при недостаточной точности floating origin

Frustum-culling визуализация позволяет оценить, какие объекты исключаются из рендера до стадии растеризации.

Инструменты Scene Debug

Объект scene содержит дополнительные диагностические флаги:

  • scene.debugShowCommands — отображение команд отрисовки
  • scene.debugShowFrustums — визуализация всех frustum-проекций
  • scene.debugShowFramesPerSecond — FPS overlay
  • scene.pickTranslucentDepth — проверка корректности picking прозрачных объектов
  • scene.logarithmicDepthBuffer — анализ точности глубины на больших расстояниях

Logarithmic depth buffer используется для устранения z-fighting на масштабах планеты. Отладка этого режима помогает выявить артефакты пересечения геометрии при больших радиусах сцены.

Debug picking и идентификация объектов

Система picking в CesiumJS позволяет определять объекты под курсором через scene.pick и scene.drillPick.

Диагностические аспекты:

  • проверка корректности id объектов
  • анализ пересечений нескольких слоёв
  • выявление конфликтов между primitive и entity слоями
  • отладка глубины для translucent объектов

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

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

Для анализа нагрузки используются внутренние метрики Cesium:

  • количество draw calls
  • число активных текстур
  • загруженные и выгруженные тайлы
  • GPU memory usage
  • время CPU на update loop

FPS-индикатор часто дополняется внешними профайлерами браузера, однако встроенные метрики позволяют локализовать проблемы именно в pipeline CesiumJS.

Режим requestRenderMode

Режим:

scene.requestRenderMode = true;

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

Диагностические эффекты:

  • снижение нагрузки на GPU при статических сценах
  • выявление лишних render loop вызовов
  • анализ зависимостей от событий камеры и данных

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

Отладка terrain provider

Terrain subsystem включает дополнительные механизмы диагностики:

  • анализ LOD-ступеней terrain
  • проверка stitching артефактов
  • визуализация tile bounds
  • оценка корректности heightmap интерполяции

Ошибки в terrain provider часто проявляются как разрывы поверхности или скачки высот при изменении масштаба камеры.

WebGL и shader debug

CesiumJS опирается на WebGL 1/2, что позволяет использовать стандартные GPU-инструменты:

  • инспекция shader programs
  • анализ uniform buffer изменений
  • проверка texture binding state
  • выявление overdraw

Дополнительно включаются debug-режимы контекста WebGL через расширенные параметры контекста, позволяющие фиксировать ошибки GPU pipeline.

Логирование и трассировка состояния сцены

Внутренние события CesiumJS могут быть отследены через систему логов:

  • загрузка тайлов
  • переключение уровней детализации
  • ошибки декодирования ресурсов
  • события разрушения/создания primitives

При интенсивной загрузке 3D Tiles логирование позволяет восстановить последовательность принятия решений LOD-алгоритмом и выявить неоптимальные пути traversal дерева тайлов.

Диагностика тайлового кэша и памяти

Система кэширования CesiumJS критична для стабильной работы больших сцен.

Отладочные параметры:

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

При перегрузке памяти наблюдается постоянная перекомпиляция GPU ресурсов и деградация производительности, что фиксируется через debug memory overlays и инспектор 3D Tiles.

Оглавление