2026-11-07 19:49:09 +01:00
2026-11-07 15:48:01 +01:00
2026-11-07 19:49:09 +01:00
2026-11-07 15:48:01 +01:00
2026-11-07 19:49:09 +01:00
2026-11-07 19:49:09 +01:00
2026-11-07 19:49:09 +01:00
2026-11-07 19:49:09 +01:00
2026-11-07 14:39:59 +01:00
2026-11-07 14:39:59 +01:00
2026-11-07 19:49:09 +01:00
2026-11-07 19:49:09 +01:00
2026-11-07 19:49:09 +01:00
2026-11-07 19:49:09 +01:00

cesiumjs

A Flutter plugin that embeds a CesiumJS 3D globe in Flutter apps on Linux, Windows and Android. It also provides WebBrowserView, a plain web page shown by the same engines.

Platform Web engine Integration Status
Linux (X11) WebKitGTK 4.1 Native view stacked above the Flutter surface Tested
Android 7+ System WebView (Chromium) Platform view (AndroidView) Tested (emulator, API 35)
Windows 10/11 WebView2 (Edge) Native child window stacked above the Flutter view Not yet tested
Other platforms — The widget shows a "not supported" placeholder —

On Linux and Windows the globe is a native web view kept aligned with the CesiumViewer widget's rectangle (Flutter has no platform views there). On Android it is a regular platform view, composed with the rest of the UI. All three engines render WebGL2 on the GPU.

Requirements

  • Flutter ≥ 3.32 / Dart ≥ 3.13
  • Linux: WebKitGTK 4.1 development files at build time:
    sudo apt install libwebkit2gtk-4.1-dev
    
    End users need the runtime library (libwebkit2gtk-4.1-0), which ships with most GTK desktops.
  • Android: minSdk 24. The plugin declares the INTERNET permission.
  • Windows: the WebView2 SDK is downloaded from NuGet by CMake on the first build (needs network access; SHA-256 pinned in windows/CMakeLists.txt). End users need the WebView2 Runtime, preinstalled on Windows 11 and up-to-date Windows 10.
  • Network access: CesiumJS is loaded from the jsDelivr CDN.
  • Optional: a Cesium ion token for Bing aerial imagery and Cesium World Terrain. Without one the globe uses OpenStreetMap and a smooth ellipsoid.

Installation

dependencies:
  cesiumjs:
    path: ../cesiumjs   # or a git: dependency

No runner changes are needed on any platform. On Linux the plugin wraps the app's FlView in a GtkOverlay at registration (an existing GtkOverlay parent is reused). On Windows the web views are created as siblings of the Flutter view inside the runner's top-level window.

Usage

import 'package:cesiumjs/cesiumjs.dart';

class GlobePage extends StatefulWidget {
  const GlobePage({super.key});
  @override
  State<GlobePage> createState() => _GlobePageState();
}

class _GlobePageState extends State<GlobePage> {
  final _controller = CesiumController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return CesiumViewer(
      ionToken: const String.fromEnvironment('CESIUM_ION_TOKEN'),
      controller: _controller,
      onReady: () => _controller.flyTo(1.4442, 43.6047, 15000), // Toulouse
      onError: (e) => debugPrint('Cesium error: $e'),
    );
  }
}

CesiumViewer

Parameter Description
ionToken Cesium ion token, optional
controller A CesiumController to drive the globe from Dart
onReady Called once the Cesium viewer is initialised
onMessage Every message posted from JavaScript (CesiumMessage)
onError Page load failures, web process crashes and JS errors
visible Hides the web view without destroying it (keeps camera state)

CesiumController

Method Description
flyTo(lon, lat, height, {durationSeconds, headingDegrees, pitchDegrees}) Animated camera move
addPoint(lon, lat, {label, cssColor, pixelSize}) Adds a ground-clamped point entity, returns its id
clearEntities() Removes all entities
setImagery(CesiumImagery) osm, ionAerial (needs a token) or ignOrtho (IGN, France)
setTerrain(bool) Cesium World Terrain on/off (needs a token)
showFps(bool) Cesium's FPS overlay
runJavaScript(script) Runs arbitrary JS; window.cesiumViewer is the Cesium.Viewer. Returns the result as a string
openInspector() Opens the dev tools (WebKit inspector on Linux, Edge DevTools on Windows). On Android, debug builds can be inspected from chrome://inspect instead; this call does nothing
isReady, messages Ready flag and broadcast stream of CesiumMessages

Controller calls are only valid after onReady (or isReady == true).

WebBrowserView

A web page in the same native web view as the globe (WebKitGTK, WebView2, Android WebView), with the same layering rules (see Limitations).

WebBrowserView(url: 'https://example.com', controller: browserController)
Parameter Description
url Page to load; changing it navigates the view
controller A WebBrowserController
onError Page load failures and web process crashes
visible Hides the web view without destroying it

Links that would open a new window load in the view itself.

WebBrowserController Description
loadUrl(url) Navigates to url
reload() Reloads the page
runJavaScript(script) Runs JS in the page, returns the result as a string
openInspector() Dev tools (no-op on Android)
isAttached Whether the controller drives a live view

nativeWebViewSupported tells whether the current platform has native web views.

Messages from JavaScript

The page calls CesiumChannel.postMessage(obj); objects are sent as JSON and arrive as CesiumMessage(type, data). Built-in types:

type data
ready cesium (version), webgl (1 or 2)
camera longitude, latitude, height (sent when the camera stops moving)
layers imagery, terrain
error message

Your own scripts (via runJavaScript) can post custom types the same way.

Limitations

  • Linux and Windows: Flutter widgets cannot be drawn over the globe: the web view is a native window above the Flutter surface. Put controls around it, or set visible: false while a drawer or overlay overlaps it. The view is hidden automatically when another route is pushed on top, including dialogs and popup menus. (Android has no such restriction.)
  • Linux and Windows: the widget is positioned in window coordinates; don't place it inside a scroll view that clips it.
  • One Flutter view per app (the default) is supported.
  • Linux: tested on X11. Wayland is untested.
  • Windows: written against WebView2 SDK 1.0.4314.35 but not yet compiled or run on a Windows machine.

Example app

example/ is a test app with places, imagery and terrain switches, markers and a camera readout. On narrow screens (phones) the side panel becomes a drawer.

cd example
cp cesium_ion.example.json cesium_ion.json   # then paste your token (optional)
flutter run -d linux   --dart-define-from-file=cesium_ion.json
flutter run -d windows --dart-define-from-file=cesium_ion.json
flutter run -d <android-device-id> --dart-define-from-file=cesium_ion.json

cesium_ion.json is git-ignored. VS Code launch configurations ("example (linux)", "example (android)", "example (windows)") are provided in .vscode/launch.json.

Development

flutter analyze
flutter test
cd example && flutter build linux     # or: flutter build apk / flutter build windows

Layout:

lib/
  cesiumjs.dart              public API (barrel)
  src/cesium_viewer.dart     CesiumViewer widget (AndroidView on Android,
                             reports its rect to native on desktop)
  src/cesium_controller.dart CesiumController, CesiumMessage, CesiumImagery
  src/cesium_html.dart       HTML page hosting Cesium (CDN version pinned here)
  src/native_channel.dart    `cesiumjs/webview` method channel wrapper
  src/native_web_view.dart   NativeWebViewHost: creates/places/hides one
                             native view (shared by both widgets)
  src/web_browser.dart       WebBrowserView, WebBrowserController
linux/
  cesiumjs_plugin.cc         WebKitGTK views in a GtkOverlay over the FlView
android/src/main/kotlin/…/CesiumjsPlugin.kt
                             android.webkit.WebView + platform view factory
windows/
  cesiumjs_plugin.cpp        WebView2 in child windows over the Flutter view
example/                     test / demo app
S
Description
No description provided
Readme
162 KiB
0 Stars 1 Watchers 0 Forks
Languages
C++ 47.3%
Dart 26.6%
CMake 16.6%
Kotlin 7.4%
C 2.1%