Визуализация данных в kepler.gl строится поверх WebGL-рендеринга, где итоговая сцена формируется библиотекой deck.gl и картографическим движком Mapbox GL. Это означает, что экспорт изображения — не «сохранение HTML», а рендеринг текущего состояния сцены в растровый буфер с последующей сериализацией в PNG или JPEG.
Экспорт всегда опирается на текущее состояние карты: слой данных, фильтры, стили, положение камеры, масштаб, поворот, а также активные визуальные эффекты.
Перед тем как рассматривать API экспорта, важно понимать цепочку визуализации:
Экспорт изображения происходит на уровне WebGL-контекста, где текущий кадр «снимается» как snapshot.
Ключевой момент: экспорт фиксирует только то, что уже отрисовано. Асинхронные слои (тайлы, подгрузка данных) должны быть полностью загружены до вызова экспорта.
В React-интеграции Kepler.gl доступ к экземпляру карты обычно
осуществляется через mapRef.
Типичный сценарий:
Экземпляр карты доступен через:
mapRef.current — React refgetKeplerGlInstance() — доступ к внутреннему APIЛогика основана на том, что Kepler.gl хранит несколько карт по ключам, и каждая имеет свой инстанс.
После получения инстанса карты используется метод экспорта:
exportToImage()Он инициирует рендер сцены в canvas и возвращает результат в формате base64 или Blob (в зависимости от реализации).
Особенность: экспорт выполняется асинхронно, так как WebGL должен завершить отрисовку всех слоёв.
Внутренняя логика обычно выглядит так:
Псевдологика:
map.render()canvas.toDataURL('image/png')или
gl.readPixels(...) (низкоуровневый путь)В стандартной сборке интерфейса kepler.gl предусмотрена панель экспорта.
Функциональность включает:
В этом режиме библиотека сама управляет синхронизацией рендеринга и блокирует экспорт до завершения загрузки тайлов.
Экспорт изображения напрямую зависит от состояния WebGL-контекста:
Если GPU-контекст был сброшен (например, из-за нагрузки), экспорт может вернуть пустое изображение.
Базовая карта может быть не полностью загружена, что приводит к «пустым плиткам».
По умолчанию фон может быть прозрачным, если не задан стиль Mapbox.
Для корректного результата важно учитывать:
Часто применяется стратегия «заморозки состояния» перед экспортом:
Стандартный экспорт использует размер canvas, соответствующий viewport. Для увеличения качества применяется масштабирование:
Это позволяет получить изображения для печати или аналитических отчётов.
kepler.gl поддерживает несколько экземпляров карт одновременно. При экспорте важно явно указывать, какая карта используется:
Ошибка выбора инстанса приводит к экспорту «пустого» слоя или дефолтного состояния.
На практике экспорт часто ломается из-за несогласованности состояния:
Решение обычно сводится к ожиданию idle-цикла рендера и проверке готовности сцены.
В более сложных системах экспорт изображения используется как этап автоматизации:
В таких сценариях Kepler.gl работает в headless-режиме (например, в Node + headless browser), где важно эмулировать браузерный WebGL-контекст.
В серверных сценариях применяется:
Экспорт в этом случае фактически становится screenshot-операцией страницы, но с гарантией полной загрузки сцены.
Существуют фундаментальные ограничения WebGL-экспорта:
Особенно критичны CORS-ошибки: если тайлы загружены с неправильными заголовками, canvas становится «tainted» и экспорт блокируется.
Для стабильного результата применяются следующие техники:
Хотя базовый экспорт ориентирован на PNG, результат можно преобразовывать:
Выбор формата зависит от сценария использования: аналитика, публикация или архивирование.
Экспорт отражает полный snapshot Redux-состояния:
Это делает экспорт воспроизводимым: при одинаковом состоянии результат изображения будет идентичен.