2026-11-07 14:39:59 +01:00
# cesiumjs
A Flutter plugin that embeds a [CesiumJS ](https://cesium.com/platform/cesiumjs/ )
2026-11-07 15:48:01 +01:00
3D globe in Flutter apps on **Linux, Windows and Android** .
2026-11-07 14:39:59 +01:00
2026-11-07 15:48:01 +01:00
| 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 | — |
2026-11-07 14:39:59 +01:00
2026-11-07 15:48:01 +01:00
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.
2026-11-07 14:39:59 +01:00
## Requirements
- Flutter ≥ 3.32 / Dart ≥ 3.13
2026-11-07 15:48:01 +01:00
- **Linux**: WebKitGTK 4.1 development files at build time:
2026-11-07 14:39:59 +01:00
```sh
sudo apt install libwebkit2gtk-4.1-dev
` ``
End users need the runtime library (` libwebkit2gtk-4.1-0`), which ships with
most GTK desktops.
2026-11-07 15:48:01 +01:00
- **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](https://developer.microsoft.com/microsoft-edge/webview2/),
preinstalled on Windows 11 and up-to-date Windows 10.
2026-11-07 14:39:59 +01:00
- Network access: CesiumJS is loaded from the jsDelivr CDN.
- Optional: a [Cesium ion token](https://ion.cesium.com/tokens) for Bing
aerial imagery and Cesium World Terrain. Without one the globe uses
OpenStreetMap and a smooth ellipsoid.
## Installation
` ``yaml
dependencies:
cesiumjs:
path: ../cesiumjs # or a git: dependency
` ``
2026-11-07 15:48:01 +01:00
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.
2026-11-07 14:39:59 +01:00
## Usage
` ``dart
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 |
2026-11-07 15:48:01 +01:00
| ` visible` | Hides the web view without destroying it (keeps camera state) |
2026-11-07 14:39:59 +01:00
### ` 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 |
2026-11-07 15:48:01 +01:00
| ` 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 |
2026-11-07 14:39:59 +01:00
| ` isReady`, ` messages` | Ready flag and broadcast stream of ` CesiumMessage`s |
Controller calls are only valid after ` onReady` (or ` isReady == true`).
### 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
2026-11-07 15:48:01 +01:00
- **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 dialog, menu or drawer overlaps it. The
view is hidden automatically when another route is pushed on top. (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.
2026-11-07 14:39:59 +01:00
- One Flutter view per app (the default) is supported.
2026-11-07 15:48:01 +01:00
- 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.
2026-11-07 14:39:59 +01:00
## Example app
` example/` is a test app with places, imagery and terrain switches, markers
2026-11-07 15:48:01 +01:00
and a camera readout. On narrow screens (phones) the side panel becomes a drawer.
2026-11-07 14:39:59 +01:00
` ``sh
cd example
cp cesium_ion.example.json cesium_ion.json # then paste your token (optional)
2026-11-07 15:48:01 +01:00
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
2026-11-07 14:39:59 +01:00
` ``
2026-11-07 15:48:01 +01:00
` cesium_ion.json` is git-ignored. VS Code launch configurations
("example (linux)", "example (android)", "example (windows)") are provided in
` .vscode/launch.json`.
2026-11-07 14:39:59 +01:00
## Development
` ``sh
flutter analyze
flutter test
2026-11-07 15:48:01 +01:00
cd example && flutter build linux # or: flutter build apk / flutter build windows
2026-11-07 14:39:59 +01:00
` ``
Layout:
` ``
lib/
cesiumjs.dart public API (barrel)
2026-11-07 15:48:01 +01:00
src/cesium_viewer.dart CesiumViewer widget (AndroidView on Android,
reports its rect to native on desktop)
2026-11-07 14:39:59 +01:00
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
linux/
cesiumjs_plugin.cc WebKitGTK views in a GtkOverlay over the FlView
2026-11-07 15:48:01 +01:00
android/src/main/kotlin/…/CesiumjsPlugin.kt
android.webkit.WebView + platform view factory
windows/
cesiumjs_plugin.cpp WebView2 in child windows over the Flutter view
2026-11-07 14:39:59 +01:00
example/ test / demo app
` ``