214 lines
8.1 KiB
Markdown
214 lines
8.1 KiB
Markdown
# 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<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 `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 <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
|
|
|
|
```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
|
|
```
|