iOS MapKit3D SDK User Guide

About iOS MapKit3D Framework

The iOS MapKit3D Application Programming Interfaces (APIs) provide mapping related functions to display and interact with 2D and 3D street maps from different vendors, and overlay additional information such as traffic and doppler images. The following sections describe how to set up MapKit to start a map session and to create a map using zoom, events, avatars, map elements, pins, layers, circles, and polylines.

MapView

The MapView class displays an interactive map within the view. It captures the key presses and touch gestures during the map movement and handles all the rendering and screen touch events.

Note	You need to set the correct size for the MapView and add MapView to the application view.

Starting a Map Session

Run the following code snippet to create a map session. In this case, the map is created with default options and the code snippet initializes the map, without using the MapOptions class.

if (![appDelegate mapView])
    {
        appDelegate.mapView = [[LMKMap3DView alloc] initWithFrame: screenBounds
                                             withContex: appDelegate.ltkContext];
        appDelegate.mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
    }

The class MapOptions can be used to override default options in the map. In this scenario, MapOptions is an optional parameter used to configure MapView by another constructor, as shown in the following code snippet.

LMKMap3DView* mapView = [[LMKMap3DView alloc]
initWithFrame: self.view.bounds withContext: ltkContext];
// Before using the map view you must wait for the initialization callback
bool isMapInitalized = NO;
LMKMapOptions *mapOptions = [[LMKMapOptions alloc]init];
LTKCoordinate coordinate;
coordinate.latitude = MAPVIEW_DEFAULT_LATITUDE;
coordinate.longitude = MAPVIEW_DEFAULT_LONGITUE;
mapOptions.defaultLanLon = coordinate;
mapOptions.defaultZoomLevel = 16;
if (![appDelegate mapView])
{
appDelegate.mapView = [[LMKMap3DView alloc] initWithFrame: screenBounds
withContex: appDelegate.ltkContext
withMapOptions:mapOptions];
appDelegate.mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth |
UIViewAutoresizingFlexibleHeight;
}

Note	LTKCoordinate is a structure that contains a geographical coordinate.

MapKit3D Delegate

Delegate is a callback function for LMKMapkit3D as shown in the following code snippet. The method didMapViewInitialized is called when the map is successfully created.

#pragma mark - Mapkit3D Delegate
- (void)didMapViewInitialized
{
isMapInitalized = YES;
}

Camera

The camera will control the Zoom features. The class LMKCameraPosition defines parameters for a camera as shown in the following code snippet.

LTKCoordinate coordinate = {DEFAULT_LATITUDE, DEFAULT_LONGITUDE};
LMKCameraPosition* cameraPosition = [[LMKCameraPosition alloc]
initWithCoordinate:coordinate
zoomLevel:17.0f
headingAngle:0.0f
tiltAngle:90.0f];
mapView.camera = cameraPosition;

When you scroll a map, you can zoom and pan/move the map by using two finger movements on the map for touchscreen devices. The following are some of the available options in zoom control.

Zoom In by Factor 1

The following code zooms in the camera by a factor of 1.

LMKCameraPosition* cameraPosition = [[LMKCameraPosition alloc]
initWithCoordinate:appDelegate.mapView.camera.coordinate
zoomLevel:appDelegate.mapView.camera.zoomLevel + 1
headingAngle:appDelegate.mapView.camera.headingAngle
tiltAngle:appDelegate.mapView.camera.tiltAngle];
[[appDelegate mapView] setCamera:cameraPosition];

Zoom Out by Factor 1

The following code zooms out the camera by a factor of 1.

LMKCameraPosition* cameraPosition = [[LMKCameraPosition alloc]
initWithCoordinate:appDelegate.mapView.camera.coordinate
zoomLevel:appDelegate.mapView.camera.zoomLevel - 1
headingAngle:appDelegate.mapView.camera.headingAngle
tiltAngle:appDelegate.mapView.camera.tiltAngle];
[[appDelegate mapView] setCamera:cameraPosition];

Animation Parameters for the Camera

The animation parameters of the camera can be created and set when the camera moves, as shown in the following code snippet.

LMKAnimationParameter* parameter = [[LMKAnimationParameter alloc] init];
parameter.accelerationType = AAT_DECELERATION;
parameter.duration = 2000;
[[appDelegate mapView] animateToCameraPosition:cameraPosition
withParameter:parameter];

The following figure shows the camera on the map.

Figure 1. Camera

Events

Map Long Click and Camera Update are major events supported in this release of iOS MapKit3D SDK.

Map Long Click

The method didLongPress is called after a long-press gesture at a particular coordinate. The map’s long presses can be captured as shown in the following code snippet.

- (void)didLongPress:(LMKMap3DView *)mapView
atCoordinate:(LTKCoordinate)coordinate
{
NSString* tapText = [NSString stringWithFormat:@"long pressed,
coord=lat/lon:(%f, %f)",
coordinate.latitude, coordinate.longitude];
NSLog(@"long pressed, coord=lat/lon:(%f, %f)",coordinate.latitude,
coordinate.longitude);
}

The following parameters are used in the above code snippet.

@param mapView : The map view that was pressed.
@param coordinate : The location that was pressed.

Camera Update

The method didChangeCameraPosition is called during any camera updates like animations or gestures on the map. The camera updates can be captured as shown in the following code snippet.

- (void)didChangeCameraPosition:(LMKMap3DView *)mapView
position:(LMKCameraPosition *)position
{
NSString* cameraText = [NSString stringWithFormat:@"lat = %f lon = %f tilt =
%f heading = %f zoomLevel = %f",
position.coordinate.latitude, position.coordinate.longitude,
position.tiltAngle, position.headingAngle, position.zoomLevel];
self.cameraTextView.text = cameraText;
}
NSLog(@"lat = %f lon = %f tilt = %f heading = %f zoomLevel = %f",
position.coordinate.latitude, position.coordinate.longitude,
position.tiltAngle, position.headingAngle,
position.zoomLevel);

Avatar

The iOS map Avatar has multiple appearance styles suited for various scenarios. You can select the one that best suits your requirements. The following screenshot shows the Avatar.

Figure 2. Avatar

The following are some of the major methods of Avatar.

Avatar Mode

The following sections show setting the Avatar to different modes, such as car or arrow.

Set Avatar Mode to Car

The following code snippet shows the call to avatarMode which is used to set the Avatar mode to car.

appDelegate.mapView.avatarMode = MAM_Car;

Set Avatar Mode to Arrow

The call to avatarMode can also be used to set the Avatar mode to an arrow using the following code snippet.

appDelegate.mapView.avatarMode = MAM_Arrow;

Set Avatar Location

The location of the Avatar is set using the following code snippet to call setMyLocation.

LTKLocation* location = [[LTKLocation alloc] init];
location.latitude = MAPVIEW_DEFAULT_LATITUDE;
location.longitude = MAPVIEW_DEFAULT_LONGITUE;
location.heading = 60.0;
location.accuracy = 200;
location.valid = LTKLOCATION_VALID_LATITUDE |
LTKLOCATION_VALID_LONGITUDE |
LTKLOCATION_VALID_HEADING |
LTKLOCATION_VALID_ACCURACY;
[appDelegate.mapView setMyLocation:location];

Map Compass

The method setCompassEnabled sets the compass to on or off as shown in the following code snippet. In this example, the compass is enabled.

[appDelegate.mapView setCompassEnabled: YES];

The following figure shows the enabled compass setting.

Figure 3. Setting Compass

A LMKPin is an icon located at a particular point on the map’s surface and contains latitude/longitude coordinates, and additional fields such as pin type and pin image. The following screenshot shows a blue pin icon.

Figure 4. Pin

The following sections give details of the major methods in the Pin class which creates pins, adds information to a pin when it is tapped, or replaces the pin with a custom bubble.

Create a Pin

The LMKPin class defines parameters for a pin. The following method creates a new pin with the specified parameters.

LMKPin* pin = [LMKPin pinWithLocation:coordinate];
pin.title = @"Location";
NSString* subtitle = [NSString stringWithFormat:@"%.2f, %.2f",
coordinate.latitude, coordinate.longitude];
pin.subTitle = subtitle;
UIImage* normalPin = [UIImage imageNamed:@"pin_normal.png"];
UIImage* selectedPin = [UIImage imageNamed:@"pin_selected.png"];
pin.unselectedIcon = normalPin;
pin.selectedIcon = selectedPin;
pin.selectedPinAnchor = CGPointMake(0.5f, 1.f);
pin.unselectedPinAnchor = CGPointMake(0.5f, 1.f);
pin.bubbleAnchor = CGPointMake(0.6f, 0.7f);
pin.unselectedPinAnchor = CGPointMake(0.5f, 1.f);
pin.selected = YES;
pin.circleRadius = 10;
pin.circleColor = [UIColor colorWithRed:0.5 green:0 blue:0.5 alpha:0.5];
pin.map = appDelegate.mapView;
[pinArray addObject:pin];

Pin Tap

The delegate didTapPin is called when a pin has been tapped, as shown in the following code snippet.

- (BOOL)mapView:(LMKMap3DView *)mapView didTapPin:(LMKPin *)pin;

Custom Bubble

To create a custom bubble instead of the drop pin, use the procedure in the following code snippet.

LTKCoordinate coordinate;
coordinate.latitude = 40.7160;
coordinate.longitude = -74.0028;
pin = [LMKPin pinWithLocation:coordinate];
pin.title = @"New York";
pin.subTitle = @"Lafayette St";
UIImage* normalPin = [UIImage imageNamed:@"pin_normal.png"];
UIImage* selectedPin = [UIImage imageNamed:@"pin_selected.png"];
pin.unselectedIcon = normalPin;
pin.selectedIcon = selectedPin;
pin.selectedPinAnchor = CGPointMake(0.5f, 1.f);
pin.unselectedPinAnchor = CGPointMake(0.5f, 1.f);
pin.bubbleAnchor = CGPointMake(0.6f, 0.7f);
pin.unselectedPinAnchor = CGPointMake(0.5f, 1.f);
pin.circleRadius = 10;
pin.circleColor = [UIColor colorWithRed:0.5 green:0 blue:0.5 alpha:0.5];
pin.selected = YES;
pin.bubble = [[CustomPOIBubble alloc] initWithPOI:pin
withMapView:appDelegate.mapView];
[self.view addSubview:(UIView*)(pin.bubble)];
pin.map = appDelegate.mapView;
LMKCameraPosition* cameraPosition = [[LMKCameraPosition alloc]
initWithCoordinate:coordinate
zoomLevel:16
headingAngle:appDelegate.mapView.camera.headingAngle
tiltAngle:appDelegate.mapView.camera.tiltAngle];
LMKAnimationParameter* parameter = [[LMKAnimationParameter alloc] init];
parameter.accelerationType = AAT_DECELERATION;
parameter.duration = 1000;
[[appDelegate mapView] animateToCameraPosition:cameraPosition
withParameter:parameter];
[pinArray addObject:pin];

The following screenshot illustrates how the pin can be created and customized as per the above code snippet. A custom bubble, highlighted in this screenshot is created above the selected red pin.

Figure 5. Selected Pin Creation

On clicking the pin, it gets unselected. The following screenshot shows the unselected blue pin.

Figure 6. Unselected Pin

Layers

The interface Layers represents a custom layer on the map. The following sections show various functionalities of layers.

Optional Layers

An Optional Layer is a layer which can be toggled. Map Optional Layers can be obtained using the following code snippet.

NSArray* layers = [[mapView] optionalLayers];

Enable Optional layers

The iOS Mapkit3D app can get a list of Optional Layers from MapView and set them to enabled or disabled. The following code is used to enable the available Optional Layers like traffic, weather etc.

NSArray* layers = [[mapView] optionalLayers];
for(int i = 0; i < layers.count; ++i)
{
LMKOptionalLayer* layer = (LMKOptionalLayer*)[layers objectAtIndex:i];
[layer setEnabled:layer.enabled];
}

Traffic Layer

The following code is used to enable the Traffic Layer on the map.

appDelegate.mapView.trafficEnabled = YES;

The figure shows the Traffic Layer supported in the iOS Mapkit3D.

Figure 7. Traffic Layer

Circle

The Circle class is used to draw circular shape on the map’s surface. A Circle has the following properties.

Geographic center
Radius in screen pixels or meters
Fill color in RGBA format
Stroke color in RGBA format
ZOrder which affects the draw orders between circles on the map.
Visibility

A circle is created through the LMKCircle class. The following code snippet and image show the creation of a circle on the map. This code draws a circle with a 50 meter radius.

LTKCoordinate coordinate ;
coordinate.latitude = 33.604f;
coordinate.longitude = -117.689f;

LMKCircle *circle =[[LMKCircle alloc]initWithPosition:coordinate radius:50   fillColor:[UIColor purpleColor] strokeColor:[UIColor cyanColor] visible:YES isMeter:NO
zOrder:1 ];
[circle setMapView:mapview];

The following figure shows the created circle.

Figure 8. Circle

Polyline

A polyline is a series of connected segments that can form various shapes and can be used to mark paths and routes on the map.

A polyline has the following properties.

setWidth: Width in screen pixels, which remains the same across different zoom levels
Points on the earth’s surface
setUnhighlightColor: Single color of the entire polyline. Blue is the default color
LMKColorSegmentAttribute: Supports multiple colors in the polyline
ZOrder: Draw orders between polylines on the map

The following code snippet creates a sample polyline.

if (!polyLineParameter ||!polyLine) {
parameter =[[LMKPolylineParameter alloc]init];
segAttr =[[LMKSegmentAttribute alloc]init];
colorSegAttr =[[LMKColorSegmentAttribute alloc]init];
for (CLLocation *coord in location) {
LTKCoordinate coordinate = {coord.coordinate.latitude,
coord.coordinate.longitude};
[parameter addCoordinate:coordinate];
}
segAttr.endIndex =0;
NSArray *arrSegAttr =@[colorSegAttr];
[parameter setSegmentAttribute:arrSegAttr];
[parameter setUnhighlightColor:[UIColor blueColor]];
[parameter setWidth:20];
parameter.outlineWidth = 10;
LMKRoundCapParameter *startRoundCap =[[LMKRoundCapParameter alloc]init];
LMKRoundCapParameter *endRoundCap =[[LMKRoundCapParameter alloc]init];
[startRoundCap setRadius:10];
[endRoundCap setRadius:10];
[parameter setStartCap:StartRoundCap];
[parameter setEndCap:endRoundCap];
polyLine=[LMKPolyline polylineWithParameter:Parameter];
polyLine.map =mapview;
polyLine.visible =YES;

}

The following figure shows the created polyline.

Figure 9. PolyLine

Building and Running the MapKit3DDemo Example App

Comtech provides an example application MapKit3DDemo that demonstrates various features of the iOS MapKit3D SDK. The following steps describe building and running the MapKit3DDemo.

Before building the project, set the value for the API key. Open credentials.plist, as shown in the following screenshot and replace "YOUR API KEY", with the API key assigned to you by Comtech.

Figure 10. Setting API Key

Run the MapKit3DDemo to explore various map features. The following screenshot shows the main screen which has options to try out different features.

Figure 11. MapKit3DDemo Main Screen

Note	For more information on all the iOS MapKit3D APIs, their respective classes and methods, see MapKit3D iOS API Reference Guide.

iOS SDK