Android MapKit3D SDK User Guide

About MapKit3D Library

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

Instances of MapOptions and LTKContext are needed to initialize the MapView as shown in the following code snippet.

// Get MapView instance
MapView mapView = findViewById(R.id.map_view);
// Initialize the MapView
mapView.initialize(mapOptions, ltkContext);

For consistent behavior of the map, the following MapView lifecycle methods must be called from the enclosing activity/fragment, from respective lifecycle methods of the sample app.

onResume()
onPause()

MapOptions

The class MapOptions initializes the options for the map.

MapOptions mapOptions = new MapOptions();
mapOptions.cacheFolder = getFilesDir().getAbsolutePath() + "/mapkit3d";
mapOptions.defaultLatitude = defaultLatitude;
mapOptions.defaultLongitude = defaultLongitude;
mapOptions.zorderLevel = 0;

MapController

MapController is the main class to interact with the Android MapKit3D SDK. It exposes all methods needed to interact with the MapView. The map instance (MapController) should be obtained by setting up a listener to the MapView using setMapStatusListener(). The listener will let you know when the map becomes available.

mapView.setMapStatusListener(new MapStatusListener() {
    @Override
    public void onMapCreated(MapController mapController) {
        // The MapController instance
    }
    @Override
    public void onMapReady() {
    }
});

MapController instance can also be obtained from the getController() method, however, this method should only be used after the map has been created otherwise it will return null.

Camera

The camera controls the Zoom features. The class CameraParameters defines parameters for a camera.

The following constructor creates CameraParameters only with coordinates.

CameraParameters(Coordinates pos)

The following constructor creates CameraParameters with all the elements.

CameraParameters(Coordinates pos, float zoomLevel, float tiltAngle, float headingAngle)

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

This code zooms in the camera by a factor of 1.

CameraParameters para = mMapView.getController().getCameraPosition();
para.setZoomLevel(para.getZoomLevel() + 1);
mMapView.getController().moveTo(para);

Zoom Out by Factor 1

This code zooms out the camera by a factor of 1.

CameraParameters para = mMapView.getController().getCameraPosition();
para.setZoomLevel(para.getZoomLevel() - 1);
mMapView.getController().moveTo(para);

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.

AnimationParameters ANIMATION = new AnimationParameters(
AnimationParameters.ACCELERATION_DECELERATION, 1000);
mMapView.getController().animateTo(parameters, ANIMATION);

Events

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

Map Long Click

Capture the map long presses by setting the setOnMapLongClickListener to MapController.

mapView.getController().setOnMapLongClickListener(new OnMapLongClickListener() {
@Override
public void onMapLongClick(Coordinates coord) {
Log.d(TAG, "long pressed, coord=lat/lon:
("
+ coord.getLatitude() + " , "
+ coord.getLongitude() + ")");
}
});

Camera Update

Capture the camera updates by setting the setCameraUpdateListener to MapController.

mapView.getController().setCameraUpdateListener(new OnCameraUpdateListener()
{
@Override
public void onCameraUpdate(CameraParameters camera) {
Log.d(TAG, "lat = " + camera.getPosition().getLatitude()
+ " lon = " + camera.getPosition().getLongitude() + " tilt = " + camera.getTiltAngle()
+ " heading = " + camera.getHeadingAngle()
+ " zoomLevel = " + camera.getZoomLevel());
}
});

Avatar

The Android 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 1. Avatar

The following are some of the major methods of Avatar.

Get Avatar

To return the avatar, use the call to getAvatar() as shown in the code snippet below.

Avatar avatar = mapView.getController().getAvatar();

Avatar Mode

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

Set Avatar Mode to Car

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

avatar.setMode(AvatarMode.AVATAR_MODE_CAR);

Set Avatar Mode to Arrow

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

avatar.setMode(AvatarMode.AVATAR_MODE_ARROW);

Set Avatar Location

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

avatar.setLocation(location);

Map Compass

The MapDecoration class sets the decoration of the Map user interface (UI). The method setCompassEnabled sets the compass to on or off as shown in the following code snippet.

MapDecoration mapDecoration = new MapDecoration();
mapDecoration.setCompassEnabled(true); // Show compass
DisplayMetrics displayMatrix = getResources().getDisplayMetrics();
int screenWidth = displayMatrix.widthPixels;
int screenHeight = displayMatrix.heightPixels;
mapView.getController().setCompassPosition( 0.9f * screenWidth, 0.1f * screenHeight);
mapView.getController().setMapDecoration(mapDecoration);

The following figure shows the compass on the map.

Figure 2. Compass

A pin is located at a particular point on the map’s surface and contains lat/long coordinates, and additional fields used by the pin manager, such as pin type and pin image. The pinImage field, can be specified only in the pins of type PIN_CUSTOM_IMAGE. All other types of pins have this object auto-filled to predefined standard images.

The following screenshot shows a blue pin icon.

Figure 3. 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 pressed, or replaces the pin with a custom pin.

Create a Pin

The PinParameters class defines parameters for a pin. The following method creates a new pin with the specified position, selectedImage, unselectedImage, radiusParameters, title, subTitle, bubble and the boolean value, as shown in the following code snippet.

PinParameters para = new PinParameters(
coordinate,null, null, null, title, subTitle, null, true);
mapView.getController().addPin(para);

Pin Click

The following code snippet shows creation of a toast (quick pop-up message) on clicking a pin. When a pin is pressed, OnPinClickListener is called back.

mapView.getController().setOnPinClickListener(new OnPinClickListener() {
@Override
public void onPinClick(Pin pin) {
Coordinates coordinate = pin.getPosition();
Toast.makeText(getBaseContext(),
"Pin at(" + coordinate.getLatitude()+ ","
+ coordinate.getLongitude() + ") is clicked" , Toast.LENGTH_SHORT).show();
}
});

Custom Pin

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

Coordinates coor = new Coordinates(lat, lon);
PinParameters pinpara = null;

pinpara = new PinParameters(
coor, new PinImageInfo()
.bitmap(customSelectedPinImage)
.pinAnchor(0.5f, 1.f)
.bubbleAnchor(0.60f, 0.05f),
new PinImageInfo()
.bitmap(customUnselectedPinImage)
.pinAnchor(0.5f, 1.f),
new RadiusParameters(100, 0x0000FF18), poi, street, null, true);
Pin pin = mMapView.getController().addPin(pinpara);

The following figure illustrates how the pins can be created and customized, using the above code snippet. In this figure, the red pin indicates the selected pin and the blue pin is unselected.

Figure 4. Custom Pin

Layers

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

Optional Layers

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

List<OptionalLayer> layers = mapView.getController().getOptionalLayers();

A listener can be set to the MapController, to get a notification when an Optional layer is loaded, as shown in the following code.

mapView.getController().setOnOptionalLayersUpdatedListener(new OnOptionalLayersUpdatedListener() {
@Override
public void onOptionalLayersUpdated() {
   }
});

Enable Optional Layers

The Android Mapkit3d app can get a list of Optional layers from MapController and set them to enabled or disabled. The following code is used to enable the available Optional layers like traffic, weather etc.

List<OptionalLayer> layers = mapView.getController().getOptionalLayers();
for(OptionalLayer layer : layers) {
layer.setEnabled(isChecked);
}

Traffic Layer

Enable the traffic layer on the map with the following code snippet.

mapView.getController().showTraffic(true);

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 CircleParameters class. The following code snippet and image show the creation of circle on the map. This code draws a circle with a 50 meter radius.

Circle circle = mapController.addCircle(new CircleParameters()
.center(new Coordinates(39.833333, -98.583333))
.radius(500.0f)
.setMeter(true)
.fillColor(0xFF000055)
.strokeColor(0x000000FF)
.visible(true));

The following figure shows the created circle.

Figure 5. 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:

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

The following code shows a sample polyline.

// First create polyline segment color

ArrayList<SegmentAttribute> segmentColor = new ArrayList<>();
segmentColor.add(new ColorSegment(0, 0x00FF00FF));

// Create polyline points

list List<Coordinates> polylinePoints = new ArrayList<>();
polylinePoints.add(new Coordinates(39.83333, -98.583333));
polylinePoints.add(new Coordinates(39.834376, -98.5828717));
polylinePoints.add(new Coordinates(39.833247, -98.577400));
polylinePoints.add(new Coordinates(39.831229, -98.579245));

//Use the segmentColor & polylinePoints to create the polyline

PolylineParameters polylineOptions = new PolylineParameters()
.setPoints(polylinePoints)
.segmentAttributes(segmentColor)
.startCap(new PolylineParameters.RoundCapParameter(10))
.endCap(new PolylineParameters.RoundCapParameter(10))
.unhighlightColor(0x0000FFFF)
.width(20);
Polyline polyline = mapController.addPolyline(polylineOptions)

The following figure shows the created polyline.

Figure 6. Polyline

Rectangle2D

A Rectangle2D is a rectangle shape on the map’s surface. It has the following properties.

Geographic Center
Size in screen pixels
Heading in degrees
Texture
Visibility

It is created through Rectangle2DParameters. The following code snippet and figure show plotting an image on the map as Rectangle2D.

// A sample indoor map of Comtech office
Coordinates[] points = {
new Coordinates(33.666372, -117.685852),
new Coordinates(33.666773, -117.685426),
new Coordinates(33.666966, -117.685689),
new Coordinates(33.666571, -117.686125)
};
// Decode the sample Comtech office map png from assets
Bitmap bmp = null;
try {
bmp = BitmapFactory.decodeStream(getAssets().open("ComtechFloorPlan32.png"));
}
catch (Exception e)
{
e.printStackTrace();
}
// Create the Rectangle2D using the coordinate points and the bitmap
Rectangle2DParameters params = new Rectangle2DParameters(points, bmp, true);
Rectangle2D rect = mapController.addRectangle2D(params);
// Center the map to the center of the image
CameraParameters cp = new CameraParameters(params.getCenter());
cp.setZoomLevel(20.0f);
mapController.moveTo(cp);

Figure 7. Rectangle2D on the Map

Building and Running the MapKit3DDemo Example App

Comtech provides an example application MapKit3DDemo that demonstrates various features of the Android MapKit3D SDK. The following sections describe how to build and run the MapKit3DDemo example app.

Importing the Project

To import the MapKit3DDemo project:

Click Open existing Android Studio project, from Studio Welcome Screen. If another project is already open in Studio, from the File menu, select Open.
Browse to the path androidSDK/sample/MapKit3DDemo. Select the option MapKit3DDemo from the dropdown and click Ok as shown in the following screenshot.

Figure 8. Importing the MapKit3DDemo Project

Click OK in the Gradle Sync dialog to auto configure the Gradle wrapper for the project.
After the completion of Gradle sync, MapKit3DDemo and the libraries can be seen in the project explorer, as shown in the following screenshot.

Figure 9. MapKit3DDemo in Project Explorer

Building and Running the MapKit3DDemo

The following steps describe building and running the MapKit3DDemo.

Before building the project, set the value for the API key.
Open com.example.mapkit3ddemo.Credential, as shown in the following screenshot. Replace your_server_token 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 Android MapKit3D APIs, their respective classes and methods, see MapKit3D Android API Reference Guide.

Android SDK