Objects and Interaction

You can select ViewObject objects by using a single tap gesture. To enable this in your code, create an OnGestureListener object and pass it to SupportMapFragment.getMapGesture().addOnGestureListener(OnGestureListener). When a single tap occurs, the listener receives the onTapEvent(PointF) callback, and if that event is not handled, then the listener receives the onMapObjectsSelected(List<ViewObject>) callback. The application can then define what to do with the selected ViewObject.

Types of ViewObject objects that are selectable are defined within the ViewObject.Type enumeration, which includes:

USER_OBJECT - an object that the application adds to a map with a MapObject base class (MapPolygon for example).

PROXY_OBJECT - an object that is added automatically to a map with a MapProxyObject base class. A proxy object may contain special information about the object, depending on the type (for example, TransitStopObject may provide transit stop-related information), but it cannot be created or modified.

UNKNOWN_OBJECT - a selectable map object that is not a USER_OBJECTnor a PROXY_OBJECT

Map Objects Example on GitHub

The ViewObject Abstract Class

The ViewObject abstract class represents the base implementation for all objects that are selectable on a MapView or SupportMapFragment. The SupportMapFragment features user-selectable objects.

Sub-classes of the ViewObject class include MapObject and MapProxyObject.

MapObject and Geo Objects

MapObject represents an abstract class for all map-related objects that can be added on a Map. The subclasses of this abstract class include:

MapContainer

MapCircle

MapPolyline

MapPolygon

MapRoute

MapMarker

MapLocalModel

MapGeoModel

MapLabeledMarker

MapScreenMarker

These objects can be created by calling the appropriate constructor methods. In some cases, a geo object is required in the constructor. Geo objects (for example, GeoPolyline and GeoPolygon) are geographical data representations that act as models to MapObjects, which act as views. Unlike map objects, geo objects cannot be added directly to a Map. For more information on geo objects and creating map objects, see the API Reference.

The following code snippet demonstrates how to create a MapPolyline and a GeoPolyline object:

To add a MapObject to the map, use Map.addMapObject(MapObject) or Map.addMapObjects(List<MapObject>). You can use the setOverlayType(MapOverlayType) method to set the display layer for the map object. By default, map objects are assigned to the foreground.

Note: For use cases where a map object needs to be viewable in 3D space, use MapLocalModel or MapGeoModel. Other map objects are not guaranteed to support 3D.

MapContainer

You can use MapContainer as a container for other MapObject instances. Map containers determine the stacking order of objects displayed on a map. To add a map object, call the MapContainer.addMapObject(MapObject) method.

Note:MapRoute and MapContainer cannot be added to a MapContainer.

Note: If a map object is a part of a MapContainer, it has the same MapOverlayType as the map container.

MapCircle

A MapCircle represents a type of MapObject in the shape of a circle, with an assigned radius distance and a GeoCoordinate center. It can be created by calling the constructor MapCircle(double radius, GeoCoordinate center).

Figure 1. A MapCircle object

MapPolyline

A MapPolyline is a MapObject in the shape of a polyline with anchor points at any number of GeoCoordinate points. It can be created via a GeoPolyline object, which can be created by calling the GeoPolyline(List<GeoCoordinate> points) constructor.

Note: A MapPolyline or MapPolygon can only contain up to 65536 vertices.

Figure 2. A MapPolyline object

MapPolygon

A MapPolygon is a MapObject in the shape of a polygon. In contrast with a MapPolyline, it is assumed that the last coordinate in the line's path is connected to the first coordinate, thereby constructing an enclosed geometry. A MapPolygon may define separate border and fill colors. To create a MapPolygon, use the constructor MapPolygon(GeoPolygon polygon). A GeoPolygon can be created by calling GeoPolygon(List<GeoCoordinate> points).

Figure 3. A MapPolygon object

MapRoute

A MapRoute is a MapObject that displays a calculated route on a map. For more information on MapRoute, see Routing .

MapMarker

A MapMarker is a MapObject that displays an icon at a geographical position on a map. You can create a MapMarker with your own custom icon by calling MapMarker(GeoCoordinate, Image).

Figure 4. A MapMarker object

MapMarker instances are always placed on top of other map objects. Refer to the diagram below for more information about z-index ordering for multiple map markers.

Figure 5. MapMarker order

You can set MapMarker to be draggable by using the MapMarker.setDraggable(true) method. To listen for drag events, such as marker position changes, use MapMarker.OnDragListener.

MapLabeledMarker

A MapLabeledMarker is a different type of marker object that avoids overlapping with other icons and text on the map. By default, the visual appearance of a MapLabeledMarker is similar to a point of interest. You can choose a preset category icon (for example, IconCategory.ZOO) or set your own Image as the marker icon.

Figure 6. A MapLabeledMarker object

Unlike MapMarker, setting the label text to a MapLabeledMarker does not require enabling an info bubble. You can set the marker label text by providing a language and a localized string to the MapLabeledMarker.setLabelText(String, String) method. The localized text in the language that matches the current Map.getMapDisplayLanguage(), if available, is displayed. Otherwise, the first-added localized text is displayed.

Note: Although a MapLabeledMarker is visually similar to a point of interest, its overlay type is set to FOREGROUND_OVERLAY by default.

MapLocalModel

A MapLocalModel is an arbitrary 3D map object that is drawn using a local coordinate (as opposed to a geocoordinate) mesh. You can create a custom MapLocalModel by calling MapLocalModel(), and setting the model mesh, texture, orientation, and geographical location before adding it to the map. For example:

While translating the 3D model mesh to the map, a unit of 1.0f represents 1 meter in the real world. For example, a Vector3f(100,200,300) represents an offset of +100 meters in the x-axis (East), +200 meters in the y-axis (North), and +300 meters in the z-axis direction (Up). You can further control the size of the 3D model mesh by setting a scaling factor with the setScale() method.

Figure 7. A MapLocalModel object

Aside from setting a texture, a MapLocalModel can also be customized by setting its material and lighting using the Phong reflection model. For example, the following code sets the ambient color, diffuse color, and light source to the MapLocalModel.

As 3D objects consume large amounts of memory, avoid using MapLocalModel and MapGeoModel to replace 2D map markers. Two examples of recommended uses of these classes are adding a few 3D structures to the map, or showing a realistic car model during guidance.

If you use MapLocalModel to create a two-dimensional object, and if you use an anchor with an undefined or zero altitude value, there is a known rendering issue with OpenGL where parts of the object may conflict with the map layer, causing the object to flicker. To get around this issue, use a z-coordinate offset that is greater than 0. For example, you can use a small floating point number such as, 0.001, so that the user is unable to distinguish between the object's altitude and the map.

MapGeoModel

A MapGeoModel is an arbitrary 3D map object that is drawn using geocoordinate vertices. You can create a MapGeoModel by calling its constructor and setting a list of geocoordinates, a list indicating the vertex order, a list of UV coordinates, and a texture Image. For example:

You can extract further Point of Interest (POI) information from a cartographic marker by using the Places feature in the HERE SDK, since cartographic markers contain identifying data that can be passed to a Place search request. For example:

The MapOverlay Class

The MapOverlay class represents a special type of map object that does not inherit from the MapObject base class. Instead, it provides a way for any Android View to be displayed at a fixed geographical location on the map.

You can add content to a map overlay by using the MapOverlay(View, GeoCoordinate) constructor. If complex view contents are required, such as a view with subviews of its own, the content should be fully initialized before adding it to the map overlay.

Due to the extra performance cost of Android views, it is recommended that the MapOverlay only be used in situations where the additional functionality provided by a View, such as a button, is needed. If the map object only needs to display a static image, use MapMarker.

Note:MapOverlay does not inherit from MapObject, but overlays are returned as a MapMarker from a a tap gesture callback by default. To avoid this behavior and these substitute markers, the appropriate gesture handling must be implemented either in a MapOverlay subclass, or in a custom view that is added as a subview to a standard MapOverlay.