MGLMapSnapshotter


@interface MGLMapSnapshotter : NSObject

An MGLMapSnapshotter generates static raster images of the map. Each snapshot image depicts a portion of a map defined by an MGLMapSnapshotOptions object you provide. The snapshotter generates an MGLMapSnapshot object asynchronously, passing it into a completion handler once tiles and other resources needed for the snapshot are finished loading.

You can change the snapshotter’s options at any time and reuse the snapshotter for multiple distinct snapshots; however, the snapshotter can only generate one snapshot at a time. If you need to generate multiple snapshots concurrently, create multiple snapshotter objects.

For an interactive map, use the MGLMapView class. Both MGLMapSnapshotter and MGLMapView are compatible with offline packs managed by the MGLOfflineStorage class.

From a snapshot, you can obtain an image and convert geographic coordinates to the image’s coordinate space in order to superimpose markers and overlays. If you do not need offline map functionality, you can use the Snapshot class in MapboxStatic.swift to generate static map images with overlays.

Example

let camera = MGLMapCamera(lookingAtCenter: CLLocationCoordinate2D(latitude: 37.7184, longitude: -122.4365), fromDistance: 100, pitch: 20, heading: 0)

let options = MGLMapSnapshotOptions(styleURL: MGLStyle.satelliteStreetsStyleURL(), camera: camera, size: CGSize(width: 320, height: 480))
options.zoomLevel = 10

let snapshotter = MGLMapSnapshotter(options: options)
snapshotter.start { (snapshot, error) in
    if error != nil {
        // error handler
    } else {
        // image handler
    }
}
  • Initializes and returns a map snapshotter object that produces snapshots according to the given options.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithOptions:
        (nonnull MGLMapSnapshotOptions *)options;

    Swift

    init(options: MGLMapSnapshotOptions)

    Parameters

    options

    The options to use when generating a map snapshot.

    Return Value

    An initialized map snapshotter.

  • Starts the snapshot creation and executes the specified block with the result.

    Declaration

    Objective-C

    - (void)startWithCompletionHandler:
        (nonnull MGLMapSnapshotCompletionHandler)completionHandler;

    Swift

    func start(completionHandler: @escaping MGLMapSnapshotCompletionHandler)

    Parameters

    completionHandler

    The block to handle the result in.

  • Starts the snapshot creation and executes the specified block with the result on the specified queue.

    Declaration

    Objective-C

    - (void)startWithQueue:(nonnull dispatch_queue_t)queue
         completionHandler:
             (nonnull MGLMapSnapshotCompletionHandler)completionHandler;

    Swift

    func start(with queue: DispatchQueue, completionHandler: @escaping MGLMapSnapshotCompletionHandler)

    Parameters

    queue

    The queue to handle the result on.

    completionHandler

    The block to handle the result in.

  • Cancels the snapshot creation request, if any.

    Once you call this method, you cannot resume the snapshot. In order to obtain the snapshot, create a new MGLMapSnapshotter object.

    Declaration

    Objective-C

    - (void)cancel;

    Swift

    func cancel()
  • The zoom level.

    The default zoom level is 0. If this property is non-zero and the camera property is non-nil, the camera’s altitude is ignored in favor of this property’s value.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) double zoomLevel;

    Swift

    var zoomLevel: Double { get set }
  • A camera representing the viewport visible in the snapshot.

    If this property is non-nil and the coordinateBounds property is set to a non-empty coordinate bounds, the camera’s center coordinate and altitude are ignored in favor of the coordinateBounds property.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) MGLMapCamera *_Nonnull camera;

    Swift

    var camera: MGLMapCamera { get set }
  • The coordinate rectangle that encompasses the bounds to capture.

    If this property is non-empty and the camera property is non-nil, the camera’s center coordinate and altitude are ignored in favor of this property’s value.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) MGLCoordinateBounds coordinateBounds;

    Swift

    var coordinateBounds: MGLCoordinateBounds { get set }
  • URL of the map style to snapshot.

    The URL may be a full HTTP or HTTPS URL, a Mapbox URL indicating the style’s map ID (mapbox://styles/{user}/{style}), or a path to a local file relative to the application’s resource path. Specify nil for the default style.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, nullable) NSURL *styleURL;

    Swift

    var styleURL: URL? { get set }
  • The size of the output image, measured in points.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGSize size;

    Swift

    var size: CGSize { get set }
  • Indicates whether a snapshot is currently being generated.

    Declaration

    Objective-C

    @property (readonly, getter=isLoading, nonatomic) BOOL loading;

    Swift

    var isLoading: Bool { get }