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)

See the Cluster point data, Use images to cluster point data, and Add live data examples to learn how to add data to your map using this MGLSource object.

Initializing a Source

Accessing a Source’s Content

  • 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, nullable) MGLShape *shape;

    Swift

    @NSCopying var shape: MGLShape? { get set }
    View Source on GitHub
  • 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, nullable) NSURL *URL;

    Swift

    var url: URL? { get set }
    View Source on GitHub

  • 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.

    View Source on GitHub

  • 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.

    View Source on GitHub

  • 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.

    View Source on GitHub

  • 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.

    View Source on GitHub