# 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)

#### Related examples

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

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

  #### Related examples

  See the Add live data example to learn how to add live data to your map by updating the an `MGLShapeSource` object’s `URL` property.

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

  View Source on GitHub
- `-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.

  #### Related examples

  See the Animate a line example to learn how to animate line data by continously updating an `MGLShapeSource`‘s `shape` attribute.

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

  View Source on GitHub
- `-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.

  View Source on GitHub
- `-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.

  View Source on GitHub

### 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 (readwrite, copy, nonatomic, 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 (readwrite, copy, nonatomic, nullable) NSURL *URL;

  Swift

      var url: URL? { get set }

  View Source on GitHub
- `-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.

  View Source on GitHub
- `-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.

  View Source on GitHub
- `-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.

  View Source on GitHub
- `-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.

  View Source on GitHub