Style Layers

MGLStyleLayer

MGLStyleLayer is an abstract base class for style layers. A style layer manages the layout and appearance of content at a specific z-index in a style. An MGLStyle object consists of one or more MGLStyleLayer objects.

Each style layer defined by the style JSON file is represented at runtime by an MGLStyleLayer object, which you can use to refine the map’s appearance. You can also add and remove style layers dynamically.

Create instances of MGLBackgroundStyleLayer and the concrete subclasses of MGLForegroundStyleLayer in order to use MGLStyleLayer‘s properties and methods. You do not create instances of MGLStyleLayer directly, and do not create your own subclasses of this class.

Do not add MGLStyleLayer objects to the style property of a MGLMapView before -mapView:didFinishLoadingStyle: is called.

See more

Declaration

Objective-C

@interface MGLStyleLayer : NSObject

Swift

class MGLStyleLayer : NSObject

MGLForegroundStyleLayer

MGLForegroundStyleLayer is an abstract superclass for style layers whose content is defined by an MGLSource object.

Create instances of MGLRasterStyleLayer, MGLHillshadeStyleLayer, and the concrete subclasses of MGLVectorStyleLayer in order to use MGLForegroundStyleLayer‘s methods. Do not create instances of MGLForegroundStyleLayer directly, and do not create your own subclasses of this class.

See more

Declaration

Objective-C

@interface MGLForegroundStyleLayer : MGLStyleLayer

Swift

class MGLForegroundStyleLayer : MGLStyleLayer

MGLBackgroundStyleLayer

An MGLBackgroundStyleLayer is a style layer that covers the entire map. Use a background style layer to configure a color or pattern to show below all other map content. If the style’s other layers use the Streets source, the background style layer is responsible for drawing land, whereas the oceans and other bodies of water are drawn by MGLFillStyleLayer objects.

A background style layer is typically the bottommost layer in a style, because it covers the entire map and can occlude any layers below it. You can therefore access it by getting the last item in the MGLStyle.layers array.

If the background style layer is transparent or omitted from the style, any portion of the map view that does not show another style layer is transparent.

See more

Declaration

Objective-C

@interface MGLBackgroundStyleLayer : MGLStyleLayer

Swift

class MGLBackgroundStyleLayer : MGLStyleLayer

MGLRasterStyleLayer

An MGLRasterStyleLayer is a style layer that renders georeferenced raster imagery on the map, especially raster tiles.

Use a raster style layer to configure the color parameters of raster tiles loaded by an MGLRasterTileSource object or raster images loaded by an MGLImageSource object. For example, you could use a raster style layer to render Satellite imagery, a raster tile set uploaded to MapTiler Cloud, or a raster map authored in MapTiler Engine.

Raster images may also be used as icons or patterns in a style layer. To register an image for use as an icon or pattern, use the -[MGLStyle setImage:forName:] method. To configure a point annotation’s image, use the MGLAnnotationImage class.

You can access an existing raster style layer using the -[MGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the MGLStyle.layers property. You can also create a new raster style layer and add it to the style using a method such as -[MGLStyle addLayer:].

Example

let layer = MGLRasterStyleLayer(identifier: "clouds", source: source)
layer.rasterOpacity = NSExpression(forConstantValue: 0.5)
mapView.style?.addLayer(layer)

See more

Declaration

Objective-C

@interface MGLRasterStyleLayer : MGLForegroundStyleLayer

Swift

class MGLRasterStyleLayer : MGLForegroundStyleLayer

MGLVectorStyleLayer

MGLVectorStyleLayer is an abstract superclass for style layers whose content is defined by an MGLShapeSource or MGLVectorTileSource object.

Create instances of MGLCircleStyleLayer, MGLFillStyleLayer, MGLFillExtrusionStyleLayer, MGLHeatmapStyleLayer, MGLLineStyleLayer, and MGLSymbolStyleLayer in order to use MGLVectorStyleLayer‘s properties and methods. Do not create instances of MGLVectorStyleLayer directly, and do not create your own subclasses of this class.

See more

Declaration

Objective-C

@interface MGLVectorStyleLayer : MGLForegroundStyleLayer

Swift

class MGLVectorStyleLayer : MGLForegroundStyleLayer

MGLCircleStyleLayer

An MGLCircleStyleLayer is a style layer that renders one or more filled circles on the map.

Use a circle style layer to configure the visual appearance of point or point collection features. These features can come from vector tiles loaded by an MGLVectorTileSource object, or they can be MGLPointAnnotation, MGLPointFeature, MGLPointCollection, or MGLPointCollectionFeature instances in an MGLShapeSource or MGLComputedShapeSource object.

A circle style layer renders circles whose radii are measured in screen units. To display circles on the map whose radii correspond to real-world distances, use many-sided regular polygons and configure their appearance using an MGLFillStyleLayer object.

You can access an existing circle style layer using the -[MGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the MGLStyle.layers property. You can also create a new circle style layer and add it to the style using a method such as -[MGLStyle addLayer:].

Example

let layer = MGLCircleStyleLayer(identifier: "circles", source: population)
layer.sourceLayerIdentifier = "population"
layer.circleColor = NSExpression(forConstantValue: UIColor.green)
layer.circleRadius = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'exponential', 1.75, %@)",
                              [12: 2,
                               22: 180])
layer.circleOpacity = NSExpression(forConstantValue: 0.7)
layer.predicate = NSPredicate(format: "%K == %@", "marital-status", "married")
mapView.style?.addLayer(layer)

See more

Declaration

Objective-C

@interface MGLCircleStyleLayer : MGLVectorStyleLayer

Swift

class MGLCircleStyleLayer : MGLVectorStyleLayer

MGLFillStyleLayer

An MGLFillStyleLayer is a style layer that renders one or more filled (and optionally stroked) polygons on the map.

Use a fill style layer to configure the visual appearance of polygon or multipolygon features. These features can come from vector tiles loaded by an MGLVectorTileSource object, or they can be MGLPolygon, MGLPolygonFeature, MGLMultiPolygon, or MGLMultiPolygonFeature instances in an MGLShapeSource or MGLComputedShapeSource object.

You can access an existing fill style layer using the -[MGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the MGLStyle.layers property. You can also create a new fill style layer and add it to the style using a method such as -[MGLStyle addLayer:].

Example

let layer = MGLFillStyleLayer(identifier: "parks", source: parks)
layer.sourceLayerIdentifier = "parks"
layer.fillColor = NSExpression(forConstantValue: UIColor.green)
layer.predicate = NSPredicate(format: "type == %@", "national-park")
mapView.style?.addLayer(layer)

See more

Declaration

Objective-C

@interface MGLFillStyleLayer : MGLVectorStyleLayer

Swift

class MGLFillStyleLayer : MGLVectorStyleLayer

MGLFillExtrusionStyleLayer

An MGLFillExtrusionStyleLayer is a style layer that renders one or more 3D extruded polygons on the map.

Use a fill-extrusion style layer to configure the visual appearance of polygon or multipolygon features. These features can come from vector tiles loaded by an MGLVectorTileSource object, or they can be MGLPolygon, MGLPolygonFeature, MGLMultiPolygon, or MGLMultiPolygonFeature instances in an MGLShapeSource or MGLComputedShapeSource object.

You can access an existing fill-extrusion style layer using the -[MGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the MGLStyle.layers property. You can also create a new fill-extrusion style layer and add it to the style using a method such as -[MGLStyle addLayer:].

Example

let layer = MGLFillExtrusionStyleLayer(identifier: "buildings", source: buildings)
layer.sourceLayerIdentifier = "building"
layer.fillExtrusionHeight = NSExpression(forKeyPath: "height")
layer.fillExtrusionBase = NSExpression(forKeyPath: "min_height")
layer.predicate = NSPredicate(format: "extrude == 'true'")
mapView.style?.addLayer(layer)

See more

Declaration

Objective-C

@interface MGLFillExtrusionStyleLayer : MGLVectorStyleLayer

Swift

class MGLFillExtrusionStyleLayer : MGLVectorStyleLayer

MGLHeatmapStyleLayer

An MGLHeatmapStyleLayer is a style layer that renders a heatmap.

A heatmap visualizes the spatial distribution of a large, dense set of point data, using color to avoid cluttering the map with individual points at low zoom levels. The points are weighted by an attribute you specify. Use a heatmap style layer in conjunction with point or point collection features. These features can come from vector tiles loaded by an MGLVectorTileSource object, or they can be MGLPointAnnotation, MGLPointFeature, MGLPointCollection, or MGLPointCollectionFeature instances in an MGLShapeSource or MGLComputedShapeSource object.

Consider accompanying a heatmap style layer with an MGLCircleStyleLayer or MGLSymbolStyleLayer at high zoom levels. If you are unsure whether the point data in an MGLShapeSource is dense enough to warrant a heatmap, you can alternatively cluster the source using the MGLShapeSourceOptionClustered option and render the data using an MGLCircleStyleLayer or MGLSymbolStyleLayer.

You can access an existing heatmap style layer using the -[MGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the MGLStyle.layers property. You can also create a new heatmap style layer and add it to the style using a method such as -[MGLStyle addLayer:].

Example

let layer = MGLHeatmapStyleLayer(identifier: "earthquake-heat", source: earthquakes)
layer.heatmapWeight = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:(magnitude, 'linear', nil, %@)",
                               [0: 0,
                                6: 1])
layer.heatmapIntensity = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'linear', nil, %@)",
                                  [0: 1,
                                   9: 3])
mapView.style?.addLayer(layer)

See more

Declaration

Objective-C

@interface MGLHeatmapStyleLayer : MGLVectorStyleLayer

Swift

class MGLHeatmapStyleLayer : MGLVectorStyleLayer

MGLHillshadeStyleLayer

An MGLHillshadeStyleLayer is a style layer that renders raster digital elevation model (DEM) tiles on the map.

Use a hillshade style layer to configure the color parameters of raster tiles loaded by an MGLRasterDEMSource object. For example, you could use a hillshade style layer to render Terrain-RGB data.

To display posterized hillshading based on vector shapes, as with the Terrain source, use an MGLVectorTileSource object in conjunction with several MGLFillStyleLayer objects.

You can access an existing hillshade style layer using the -[MGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the MGLStyle.layers property. You can also create a new hillshade style layer and add it to the style using a method such as -[MGLStyle addLayer:].

Example

let layer = MGLHillshadeStyleLayer(identifier: "hills", source: source)
layer.hillshadeExaggeration = NSExpression(forConstantValue: 0.6)
if let canalShadowLayer = mapView.style?.layer(withIdentifier: "waterway-river-canal-shadow") {
mapView.style?.insertLayer(layer, below: canalShadowLayer)
}

See more

Declaration

Objective-C

@interface MGLHillshadeStyleLayer : MGLForegroundStyleLayer

Swift

class MGLHillshadeStyleLayer : MGLForegroundStyleLayer

MGLLineStyleLayer

An MGLLineStyleLayer is a style layer that renders one or more stroked polylines on the map.

Use a line style layer to configure the visual appearance of polyline or multipolyline features. These features can come from vector tiles loaded by an MGLVectorTileSource object, or they can be MGLPolyline, MGLPolylineFeature, MGLMultiPolyline, or MGLMultiPolylineFeature instances in an MGLShapeSource or MGLComputedShapeSource object.

You can access an existing line style layer using the -[MGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the MGLStyle.layers property. You can also create a new line style layer and add it to the style using a method such as -[MGLStyle addLayer:].

Example

let layer = MGLLineStyleLayer(identifier: "trails-path", source: trails)
layer.sourceLayerIdentifier = "trails"
layer.lineWidth = NSExpression(format: "mgl_interpolate:withCurveType:parameters:stops:($zoomLevel, 'exponential', 1.5, %@)",
                           [14: 2,
                            18: 20])
layer.lineColor = NSExpression(forConstantValue: UIColor.brown)
layer.lineCap = NSExpression(forConstantValue: "round")
layer.predicate = NSPredicate(format: "%K == %@", "trail-type", "mountain-biking")
mapView.style?.addLayer(layer)

See more

Declaration

Objective-C

@interface MGLLineStyleLayer : MGLVectorStyleLayer

Swift

class MGLLineStyleLayer : MGLVectorStyleLayer

MGLSymbolStyleLayer

An MGLSymbolStyleLayer is a style layer that renders icon and text labels at points or along lines on the map.

Use a symbol style layer to configure the visual appearance of feature labels. These features can come from vector tiles loaded by an MGLVectorTileSource object, or they can be MGLShape or MGLFeature instances in an MGLShapeSource or MGLComputedShapeSource object.

You can access an existing symbol style layer using the -[MGLStyle layerWithIdentifier:] method if you know its identifier; otherwise, find it using the MGLStyle.layers property. You can also create a new symbol style layer and add it to the style using a method such as -[MGLStyle addLayer:].

Example

let layer = MGLSymbolStyleLayer(identifier: "coffeeshops", source: pois)
layer.sourceLayerIdentifier = "pois"
layer.iconImageName = NSExpression(forConstantValue: "coffee")
layer.iconScale = NSExpression(forConstantValue: 0.5)
layer.text = NSExpression(forKeyPath: "name")
layer.textTranslation = NSExpression(forConstantValue: NSValue(cgVector: CGVector(dx: 10, dy: 0)))
layer.textJustification = NSExpression(forConstantValue: "left")
layer.textAnchor = NSExpression(forConstantValue: "left")
layer.predicate = NSPredicate(format: "%K == %@", "venue-type", "coffee")
mapView.style?.addLayer(layer)

See more

Declaration

Objective-C

@interface MGLSymbolStyleLayer : MGLVectorStyleLayer

Swift

class MGLSymbolStyleLayer : MGLVectorStyleLayer