Primitive Shapes

The DingiAnnotation 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.

The DingiOverlay 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.

DingiShape 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 DingiPointAnnotation, DingiPointCollection, DingiPolyline, DingiMultiPolyline, DingiPolygon, DingiMultiPolygon, or DingiShapeCollection in order to use DingiShape‘s methods. Do not create instances of DingiShape 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 +[DingiShape shapeWithData:encoding:error:] factory method to create one of the concrete subclasses of DingiShape noted above from GeoJSON data. To access a shape’s attributes, use the corresponding DingiFeature class instead.

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

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

Create instances of DingiPolyline or DingiPolygon in order to use properties of DingiMultiPoint. Do not create instances of DingiMultiPoint 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 DingiMultiPoint with DingiPointCollection, which represents a collection of related but disconnected points.

An DingiPointAnnotation object represents a one-dimensional shape located at a single geographical coordinate. Depending on how it is used, an DingiPointAnnotation 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 DingiShapeSource object. Configure the appearance of an DingiShapeSource’s or DingiVectorTileSource’s point shapes collectively using an DingiCircleStyleLayer or DingiSymbolStyleLayer object.

For more interactivity, add a selectable point annotation to a map view using the -[DingiMapView addAnnotation:] method. Alternatively, define your own model class that conforms to the MGLAnnotation protocol. Configure a point annotation’s appearance using -[DingiMapViewDelegate mapView:imageForAnnotation:] or -[DingiMapViewDelegate mapView:viewForAnnotation:] (iOS only). A point annotation’s DingiShape.title and DingiShape.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 DingiPointCollection or DingiShapeCollection object. To access a point’s attributes, use an DingiPointFeature object.

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

An DingiPointCollection 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 DingiShapeSource object. Configure the appearance of an DingiShapeSource’s or DingiVectorTileSource’s point collections collectively using an DingiCircleStyleLayer or DingiSymbolStyleLayer object. To access a point collection’s attributes, use an DingiPointCollectionFeature object.

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

A point collection is known as a MultiPoint geometry in GeoJSON. Do not confuse DingiPointCollection with DingiMultiPoint, the abstract superclass of DingiPolyline and DingiPolygon.

An DingiPolygon 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 DingiShapeSource object. Configure the appearance of an DingiShapeSource’s or DingiVectorTileSource’s polygons collectively using an DingiFillStyleLayer or DingiSymbolStyleLayer object. To access a polygon’s attributes, use an DingiPolygonFeature object.

Alternatively, you can add a polygon overlay directly to a map view using the -[DingiMapView addAnnotation:] or -[DingiMapView addOverlay:] method. Configure a polygon overlay’s appearance using -[DingiMapViewDelegate mapView:strokeColorForShapeAnnotation:] and -[DingiMapViewDelegate 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 DingiPolyline object.

A polygon may have one or more interior polygons, or holes, that you specify as DingiPolygon 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 DingiMultiPolygon or DingiShapeCollection object.

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

An DingiMultiPolygon 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 DingiPolygon 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 DingiShapeSource object. Configure the appearance of an DingiShapeSource’s or DingiVectorTileSource’s multipolygons collectively using an DingiFillStyleLayer or DingiSymbolStyleLayer object.

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

An DingiPolyline 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 DingiShapeSource object. Configure the appearance of an DingiShapeSource’s or DingiVectorTileSource’s polylines collectively using an DingiLineStyleLayer or DingiSymbolStyleLayer object. To access a polyline’s attributes, use an DingiPolylineFeature object.

Alternatively, you can add a polyline overlay directly to a map view using the -[DingiMapView addAnnotation:] or -[DingiMapView addOverlay:] method. Configure a polyline overlay’s appearance using -[DingiMapViewDelegate mapView:strokeColorForShapeAnnotation:] and -[DingiMapViewDelegate 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 DingiPolygon object. To group multiple polylines together in one shape, use an DingiMultiPolyline or DingiShapeCollection 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 = DingiPolyline(coordinates: coordinates, count: UInt(coordinates.count))

A polyline is known as a LineString geometry in GeoJSON.

An DingiMultiPolyline 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 DingiPolyline object.

You can add multipolyline shapes to the map by adding them to an DingiShapeSource object. Configure the appearance of an DingiShapeSource’s or DingiVectorTileSource’s multipolylines collectively using an DingiLineStyleLayer or DingiSymbolStyleLayer object.

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

A multipolyline is known as a MultiLineString geometry in GeoJSON.

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

DingiShapeCollection is most commonly used to add multiple shapes to a single DingiShapeSource. Configure the appearance of an DingiShapeSource’s or DingiVectorTileSource’s shape collection collectively using an DingiSymbolStyleLayer object, or use multiple instances of DingiCircleStyleLayer, DingiFillStyleLayer, and DingiLineStyleLayer to configure the appearance of each kind of shape inside the collection.

You cannot add an DingiShapeCollection object directly to a map view as an annotation. However, you can create individual DingiPointAnnotation, DingiPolyline, and DingiPolygon objects from the shapes array and add those annotation objects to the map view using the -[DingiMapView addAnnotations:] method.

To represent a collection of point, polyline, or polygon shapes, it may be more convenient to use an DingiPointCollection, DingiMultiPolyline, or DingiMultiPolygon object, respectively. To access a shape collection’s attributes, use the corresponding DingiFeature object.

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