Snapshotter
The snapshot functionality of the Mapbox Maps SDK for Android generates a static map image to use in your Android project. Take a snapshot of any Mapbox map and add the image into:
- another screen in your app
- a home screen
- a home screen widget
- a notification
- a
ListView/RecyclerView - wherever else a
Bitmapcan be placed
A Mapbox map doesn't need to be displayed to use the snapshot functionality. MapSnapshotter can be invoked anywhere in the app.
Unless you have the map tiles already cached, the device will need an internet connection to download the style and tiles necessary to render the map, and thus, the snapshot.
Snapshot generation can happen on the device's background thread and won't compromise the user experience.
This snapshot feature is different than the Mapbox Static Images API. The MapboxStaticMap class helps you build a URL to request a static map image which looks like an embedded map without interactivity or controls.
Taking a map snapshot
The MapSnapshotter constructor requires a MapSnapshotter.Options object.
MapSnapshotter.Options snapShotOptions = new MapSnapshotter.Options(500, 500);
snapShotOptions.withRegion(mapboxMap.getProjection().getVisibleRegion().latLngBounds);
snapShotOptions.withStyle(mapboxMap.getStyle().getUrl());
MapSnapshotter mapSnapshotter = new MapSnapshotter(this, snapShotOptions);
val snapShotOptions = MapSnapshotter.Options(500, 500)
snapShotOptions.withRegion(mapboxMap.projection.visibleRegion.latLngBounds)
snapShotOptions.withStyle(mapboxMap.style!!.url)
val mapSnapshotter = MapSnapshotter(this, options)
Here are the various settings that are available within the MapSnapshotter.Options class. You would use them in the same way that withRegion() and withStyle() are used in the code snippet above.
| Method | Description |
|---|---|
withApiBaseUrl | Specifies the URL used for the Maps API endpoint. It's rare that you'll need to change the API base URL. |
withLocalIdeographFontFamily | Set the font family for generating glyphs locally for ideographs in the "CJK Unified Ideographs" and "Hangul Syllables" ranges. |
withCameraPosition | The camera position to use for the snapshot image. This position is overridden if withRegion is also used. |
withLogo | A boolean flag to determine whether the Mapbox logo is included in the snapshot image. |
withPixelRatio | The pixel ratio to use. The default is 1. |
withRegion | The region to show in the snapshot image. This is applied after the camera position. |
withStyle | The map style to use in the snapshot image. |
withStyleJson | The map style JSON to use instead of a map style URL. |
Start the snapshot process with start() once you've created your MapSnapshotter object. When MapSnapshot is ready, use snapshot.getBitmap() to retrieve the Bitmap image.
mapSnapshotter.start(new MapSnapshotter.SnapshotReadyCallback() {
@Override
public void onSnapshotReady(MapSnapshot snapshot) {
// Display, share, or use bitmap image how you'd like
Bitmap bitmapImage = snapshot.getBitmap();
}
});
mapSnapshotter?.start { snapshot ->
// Display, share, or use bitmap image how you'd like
val bitmapOfMapSnapshotImage = snapshot.bitmap
}
Once you have the Bitmap image, you're free to use it how you'd like.
The Mapbox Android demo app has two examples that show how the snapshot Bitmap images can be used:
Share the real-time map snapshot image.
Use the map snapshot image in a notification.