MGLMapSnapshotter

 

@interface MGLMapSnapshotter : NSObject <MGLStylable>

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, calling MGLMapSnapshotterDelegate methods if defined, then 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), altitude: 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 let error = error {
        fatalError(error.localizedDescription)
    }

    image = snapshot?.image
}

See the Create a static map snapshot example to learn how to use the MGLMapSnapshotter to generate a static image based on an MGLMapView object’s style, camera, and view bounds.

  • 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.

    View Source on GitHub

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

    Declaration

    Objective-C

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

    Swift

    func start() async throws -> MGLMapSnapshot

    Parameters

    completionHandler

    The block to call with a finished snapshot. The block is executed on the main queue.
    View Source on GitHub

  • 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) async throws -> MGLMapSnapshot

    Parameters

    queue

    The queue on which to call the block specified in the completionHandler parameter.
    completionHandler

    The block to call with a finished snapshot. The block is executed on the queue specified in the queue parameter.
    View Source on GitHub

  • Starts the snapshot creation and executes the specified blocks with the result on the specified queue. Use this option if you want to add custom drawing on top of the resulting MGLMapSnapshot.

    Declaration

    Objective-C

    - (void)startWithOverlayHandler:
            (nonnull MGLMapSnapshotOverlayHandler)overlayHandler
              completionHandler:
                  (nonnull MGLMapSnapshotCompletionHandler)completionHandler;

    Swift

    func start(overlayHandler: @escaping MGLMapSnapshotOverlayHandler) async throws -> MGLMapSnapshot

    Parameters

    overlayHandler

    The block to call after the base map finishes drawing but before certain built-in overlays draw. The block can use Core Graphics to draw custom content directly over the base map. The block is executed on a background queue.
    completionHandler

    The block to call with a finished snapshot. The block is executed on the main queue.
    View Source on GitHub

  • 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()
    View Source on GitHub

  • The options to use when generating a map snapshot.

    Declaration

    Objective-C

    @property (nonatomic) MGLMapSnapshotOptions *_Nonnull options;

    Swift

    var options: MGLMapSnapshotOptions { get set }
    View Source on GitHub

  • Indicates whether a snapshot is currently being generated.

    Declaration

    Objective-C

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

    Swift

    var isLoading: Bool { get }
    View Source on GitHub

  • The snapshotter’s delegate.

    The delegate is responsible for responding to significant changes during the snapshotting process, such as the style loading. Implement a delegate to customize the style that is depicted by the snapshot.

    You set the delegate after initializing the snapshotter but before receiving the snapshot, typically before starting the snapshot. The snapshotter keeps a weak reference to its delegate, so you must keep a strong reference to it to ensure that your style customizations apply.

    Declaration

    Objective-C

    @property (nonatomic, weak) id<MGLMapSnapshotterDelegate> _Nullable delegate;

    Swift

    weak var delegate: MGLMapSnapshotterDelegate? { get set }
    View Source on GitHub

  • The style displayed in the resulting snapshot.

    Unlike the MGLMapSnapshotOptions.styleURL property, this property is set to an object that allows you to manipulate every aspect of the style locally.

    This property is set to nil until the style finishes loading. If the style has failed to load, this property is set to nil. Because the style loads asynchronously, you should manipulate it in the -[MGLMapSnapshotterDelegate mapSnapshotter:didFinishLoadingStyle:] method. It is not possible to manipulate the style before it has finished loading.

    Note

    The default styles provided by Mapbox contain sources and layers with identifiers that will change over time. Applications that use APIs that manipulate a style’s sources and layers must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:] or a manually constructed NSURL.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) MGLStyle *style;

    Swift

    var style: MGLStyle? { get }
    View Source on GitHub