first commit
This commit is contained in:
commit
c069b8945d
34 files changed
+2424
No files matched your search
@@ -0,0 +1,160 @@
|
||||
# cesiumjs
|
||||
|
||||
A Flutter plugin that embeds a [CesiumJS](https://cesium.com/platform/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:
|
||||
```sh
|
||||
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](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 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
|
||||
|
||||
```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 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 `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
|
||||
|
||||
- **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.
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
`cesium_ion.json` is git-ignored. A VS Code launch configuration
|
||||
("example (linux)") is provided in `.vscode/launch.json`.
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
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
|
||||
```
|
||||
Reference in new issue
Block a user