MGLVectorSource


@interface MGLVectorSource : MGLTileSource

MGLVectorSource is a map content source that supplies tiled vector data in Mapbox Vector Tile format to be shown on the map. The location of and metadata about the tiles are defined either by an option dictionary or by an external file that conforms to the TileJSON specification. A vector source is added to an MGLStyle object along with one or more MGLVectorStyleLayer objects. A vector style layer defines the appearance of any content supplied by the vector source.

Each vector source defined by the style JSON file is represented at runtime by an MGLVectorSource object that you can use to initialize new style layers. You can also add and remove sources dynamically using methods such as -[MGLStyle addSource:] and -[MGLStyle sourceWithIdentifier:].

Within each vector tile, each geometric coordinate must lie between −1 × extent and (extent × 2) − 1, inclusive. Any vector style layer initialized with a vector source must have a non-nil value in its sourceLayerIdentifier property.

Commonly used vector sources include Mapbox Streets, Mapbox Terrain, and Mapbox Traffic.

Example

let source = MGLVectorSource(identifier: pois, tileURLTemplates: [https://example.com/vector-tiles/{z}/{x}/{y}.mvt], options: [
    .minimumZoomLevel: 9,
    .maximumZoomLevel: 16,
    .attributionInfos: [
        MGLAttributionInfo(title: NSAttributedString(string: © Mapbox), url: URL(string: http://mapbox.com))
    ]
])
mapView.style?.addSource(source)

  • Returns a vector source initialized with an identifier and configuration URL.

    After initializing and configuring the source, add it to a map view’s style using the -[MGLStyle addSource:] method.

    The URL may be a full HTTP or HTTPS URL or, for tile sets hosted by Mapbox, a Mapbox URL indicating a map identifier (mapbox://<mapid>). The URL should point to a JSON file that conforms to the TileJSON specification.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithIdentifier:(nonnull NSString *)identifier
                              configurationURL:(nonnull NSURL *)configurationURL;

    Swift

    init(identifier: String, configurationURL: URL)

    Parameters

    identifier

    A string that uniquely identifies the source in the style to which it is added.

    configurationURL

    A URL to a TileJSON configuration file describing the source’s contents and other metadata.

    Return Value

    An initialized vector source.

  • Returns a vector source initialized an identifier, tile URL templates, and options.

    After initializing and configuring the source, add it to a map view’s style using the -[MGLStyle addSource:] method.

    Tile URL templates

    Tile URL templates are strings that specify the URLs of the tile images to load. Each template resembles an absolute URL, but with any number of placeholder strings that the source evaluates based on the tile it needs to load. For example:

    • http://www.example.com/tiles/{z}/{x}/{y}.pbf could be evaluated as http://www.example.com/tiles/14/6/9.pbf.
    • http://www.example.com/tiles/{z}/{x}/{y}{ratio}.png could be evaluated as http://www.example.com/tiles/14/6/9@2x.png.

    Tile sources support the following placeholder strings in tile URL templates, all of which are optional:

    Placeholder stringDescription
    {x} The index of the tile along the map’s x axis according to Spherical Mercator projection. If the value is 0, the tile’s left edge corresponds to the 180th meridian west. If the value is 2z−1, the tile’s right edge corresponds to the 180th meridian east.
    {y} The index of the tile along the map’s y axis according to Spherical Mercator projection. If the value is 0, the tile’s tile edge corresponds to arctan(sinh(π)), or approximately 85.0511 degrees north. If the value is 2z−1, the tile’s bottom edge corresponds to −arctan(sinh(π)), or approximately 85.0511 degrees south. The y axis is inverted if the options parameter contains MGLTileSourceOptionTileCoordinateSystem with a value of MGLTileCoordinateSystemTMS.
    {z} The tile’s zoom level. At zoom level 0, each tile covers the entire world map; at zoom level 1, it covers ¼ of the world; at zoom level 2, 116 of the world, and so on. For tiles loaded by a MGLRasterSource object, whether the tile zoom level matches the map’s current zoom level depends on the value of the source’s tile size as specified in the MGLTileSourceOptionTileSize key of the options parameter.
    {bbox-epsg-3857} The tile’s bounding box, expressed as a comma-separated list of the tile’s western, southern, eastern, and northern extents according to Spherical Mercator (EPSG:3857) projection. The bounding box is typically used with map services conforming to the Web Map Service protocol.
    {quadkey} A quadkey indicating both the tile’s location and its zoom level. The quadkey is typically used with Bing Maps.
    {ratio} A suffix indicating the resolution of the tile image. The suffix is the empty string for standard resolution displays and @2x for Retina displays, including displays for which NSScreen.backingScaleFactor or UIScreen.scale is 3.
    {prefix} Two hexadecimal digits chosen such that each visible tile has a different prefix. The prefix is typically used for domain sharding.

    For more information about the {x}, {y}, and {z} placeholder strings, consult the OpenStreetMap Wiki.

    Declaration

    Objective-C

    - (nonnull instancetype)
    initWithIdentifier:(nonnull NSString *)identifier
      tileURLTemplates:(nonnull NSArray<NSString *> *)tileURLTemplates
               options:(nullable NSDictionary<MGLTileSourceOption, id> *)options;

    Swift

    init(identifier: String, tileURLTemplates: [String], options: [MGLTileSourceOption : Any]? = nil)

    Parameters

    identifier

    A string that uniquely identifies the source in the style to which it is added.

    tileURLTemplates

    An array of tile URL template strings. Only the first string is used; any additional strings are ignored.

    options

    A dictionary containing configuration options. See MGLTileSourceOption for available keys and values. Pass in nil to use the default values.

    Return Value

    An initialized tile source.

  • Returns an array of map features loaded by this source, restricted to the given source layers and filtered by the given predicate.

    Each object in the returned array represents a feature loaded by the source and provides access to attributes specified as part of the loaded feature. The source loads a feature if the source is added to an MGLMapView’s style; that style has a layer that uses the source; and the map view has recently scrolled to the region containing the feature.

    Features come from tiled vector data that is converted to tiles internally, so feature geometries are clipped at tile boundaries and features may appear duplicated across tiles. For example, suppose part of a lengthy polyline representing a road has recently scrolled into view. The resulting array includes those parts of the road that lie within the map tiles that the source has loaded, even if the road extends into other tiles. The portion of the road within each map tile is included individually.

    Returned features may not necessarily be visible to the user at the time they are loaded: the style may contain a layer that forces the source’s tiles to load but filters out the features in question, preventing them from being drawn. To obtain only visible features, use the -[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:predicate:] or -[MGLMapView visibleFeaturesInRect:inStyleLayersWithIdentifiers:predicate:] method.

    Declaration

    Objective-C

    - (nonnull NSArray<id<MGLFeature>> *)
    featuresInSourceLayersWithIdentifiers:
        (nonnull NSSet<NSString *> *)sourceLayerIdentifiers
                                predicate:(nullable NSPredicate *)predicate;

    Swift

    func features(sourceLayerIdentifiers: Set

    Parameters

    sourceLayerIdentifiers

    The source layers to include in the query. Only the features contained in these source layers are included in the returned array. This array may not be empty.

    predicate

    A predicate to filter the returned features. Use nil to include all loaded features.

    Return Value

    An array of objects conforming to the MGLFeature protocol that represent features loaded by the source that match the predicate.