MGLShapeSource

@interface MGLShapeSource : MGLSource

MGLShapeSource is a map content source that supplies vector shapes to be shown on the map. The shapes may be instances of MGLShape or MGLFeature, or they may be defined by local or external GeoJSON code. A shape source is added to an MGLStyle object along with an MGLVectorStyleLayer object. The vector style layer defines the appearance of any content supplied by the shape source. You can update a shape source by setting its shape or URL property.

MGLShapeSource is optimized for data sets that change dynamically and fit completely in memory. For large data sets that do not fit completely in memory, use the MGLComputedShapeSource or MGLVectorTileSource class.

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

Any vector style layer initialized with a shape source should have a nil value in its sourceLayerIdentifier property.

Example

var coordinates: [CLLocationCoordinate2D] = [
CLLocationCoordinate2D(latitude: 37.77, longitude: -122.42),
CLLocationCoordinate2D(latitude: 38.91, longitude: -77.04),
]
let polyline = MGLPolylineFeature(coordinates: &coordinates, count: UInt(coordinates.count))
let source = MGLShapeSource(identifier: "lines", features: [polyline], options: nil)
mapView.style?.addSource(source)

Initializing a Source

-initWithIdentifier:URL:options:

Returns a shape source with an identifier, URL, and dictionary of options for the source.

This class supports the following options: MGLShapeSourceOptionClustered, MGLShapeSourceOptionClusterRadius, MGLShapeSourceOptionMaximumZoomLevelForClustering, MGLShapeSourceOptionMinimumZoomLevel, MGLShapeSourceOptionMaximumZoomLevel, MGLShapeSourceOptionBuffer, and MGLShapeSourceOptionSimplificationTolerance. Shapes provided by a shape source are not clipped or wrapped automatically.

Declaration

Objective-C

- (nonnull instancetype)
initWithIdentifier:(nonnull NSString *)identifier
               URL:(nonnull NSURL *)url
           options:
               (nullable NSDictionary<MGLShapeSourceOption, id> *)options;

Swift

init(identifier: String, url: URL, options: [MGLShapeSourceOption : Any]? = nil)

Parameters

identifier

A string that uniquely identifies the source.

url

An HTTP(S) URL, absolute file URL, or local file URL relative to the current application’s resource bundle.

options

An NSDictionary of options for this source.

Return Value

An initialized shape source.

-initWithIdentifier:shape:options:

Returns a shape source with an identifier, a shape, and dictionary of options for the source.

This class supports the following options: MGLShapeSourceOptionClustered, MGLShapeSourceOptionClusterRadius, MGLShapeSourceOptionMaximumZoomLevelForClustering, MGLShapeSourceOptionMinimumZoomLevel, MGLShapeSourceOptionMaximumZoomLevel, MGLShapeSourceOptionBuffer, and MGLShapeSourceOptionSimplificationTolerance. Shapes provided by a shape source are not clipped or wrapped automatically.

To specify attributes about the shape, use an instance of an MGLShape subclass that conforms to the MGLFeature protocol, such as MGLPointFeature. To include multiple shapes in the source, use an MGLShapeCollection or MGLShapeCollectionFeature object, or use the -initWithIdentifier:features:options: or -initWithIdentifier:shapes:options: methods.

To create a shape from GeoJSON source code, use the +[MGLShape shapeWithData:encoding:error:] method.

Declaration

Objective-C

- (nonnull instancetype)
initWithIdentifier:(nonnull NSString *)identifier
             shape:(nullable MGLShape *)shape
           options:
               (nullable NSDictionary<MGLShapeSourceOption, id> *)options;

Swift

init(identifier: String, shape: MGLShape?, options: [MGLShapeSourceOption : Any]? = nil)

Parameters

identifier

A string that uniquely identifies the source.

shape

A concrete subclass of MGLShape

options

An NSDictionary of options for this source.

Return Value

An initialized shape source.

-initWithIdentifier:features:options:

Returns a shape source with an identifier, an array of features, and a dictionary of options for the source.

This class supports the following options: MGLShapeSourceOptionClustered, MGLShapeSourceOptionClusterRadius, MGLShapeSourceOptionMaximumZoomLevelForClustering, MGLShapeSourceOptionMinimumZoomLevel, MGLShapeSourceOptionMaximumZoomLevel, MGLShapeSourceOptionBuffer, and MGLShapeSourceOptionSimplificationTolerance. Shapes provided by a shape source are not clipped or wrapped automatically.

Unlike -initWithIdentifier:shapes:options:, this method accepts MGLFeature instances, such as MGLPointFeature objects, whose attributes you can use when applying a predicate to MGLVectorStyleLayer or configuring a style layer’s appearance.

To create a shape from GeoJSON source code, use the +[MGLShape shapeWithData:encoding:error:] method.

Declaration

Objective-C

- (nonnull instancetype)
initWithIdentifier:(nonnull NSString *)identifier
          features:(nonnull NSArray<MGLShape<MGLFeature> *> *)features
           options:
               (nullable NSDictionary<MGLShapeSourceOption, id> *)options;

Parameters

identifier

A string that uniquely identifies the source.

features

An array of objects that conform to the MGLFeature protocol.

options

An NSDictionary of options for this source.

Return Value

An initialized shape source.

-initWithIdentifier:shapes:options:

Returns a shape source with an identifier, an array of shapes, and a dictionary of options for the source.

This class supports the following options: MGLShapeSourceOptionClustered, MGLShapeSourceOptionClusterRadius, MGLShapeSourceOptionMaximumZoomLevelForClustering, MGLShapeSourceOptionMinimumZoomLevel, MGLShapeSourceOptionMaximumZoomLevel, MGLShapeSourceOptionBuffer, and MGLShapeSourceOptionSimplificationTolerance. Shapes provided by a shape source are not clipped or wrapped automatically.

Any MGLFeature instance passed into this initializer is treated as an ordinary shape, causing any attributes to be inaccessible to an MGLVectorStyleLayer when evaluating a predicate or configuring certain layout or paint attributes. To preserve the attributes associated with each feature, use the -initWithIdentifier:features:options: method instead.

To create a shape from GeoJSON source code, use the +[MGLShape shapeWithData:encoding:error:] method.

Declaration

Objective-C

- (nonnull instancetype)
initWithIdentifier:(nonnull NSString *)identifier
            shapes:(nonnull NSArray<MGLShape *> *)shapes
           options:
               (nullable NSDictionary<MGLShapeSourceOption, id> *)options;

Swift

convenience init(identifier: String, shapes: [MGLShape], options: [MGLShapeSourceOption : Any]? = nil)

Parameters

identifier

A string that uniquely identifies the source.

shapes

An array of shapes; each shape is a member of a concrete subclass of MGLShape.

options

An NSDictionary of options for this source.

Return Value

An initialized shape source.

Accessing a Source’s Content

shape

The contents of the source. A shape can represent a GeoJSON geometry, a feature, or a collection of features.

If the receiver was initialized using -initWithIdentifier:URL:options:, this property is set to nil. This property is unavailable until the receiver is passed into -[MGLStyle addSource:].

You can get/set the shapes within a collection via this property. Actions must be performed on the application’s main thread.

Declaration

Objective-C

@property (nonatomic, copy, readwrite, nullable) MGLShape *shape;

Swift

@NSCopying var shape: MGLShape? { get set }

URL

The URL to the GeoJSON document that specifies the contents of the source.

If the receiver was initialized using -initWithIdentifier:shape:options:, this property is set to nil.

Declaration

Objective-C

@property (nonatomic, copy, readwrite, nullable) NSURL *URL;

Swift

var url: URL? { get set }

-featuresMatchingPredicate:

Returns an array of map features for this source, filtered by the given predicate.

Each object in the returned array represents a feature for the current style and provides access to attributes specified via the shape property.

Features come from tiled GeoJSON 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 this source contains a long polyline representing a road. 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 lack a layer that draws the features in question. To obtain only visible features, use the -[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:predicate:] or -[MGLMapView visibleFeaturesInRect:inStyleLayersWithIdentifiers:predicate:] method.

Declaration

Objective-C

- (nonnull NSArray<id<MGLFeature>> *)featuresMatchingPredicate:
(nullable NSPredicate *)predicate;

Parameters

predicate

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

Return Value

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

-leavesOfCluster:offset:limit:

Returns an array of map features that are the leaves of the specified cluster. (Leaves are the original points that belong to the cluster.)

This method supports pagination; you supply an offset (number of features to skip) and a maximum number of features to return.

Declaration

Objective-C

- (nonnull NSArray<id<MGLFeature>> *)
leavesOfCluster:(nonnull MGLPointFeatureCluster *)cluster
         offset:(NSUInteger)offset
          limit:(NSUInteger)limit;

Parameters

cluster

An object of type MGLPointFeatureCluster (that conforms to the MGLCluster protocol).

offset

Number of features to skip.

limit

The maximum number of features to return

Return Value

An array of objects that conform to the MGLFeature protocol.

-childrenOfCluster:

Returns an array of map features that are the immediate children of the specified cluster on the next zoom level. The may include features that also conform to the MGLCluster protocol (currently only objects of type MGLPointFeatureCluster).

Note

The returned array may contain the cluster that was passed in, if the next zoom level doesn’t match the zoom level for expanding that cluster. See -[MGLShapeSource zoomLevelForExpandingCluster:].

Declaration

Objective-C

- (nonnull NSArray<id<MGLFeature>> *)childrenOfCluster:
(nonnull MGLPointFeatureCluster *)cluster;

Parameters

cluster

An object of type MGLPointFeatureCluster (that conforms to the MGLCluster protocol).

Return Value

An array of objects that conform to the MGLFeature protocol.

-zoomLevelForExpandingCluster:

Returns the zoom level at which the given cluster expands.

Declaration

Objective-C

- (double)zoomLevelForExpandingCluster:
(nonnull MGLPointFeatureCluster *)cluster;

Swift

func zoomLevel(forExpanding cluster: MGLPointFeatureCluster) -> Double

Parameters

cluster

An object of type MGLPointFeatureCluster (that conforms to the MGLCluster protocol).

Return Value

Zoom level. This should be >= 0; any negative return value should be considered an error.