Mapbox

CesiumJS поддерживает подключение внешних картографических провайдеров через систему imagery layers, где Mapbox занимает одно из ключевых мест благодаря поддержке тайлов, стилей и векторных данных.

В основе взаимодействия CesiumJS с Mapbox лежит модель слоёв (Imagery Layers). Каждый слой представляет собой источник тайлов, накладываемый на глобус. Mapbox предоставляет несколько типов ресурсов:

  • raster tiles (растровые тайлы)
  • vector tiles (векторные тайлы)
  • style API (JSON-описания стилей)
  • static images (статические карты)

CesiumJS не зависит от конкретного провайдера, поэтому Mapbox подключается через специализированные классы ImageryProvider.

Основная схема:

Viewer → ImageryLayer → ImageryProvider → Mapbox API → Tiles

Подключение растровых тайлов Mapbox

Самый базовый способ интеграции — использование готового Mapbox raster tiles endpoint.

Ключевая особенность: требуется access token, выдаваемый платформой Mapbox.

import { Viewer, UrlTemplateImageryProvider } from "cesium";

const viewer = new Viewer("cesiumContainer");

const mapboxLayer = new UrlTemplateImageryProvider({
  url: "https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/{z}/{x}/{y}?access_token=YOUR_MAPBOX_TOKEN",
  tileWidth: 512,
  tileHeight: 512,
  minimumLevel: 0,
  maximumLevel: 19
});

viewer.imageryLayers.addImageryProvider(mapboxLayer);

Особенности конфигурации:

  • {z}/{x}/{y} — стандартная схема Web Mercator
  • tileSize 512 используется Mapbox для современных стилей
  • уровни детализации ограничиваются тарифом API

Использование Mapbox Styles API

Mapbox предоставляет систему стилевых описаний в формате JSON. Это позволяет централизованно управлять визуальным представлением карты.

Пример подключения через style endpoint:

const styleLayer = new UrlTemplateImageryProvider({
  url: "https://api.mapbox.com/styles/v1/mapbox/light-v11/tiles/{z}/{x}/{y}?access_token=YOUR_MAPBOX_TOKEN",
  tileWidth: 512,
  tileHeight: 512
});

viewer.imageryLayers.addImageryProvider(styleLayer);

Популярные стили:

  • streets-v11 — классическая уличная карта
  • light-v11 — светлая минималистичная карта
  • dark-v11 — тёмная карта
  • satellite-v9 — спутниковые снимки
  • satellite-streets-v11 — гибридный режим

Векторные тайлы Mapbox

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

CesiumJS поддерживает векторные источники через VectorTileImageryProvider (или кастомные реализации).

Структура данных:

  • дороги — линии
  • здания — полигоны
  • POI — точки
  • административные границы

Основная проблема интеграции — различие в рендеринговых моделях: Mapbox GL использует собственный стиль-рендерер, тогда как CesiumJS работает через WebGL сцены глобуса.

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

Работа с токенами доступа

Mapbox требует авторизации через access token:

const MAPBOX_TOKEN = "pk.eyJ1Ijo...";

const provider = new UrlTemplateImageryProvider({
  url: `https://api.mapbox.com/...&access_token=${MAPBOX_TOKEN}`
});

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

  • токен ограничивает количество запросов
  • привязан к проекту Mapbox
  • может иметь ограничения по доменам
  • критичен для продакшн-систем

Координатная система и проекция

Mapbox использует стандарт Web Mercator (EPSG:3857). CesiumJS также работает в геодезической модели WGS84, но визуализация тайлов происходит в проекции:

  • X/Y — метры в Mercator
  • Z — уровень зума

Преобразование выполняется автоматически внутри CesiumJS.

Ключевой момент: несоответствие между 3D-глобусом и плоскими тайлами компенсируется системой reprojection.

Слои и порядок рендеринга

Imagery layers в CesiumJS упорядочиваются по индексу:

viewer.imageryLayers.addImageryProvider(layer);
viewer.imageryLayers.raise(layer);
viewer.imageryLayers.lower(layer);

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

  • terrain provider (3D рельеф)
  • custom imagery layers
  • geojson overlays

Пример многослойной конфигурации:

Mapbox satellite → terrain → labels overlay → vector data

Использование спутниковых данных Mapbox

Спутниковые тайлы обладают высокой нагрузкой на сеть, поэтому важны настройки кэширования:

const satellite = new UrlTemplateImageryProvider({
  url: "https://api.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}.jpg?access_token=TOKEN",
  tileWidth: 256,
  tileHeight: 256
});

Режимы применения:

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

Производительность и оптимизация

При интеграции Mapbox в CesiumJS критичны следующие аспекты:

Кэширование тайлов

CesiumJS использует встроенный tile cache, но можно дополнительно оптимизировать:

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

Управление уровнем детализации

maximumScreenSpaceError: 2

Меньшее значение → выше качество → ниже производительность.

Lazy loading

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

Комбинация Mapbox и 3D-глобуса CesiumJS

Главное отличие CesiumJS — полноценный 3D-глобус. Mapbox традиционно работает как 2.5D карта. При интеграции возникают особенности:

  • наклон камеры требует корректного тайлинга
  • перспективные искажения компенсируются CesiumJS
  • здания Mapbox не всегда корректно совпадают с terrain

Пример камеры:

viewer.camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(71.4304, 51.1283, 15000)
});

Terrain и Mapbox совместимость

Mapbox terrain (высотные данные) может конфликтовать с Cesium terrain provider.

Типовые сценарии:

  • Mapbox как imagery layer
  • Cesium World Terrain как геометрическая основа

Такое разделение позволяет:

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

Ограничения интеграции

При использовании Mapbox внутри CesiumJS возникают ограничения:

  • отсутствие нативной поддержки Mapbox GL styles
  • ограниченная работа vector tiles
  • зависимость от API тарифов
  • различие в lighting/shading моделях
  • невозможность полной синхронизации 3D building extrusion

Альтернативные подходы

Вместо прямого подключения Mapbox иногда используется:

  • предварительно рендеренные тайлы
  • собственные tile servers
  • Cesium ion imagery pipeline
  • hybrid raster/vector caching

Такие подходы уменьшают зависимость от внешнего API.

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

Смена стиля Mapbox может выполняться динамически:

viewer.imageryLayers.removeAll();

const darkLayer = new UrlTemplateImageryProvider({
  url: "https://api.mapbox.com/styles/v1/mapbox/dark-v11/tiles/{z}/{x}/{y}?access_token=TOKEN"
});

viewer.imageryLayers.addImageryProvider(darkLayer);

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

  • переключения дневного/ночного режима
  • аналитических визуализаций
  • тематических карт

Работа с overlay данными

Mapbox слой часто комбинируется с GeoJSON:

import { GeoJsonDataSource } from "cesium";

const data = await GeoJsonDataSource.load("data.geojson");
viewer.dataSources.add(data);

Результат:

  • Mapbox — базовая карта
  • GeoJSON — аналитические объекты
  • Cesium — 3D сцена

Сетевые особенности

Mapbox использует CDN, что влияет на:

  • latency в разных регионах
  • стабильность тайлов
  • скорость загрузки zoom levels

CesiumJS компенсирует это:

  • параллельной загрузкой
  • приоритетной подгрузкой viewport tiles
  • fallback механизмы кеша

Практическая модель применения

Типовая архитектура решений:

  • Mapbox: визуальная подложка
  • CesiumJS: 3D геометрия и аналитика
  • внешние API: данные в реальном времени

Такой подход используется в:

  • геоинформационных системах
  • симуляторах
  • urban planning инструментах
  • авиационных и морских визуализациях
Оглавление