MapsGL iOS - Map Controller

A map controller acts as an adapter to a third-party mapping library and provides a consistent interface between the functionality of MapsGL and the underlying implementation of a third-party mapping library. All MapsGL-related data, such as data sources, weather layers, custom layers, and animation timeline information, is managed by the map controller.

Supported Mapping Libraries

MapsGL SDK for Apple Platforms currently supports integration with the following third-party mapping libraries:

Library + Version	Controller	Adapter Library
Mapbox Maps , v11.x.x	`MapboxMapController`	`MapsGLMapbox`
MapLibre Native for iOS , v6.18.0+	`MapLibreMapController`	`MapsGLMapLibre`

Read more about setting up and using a map controller with third-party mapping libraries.

Example

The following example creates a Mapbox map instance and initializes a MapsGL MapController with the map. If you are using MapLibre as your map provider, use MapLibreMapController from MapsGLMapLibre instead.


import UIKit
import MapsGLMaps
@_spi(Experimental) import MapboxMaps
 
final class ViewController: UIViewController {
    private var mapView: MapView!
    private var mapController: MapController!
    private var cancellables: Set<AnyCancellable> = []
 
    override func viewDidLoad() {
        super.viewDidLoad()
 
        // Create a Mapbox map
        let cameraOptions = CameraOptions(
            center: CLLocationCoordinate2D(latitude: 39.654, longitude: -93.102),
            zoom: 5)
        let options = MapInitOptions(cameraOptions: cameraOptions)
 
        mapView = MapView(frame: view.bounds, mapInitOptions: options)
        try! mapView.mapboxMap.setProjection(.init(name: .mercator)) // Set 2D map projection
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
 
        // Create a MapsGL map controller
        let xweatherAccount = XweatherAccount(id: "CLIENT_ID", secret: "CLIENT_SECRET")
        mapController = MapboxMapController(map: mapView, account: xweatherAccount)
 
        // Once the map has completed initial load…
        mapController.onLoad.observe { _ in
 
            // Add weather layers...
 
        }.store(in: &cancellables)
    }
}

Refer to the MapController API reference for more information about the available properties and methods.

Registering Custom Images

If you need to use a custom image with symbol-based styling, such as a custom icon for a GridLayerDescriptor, register it with addImage(id:image:sdf:) before adding the layer:


let image = UIImage(named: "my-grid-icon")!
try mapController.addImage(id: "my-grid-icon", image: image)

You can then reference the registered image id from your layer paint configuration:


let layer = GridLayerDescriptor(
    id: "custom-grid",
    source: source.id,
    paint: .init(
        sample: samplePaint,
        icon: .init(
            image: .constant("my-grid-icon"),
            size: CGSize(width: 24, height: 24)
        )
    )
)