# Primitive Shapes

- `MGLAnnotation`

  The `MGLAnnotation` protocol is used to provide annotation-related information to a map view. To use this protocol, you adopt it in any custom objects that store or represent annotation data. Each object then serves as the source of information about a single map annotation and provides critical information, such as the annotation’s location on the map. Annotation objects do not provide the visual representation of the annotation but typically coordinate (in conjunction with the map view’s delegate) the creation of an appropriate objects to handle the display.

  An object that adopts this protocol must implement the `coordinate` property. The other methods of this protocol are optional.

  #### Related examples

  See the Annotation models and Annotation views examples to learn how to add objects that follow the `MGLAnnotation` protocol.

  See more

  #### Declaration

  Objective-C

      @protocol MGLAnnotation <NSObject>

  Swift

      protocol MGLAnnotation : NSObjectProtocol

  View Source on GitHub

- `MGLOverlay`

  The `MGLOverlay` protocol defines a specific type of annotation that represents both a point and an area on a map. Overlay objects are essentially data objects that contain the geographic data needed to represent the map area. Overlays can take the form of a polyline or polygon.

  You use overlays to layer more sophisticated content on top of a map view. For example, you could use an overlay to show the boundaries of a national park or trace a bus route along city streets. This SDK defines several concrete classes that conform to this protocol and define standard shapes.

  See more

  #### Declaration

  Objective-C

      @protocol MGLOverlay <MGLAnnotation>

  Swift

      protocol MGLOverlay : MGLAnnotation

  View Source on GitHub

- `MGLShape`

  `MGLShape` is an abstract class that represents a shape or annotation. Shapes constitute the content of a map — not only the overlays atop the map, but also the content that forms the base map.

  Create instances of `MGLPointAnnotation`, `MGLPointCollection`, `MGLPolyline`, `MGLMultiPolyline`, `MGLPolygon`, `MGLMultiPolygon`, or `MGLShapeCollection` in order to use `MGLShape`‘s methods. Do not create instances of `MGLShape` directly, and do not create your own subclasses of this class. The shape classes correspond to the Geometry object types in the GeoJSON standard, but some have nonstandard names for backwards compatibility.

  Although you do not create instances of this class directly, you can use its `+[MGLShape shapeWithData:encoding:error:]` factory method to create one of the concrete subclasses of `MGLShape` noted above from GeoJSON data. To access a shape’s attributes, use the corresponding `MGLFeature` class instead.

  You can add shapes to the map by adding them to an `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorTileSource`’s shapes collectively using a concrete instance of `MGLVectorStyleLayer`. Alternatively, you can add some kinds of shapes directly to a map view as annotations or overlays.

  See more

  #### Declaration

  Objective-C

      @interface MGLShape : NSObject <MGLAnnotation, NSSecureCoding>

  Swift

      class MGLShape : NSObject, MGLAnnotation, NSSecureCoding

  View Source on GitHub

- `MGLMultiPoint`

  The `MGLMultiPoint` class is an abstract superclass used to define shapes composed of multiple vertices.

  Create instances of `MGLPolyline` or `MGLPolygon` in order to use properties of `MGLMultiPoint`. Do not create instances of `MGLMultiPoint` directly and do not create your own subclasses of this class. You can use the method and properties of this class to access information about the vertices of the line or polygon.

  Do not confuse `MGLMultiPoint` with `MGLPointCollection`, which represents a collection of related but disconnected points.

  See more

  #### Declaration

  Objective-C

      @interface MGLMultiPoint : MGLShape

  Swift

      class MGLMultiPoint : MGLShape

  View Source on GitHub

- `MGLPointAnnotation`

  An `MGLPointAnnotation` object represents a one-dimensional shape located at a single geographical coordinate. Depending on how it is used, an `MGLPointAnnotation` object is known as a point annotation or point shape. For example, you could use a point shape to represent a city at low zoom levels, an address at high zoom levels, or the location of a long press gesture.

  You can add point shapes to the map by adding them to an `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorTileSource`’s point shapes collectively using an `MGLCircleStyleLayer` or `MGLSymbolStyleLayer` object.

  For more interactivity, add a selectable point annotation to a map view using the `-[MGLMapView addAnnotation:]` method. Alternatively, define your own model class that conforms to the `MGLAnnotation` protocol. Configure a point annotation’s appearance using `-[MGLMapViewDelegate mapView:imageForAnnotation:]` or `-[MGLMapViewDelegate mapView:viewForAnnotation:]` (iOS only). A point annotation’s `MGLShape.title` and `MGLShape.subtitle` properties define the default content of the annotation’s callout (on iOS) or popover (on macOS).

  To group multiple related points together in one shape, use an `MGLPointCollection` or `MGLShapeCollection` object. To access a point’s attributes, use an `MGLPointFeature` object.

  A point shape is known as a Point geometry in GeoJSON.

  #### Related examples

  See the Mark a place on the map with an annotation, Mark a place on the map with an image, and Default callout usage examples to learn how to add `MGLPointAnnotation` objects to your map.

  See more

  #### Declaration

  Objective-C

      @interface MGLPointAnnotation : MGLShape

  Swift

      class MGLPointAnnotation : MGLShape

  View Source on GitHub

- `MGLPointCollection`

  An `MGLPointCollection` object represents a shape consisting of one or more disconnected vertices, specified as `CLLocationCoordinate2D` instances. The points in the collection may be related but are not connected spatially. For example, you could use a point collection to represent all the trees in an orchard.

  You can add point collections to the map by adding them to an `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorTileSource`’s point collections collectively using an `MGLCircleStyleLayer` or `MGLSymbolStyleLayer` object. To access a point collection’s attributes, use an `MGLPointCollectionFeature` object.

  You cannot add an `MGLPointCollection` object directly to a map view as an annotation. However, you can create individual `MGLPointAnnotation` objects from the `coordinates` array and add those annotation objects to the map view using the `-[MGLMapView addAnnotations:]` method.

  A point collection is known as a MultiPoint geometry in GeoJSON. Do not confuse `MGLPointCollection` with `MGLMultiPoint`, the abstract superclass of `MGLPolyline` and `MGLPolygon`.

  See more

  #### Declaration

  Objective-C

      @interface MGLPointCollection : MGLShape <MGLOverlay>

  Swift

      class MGLPointCollection : MGLShape, MGLOverlay

  View Source on GitHub

- `MGLPolygon`

  An `MGLPolygon` object represents a closed shape consisting of four or more vertices, specified as `CLLocationCoordinate2D` instances, and the edges that connect them. For example, you could use a polygon shape to represent a building, a lake, or an area you want to highlight.

  You can add polygon shapes to the map by adding them to an `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorTileSource`’s polygons collectively using an `MGLFillStyleLayer` or `MGLSymbolStyleLayer` object. To access a polygon’s attributes, use an `MGLPolygonFeature` object.

  Alternatively, you can add a polygon overlay directly to a map view using the `-[MGLMapView addAnnotation:]` or `-[MGLMapView addOverlay:]` method. Configure a polygon overlay’s appearance using `-[MGLMapViewDelegate mapView:strokeColorForShapeAnnotation:]` and `-[MGLMapViewDelegate mapView:fillColorForPolygonAnnotation:]`.

  The vertices are automatically connected in the order in which you provide them. You should close the polygon by specifying the same `CLLocationCoordinate2D` as the first and last vertices; otherwise, the polygon’s fill may not cover the area you expect it to. To avoid filling the space within the shape, give the polygon a transparent fill or use an `MGLPolyline` object.

  A polygon may have one or more interior polygons, or holes, that you specify as `MGLPolygon` objects with the `+polygonWithCoordinates:count:interiorPolygons:` method. For example, if a polygon represents a lake, it could exclude an island within the lake using an interior polygon. Interior polygons may not themselves have interior polygons. To represent a shape that includes a polygon within a hole or, more generally, to group multiple polygons together in one shape, use an `MGLMultiPolygon` or `MGLShapeCollection` object.

  To make the polygon straddle the antimeridian, specify some longitudes less than −180 degrees or greater than 180 degrees.

  #### Related examples

  See the Add a polygon annotation example to learn how to initialize an `MGLPolygon` object from an array of coordinates.

  See more

  #### Declaration

  Objective-C

      @interface MGLPolygon : MGLMultiPoint <MGLOverlay>

  Swift

      class MGLPolygon : MGLMultiPoint, MGLOverlay

  View Source on GitHub
- `MGLMultiPolygon`

  An `MGLMultiPolygon` object represents a shape consisting of one or more polygons that do not overlap. For example, you could use a multipolygon shape to represent the body of land that consists of an island surrounded by an atoll: the inner island would be one `MGLPolygon` object, while the surrounding atoll would be another. You could also use a multipolygon shape to represent a group of disconnected but related buildings.

  You can add multipolygon shapes to the map by adding them to an `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorTileSource`’s multipolygons collectively using an `MGLFillStyleLayer` or `MGLSymbolStyleLayer` object.

  You cannot add an `MGLMultiPolygon` object directly to a map view using `-[MGLMapView addAnnotation:]` or `-[MGLMapView addOverlay:]`. However, you can add the `polygons` array’s items as overlays individually.

  See more

  #### Declaration

  Objective-C

      @interface MGLMultiPolygon : MGLShape <MGLOverlay>

  Swift

      class MGLMultiPolygon : MGLShape, MGLOverlay

  View Source on GitHub

- `MGLPolyline`

  An `MGLPolyline` object represents a shape consisting of two or more vertices, specified as `CLLocationCoordinate2D` instances, and the line segments that connect them. For example, you could use an polyline to represent a road or the path along which something moves.

  You can add polyline shapes to the map by adding them to an `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorTileSource`’s polylines collectively using an `MGLLineStyleLayer` or `MGLSymbolStyleLayer` object. To access a polyline’s attributes, use an `MGLPolylineFeature` object.

  Alternatively, you can add a polyline overlay directly to a map view using the `-[MGLMapView addAnnotation:]` or `-[MGLMapView addOverlay:]` method. Configure a polyline overlay’s appearance using `-[MGLMapViewDelegate mapView:strokeColorForShapeAnnotation:]` and `-[MGLMapViewDelegate mapView:lineWidthForPolylineAnnotation:]`.

  The vertices are automatically connected in the order in which you provide them. The first and last vertices are not connected to each other, but you can specify the same `CLLocationCoordinate2D` as the first and last vertices in order to close the polyline. To fill the space within the shape, use an `MGLPolygon` object. To group multiple polylines together in one shape, use an `MGLMultiPolyline` or `MGLShapeCollection` object.

  To make the polyline go across the antimeridian or international date line, specify some longitudes less than −180 degrees or greater than 180 degrees. For example, a polyline that stretches from Tokyo to San Francisco would have coordinates of (35.68476, -220.24257) and (37.78428, -122.41310).

      let coordinates = [
          CLLocationCoordinate2D(latitude: 35.68476, longitude: -220.24257),
          CLLocationCoordinate2D(latitude: 37.78428, longitude: -122.41310)
      ]
      let polyline = MGLPolyline(coordinates: coordinates, count: UInt(coordinates.count))

  A polyline is known as a LineString geometry in GeoJSON.

  #### Related examples

  See the Annotation models example to learn how to add an `MGLPolyine` object to your map.

  See more

  #### Declaration

  Objective-C

      @interface MGLPolyline : MGLMultiPoint <MGLOverlay>

  Swift

      class MGLPolyline : MGLMultiPoint, MGLOverlay

  View Source on GitHub
- `MGLMultiPolyline`

  An `MGLMultiPolyline` object represents a shape consisting of one or more polylines. For example, you could use a multipolyline shape to represent both sides of a divided highway (dual carriageway), excluding the median (central reservation): each carriageway would be a distinct `MGLPolyline` object.

  You can add multipolyline shapes to the map by adding them to an `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorTileSource`’s multipolylines collectively using an `MGLLineStyleLayer` or `MGLSymbolStyleLayer` object.

  You cannot add an `MGLMultiPolyline` object directly to a map view using `-[MGLMapView addAnnotation:]` or `-[MGLMapView addOverlay:]`. However, you can add the `polylines` array’s items as overlays individually.

  A multipolyline is known as a MultiLineString geometry in GeoJSON.

  See more

  #### Declaration

  Objective-C

      @interface MGLMultiPolyline : MGLShape <MGLOverlay>

  Swift

      class MGLMultiPolyline : MGLShape, MGLOverlay

  View Source on GitHub

- `MGLShapeCollection`

  An `MGLShapeCollection` object represents a shape consisting of zero or more distinct but related shapes that are instances of `MGLShape`. The constituent shapes can be a mixture of different kinds of shapes.

  `MGLShapeCollection` is most commonly used to add multiple shapes to a single `MGLShapeSource`. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorTileSource`’s shape collection collectively using an `MGLSymbolStyleLayer` object, or use multiple instances of `MGLCircleStyleLayer`, `MGLFillStyleLayer`, and `MGLLineStyleLayer` to configure the appearance of each kind of shape inside the collection.

  You cannot add an `MGLShapeCollection` object directly to a map view as an annotation. However, you can create individual `MGLPointAnnotation`, `MGLPolyline`, and `MGLPolygon` objects from the `shapes` array and add those annotation objects to the map view using the `-[MGLMapView addAnnotations:]` method.

  To represent a collection of point, polyline, or polygon shapes, it may be more convenient to use an `MGLPointCollection`, `MGLMultiPolyline`, or `MGLMultiPolygon` object, respectively. To access a shape collection’s attributes, use the corresponding `MGLFeature` object.

  A shape collection is known as a GeometryCollection geometry in GeoJSON.

  See more

  #### Declaration

  Objective-C

      @interface MGLShapeCollection : MGLShape

  Swift

      class MGLShapeCollection : MGLShape

  View Source on GitHub