cesiumjs
A Flutter plugin that embeds a CesiumJS 3D globe in Flutter Linux desktop apps.
Flutter on Linux has no platform views, so the globe is a native WebKitGTK
web view stacked above the Flutter surface and kept aligned with the
CesiumViewer widget. WebKitGTK renders WebGL2 on the GPU, so Cesium runs at
full frame rate.
| Platform | Status |
|---|---|
| Linux (X11) | Supported |
| Other platforms | The widget shows a "not supported" placeholder |
Requirements
- Flutter ≥ 3.32 / Dart ≥ 3.13
- WebKitGTK 4.1 development files at build time:
End users need the runtime library (
sudo apt install libwebkit2gtk-4.1-devlibwebkit2gtk-4.1-0), which ships with most GTK desktops. - 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 changes to your Linux runner are needed: on registration the plugin wraps
the app's FlView in a GtkOverlay. If your runner already places the
FlView inside a GtkOverlay, that overlay is used as is.
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 native 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 WebKit dev tools |
isReady, messages |
Ready flag and broadcast stream of CesiumMessages |
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
- 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: falsewhile a dialog, menu or drawer overlaps it. The view is hidden automatically when another route is pushed on top. - 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.
- Tested on X11. Wayland is untested.
Example app
example/ is a test app with places, imagery and terrain switches, markers
and a camera readout.
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
cesium_ion.json is git-ignored. A VS Code launch configuration
("example (linux)") is provided in .vscode/launch.json.
Development
flutter analyze
flutter test
cd example && flutter build linux
Layout:
lib/
cesiumjs.dart public API (barrel)
src/cesium_viewer.dart CesiumViewer widget, reports its rect to native
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
example/ test / demo app