Snapshotter

 
public class Snapshotter : StyleManager

A utility class for capturing styled map snapshots.

Use a MapSnapshotter when you need to capture a static snapshot of a map without using the actual MapView. You can configure the final result via MapSnapshotOptions upon construction time and take.

  • A style object that can be manipulated to set different styles for a snapshot.

    Declaration

    Swift

    @available(*, deprecated, message: "Access style APIs directly from Snapshotter instance instead")
public var style: StyleManager { get }

  • Initializes a Snapshotter instance.

    Declaration

    Swift

    convenience public init(options: MapSnapshotOptions)

    Parameters

    options

    Options describing an intended snapshot

  • The size of the snapshot

    Declaration

    Swift

    public var snapshotSize: CGSize { get set }

  • The current camera state of the snapshotter

    Declaration

    Swift

    public var cameraState: CameraState { get }

  • Sets the camera of the snapshotter

    Declaration

    Swift

    public func setCamera(to cameraOptions: CameraOptions)

    Parameters

    cameraOptions

    The target camera options

  • Request a new snapshot. If there is a pending snapshot request, it is cancelled automatically.

    Declaration

    Swift

    public func start(overlayHandler: SnapshotOverlayHandler?,
                  completion: @escaping (Result<UIImage, SnapshotError>) -> Void)

    Parameters

    overlayHandler

    The optional block to call after the base map finishes drawing, but before the final snapshot has been drawn. This block provides a SnapshotOverlayHandler type, which can be used with Core Graphics to draw custom content directly over the snapshot image.
    completion

    The block to call once the snapshot has been generated, providing a Result<UIImage, SnapshotError> type.

  • Cancels the current snapshot operation.The callback passed to the start method is called with error parameter set.

    Declaration

    Swift

    public func cancel()

  • Undocumented

    See more

    Declaration

    Swift

    public enum SnapshotError : Error

Camera

  • Returns the coordinate bounds corresponding to a given CameraOptions

    Declaration

    Swift

    public func coordinateBounds(for camera: CameraOptions) -> CoordinateBounds

    Parameters

    camera

    The camera for which the coordinate bounds will be returned.

    Return Value

    CoordinateBounds for the given CameraOptions

  • Calculates a CameraOptions to fit a list of coordinates.

    Declaration

    Swift

    public func camera(for coordinates: [CLLocationCoordinate2D],
                   padding: UIEdgeInsets?,
                   bearing: Double?,
                   pitch: Double?) -> CameraOptions

    Parameters

    coordinates

    Array of coordinates that should fit within the new viewport.
    padding

    The new padding to be used by the camera.
    bearing

    The new bearing to be used by the camera.
    pitch

    The new pitch to be used by the camera.

    Return Value

    A CameraOptions that fits the provided constraints

  • Returns array of tile identifiers that cover current map camera.

    Declaration

    Swift

    @_documentation(visibility: public)
@_spi(Experimental)
public func tileCover(for options: TileCoverOptions) -> [CanonicalTileID]

Snapshotter Event handling

  • An error that has occurred while loading the Map. The type property defines what resource could not be loaded and the message property will contain a descriptive error message. In case of source or tile loading errors, sourceID or tileID will contain the identifier of the source failing.

    Declaration

    Swift

    public var onMapLoadingError: Signal<MapLoadingError> { get }

  • The requested style has been fully loaded, including the style, specified sprite and sources’ metadata.

    The style specified sprite would be marked as loaded even with sprite loading error (an error will be emitted via onMapLoadingError). Sprite loading error is not fatal and we don’t want it to block the map rendering, thus this event will still be emitted if style and sources are fully loaded.

    Declaration

    Swift

    public var onStyleLoaded: Signal<StyleLoaded> { get }

  • The requested style data has been loaded. The type property defines what kind of style data has been loaded. Event may be emitted synchronously, for example, when loadStyle(_:transition:completion:) is used to load style.

    Based on an event data type property value, following use-cases may be implemented:

    • style: Style is parsed, style layer properties could be read and modified, style layers and sources could be added or removed before rendering is started.
    • sprite: Style’s sprite sheet is parsed and it is possible to add or update images.
    • sources: All sources defined by the style are loaded and their properties could be read and updated if needed.

    Declaration

    Swift

    public var onStyleDataLoaded: Signal<StyleDataLoaded> { get }

  • A style has a missing image. This event is emitted when the map renders visible tiles and one of the required images is missing in the sprite sheet. Subscriber has to provide the missing image by calling addImage(_:id:sdf:contentInsets:).

    Declaration

    Swift

    public var onStyleImageMissing: Signal<StyleImageMissing> { get }

  • Listen to a single occurrence of a Map event.

    This will observe the next (and only the next) event of the specified type. After observation, the underlying subscriber will unsubscribe from the map or snapshotter.

    If you need to unsubscribe before the event fires, call cancel() on the returned Cancelable object.

    Declaration

    Swift

    @available(*, deprecated, message: "Use snapshotter.on<eventType>.observeNext instead.")
@discardableResult
public func onNext<Payload>(event: MapEventType<Payload>, handler: @escaping (Payload) -> Void) -> Cancelable

    Parameters

    eventType

    The event type to listen to.
    handler

    The closure to execute when the event occurs.

    Return Value

    A Cancelable object that you can use to stop listening for the event. This is especially important if you have a retain cycle in the handler.

  • Listen to multiple occurrences of a Map event.

    Declaration

    Swift

    @available(*, deprecated, message: "Use snapshotter.on<eventType>.observe instead.")
@discardableResult
public func onEvery<Payload>(event: MapEventType<Payload>, handler: @escaping (Payload) -> Void) -> Cancelable

    Parameters

    eventType

    The event type to listen to.
    handler

    The closure to execute when the event occurs.

    Return Value

    A Cancelable object that you can use to stop listening for events. This is especially important if you have a retain cycle in the handler.

Clear data

  • Clears temporary map data.

    Clears temporary map data from the data path defined in the given resource options. Useful to reduce the disk usage or in case the disk cache contains invalid data.

    Note

    Calling this API will affect all maps that use the same data path and does not affect persistent map data like offline style packages.

    Declaration

    Swift

    public func clearData(completion: @escaping (Error?) -> Void)

    Parameters

    completion

    Called once the request is complete