# cesiumjs A Flutter plugin that embeds a [CesiumJS](https://cesium.com/platform/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: ```sh 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](https://developer.microsoft.com/microsoft-edge/webview2/), preinstalled on Windows 11 and up-to-date Windows 10. - 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 ``` 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 ```dart import 'package:cesiumjs/cesiumjs.dart'; class GlobePage extends StatefulWidget { const GlobePage({super.key}); @override State createState() => _GlobePageState(); } class _GlobePageState extends State { 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 `CesiumMessage`s | 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). ```dart 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. ```sh 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 --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 ```sh 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 ```