Shapes and Annotations

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.

The MGLAnnotationImage class is responsible for presenting point-based annotations visually on an MGLMapView instance. Annotation image objects pair NSImage objects with annotation-related metadata. They may be recycled later and put into a reuse queue that is maintained by the map view.

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.

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.

You can filter the features in a MGLVectorStyleLayer or vary their layout or paint attributes based on the features’ geographies. Pass an MGLShape into an NSPredicate with the format SELF IN %@ or %@ CONTAINS SELF and set the MGLVectorStyleLayer.predicate property to that predicate, or set a layout or paint attribute to a similarly formatted NSExpression.

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.

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.

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.

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.

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.

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.

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.

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.