Files
cesiumflutter/README.md
T
2026-11-07 14:39:59 +01:00

5.2 KiB

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:
    sudo apt install libwebkit2gtk-4.1-dev
    
    End users need the runtime library (libwebkit2gtk-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: false while 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