Lower Manhattan drawn by vmap, tilted to 72 degrees, its towers standing to the far edge of the view under the sky

vmap

Maps for Flutter, drawn on the GPU.
MapLibre styles, 3D buildings, terrain and the globe.
Android, iOS, macOS, Windows, Linux and the web.

vmap on pub.dev CI MapLibre render tests MIT license

Try the live demo | Side by side with MapLibre GL JS | Get started | API reference | Example app | Changelog

The globe, with country names in their own scripts The Matterhorn raised from elevation tiles, the map draped over it Erbil's citadel in 3D, with Kurdish and Arabic names
The globe at low zooms. Terrain with the map draped over it. Kurdish and Arabic, shaped and joined.


  • MapLibre styles. vmap passes 1,394 of the 1,519 MapLibre render tests that apply to it, and draws real styles within a few percent of MapLibre GL JS.
  • 3D. Buildings with depth that stand to the far edge of a tilted view, terrain draped with the map, sky and fog, the globe, and tilt up to 85 degrees.
  • Labels that read right. Arabic, Kurdish and Syriac are shaped correctly, and labels are placed as MapLibre places them, steady while the map moves.
  • Dart all the way down. One widget, with no native map SDK under it and no platform channels. Markers are widgets, and gestures cover touch, mouse, trackpad and keyboard.
  • Your data. GeoJSON with clustering, heatmaps, feature state for highlighting, and taps that tell you what was hit.
  • Offline. A disk cache, regions downloaded ahead, and PMTiles archives.

Contents

Get started

1. Add the package. vmap needs Flutter 3.47.1 or newer.

flutter pub add vmap

2. Switch Flutter GPU on in your app's platform folders, and let it load tiles. Impeller is on by default, but Flutter GPU, the API vmap draws with, is a separate switch that Flutter leaves off:

dart run vmap:setup

It edits the Android manifest, the iOS and macOS Info.plist files and entitlements, and the Windows and Linux runners, and changes nothing that is already set. dart run vmap:setup --check only reports, and fails if anything is missing, for CI. The web needs nothing.

3. Show a map.

import 'package:flutter/material.dart';
import 'package:vmap/vmap.dart';

class MapPage extends StatelessWidget {
  const MapPage({super.key});

  @override
  Widget build(BuildContext context) => const Scaffold(
    body: Vmap(
      initialCamera: VmapCamera(center: LatLng(36.19, 44.01), zoom: 14),
    ),
  );
}

That is a whole map: vmap's built in style over OpenFreeMap tiles, which need no key, with gestures and the tiles' credit in the corner. The example app adds a style switcher, a marker, taps and 3D in about a hundred lines.

What vmap:setup changes, to do it by hand
Platform File Add
Android android/app/src/main/AndroidManifest.xml, inside <application> <meta-data android:name="io.flutter.embedding.android.EnableFlutterGPU" android:value="true" />
Android the same file, inside <manifest> <uses-permission android:name="android.permission.INTERNET"/>
iOS, macOS ios/Runner/Info.plist, macos/Runner/Info.plist <key>FLTEnableFlutterGPU</key><true/>
macOS macos/Runner/DebugProfile.entitlements, Release.entitlements <key>com.apple.security.network.client</key><true/>
Windows windows/runner/main.cpp, after DartProject project(...) project.set_enable_flutter_gpu(true);
Linux linux/runner/my_application.cc, after fl_dart_project_new() fl_dart_project_set_enable_flutter_gpu(project, TRUE);

flutter run --enable-flutter-gpu switches Flutter GPU on for one run. When it is off, debug builds say which switch is missing, and onError hears it as a VmapErrorKind.gpu error.

Styles

Vmap(style: VmapStyle.light)   // the default, built in
Vmap(style: VmapStyle.dark)    // built in
Vmap(style: VmapStyle.url('https://tiles.openfreemap.org/styles/liberty'))
Vmap(style: VmapStyle.json(myStyleDocument))

Erbil in the built in light style, with Kurdish street names The same view in the built in dark style
VmapStyle.light and VmapStyle.dark over Erbil.

The style decides the look and where the tiles come from. Styles are compared by content, so building one in build is fine.

Change single layers without writing the style out again, by layer id:

Vmap(
  style: VmapStyle.url('https://tiles.openfreemap.org/styles/liberty'),
  styleEdits: [
    const VmapStyleEdit.paint('water', 'fill-color', '#2a6fdb'),
    const VmapStyleEdit.visible('building', false),
    const VmapStyleEdit.filter('poi_r1', ['==', 'class', 'hospital']),
    VmapStyleEdit.zoomRange('road_minor', min: 14),
  ],
)

These are MapLibre's setPaintProperty, setLayoutProperty, setFilter and setLayerZoomRange. A paint change animates as the style's transitions say; the others rebuild the tiles behind what is on screen.

The camera

A VmapController moves the map and reads where it looks.

final controller = VmapController(
  const VmapCamera(center: LatLng(36.19, 44.01), zoom: 14),
);

Vmap(controller: controller)

controller.flyTo(const VmapCamera(center: LatLng(35.56, 45.44), zoom: 15, pitch: 55));
controller.easeTo(controller.camera.copyWith(bearing: 90));
controller.fitBounds(VmapBounds.around(points), padding: const EdgeInsets.all(40));
controller.camera = someCamera; // jump

Zooms are MapLibre's: the world is 512 pixels wide at zoom 0. flyTo follows MapLibre's path, rising over long distances, and a released gesture or an interrupted animation keeps its speed. VmapCamera.padding keeps part of the map free, under a bottom sheet for example. toScreen and toLatLng convert between places and points on the map.

Gestures

Input What it does
Touch One finger pans. Two pinch to zoom and twist to turn, and tilt when dragged up or down together. A double tap zooms in, a two finger tap zooms out, and a double tap held and dragged zooms.
Mouse The wheel zooms about the pointer. A double click zooms in, and with shift, out. A right drag or a control drag turns and tilts. A shift drag zooms to the box it draws.
Trackpad In a browser, as on MapLibre GL JS maps: two fingers sliding up or down zoom, as does a pinch. In an app, two fingers slide the map, a pinch zooms about the fingers, and a twist turns it.
Keyboard Once the map has focus: the arrows pan, shift with them turns and tilts, and + and - zoom a level, two with shift.

gestures switches them off one by one, by MapLibre GL JS's handler names, with flutter_map's two flags for turning and tilting on top:

Vmap(
  gestures: const VmapGestureOptions(
    rotate: false, // nothing turns the map
    boxZoom: false,
    scrollZoom: false,
    wheelZoomRate: 1 / 300,
  ),
)
Every gesture option, and its name in MapLibre GL JS
Option MapLibre GL JS What it switches
dragPan dragPan one finger, a mouse drag, two fingers sliding in an app
scrollZoom scrollZoom the mouse wheel, and in a browser two fingers on a trackpad
boxZoom boxZoom a shift drag zooming to a box
dragRotate, pitchWithRotate dragRotate, pitchWithRotate a right or control drag turning, and tilting
keyboard keyboard the arrows, + and -
doubleClickZoom doubleClickZoom double tap and click, and a two finger tap
touchZoomRotate touchZoomRotate two finger pinch and twist
touchPitch touchPitch two fingers dragged up or down
rotate, pitch (flutter_map's rotate flag) any turn, any tilt
inertia the drag handlers' inertia the glide after a release

VmapGestureOptions.none leaves only code moving the map; taps and long presses are still reported. Hosts that draw vmap's camera some other way use the same recognizer from package:vmap/gestures.dart, as the flutter_map adapter does.

3D, terrain and the globe

Styles with fill-extrusion layers stand their buildings up when the map is tilted. maxPitch is 60 degrees unless you raise it, to 85 at most; past about 60 the horizon shows, and the style's sky draws the sky and fog beyond it.

Vmap(
  maxPitch: 85,
  style: VmapStyle.url('https://tiles.openfreemap.org/styles/liberty'),
)

A style's terrain raises the ground, or an overlay adds one:

const VmapOverlay(
  sources: {
    'dem': {
      'type': 'raster-dem',
      'tiles': ['https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png'],
      'encoding': 'terrarium',
      'maxzoom': 15,
    },
  },
  terrain: {'source': 'dem', 'exaggeration': 1.5},
)

A style with "projection": {"type": "globe"} draws the globe at low zooms and the flat map up close.

Rendering options

Vmap(
  rendering: const VmapRenderOptions(
    renderer: VmapRenderer.canvas,
    farBuildings: false,
  ),
)
Option Default What it does
renderer VmapRenderer.gpu canvas draws with Flutter's canvas, which runs everywhere: a tilted map with flat buildings, and no terrain or globe. The GPU renderer hands the map to it by itself where Flutter GPU does not run.
antialias true Smooths the edges of buildings, raised ground and the globe. The web never smooths them this way.
glyphs VmapGlyphs.style Where the letters of labels come from: the style's glyph ranges, or the app's fonts for every label with VmapGlyphs.fonts.
maxCachedTiles 56 The fewest tiles kept in memory per source beyond those on screen.
farBuildings true In a view tilted past 60 degrees, buildings stand farther from the camera than MapLibre draws them, and sink into the ground before they end. Off, they end at the edge of a tile, where MapLibre's do.

Taps and features

Vmap(
  onTap: (point) => print('tapped $point'),
  onFeatureTap: (feature, point) {
    print('${feature.properties['name']} in ${feature.layers.first}');
  },
  tappableLayers: const ['poi', 'my-route'], // optional
)

onFeatureTap gets the topmost feature under a tap: a road, a place, a building, or one of your own. Each feature has its properties, its source, the style layers that draw it, and its geometry. tappableLayers limits it to some layers, as MapLibre's map.on('click', layerId) does.

For everything at a point, or in an area, ask the controller:

final here = await controller.featuresAt(point);
final inView = await controller.featuresIn(VmapBounds.around(corners));

To highlight a feature, give it state that the style reads with ['feature-state', name]:

Vmap(
  featureStates: [
    if (picked != null) VmapFeatureState.of(picked!, const {'picked': true}),
  ],
)

with a paint property such as ['case', ['==', ['feature-state', 'picked'], true], '#E5484D', '#1A73E8']. The feature needs an id: a GeoJSON feature's id, the id its vector tile carries, or a property named by the source's promoteId.

Markers

Markers are widgets at places. Map labels keep out of their way, and a marker's name is written beside it when there is room.

Vmap(
  markers: [
    VmapMarker(
      point: const LatLng(36.18946, 44.00970),
      name: 'Machko Chaikhana',
      width: 32,
      height: 32,
      alignment: Alignment.topCenter, // the box sits above the point
      child: GestureDetector(
        onTap: showCafe,
        child: const Icon(Icons.location_on, size: 32),
      ),
    ),
  ],
)

A tap on a marker belongs to the marker and does not reach onTap.

pins: VmapPins.standard draws the style's places of interest as round pins instead of its small icons. It uses Material icons, so the app needs uses-material-design: true.

Your own data

An overlay adds sources and layers to whatever style is showing, written as a MapLibre style writes them:

Vmap(
  overlay: VmapOverlay(
    sources: {
      'route': {
        'type': 'geojson',
        'data': {
          'type': 'LineString',
          'coordinates': [[44.0053, 36.1930], [44.0087, 36.1890]],
        },
      },
    },
    layers: const [
      {
        'id': 'route',
        'type': 'line',
        'source': 'route',
        'layout': {'line-cap': 'round'},
        'paint': {'line-color': '#1A73E8', 'line-width': 5},
      },
    ],
  ),
)
  • A layer with 'before': 'some-layer-id' is drawn under that style layer.
  • data may also be the address of a GeoJSON file.
  • Overlays are compared by content. Change data to move things: the old features stay up until the new ones are ready, so a moving dot does not blink.
  • A GeoJSON source with 'cluster': true clusters its points as MapLibre does. controller.clusterExpansionZoom, clusterChildren and clusterLeaves tell where a tapped cluster comes apart and what it holds.

Labels and languages

Vmap(
  style: VmapStyle.url(styleUrl, nameKeys: ['name:en', 'name']),
  textStyle: const VmapTextStyle(fontFamily: 'Inter'),
)

nameKeys picks the label language, tried in order. Letters come from the style's glyph ranges, as MapLibre draws them, and from fonts for what the ranges cannot shape, such as the Kurdish letters ڵ and ێ. VmapRenderOptions(glyphs: VmapGlyphs.fonts) draws every label from fonts.

vmap ships Vazirmatn and Noto Sans Syriac Eastern (300 KB together), so Arabic script and Syriac work with no setup. Text drawn from fonts goes through vmap's own OpenType shaper, written in Dart and tested against HarfBuzz glyph for glyph: joining forms, ligatures, kerning, mark placement, variable weights, and right-to-left text in the Unicode bidirectional order. Fonts need TrueType outlines (.ttf). Indic and Southeast Asian scripts, which need their letters reordered, are planned.

labels: VmapLabelOptions(...) hides every label, keeps road names off bends, or lets the labels of different sources overlap.

Offline

Vmap(
  controller: controller,
  network: VmapNetworkOptions(cacheDirectory: '${dir.path}/vmap'),
)

final result = await controller.downloadRegion(
  VmapBounds(const LatLng(36.10, 43.90), const LatLng(36.30, 44.15)),
  minZoom: 10,
  maxZoom: 16,
  onProgress: (done, total) => print('$done of $total'),
);

With a cache directory, tiles, styles and sprites are kept between runs, and the next start draws from disk at once while it checks the server. downloadRegion fetches every tile the style draws for an area ahead of time; the count grows fourfold with each zoom, so check the terms of your tile server first.

A source whose address starts with pmtiles:// is read from a PMTiles archive, on a server that answers range requests or on the device. VmapNetworkOptions also sets the user agent and headers sent with every request, for servers that want a key.

Loading, events and errors

Vmap(
  loadingBuilder: (context) => const Center(child: CircularProgressIndicator()),
  onStyleLoaded: () {},
  onCameraMove: (camera) {},
  onCameraIdle: (camera) {},
  onIdle: () {},
  onError: (error) => log('${error.kind} ${error.url}: ${error.cause}'),
)

The loading builder covers the map until it first draws tiles. onError hears every style, tile, sprite, font or GPU failure; the map keeps retrying where that can help.

The web

Build with WebAssembly, and serve Flutter's engine from your own host:

flutter build web --wasm --no-web-resources-cdn

The WebAssembly build draws on a thread of its own, which leaves the page's thread to the map: panning over Erbil on an Apple silicon Mac, the page's thread sat idle about two thirds of the time, against a tenth in the JavaScript build. That thread needs the page served cross-origin isolated:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Browsers without WebAssembly garbage collection get the JavaScript build, which draws the map too. Tiles are built in a web worker vmap ships. There is no disk cache in a browser, and a PMTiles archive has to be at an https:// address.

flutter_map

Apps already on flutter_map can draw vmap's maps in it with the vmap_flutter_map package: a layer that goes where a TileLayer would, without tilt or 3D. It lives in this repository and is not on pub.dev yet.

Platforms

Platform Draws with Seen running on
Android 10 and newer Impeller on Vulkan, or OpenGL ES where Vulkan is missing a phone on each, and the emulator
iOS Impeller on Metal an iPhone 13 Pro, and the simulator
macOS Impeller on Metal a Mac, where most of vmap is developed
Windows, Linux Impeller built by CI, not run yet
Web WebGL2 Chrome and Safari, and Firefox and WebKit headless

vmap draws with Flutter GPU, which Flutter still marks as a preview. Where it does not run (Android 9 and older, Android devices with a Vivante GPU, a browser without WebGL2, flutter test) the map is drawn with Flutter's canvas instead: tilted, with flat buildings, and without terrain or the globe. Windows and Linux have not been run yet. doc/platform-support.md has the details and their sources.

How it is tested

  • MapLibre's own render tests. CI draws them on the GPU on macOS against a pinned MapLibre GL JS commit, and fails when the count drops below a floor: 1,394 of the 1,519 that apply to vmap pass. The roadmap lists the kinds that still fail.
  • Real styles over real places. OpenFreeMap's Liberty, Bright and Positron are drawn next to MapLibre GL JS and compared pixel by pixel.
  • Text. The shaper and the bidirectional algorithm are held to HarfBuzz and to Unicode's conformance tests.
  • Speed. Frame times are measured next to MapLibre GL JS on the same camera path. The numbers, and what is still slow, are in doc/performance-plan.md.

Status and roadmap

vmap is in its 0.x versions, so the API can still change between minor versions. The changelog says what changed in each.

Next, in order: every platform run on real devices, custom GPU layers and 3D models placed on the map, and the MapLibre render tests that still fail. The roadmap has each step and the decisions behind them.

Working on vmap

To Run
run the unit and golden tests flutter test
rebuild the web worker, after any change under lib/ dart run tool/build_web_worker.dart
run the example app flutter run, in example/
run the demo flutter run -d chrome --wasm, in demo/
run MapLibre's render tests against a checkout of maplibre-gl-js tool/render_suite.sh
draw real styles next to MapLibre GL JS tool/compare_style.sh
draw the pictures on this page tool/readme_shots.sh

Bugs and questions go to the issue tracker.

License

MIT. vmap bundles Vazirmatn and Noto Sans Syriac Eastern under the SIL Open Font License, its Unicode tables come from the Unicode Character Database (Unicode License V3), and its WebGL2 backend comes from flutter_scene (MIT). Map data in the pictures is from OpenStreetMap, through OpenFreeMap's tiles.

Libraries

debug
What the engine counts and times, for benchmarks and diagnosis: VmapEngine.stats is a VmapStats.
gestures
vmap's gestures, for a map widget other than Vmap that draws with a VmapEngine: the flutter_map layer takes them from here. Implement MapGestureTarget for the widget's camera, give it to a MapGestureRecognizer, and put a MapGestureDetector over the map.
vmap
Maps for Flutter in any MapLibre style, drawn on the GPU.
web_worker
The other half of VmapEngine.useWebWorker: what the worker script runs.